memory-router

Input: one item, claim | evidence | date, plus the current cwd. Output: a destination, a file path, and the exact text shape to write. Never writes anything itself when called by save-session; when used standalone it writes the one item and prints the absolute path.

Two tests decide almost everything:

• Test 1. Does it prescribe behavior ("always", "never", "before X do Y")? Then a rules file or a CLAUDE.md.
• Test 2. Is it a fact about the world that could change? Then STATUS.md if it is live, the brain if it is cross-session.

Everything below is those two tests plus scope and volatility.

Classify first

Answer these five for the item:

Decision table

Tie-breaks, in order

1. Applies in more than one repo -> go up one level. The brain INDEX.md is read at every session start; a project memory is invisible from any other repo. A decision or a sibling-repo fact saved only in one repo's memory is the classic way knowledge gets lost.
2. Prescriptive beats descriptive. A rule goes to a rules file; the incident that produced it goes to memory. Never store only the story.
3. False within 30 days -> STATUS.md, TODO.md or a status file. Never memory. Counts are the classic case.
4. An owner_doc exists -> update the owner; at most a one-line pointer in memory. Two sources for one fact will drift.
5. Same fact never twice. A dedupe hit (brain recall) means update in place and report "updated".
6. An explicit remember/save/memory ask always writes at least one file and echoes the path, even when the table says discard.
7. Secrets and identifiers are stripped before any of the above.
8. Still undecided between the brain and project memory -> the brain plus a wikilink line in the project memory index.

Paths

• Brain: $AGENT_BRAIN_DIR (default ~/.agent-brain), index INDEX.md. Write with brain remember, read with brain recall, check with brain lint. Create INDEX.md with the four headings if missing.
• Project memory: your agent's per-project memory dir if it keeps one; otherwise a brain file whose description names the repo.
• Rules: your agent's user-level rules files (for Claude Code, ~/.claude/rules/*.md).
• Live state: optional STATUS.md and TODO.md in the workspace root.
• Session-gating local notes: the workspace CLAUDE.local.md (never committed).

Exact formats

Memory file (the canonical shape; write canonical, never rewrite legacy files that use a different frontmatter):

---
name: <kebab-case-lesson-name>
description: "<one line stating the lesson itself, not the topic>"
metadata:
  node_type: memory
  type: user | feedback | project | reference
  modified: <ISO 8601 UTC>
---

<one paragraph stating the fact or rule, absolute dates>

**Why:** <incident or measurement, the user's words quoted, date>

**How to apply:** <imperative bullets; include when it does NOT apply>

Related: [[other-memory-name]]

Name the file by the lesson (cpp-solutions-use-vector-never-arrays.md), never by session or date. Add originSessionId under metadata when the session id is known.

INDEX.md line, under ## User / ## Feedback / ## Project / ## Reference:

- [{{Title}}]({{file-name}}.md) - <one-line summary with the key number or rule>

Rules file: an imperative bullet under the existing matching section, trigger case and date in parentheses.

Vocabulary rules file: - **\<phrase>`** = <meaning>. <what to do>.under the matching##`.

STATUS.md: keep the > Last updated: <YYYY-MM-DD> (<what changed>) line current; sections ## <topic> (<YYYY-MM-DD>) -- <STATE>; PR links as [owner/repo#N](https://github.com/owner/repo/pull/N); every count carries its source query.

TODO.md: ## <Idea>, **Status**: Planned | Parked (<date>), bullets, Decided <YYYY-MM-DD>: ....

Repo CLAUDE.md: any shared preamble stays verbatim; one bullet under the nearest section; file stays under ~250 lines.

CHANGELOG.md: Keep a Changelog headings under a concrete next version.

Never

• Never write a secret value, cookie, booking reference, order number, phone number or address anywhere. Names only.
• Never create a memory file for live state or a count.
• Never write inside a fork of someone else's repo.
• Never write to .claude/handoffs/; nothing reads it.
• Never an em or en dash character; -- or -.
• Never a relative date.