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 set of rules, and call it done. Claude knows their preferences now. Claude will remember things. Claude has context. The problem looks solved.
Then they close the terminal and open a new session the next morning. Claude forgot that the project uses Zod for validation. It suggests a class component. That codebase dropped class components two years ago. It tries to initialize a database connection that already exists in three other files.
The rules file is there. The memory is absent.
CLAUDE.md is a rules file, and it is not a memory system.
It tells Claude who it is. It forgets what you did yesterday, what went wrong last week, and what your knowledge base contains. Most developers run one layer of this stack. Some run two. Almost nobody runs all five.
One layer gives you an assistant that resets every morning. Five layers give you an assistant 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 and the conversation history is gone. Something must load that information explicitly. Otherwise Claude meets your codebase for the first time, every time.
CLAUDE.md partially solves this. It loads at session start and gives Claude a baseline for how to behave. A behavioral rule differs from situational awareness. "Use TypeScript strict mode" is a behavioral rule. Situational awareness reads like this. "We are three commits into a refactor of the auth module, and the middleware breaks until that lands."
That situational awareness must come from somewhere else. It must also load automatically. You will forget to provide it by hand, and that failure defeats the purpose.
The 5-layer recall stack solves this problem. The recall stack is a set of files and hooks that load context at session start.
The 5 layers
Layer 1. CLAUDE.md
Location: ~/.claude/CLAUDE.md
This file is your foundation. It holds permanent rules and behavioral preferences, and it loads at every session start. It answers four questions.
How should Claude format its output? Which tools should it use? Which patterns should it avoid? What does your tech stack contain?
CLAUDE.md handles all of that. Write it once, and it applies everywhere.
The file never updates itself. It never learns from a mistake. It retains nothing about a previous session. It is a static preferences file, and a learning system is a different thing. Write standards here and keep state out.
A good CLAUDE.md covers your coding philosophy and your linting and formatting rules. It also covers 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. A hook overwrites it after every completed task. The new contents carry the current state of your work. That means the active project, the completed task, the exact next step, and any open blocker.
Every time you start a new Claude session, primer.md is already current. The hook updated it, and you did nothing.
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 knows three facts at once.
You sat in the middle of the payment flow refactor. You finished the extraction of the StripeService class. The next step wires that class into the checkout controller.
You need no briefing. You write no "here is what we were doing" preamble. You type claude and you land in the middle of the work.
CLAUDE.md reads like a job description. primer.md reads like a shift handoff note. Both matter, and they do completely different jobs.
Layer 3. Git context
Mechanism: SessionStart hook
Every session, before you type anything, a hook fires. It injects live codebase context into the conversation. That context is the current branch, the last five commits, and the modified files. The hook pulls all of it fresh from git log and git status.
Claude often needs to reason about trajectory as well as current state. No static file answers the question "what changed recently?". That answer needs real repository history.
The Git context layer tells Claude three things before you say a word. It knows the state of the codebase yesterday, the changes from today, and the files open right now. That removes a whole class of errors. Claude stops making suggestions that conflict with changes already in flight.
It also makes @workspace style questions far more accurate. You ask "where should this new module go?". Claude reasons from your real file tree and your recent patterns. It stops guessing from a description you wrote 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 stores no files and retrieves no documents. It extracts patterns from your past coding sessions and feeds them into future ones.
Your session ends and a SessionEnd hook fires. The hook sends the session transcript through Hindsight's pattern extraction. Hindsight identifies recurring behavior.
It records what you rewrote and which suggestions you accepted. It also records what you keep asking about, and where Claude repeated the same class of mistake. It stores those patterns 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 you rewrote the service layer Claude generated in your last three sessions. So it approaches that layer differently.
This is actual learning rather than retrieval or a documentation lookup. The system changes how Claude responds. It bases that change on accumulated observations of how you work.
Hindsight requires Docker, because the underlying service uses uvloop. uvloop runs on Linux only. 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:latestAfter the container starts, 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. The SessionEnd hook retains the patterns and the SessionStart hook recalls them. The --restart unless-stopped flag restarts Hindsight with Docker Desktop after a reboot. You never think about it again.
You can also skip Docker. The recall stack hooks skip Layer 4 whenever Hindsight is absent. You still get layers 1, 2, 3, and 5. That result already beats most setups.
Layer 5. Obsidian vault
Mechanism: Shell alias with --add-dir
Your entire Obsidian vault becomes Claude's working directory.
The --add-dir flag makes the whole vault available as context. That covers every note you wrote, every clipping you saved, and every reference doc you organized. The flag needs no plugin, no sync setup, and no notes API key. You add a shell alias that mounts your vault as a directory. Claude then reads from it as easily as it reads any local file.
alias claude='claude --add-dir ~/path/to/your/vault'Your second brain is now Claude's second brain.
You ask "what did I note about rate limiting last month?" and Claude looks it up. You write documentation and want the tone of your earlier writing. Claude reads that earlier writing. You design an API and want a check against architecture decisions from six months ago. Claude reads the ADRs in your vault.
The vault syncs to mobile through iCloud or Obsidian Sync. You add a note on your phone during your commute. Claude reads that note in your next session. The knowledge compounds, because it sits in one place and Claude reads 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 sessionEvery session feeds the next one. The stack gets more accurate the longer you use it.
One command for layers 1, 2, 3, and 5
The recall stack bundles all of this into one repository with a setup script. Clone the repository and run one command. The script wires everything except Hindsight.
git clone https://github.com/keshavsuki/recall-stack.git
cd recall-stack
bash setup.sh --obsidian ~/path/to/your/vaultThe 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
Set up Layer 4, Hindsight, separately with the Docker steps above. It requires a persistent background service.
What each layer actually does
CLAUDE.md carries your permanent standards, which never change from session to session. primer.md carries your current state. That is where you left off, what broke, and what comes next.
The Git context layer gives Claude a live snapshot of your repository at launch. That snapshot holds the branch, the recent commits, and the modified files. Hindsight changes how Claude responds, and it uses patterns from past sessions. Your Obsidian vault hands Claude everything you wrote down.
The five layers stay separate. CLAUDE.md cannot track state, so primer.md exists. primer.md cannot see what changed in the repository, so Git context exists. Git context cannot adapt Claude to your working patterns, and that is Hindsight's job. Hindsight cannot read your notes or your reference docs, and that is the point of the vault.
You get five separate failure modes and five separate fixes.
The thing nobody mentions
Every serious Claude Code user burns context tokens on the same re-explanations. "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, and it compounds. It fragments your flow. It wastes tokens on things you already said last Tuesday. Each instance feels small, at one sentence and thirty seconds. Then you notice that you re-briefed the same assistant for six months.
The recall stack removes that cost. It puts the right information in place at session start, through a system that runs itself. You set it up one time. Every session after that opens with what matters already loaded.
I ran a version of this for a few months. The saved briefing time surprised me less than I expected. My own thinking got clearer instead. I stopped spending the first ten minutes of every session on context. That overhead changed how I worked, and I noticed it only after it went away.
Related reading: Token Anxiety and the Illusion of Productivity, AI Costs Part 2, Skills 2.0, Building An AI Marketing Team with Claude Skills
