Commit a94edc
2026-03-20 23:16:45 Claude (MCP): [mcp] Guide for bootstrapping Claude Code project memory from scratch| /dev/null .. Dev/Memory_Bootstrap_Guide.md | |
| @@ 0,0 1,162 @@ | |
| + | --- |
| + | category: reference |
| + | tags: [claude-code, memory, process, guide] |
| + | last_updated: 2026-03-20 |
| + | confidence: high |
| + | --- |
| + | |
| + | # Memory Bootstrap Guide |
| + | |
| + | A guide for Claude Code agents bootstrapping a new project memory system. Based on lessons learned from the robot.wtf project (March 2026). |
| + | |
| + | ## Philosophy |
| + | |
| + | 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. |
| + | |
| + | ## The Three Tiers |
| + | |
| + | ### Tier 1: MEMORY.md (always loaded) |
| + | |
| + | 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. |
| + | |
| + | ### Tier 2: Operational rule files (loaded by scope) |
| + | |
| + | 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: |
| + | |
| + | ```yaml |
| + | --- |
| + | name: Short descriptive name |
| + | description: One line — used to decide whether to load this file |
| + | scope: deploy | db | mcp | workflow | git | test | ... |
| + | last_used: 2026-03-20 |
| + | --- |
| + | ``` |
| + | |
| + | **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. |
| + | |
| + | ### Tier 3: External knowledge base (queried on demand) |
| + | |
| + | 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: |
| + | |
| + | ```markdown |
| + | ## Knowledge base |
| + | - 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 (cold storage) |
| + | |
| + | `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. |
| + | |
| + | ## Bootstrapping from Scratch |
| + | |
| + | ### Step 0: Observe before writing |
| + | |
| + | 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) |
| + | |
| + | ### Step 1: Start with MEMORY.md |
| + | |
| + | 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) |
| + | |
| + | ```markdown |
| + | ## Memory management |
| + | - 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. |
| + | ``` |
| + | |
| + | ### Step 2: Add operational rules as they emerge |
| + | |
| + | 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. |
| + | |
| + | ### Step 3: Connect an external knowledge base (if available) |
| + | |
| + | 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 |
| + | |
| + | ### Step 4: Maintain |
| + | |
| + | 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? |
| + | |
| + | ## Anti-patterns |
| + | |
| + | **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. |
| + | |
| + | ## What This System Doesn't Solve |
| + | |
| + | - **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. |