The 5 Files That Give Claude Code Permanent Memory
Most developers build one layer of memory. Here are the other four that actually compound
Most people set up CLAUDE.md and think they’re done. They’re not even close.
Let me tell you the mistake everyone makes with Claude Code.
They create CLAUDE.md, paste in a bunch of rules, and call it done. Claude knows their preferences now. Claude will remember things. Claude has context. Problem solved.
Then they close the terminal, open a new session the next morning, and Claude has forgotten that the project uses Zod for validation. It suggests a class component in a codebase that has not used one in two years. It tries to initialize a database connection that already exists in three other files. The rules file is there. The memory is not.
Here is the thing: CLAUDE.md is a rules file. It is not a memory system.
It tells Claude who it is. It does not remember what you did yesterday, what went wrong last week, or what your knowledge base contains. Most developers have one layer of this stack. Some have two. Almost nobody has all five. And the difference between one layer and five layers is the difference between an assistant that resets every morning and one that compounds knowledge over time.
Why This Gap Exists
Claude Code is stateless by design. Every new session starts from scratch. The context window is fresh, the conversation history is gone, and unless something explicitly loads that information, Claude is meeting your codebase for the first time, every time.
CLAUDE.md partially solves this. It loads automatically at session start and gives Claude a baseline for how to behave. But behavioral rules are not the same as situational awareness. Knowing “use TypeScript strict mode” is different from knowing “we are currently three commits into a refactor of the auth module and the middleware is broken until that lands.”
That situational awareness has to come from somewhere else. And it has to load automatically, or you will forget to provide it, which defeats the entire purpose.
This is the problem the 5-layer recall stack solves.
The 5 layers
Layer 1 — CLAUDE.md
Location: ~/.claude/CLAUDE.md
This is your foundation. Permanent rules and behavioral preferences that load automatically at every session start. How should Claude format its output? What tools should it use? What patterns should it avoid? What is your tech stack?
CLAUDE.md handles all of that. Write it once, and it applies everywhere.
What it does not do: update itself, learn from mistakes, or retain any information about what happened in a previous session. It is a static preferences file, not a learning system. Treat it accordingly. Write standards here, not state.
A good CLAUDE.md covers your coding philosophy, your linting and formatting rules, your preferred libraries, and your non-negotiables. It is the instruction manual Claude reads before every session.
Layer 2 — primer.md
Location: ~/.claude/primer.md
primer.md is a self-rewriting context file. After every completed task, a hook automatically overwrites it with the current state of your work: the active project, what was just completed, what the exact next step is, and any open blockers.
Every time you start a new Claude session, primer.md is already current. Not because you remembered to update it. Because the hook did.
Think about what this solves. You close your terminal at 11 PM mid-task. You come back the next morning. Claude loads primer.md and immediately knows: you were in the middle of the payment flow refactor, you just finished extracting the StripeService class, and the next step is wiring it into the checkout controller. No briefing required. No “here is what we were doing” preamble. You type claude and you are already in the middle of the work.
The difference between CLAUDE.md and primer.md is the difference between a job description and a shift handoff note. Both matter. They are doing completely different things.
Layer 3 — Git context
Mechanism: SessionStart hook
Every session, before you type anything, a hook fires and injects live codebase context into the conversation. Current branch, last five commits, modified files. All of it pulled fresh from git log and git status.
This matters because Claude often needs to reason about trajectory, not just current state. “What changed recently?” is a question that cannot be answered from static files. It requires actual repository history.
With the Git Context layer, Claude knows what the codebase looked like yesterday, what changed today, and what is currently being edited before you say a word. This eliminates an entire class of errors where Claude makes suggestions that conflict with changes already in flight.
It also makes @workspace style questions dramatically more accurate. When you ask “where should this new module go?”, Claude is reasoning from your actual file tree and recent patterns, not from a vague memory of what you described in CLAUDE.md six weeks ago.
Layer 4 — Hindsight
Mechanism: SessionStart + SessionEnd hooks via Docker
This is the layer almost nobody has. It is also the most powerful one.
Hindsight is a behavioral learning engine. It does not store files or retrieve documents. It extracts patterns from your past coding sessions and feeds them back into future ones.
Here is how it works: when your session ends, a SessionEnd hook fires and sends the session transcript through Hindsight’s pattern extraction. Hindsight identifies recurring behaviors — what you consistently rewrote, what suggestions you accepted, what you keep asking about, where Claude kept making the same class of mistake. These patterns are stored in a persistent memory bank called claude-sessions.
The next time you start a session, the SessionStart hook fires, recalls those patterns, and injects them as context. Claude now knows that you almost always reject suggestions that use any in TypeScript. It knows you prefer early returns over nested conditionals. It knows that in your last three sessions, you ended up rewriting the service layer Claude generated, so it should approach that differently.
This is actual learning. Not retrieval. Not documentation lookup. The system changes how Claude responds based on accumulated observations of how you actually work.
Running Hindsight requires Docker because the underlying service uses uvloop, which only runs on Linux. Docker gives you that Linux runtime on any platform.
export ANTHROPIC_API_KEY=your-key-here
docker run -d \
--name hindsight \
--restart unless-stopped \
-p 8888:8888 \
-p 9999:9999 \
-e HINDSIGHT_API_LLM_PROVIDER=anthropic \
-e HINDSIGHT_API_LLM_API_KEY=$ANTHROPIC_API_KEY \
-v hindsight-data:/home/hindsight/.pg0 \
ghcr.io/vectorize-io/hindsight:latest
After starting the container, create your memory bank once:
curl -s -X PUT http://localhost:8888/v1/default/banks/claude-sessions \
-H 'Content-Type: application/json' \
-d '{"name": "claude-sessions"}'
Then the hooks handle everything automatically. SessionEnd retains. SessionStart recalls. The --restart unless-stopped flag means Hindsight restarts with Docker Desktop after a reboot. You never have to think about it again.
If you do not want to run Docker, that is fine. The hooks in the recall stack gracefully skip Layer 4 if Hindsight is not running. You still get layers 1, 2, 3, and 5. That is already better than what most setups have.
Layer 5 — Obsidian vault
Mechanism: Shell alias with --add-dir
Your entire Obsidian vault becomes Claude’s working directory.
Every note you have written, every clipping you have saved, every reference doc you have organized — all of it is now available as context via the --add-dir flag. No plugin required. No sync setup. No API key for a notes integration. You add a shell alias that mounts your vault as a directory, and Claude can read from it as naturally as it reads from any local file.
alias claude='claude --add-dir ~/path/to/your/vault'
Your second brain is now Claude’s second brain.
When you ask “what did I note about rate limiting last month?”, Claude can actually look. When you are writing documentation and want it to match the tone of your previous writing, Claude can reference your actual writing. When you are designing an API and want to check it against architecture decisions you made six months ago, Claude reads the ADRs in your vault.
The vault syncs to mobile via iCloud or Obsidian Sync, which means whatever you add on your phone during your commute is available in Claude during your next session. The knowledge compounds because it is stored in one place and Claude has access to all of it.
The full stack in motion
Here is what actually happens when you open a new session:
You type: claude
Layer 1 CLAUDE.md loads → How should I behave?
Layer 2 primer.md loads → Where did we leave off?
Layer 3 SessionStart hook fires → What changed in the codebase?
Layer 4 Hindsight recall fires → What patterns should I follow?
Layer 5 Obsidian vault mounts → What is in the knowledge base?
Claude sees everything before you type a word.
...you work...
...primer.md auto-rewrites after each completed task...
...post-commit hook logs every commit to session history...
Session ends:
Layer 4 Hindsight retain fires → Extracts behavioral patterns,
stores them for next session
Every session feeds the next one. The stack gets more accurate the longer you use it.
Setup: one command for layers 1, 2, 3, and 5
The recall stack bundles all of this into a single repository with a setup script. Clone it, run one command, and everything except Hindsight is wired automatically.
git clone https://github.com/keshavsuki/recall-stack.git
cd recall-stack
bash setup.sh --obsidian ~/path/to/your/vault
The setup script handles:
Copying
CLAUDE.mdandprimer.mdto~/.claude/Copying hooks to
~/.claude/hooks/and marking them executableWriting SessionStart and SessionEnd config to
~/.claude/settings.jsonAdding the
--add-diralias for your Obsidian vault to your shell profileOptionally copying the post-commit hook to your current repository
Layer 4 (Hindsight) is set up separately using the Docker steps above, since it requires a persistent background service.
What each layer actually does
CLAUDE.md carries your permanent standards — the stuff that never changes session to session. primer.md carries your current state: where you left off, what’s broken, what’s next. The Git context layer gives Claude a live snapshot of your repository at launch — branch, recent commits, modified files. Hindsight quietly changes how Claude responds based on patterns from past sessions, without you doing anything. Your Obsidian vault hands Claude everything you’ve ever written down.
None of them overlap. CLAUDE.md can’t track state, which is why primer.md exists. primer.md doesn’t know what changed in the repo, which is why Git context exists. Git context can’t adapt Claude to your working patterns — that’s Hindsight’s job. And Hindsight has no idea what’s in your notes or reference docs, which is the entire point of the vault.
Five separate failure modes. Five separate fixes.
The thing nobody mentions
Every developer who works seriously with Claude Code has, at some point, burned context tokens re-explaining the same things. “We use Zod, not Yup.” “The auth module is already written, don’t create a new one.” “I told you about this pattern in the last session.”
That re-explanation cost is invisible, but it compounds. It fragments your flow. It wastes tokens on things you already said last Tuesday. And it’s easy to miss because each individual instance feels small — one sentence, thirty seconds — right up until you realize you’ve been re-briefing the same assistant for six months.
The recall stack eliminates that. Not through some clever memory architecture in the model itself, but by making the right information available at session start through a system that runs itself. You set it up once. After that, every session opens already knowing what matters.
I’ve been using a version of this for a few months now. The thing that surprised me wasn’t the time saved on briefing — it was how much clearer my own thinking got when I stopped spending the first ten minutes of every session re-establishing context. That overhead was doing something to how I worked, and I hadn’t noticed until it was gone.