# 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.
