10 — Memory System
Claude Code sessions don't remember each other by default. Memory fixes that. The goal: stop re-explaining your project to every new session.
The problem
Every session starts cold. Claude doesn't know what you decided yesterday, why you structured the code that way, or which approach you already tried and abandoned. You either paste context manually at the start of every session — or you build something that does it for you.
Two kinds of memory
Facts that are always true — your project's architecture, conventions, decisions made, things to never do. These don't change often. They belong in a file Claude reads at session start.
Things that happened — session logs, past conversations, code changes over time. These are queryable. You want semantic search over them, not a flat file.
Most setups combine both.
Three approaches
Option A: Vault + structured CLAUDE.md
The simplest option. Keep a CLAUDE.md in each project with conventions, constraints, and key decisions. Use @path imports to pull in shared context (brand voice, architecture docs, ICP).
Good fit if: your context is relatively stable and you're okay updating it manually.
Limitation: no search. If you have 50 past sessions worth of decisions, you can't query them.
Option B: Obsidian vault + lean-ctx
Keep a vault of markdown notes — one per project, one per decision, session logs. Use ctx_search to pull relevant notes into context at session start.
This gives you searchable, human-readable memory with no infrastructure. The tradeoff is that search is keyword-based, not semantic.
Good fit if: you already use Obsidian or similar, and your notes are well-named.
Option C: Embeddings + vector search (mem0, Pinecone, pgvector)
Store session summaries, decisions, and code snippets as embeddings. Query by semantic similarity at the start of each session — "what do I know about the auth system?" returns relevant past context even if the wording differs.
Tools worth knowing:
- mem0 — managed memory layer with an API, designed for agents
- Pinecone / pgvector — if you want to roll your own
- A FastMCP server — expose search as a tool Claude can call mid-session
Good fit if: you have months of session history, complex projects, or multiple agents that need shared memory.
What to pin at session start
Whatever approach you pick, the pattern is the same: load the right context before Claude does any work.
Useful things to always load:
- Project conventions and constraints
- Current architecture decisions
- Things that didn't work (saves re-trying them)
- Any external context Claude can't infer from code (team conventions, business rules)
A SessionStart hook is the cleanest way to inject this automatically — see 09 — Hooks & Scripts.
Start simple
Don't build a pipeline before you know you need one. Start with a CLAUDE.md and a session log you append to manually. When you find yourself re-explaining the same thing three sessions in a row, that's the signal to automate it.