Jason Woltje
2a91f6c202
Agents consistently ignore written instructions about memory routing and default to writing local MEMORY.md files regardless of rules in RUNTIME.md, CLAUDE.md, or MEMORY.md itself. Instructions alone are insufficient — a technical gate is required. Changes: - Add tools/qa/prevent-memory-write.sh — PreToolUse hook that blocks Write/Edit/MultiEdit to ~/.claude/projects/*/memory/*.md (exit 2) - Register hook in runtime/claude/settings.json PreToolUse array - Update runtime/claude/RUNTIME.md: replace soft "Memory Override" note with hard-gate policy, what-goes-where table, and rationale - Rewrite guides/MEMORY.md: OpenBrain as primary layer, blocked silos table, project continuity files, how-the-hook-works section The correct behavior is now the only possible behavior for Claude Code. All agent learnings route to OpenBrain where every harness can read them. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
51 lines
2.3 KiB
Markdown
51 lines
2.3 KiB
Markdown
# Memory and Retention Rules
|
|
|
|
## Primary Memory Layer: OpenBrain
|
|
|
|
**OpenBrain is the canonical shared memory for all Mosaic agents across all harnesses and sessions.**
|
|
|
|
Use the `capture` MCP tool (or REST `POST /v1/thoughts`) to store:
|
|
- Discovered gotchas and workarounds
|
|
- Architectural decisions and rationale
|
|
- Project state and context for handoffs
|
|
- Anything a future agent should know
|
|
|
|
Use `search` or `recent` at session start to load prior context before acting.
|
|
|
|
This is not optional. An agent that uses local file-based memory instead of OpenBrain is a broken agent — its knowledge is invisible to every other agent on the platform.
|
|
|
|
## Hard Rules
|
|
|
|
1. Agent learnings MUST go to OpenBrain — not to any file-based memory location.
|
|
2. You MUST NOT write to runtime-native memory silos (they are write-blocked by hook).
|
|
3. Active execution state belongs in project `docs/` — not in memory files.
|
|
4. `~/.config/mosaic/memory/` is for mosaic framework technical notes only, not project knowledge.
|
|
|
|
## Runtime-Native Memory Silos (WRITE-BLOCKED)
|
|
|
|
These locations are blocked by PreToolUse hooks. Attempting to write there fails at the tool level.
|
|
|
|
| Runtime | Blocked silo | Use instead |
|
|
|---------|-------------|-------------|
|
|
| Claude Code | `~/.claude/projects/*/memory/*.md` | OpenBrain `capture` |
|
|
| Codex | Runtime session memory | OpenBrain `capture` |
|
|
| OpenCode | Runtime session memory | OpenBrain `capture` |
|
|
|
|
MEMORY.md files may only contain behavioral guardrails that must be injected at load-path — not knowledge.
|
|
|
|
## Project Continuity Files (MANDATORY)
|
|
|
|
| File | Purpose | Location |
|
|
|---|---|---|
|
|
| `docs/PRD.md` or `docs/PRD.json` | Source of requirements | Project `docs/` |
|
|
| `docs/TASKS.md` | Task tracking, milestones, issues, status | Project `docs/` |
|
|
| `docs/scratchpads/<task>.md` | Task-specific working memory | Project `docs/scratchpads/` |
|
|
| `AGENTS.md` | Project-local patterns and conventions | Project root |
|
|
|
|
## How the Block Works
|
|
|
|
`~/.config/mosaic/tools/qa/prevent-memory-write.sh` is registered as a `PreToolUse` hook in
|
|
`~/.claude/settings.json`. It intercepts Write/Edit/MultiEdit calls and rejects any targeting
|
|
`~/.claude/projects/*/memory/*.md` before the tool executes. Exit code 2 blocks the call and
|
|
the agent sees a message directing it to OpenBrain instead.
|