10689a30d2
Work packages completed: - WP1: packages/forge — pipeline runner, stage adapter, board tasks, brief classifier, persona loader with project-level overrides. 89 tests, 95.62% coverage. - WP2: packages/macp — credential resolver, gate runner, event emitter, protocol types. 65 tests, 96.24% coverage. Full Python-to-TS port preserving all behavior. - WP3: plugins/mosaic-framework — OC rails injection plugin (before_agent_start + subagent_spawning hooks for Mosaic contract enforcement). - WP4: profiles/ (domains, tech-stacks, workflows), guides/ (17 docs), skills/ (5 universal skills), forge pipeline assets (48 markdown files). Board deliberation: docs/reviews/consolidation-board-memo.md Brief: briefs/monorepo-consolidation.md Consolidates mosaic/stack (forge, MACP, bootstrap framework) into mosaic/mosaic-stack. 154 new tests total. Zero Python — all TypeScript/ESM.
52 lines
2.7 KiB
Markdown
52 lines
2.7 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.
|