memory-keeper

Memory Keeper

Two memory stores exist. Use the right one.

Store 1: MEMORY.md (fast-path)

${CLAUDE_PLUGIN_ROOT}/identity/MEMORY.md

Use for one-line entries that need to be loaded into every session prompt. Capacity: keep under ~40 lines total. When it grows past that, promote older entries to Store 2 and remove them here.

Good fit:

• "User's GitHub username is orlandowatson."
• "Default deployment target is the prod branch."
• "Don't suggest tailwind — user prefers vanilla CSS."

Format: bullet, one line, present tense.

Store 2: Auto-memory (long-form)

~/.claude/projects/<current-project>/memory/

Use for structured topic memory — one file per topic, with frontmatter. This is Claude Code's built-in auto-memory system. Follow the rules already in your system prompt for what types exist (user, feedback, project, reference) and what NOT to save.

Good fit for Store 2:

• A project's quirks, deadlines, and stakeholders.
• Feedback the user gave that includes a reason ("don't mock the DB because…").
• Pointers to external resources ("logs live in Grafana board X").

Decision tree

Did the user explicitly say "remember"?
├── Yes → write to whichever store fits the content (default: Store 2)
└── No → ask: would behaving differently next session require this?
    ├── Yes → write
    └── No → don't write

What NOT to remember

• Facts derivable from git log, the codebase, or live tools.
• Ephemeral state ("we're three commits into the refactor").
• Negative judgments about the user.

Updating, not appending

When a fact changes, edit the existing entry rather than adding a new one. Stale memory is worse than missing memory.

Periodic curation

Once a week (Friday afternoon by default — see HEARTBEAT.md), run the librarian subagent to:

• Merge duplicate entries.
• Promote entries from Store 1 to Store 2.
• Delete anything contradicted by current state.