memory

Memory protocol

The vault's memory system is deliberately organic and lazy-loaded. Filenames describe content; there is no preset taxonomy. Files are read only when their descriptor suggests they're relevant to the current task.

The structure

• MEMORY.md is a flat bullet list. No headers. No sub-sections. Each entry:

  - [[memory/<filename>]] — <one-line descriptor of what's in this file>
  

• Files under memory/ are named after content:
  • A single discrete fact → its own file (memory/passport-expires-2028.md).
  • A cluster of related rules or lessons → one shared file (memory/kyoto-ryokan-lessons.md).
• There are NO preset categories. Don't create memory/travel/ or memory/preferences/ subfolders.

When to WRITE memory

Only during Verify of a passing Full job. Never during Light requests. Never during Explore. Never mid-Apply.

If a Light-tier request produces a lesson worth keeping, promote it to Full tier: write a minimal plan.md in Design (the lesson is the deliverable), work the V-tasks in Verify to confirm it, then write the memory. This prevents memory from getting populated off-loop.

What counts as a durable lesson

• Facts the user won't want to re-explain (dates, IDs, names, environmental state).
• Preferences and feedback the user gave about how you work ("don't X because Y happened last time").
• Project-specific context that isn't in the filesystem or git log.
• Pointers to external systems ("our Slack #errors channel has the traces").

What does NOT go into memory

• Ephemeral task state — put it in the job folder.
• Anything derivable from the current filesystem, git log, git blame, or ls.
• One-off fix recipes — the fix is in the code; context in the commit message.
• Long explanations of what code does.
• Negative judgements about the user.

How to WRITE memory (two-step)

Step 1 — write the lesson to a file under memory/. Name the file after content. Body is imperative. For rules and preferences that might need edge-case judgement, include:

# <short title>

<the rule or fact, one or two sentences>

**Why:** <the motivation — often a specific past incident or preference>

**How to apply:** <when the rule kicks in; edge-case guidance>

Step 2 — update MEMORY.md:

• If you created a new file, add the index line: - [[memory/<filename>]] — <one-line descriptor>.
• If you appended to an existing file, the descriptor still holds — do NOT touch MEMORY.md.

When to READ memory

Lazy-load during Explore only. Not during Light. Not mid-Apply.

1. Read MEMORY.md in full (designed to be thin).
2. Decide which memory/*.md files are relevant to this task by their descriptors.
3. Read only those files.

Do NOT read every memory/*.md file. Do NOT eager-read memory at session start (AGENTS.md is already loaded as the system prompt — memory is separate).

Before recommending from memory

A remembered fact is true as of when it was written. Before acting on it:

• If it names a file path → check the file still exists.
• If it names a person / team / external system → check the reference still resolves.
• If the user is about to act on the recommendation → double-check before they act.

If a remembered fact turns out to be stale: update or delete the memory file, don't act on the stale version. Deleting: remove the file AND its line in MEMORY.md.

How to FIX memory inconsistencies

• Broken wikilink in MEMORY.md (points to a file that doesn't exist): delete the broken line, OR restore the file if you know its content.
• Orphan memory file (file under memory/ with no line in MEMORY.md): add a descriptor line to MEMORY.md, OR delete the orphan if it's truly obsolete.

Do these repairs during the next Verify that touches the relevant memory — not speculatively.

Guardrails

• No preset taxonomy. Files under memory/ sit flat. No memory/travel/. No memory/work/. No memory/<domain>/.
• Organic naming. Filenames describe what's in the file. Don't use cryptic slugs; don't use generic ones like memory/notes.md.
• Memory writes are a Verify privilege. If you catch yourself wanting to write memory outside Verify, you're in the wrong phase. Pause and reclassify.
• Descriptors are the API. Other sessions will pick files by descriptor. Write descriptors that actually help — "travel lesson" is vague; "Kyoto ryokans: book 60+ days out or lose the english-friendly ones" is specific.