How to Give Claude Code Memory of Your Entire Project

Claude Code forgets everything when you close a session. That's not a bug you can fix in settings, it's a fundamental property of how large language models work. But you can work around it by giving Claude a persistent memory layer that lives inside your project directory. The most practical approach right now is a community-built system that creates a .wolf/ directory in your repo, which stores structured context about your codebase across sessions. Every time Claude starts a new session, it reads from that directory instead of re-scanning files from scratch, saving tokens, cutting setup time, and keeping the model's understanding consistent over weeks of development.

What Is a Persistent Memory Layer for Claude Code?

A persistent memory layer is a structured file-based system that stores information Claude would otherwise lose when a session ends. Think of it as an external brain that sits alongside your code. It doesn't change how Claude works internally, it changes what Claude reads at the start of each session.

The .wolf/ directory approach stores several types of information: which files Claude has already read, what decisions were made and why, what mistakes were encountered, user preferences about code style and architecture, and a running log of token consumption per operation. Claude reads this directory early in each session and picks up roughly where it left off.

This matters more than most developers realize at first. On a project with 200+ files, a cold-start session can burn through 15,000 to 20,000 tokens just orienting Claude to the codebase before any real work begins. A well-maintained .wolf/ brain can cut that orientation cost by roughly 60%, because Claude already knows which files matter and which it can skip. If you're managing token budgets seriously, and on complex projects you should be, that's a meaningful difference. You can read more about how Claude's Ultra plan handles token efficiency to understand why session startup cost compounds quickly.

Why Claude's Stateless Context Window Is a Real Problem for Large Codebases

Every Claude Code session starts cold. There's no built-in continuity between sessions, no memory of the files you worked on yesterday, no record of the architectural decision you made last Tuesday, no awareness that you spent three hours debugging a race condition in your WebSocket handler. You start from zero every time.

For a small script or a one-off task, that's fine. For a long-running professional project, it becomes a genuine bottleneck. Developers using Claude Code on codebases above roughly 50,000 lines typically report spending the first 5 to 10 minutes of every session re-explaining project context. That's not a workflow problem, it's a structural cost that adds up to hours per month.

There's also a consistency issue. Without memory, Claude can suggest approaches that contradict decisions you already made and documented elsewhere. It might recommend a library you explicitly chose not to use, or propose a pattern that conflicts with your existing architecture. A persistent memory layer surfaces those past decisions automatically, so Claude's suggestions stay coherent with what your project already does. For a deeper look at how Claude handles memory at the architectural level, how Claude AI memory works across conversation types gives useful background on why session-level amnesia is baked into the system.

How to Set Up Persistent Memory for Claude Code Using the .wolf Brain System

Here's how the system works in practice. The .wolf/ directory sits at the root of your project and contains a set of structured files that Claude reads at session start and updates throughout the session via lifecycle hooks.

Step 1: Initialize the .wolf Directory

Create the directory and its core files manually or with a setup script. The minimum structure you need looks like this:

mkdir -p .wolf
touch .wolf/brain.md
touch .wolf/file-map.json
touch .wolf/token-log.json
touch .wolf/mistakes.md
touch .wolf/preferences.md
echo ".wolf/token-log.json" >> .gitignore

Add the token log to .gitignore since it's session-specific data you don't need in version control. The other files should be committed, they're the actual persistent knowledge base.

Step 2: Populate brain.md With Project Context

The brain.md file is what Claude reads first. Write it like a briefing document for a new team member who is technically sharp but knows nothing about your specific project. Include the stack, the architecture decisions that aren't obvious from the code, and any constraints the project has.

# Project Brain

## Stack
- Node.js 20, Express, PostgreSQL via Prisma
- React 18 frontend, deployed on Vercel
- Redis for session management

## Key Decisions
- We chose Prisma over raw SQL for type safety, do not suggest query builders
- Auth is handled by a custom JWT system in /src/auth, do not suggest Passport.js
- All API routes follow REST conventions, no GraphQL

## Known Issues
- WebSocket reconnection logic in /src/realtime/socket.ts has a known race condition under load (ticket #204)

Step 3: Use the Six Lifecycle Hooks

The real power comes from six hooks that intercept Claude's actions during a session and update the brain automatically. These hooks fire on: file read, file write, tool call start, tool call end, error occurrence, and session end. You configure these in your Claude Code settings or via a wrapper script.

Here's what each hook tracks:

• on_file_read - logs the file path and timestamp to file-map.json so Claude knows what it's already seen
• on_file_write - records what was changed and appends a summary to brain.md
• on_tool_start / on_tool_end - tracks token consumption per operation in token-log.json
• on_error - writes a structured entry to mistakes.md including the file, the error, and what fixed it
• on_session_end - triggers a summary pass that consolidates what happened into brain.md

A minimal hook configuration in your project's Claude settings file looks like this:

{
  "hooks": {
    "on_file_read": "echo '{\"file\": \"$FILE\", \"ts\": \"$TIMESTAMP\"}' >> .wolf/file-map.json",
    "on_error": "echo '## Error $TIMESTAMP\nFile: $FILE\nError: $ERROR\nFix: pending' >> .wolf/mistakes.md",
    "on_session_end": "claude summarize-session --output .wolf/brain.md --append"
  }
}

Step 4: Tell Claude to Read the Brain at Session Start

Add a line to your CLAUDE.md file, the project-level instruction file Claude reads automatically, directing it to load the brain before doing anything else:

## Session Start Protocol
Before any task, read .wolf/brain.md and .wolf/mistakes.md in full.
Check .wolf/file-map.json to identify files already processed this sprint.
Do not re-read files marked as reviewed unless explicitly asked.

This alone can save 3 to 8 minutes of re-orientation per session on a medium-sized codebase. If you want to understand how to structure CLAUDE.md and supporting files for maximum effect, the 8 files you need to master Claude in 2026 covers the full file hierarchy in detail.

How the .wolf System Learns Your Preferences Over Time

The most underrated part of this architecture is the learning loop. The preferences.md file starts empty, but over time the session-end hook populates it with patterns it detects from your corrections and choices. If you consistently reject a certain type of suggestion or always ask Claude to format responses a specific way, those patterns get written to the preferences file and loaded next session.

In practice, developers using this system report that Claude's first-pass accuracy on their specific codebase improves noticeably after about 10 sessions, because the model has 10 sessions worth of preference signals to work from. That's not magic; it's just giving the model better context. The preference file grows to roughly 200 to 400 words over a month of active use, which is a tiny token cost compared to the accuracy gains it produces.

This pattern, using structured files to build a second brain that sits alongside your AI tools, is the same principle behind building a second brain with Claude Code and Obsidian, applied directly to your development workflow rather than your knowledge management system.

Claude Code's stateless nature is a constraint you can't remove, but it's a constraint you can design around. The .wolf/ brain system turns a weakness into a structured process: every session adds to a growing knowledge base about your project, your preferences, and the mistakes already made. The longer you use it on a given codebase, the faster and more accurate Claude becomes on that codebase. Set it up once, commit the brain files to your repo, and treat them like documentation, because that's exactly what they are.