> Published sample from the Setup Audit library, exactly as it ships in a > pack apart from this note. Placeholders like {{CLIENT_NAME}} are filled > from your interview answers at assembly time. --- id: memory-context-02 title: Implement three-tier memory category: memory-context type: upgrade points: 7 effort: M prereqs: [foundation-03, memory-context-01] personalisation: include_if: always boost_if: session_end_habit == nowhere placeholders: [CLIENT_NAME, CLIENT_SLUG] --- # Implement three-tier memory **Goal**: All three memory tiers exist concretely for every project: a confirmed global manual, working `memory/` folders with a stated promotion rule, and a chosen, working long-term archive with its location declared in each project's `CLAUDE.md`. **Effort**: M (under 2 hours) **Prereqs**: foundation-03, memory-context-01 ## Why this matters (claude.ai also has a built-in cross-chat memory; that is a separate, complementary decision covered in memory-context-05 where the pack includes it. This runbook builds the file-based system your workspace owns.) The memory-context-01 audit named where context gets lost. This task closes those gaps with a specific, working structure rather than a vague promise to "keep better notes". Three tiers, each doing one job: identity, in-flight work, and history. Skipping straight to a database front-loads infrastructure {{CLIENT_NAME}} does not need yet; skipping the archive entirely repeats the context-loss problem this kit exists to fix. ## Instructions for Claude 1. Confirm tier 1 is in place: read `~/.claude/CLAUDE.md` and confirm it exists and is the stable identity layer written in foundation-02 (short, rarely edited, covers identity, workstreams, working style). Do not rewrite it here; this task only confirms it. **Verify:** `~/.claude/CLAUDE.md` exists and its content matches the one-line summary from foundation-02's findings, spot checked. 2. Confirm tier 2 is in place: for each project folder created in foundation-03 under `~/claude-workspace/`, confirm `CLAUDE.md` and `memory/` both exist. **Verify:** `ls -d ~/claude-workspace/*/CLAUDE.md ~/claude-workspace/*/memory` shows both present for every project folder. 3. Define what belongs in `memory/` by adding a short section to each project `CLAUDE.md` if not already present: working docs, interview checkpoints, draft analyses, anything still mid-flight. State the promotion rule explicitly: when a draft in `memory/` produces a durable decision or fact, promote it into the project `CLAUDE.md` with a dated line, for example `- 2026-07-11: decided to X because Y`. **Verify:** each project `CLAUDE.md` contains a "memory/" section naming what belongs there and the promotion rule in those terms. 4. **Ask the client:** present the tier 3 choice plainly, then record their answer. - Option A (default, start here): plain dated markdown files `memory/archive/YYYY-MM-DD-.md` per project. Searchable with grep or by Claude reading the folder. Zero infrastructure, works offline, works across {{CLIENT_NAME}}'s accounts because it is just files on the machine. - Option B (at scale): a vector database such as Pinecone, index `{{CLIENT_SLUG}}-memory`, one namespace per project, semantic search across hundreds of wrap-ups. Worth it once the archive outgrows what Claude can read in a session in one pass, not before. - Decision heuristic: start with files; revisit only if the archive exceeds roughly 50-100 records, or grep starts failing to find what the client needs. **Verify:** their choice is recorded in the CLAUDE.md footer from step 7, not assumed by Claude. 5. Create the archive folder for each project: `mkdir -p ~/claude-workspace/*/memory/archive`. **Verify:** `ls -d ~/claude-workspace/*/memory/archive` shows the folder exists for every project. 6. Write a first archive record by hand, as a template, in each project: `memory/archive/-kit-setup.md`, containing the Topic, Date, Status, Decisions, Next actions and Source IDs structure (the same structure the wrap-up ritual in memory-context-03 uses). **Verify:** file exists, is non-empty, and contains all six fields. 7. Add a "Memory" footer to each project's `CLAUDE.md` declaring all three tier locations: the global manual path, this project's `memory/` folder, this project's `memory/archive/` folder, and, if Option B was chosen, the Pinecone index and namespace name. Example (substitute the actual project folder name for ``): ```markdown ## Memory - Tier 1, global manual: ~/.claude/CLAUDE.md - Tier 2, in-flight drafts: ~/claude-workspace//memory/ - Tier 3, long-term archive: ~/claude-workspace//memory/archive/ ``` **Verify:** `grep -A4 "## Memory" ~/claude-workspace/*/CLAUDE.md` returns the footer in every project file. 8. Final verify: from a fresh Claude Code session opened inside any one of {{CLIENT_NAME}}'s project folders under `~/claude-workspace/`, ask Claude "where does long-term memory live for this project?". It should answer using the Memory footer, not by guessing. **Verify:** Claude's answer names the exact archive path stated in the footer. ## Verify - Every project folder has `memory/archive/` present and a first archive record inside it. - Every project `CLAUDE.md` contains a Memory footer naming all three tiers and the chosen tier-3 option. - The promotion rule (draft to dated CLAUDE.md line) is stated in each project `CLAUDE.md`. - The fresh-session test in step 8 is answered correctly from the CLAUDE.md footer, not invented. ## Done when - [ ] Tier 1 confirmed in place, unchanged - [ ] Tier 2 `memory/` folders confirmed and the promotion rule documented in each project `CLAUDE.md` - [ ] Tier 3 choice made and recorded, archive folders created, first archive record written - [ ] Memory footer present in every project `CLAUDE.md` and passes the fresh-session test