category: reference

tags: [claude-code, memory, process, guide]

last_updated: 2026-03-20

A guide for Claude Code agents bootstrapping a new project memory system. Based on lessons learned from the robot.wtf project (March 2026).

Memory exists so that a fresh session can behave correctly before it knows what task it's working on, and find relevant context once it does.

Three principles:

1. **Progressive disclosure.** Not everything needs to be in context at once. Load behavioral rules always, operational rules by scope, and project knowledge on demand.

2. **Separate what you are from what you know.** Behavioral rules (how to work) are durable and belong locally. Project knowledge (what's going on) changes fast and belongs in an external knowledge base if one exists.

3. **Memory that isn't maintained is memory that lies.** Every memory will go stale. Build in mechanisms to detect and manage staleness rather than trusting that memories are current.

This file is automatically injected into every conversation. Keep it short (under 100 lines ideally, hard cap at 150). It contains:

- **Project identity** — one or two lines. What is this project? Where do the repos live?

- **User preferences** — how the user likes to work. Tone, process preferences, things to avoid.

- **Behavioral rules** — inline, no separate files. These are rules about *how you think and decide* that apply regardless of the task. Examples: "always write tests first," "never push without asking," "verify before merging."

- **Memory management protocol** — how memories are organized, when to review, when to archive.

- **Knowledge base index** — if there's an external knowledge store (wiki, Notion, etc.), a short index of what's where plus instructions for querying it.

- **Operational rules index** — pointers to separate files, organized by scope, with one-line descriptions.

MEMORY.md is an operational briefing, not an encyclopedia. If you're tempted to add detail, ask: "Does a fresh session need this before it knows the task?" If no, it belongs in a file or external store.

These are individual markdown files for project-specific procedures and gotchas. They answer "how do I do X in this project?" and "what will bite me if I'm not careful?"

Each file has frontmatter:

**Scope** is a coarse tag indicating when this memory is relevant. Keep scopes broad — you want maybe 5-7 scopes total, not one per file. Common scopes:

- `deploy` — deployment procedures, infrastructure access, reproducibility rules

- `db` — database schemas, config behavior, migration gotchas

- `workflow` — implementation pipeline, review process, checklists

- `git` — repo locations, branch strategies, merge procedures

- `test` — test infrastructure, fixtures, known failures

**last_used** is the date this memory was last relevant to a conversation (not just read — actually applied). Update it at session end. Use it to detect staleness: if `last_used` is more than 2 weeks old, the memory is a candidate for archival or validation.

A behavioral rule in MEMORY.md should say: "On session start, scan operational rules below. Load any that match the task." This makes scope-based loading a conscious decision rather than requiring automation.

Project status, design docs, architecture decisions, implementation history, benchmarks — anything that describes *what's going on* rather than *how to behave* — should live in an external store if one is available (wiki, docs site, issue tracker).

Local memory should never duplicate this. Instead, MEMORY.md carries a short index:

- Design/ — feature specs, architecture decisions

- Dev/ — implementation summaries, benchmarks

- Tasks/ — task breakdowns

- Use semantic_search when the page location isn't obvious.

If no external knowledge base exists, you have two options:

1. Keep project knowledge in local files, but tag them clearly as informational and review them aggressively for staleness.

2. Accept that project knowledge will be derived from code, git history, and conversation each session.

Option 2 is often fine for small projects.

`archive.md` is a secondary index for operational rules that haven't been used recently. It's never automatically loaded — you consult it when something feels familiar or when a task might relate to old context.

Moving a memory to the archive means moving its entry from MEMORY.md's operational rules section to archive.md. The file itself stays put.

In your first session with a new project, don't create memories immediately. Work normally. Notice:

- What does the user correct you on? (→ behavioral rules)

- What project-specific procedures do you have to look up? (→ operational rules)

- What context do you keep re-deriving from code? (→ consider whether this needs to be stored or is fine to re-derive)

After 1-2 sessions, create MEMORY.md with:

- Project identity (2-3 lines)

- User preferences (what you've observed)

- Any behavioral rules from corrections

- Memory management section (copy the protocol below)

- Behavioral rules: inline above, no separate files.

- Operational rules: individual files with scope and last_used in frontmatter.

- Informational/project knowledge: write to [external store] OR derive from code.

- Cold operational rules: move index entry to archive.md.

- Session end: update last_used on any operational rule that was applied.

- Review when: last_used > 2 weeks OR MEMORY.md exceeds 150 lines.

Don't pre-populate. Create operational rule files when you encounter a procedure or gotcha that:

- You had to look up or figure out

- The user corrected you on

- Would be non-obvious to a fresh session

Give each file a scope. Add it to the operational rules index in MEMORY.md.

If the project has a wiki, docs site, or structured knowledge base:

- Add a knowledge base section to MEMORY.md with a short index

- Stop writing informational/project memories locally

- Migrate any existing project-status memories to the external store

At session end:

- Update `last_used` on any operational rules you applied

- If you learned new behavioral rules, add them inline to MEMORY.md

- If you learned new operational procedures, create a scoped file

Periodically (when `last_used > 2 weeks` or MEMORY.md exceeds 150 lines):

- Archive cold operational rules

- Validate remaining operational rules against current code/reality

- Check behavioral rules — are any redundant or contradictory?

**The append-only index.** MEMORY.md grows without curation until it's too long to be useful. Fix: the 150-line pressure valve and active archival.

**The stale project memory.** You write "Feature X is in progress" and never update it when X ships. Fix: don't store project status locally. Use an external store, or don't store it at all.

**The redundant file.** A behavioral rule gets its own file with frontmatter, Why, and How to apply — but it's a one-liner that could live inline. Fix: only create files for operational rules that have enough substance to justify a file.

**The premature memory.** You create a memory after one interaction, before you know if the pattern will recur. Fix: wait for the second occurrence. One correction is an event; two is a pattern.

**The unscoped dump.** All operational rules loaded every session regardless of task. Fix: scope tags and the "scan and load" behavioral rule.

- **Cross-machine sync.** Local memories are path-dependent. Different machines see different memory directories. An external knowledge base is the only durable store.

- **Automated staleness detection.** `last_used` is manually updated. There's no daemon checking for drift. Discipline is the mechanism.

- **Semantic retrieval.** Loading by scope is coarse. If you need "find the memory most relevant to this error message," you need a vector store, not markdown files.

These are acceptable trade-offs for a system that runs on flat files with no infrastructure.