memory-layer

Memory Layer

Three-tier wrapper on top of code-memory-router plus a local file-tier scratchpad.

Tiers

Tier	Purpose	Backend	Lifetime
scratch	Volatile session notes, in-flight findings	.agents/memory/scratch/<topic>.md (file-tier)	Session, until promoted or /mddesign:handoff promote
WHERE	Locational queries (where is X, which file, which directory)	QMD via /memory-router	Project lifetime
WHY	Decisions, rationale, post-mortems, "we picked X because"	MemPalace drawers via /memory-router	Forever

Operations

/mddesign:memory save <text> (default tier: scratch)

1. Determine the active topic. The active phase id from task_plan.md is the default topic. If no plan exists, use general.
2. Append <text> plus an ISO timestamp to .agents/memory/scratch/<topic>.md. Create parent directories if needed.
3. Print confirmation: "Saved to scratch / topic=".

/mddesign:memory save --tier why <text>

1. Print the text to the user with a clear "About to promote to MemPalace WHY tier. Approve? [y/N]" line.
2. The PreToolUse hook intercepts the next Bash or /memory-router invocation (named checkpoint: before_mempalace_write).
3. On approval, invoke /memory-router with the canonical "save to MemPalace" pattern documented in code-memory-router's SKILL.md. Pass the text plus a project tag derived from CWD basename.
4. On the same approval, append a marker to .agents/memory/scratch/<topic>.md: "PROMOTED to MemPalace at ." The original scratch entry stays in place for the rest of the session for context continuity.

/mddesign:memory recall <query>

Routing rule:

• If the query starts with "where", "which file", "find", "locate", route to WHERE.
• If the query starts with "why", "decision", "history", "what did we decide", route to WHY.
• Otherwise, peek at scratch first; if nothing matches, fall back to WHERE.

Routing target:

• WHERE → invoke /memory-router and let the router dispatch to QMD.
• WHY → invoke /memory-router and let the router dispatch to MemPalace.
• scratch → grep .agents/memory/scratch/**/*.md for the query.

Always print the source tier next to each result so the user sees provenance.

Stop hook integration

On Stop, the memory-keeper subagent runs and proposes promotions. This skill is the executor: when memory-keeper returns a list of WHY candidates, this skill drives /mddesign:memory save --tier why for each (each one HITL gated). Anything not promoted stays in scratch and is available for next session if session-handoff is configured.

Core rules

• Never edit task_plan.md, findings.md, or progress.md directly. Memory is a separate file space.
• Never write to MemPalace without HITL approval.
• Never bypass code-memory-router. If you cannot reach it, fail loudly and tell the user to install code-memory-router.
• Scratch directory is .agents/memory/scratch/. Never put memory in task_plan.md or findings.md.

External dependencies

• code-memory-router skill (the user's, required) — routes WHERE to QMD and WHY to MemPalace
• File-tier scratch needs no install
• Claude Memory Tool integration (Anthropic Messages API tool type memory_20250818) is reserved for v0.2 once it is exposed via MCP for cross-IDE use. v0.1.0 ships file-tier scratch as the substitute that works today on every coding agent.

Example

User runs /mddesign:memory save Decided to use Postgres over SQLite for the memory store, scaling concern.

This skill:

1. Reads task_plan.md to find the active phase id (e.g., phase-2-data-model).
2. Appends to .agents/memory/scratch/phase-2-data-model.md:

   ## 2026-04-23T10:30:00Z
   Decided to use Postgres over SQLite for the memory store, scaling concern.
   

3. Prints "Saved to scratch / topic=phase-2-data-model"

Later in the session the user says /mddesign:memory recall why postgres. This skill:

1. Routes to WHY because of "why" prefix.
2. Invokes /memory-router to query MemPalace.
3. If MemPalace returns nothing yet, falls back to grep on .agents/memory/scratch/**/*.md.
4. Surfaces the entry above with [source: scratch] next to it.

On Stop, memory-keeper flags this entry as a WHY candidate. The user approves. This skill promotes via /memory-router. Next session, /mddesign:memory recall why postgres returns from MemPalace with [source: WHY].