MEMORY pattern

Persistent agent memory survives between sessions. The pattern: one fact per file, plus an index file.

Layout

.agent-memory/
  MEMORY.md            # index: one line per memory, no frontmatter, never holds content
  user_<slug>.md       # who the user is (role, expertise, preferences)
  feedback_<slug>.md   # guidance the user has given on how the agent should work
  project_<slug>.md    # ongoing work, goals, constraints not derivable from code
  reference_<slug>.md  # pointers to external resources (URLs, dashboards, tickets)

File frontmatter

Each memory file has:

---
name: <short-kebab-case-slug>
description: <one-line summary — used to decide relevance during recall>
metadata:
  type: user | feedback | project | reference
---

<the fact; for feedback/project, follow with **Why:** and **How to apply:** lines.
Link related memories with [[their-name]].>

Index file

MEMORY.md is the only file loaded into context every session. One line per memory:

- [Short title](file.md) — one-line hook

No frontmatter. No body content. Just the index.

Type semantics

• user — facts about the human you're collaborating with. Role, expertise, preferences. Rarely changes.
• feedback — guidance the user has given on how to work. Corrections AND confirmed approaches. Include the why.
• project — ongoing work, goals, or constraints not derivable from the code or git history. Convert relative dates to absolute.
• reference — pointers to external resources (URLs, dashboards, tickets).

Rules

1. One fact per file. If a memory has two unrelated parts, split it.
2. Don't save what the repo already records. Code structure, past fixes, git history, CLAUDE.md content — do not duplicate.
3. Don't save chat-scoped facts. "We just decided X in this conversation" belongs in the PR, not memory.
4. Convert dates to absolute. "Last week" today is "two weeks ago" next month.
5. Link liberally. Use [[other-memory-name]]; an unresolved link marks a future memory worth writing.
6. Verify before recommending. When recalled, memories appear in \<system-reminder\> blocks — they reflect what was true when written. If one names a file/function/flag, confirm it still exists before acting.

Lifecycle

• Add when a non-obvious lesson lands. Not at session end as a chore.
• Update rather than duplicate. Check for an existing file covering the topic first.
• Delete memories that turn out to be wrong. Wrong memory > worse than no memory.

Example

feedback_no_nested_ternary.md:

---
name: no-nested-ternary
description: User insists no nested ternaries; use if/else or lookup tables
metadata:
  type: feedback
---

Never nest `?:` inside another `?:`. Use if/else, early return, or a lookup map.

**Why:** Nested ternaries are unreviewable; agents misread the precedence.

**How to apply:** When tempted to nest, extract to a `const x = (() => { if (...) return ... })()` IIFE or a lookup map.

See also [[file-size-budget]] — long ternaries also bust the line budget.

MEMORY.md index entry:

- [No nested ternaries](feedback_no_nested_ternary.md) — never nest `?:`; use if/else or lookup

See also

• ../pillars/ai-collaboration/README.md
• CLAUDE.md.template.md — the bootstrap doc loads MEMORY.md every session.