Files

Jason Woltje 2a91f6c202 feat: hard-gate agent memory to OpenBrain via PreToolUse hook

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>

2026-03-02 21:15:28 -06:00

2.3 KiB

Raw Blame History

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

Agent learnings MUST go to OpenBrain — not to any file-based memory location.
You MUST NOT write to runtime-native memory silos (they are write-blocked by hook).
Active execution state belongs in project docs/ — not in memory files.
~/.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.

2.3 KiB Raw Blame History