A fresh Claude Code session retains the files and configuration available to it, but not the full reasoning from every previous conversation. Decisions, solved bugs, and discarded alternatives need somewhere durable to live if they matter later.
This chapter examines two practical approaches from people using Claude Code in ongoing work. Both converge on the same insight: useful memory is a design problem, not just a tooling feature.
Teresa Torres’s Three-Layer Context System
Teresa Torres, the product discovery coach behind Product Talk, developed a system for Claude Code that I think is the most practical approach to this problem. She described it in detail in her blog post “Stop Repeating Yourself: Give Claude Code a Memory” and in Peter Yang’s interview from December 2025. The system works because it’s built around a principle that’s easy to state and hard to internalise: every conversation starts from scratch, so you have to create memory deliberately.
Layer 1: Global CLAUDE.md
This lives in ~/.claude/CLAUDE.md and loads into every single session, regardless of what you’re working on. Torres keeps it extremely short: personal working preferences (always plan before doing anything, never just act), planning at multiple levels, feedback preferences, and an index of reference context files.
The critical design decision: keep it short. This file loads even when she asks Claude if her dog can eat a particular food or when brainstorming Christmas gifts. None of that needs business context. If you’ve ever wondered why your Claude sessions feel sluggish despite a modest CLAUDE.md, this might be why. Everything in that file competes for attention on every single task.
The global CLAUDE.md is configuration, but it also consumes attention whenever it loads. Make it worth the cost.
What does NOT go here: business details, product descriptions, team information, audience profiles. All of that belongs in reference files loaded on demand.
Layer 2: Project CLAUDE.md
Each project folder has its own CLAUDE.md with project-specific rules. Torres treats each folder as a separate Claude “project”; launching Claude inside that folder gives it that folder’s context.
Her tasks folder CLAUDE.md explains how the task system works, how tagging works, how Obsidian front matter is structured. Her writing folder CLAUDE.md says “Claude is a thought partner, not a writer. You’re acting as an editor.” It also includes: “At the start of every session, read my writing style guide.”
The separation matters more than you’d think because the folders have completely different rules. The tasks CLAUDE.md carries no writing workflow, and the writing CLAUDE.md carries no task-system detail. This prevents context contamination, a problem we’ve all hit without realising what caused it.
Layer 3: Reference Context Files
A folder of small, focused markdown files, each covering one topic. Business profile. Target audience. Marketing profile. Differentiators. Company overview. Business model. Personal profile. Individual product files.
These are NOT loaded automatically. The global CLAUDE.md contains an index telling Claude where to find them and to only load what’s relevant. If Torres says “let’s work on the landing page for my story-based customer interview course,” Claude already knows where to find details about the course, the company, and the target audience without being told.
The key: small and many. Torres deliberately creates many small files rather than few large ones, so she can mix and match. Claude loads only what the current task needs. Progressive disclosure applied to agent context, the same principle that makes well-designed APIs pleasant to work with.
The Stop and Capture Rule
This is Torres’s simplest and most actionable advice, and the one that changed how I think about context:
Whenever you find yourself explaining context to Claude, stop. Ask: “Am I going to explain this again?” If the answer is yes, do not leave it only in this session. Capture it in a file.
She never sat down to create all her context files in one session. Instead, whenever she felt the need to explain context, she’d stop: “Claude, you need to know about my differentiators. Maybe interview me.” Claude asks questions, she answers, Claude writes the file. Over time, the collection grew organically. Every conversation became a context-building opportunity.
Before I encountered this, I kept meaning to “properly document” my context and never finding the time. The stop-and-capture approach reframes it entirely. You’re not carving out dedicated setup time; you’re capturing context as a byproduct of working.
The End-of-Session Ritual
At the end of every working session, Torres asks: “What did you learn about working with me? What should we add to the context files?”
This creates a conversation about where new information should go. Preferences and working style belong in CLAUDE.md; business, product or audience context belongs in a reference file. She actively resists Claude’s tendency to jam everything into CLAUDE.md, keeping the global file lean.
There’s a nice maintenance trick here too: Torres never manually updates the index of context files. Every time she has Claude add a new file, she says “What index needs to be updated?” Claude figures it out. The profile/index file was entirely maintained by Claude over time. Delegation done right.
The claudecode-kb Implementation
Patrick Zandl took these principles and built a pragmatic, developer-focused implementation called claudecode-kb (he wrote about the reasoning in this blog post). File-based, git-versioned. No database, no API, no build step. Just files and conventions, which is about the right level of complexity for this problem.
The architecture is clean:
my-knowledgebase/
├── preferences/ # Coding style, tools, stack
├── patterns/ # Reusable architectural patterns
├── snippets/ # Reusable code pieces
├── troubleshooting/ # Solved problems
├── projects/ # Per-project notes + session logs
├── memory/ # Decisions with reasoning
└── scripts/ # Helper scriptsZandl reports that his original 170-line CLAUDE.md lost instructions in the middle. Liu et al.’s “Lost in the Middle” (TACL 2024) found that some models performed better when relevant information appeared near the beginning or end of a long context. That does not establish a universal line limit for CLAUDE.md, but it supports the case for concise, well-routed instructions.
Zandl cut the file to 40 lines, using it mainly to route Claude to detailed instructions, and reports that his results improved.
Your CLAUDE.md is a table of contents, not an encyclopaedia.
JSONL Session Logs
Each project has a human-readable overview file and a machine-readable session log in JSONL format. The tooling treats the JSONL log as append-only, reducing the chance that an update replaces months of history.
This matters more than it sounds. Zandl reports losing data when Claude rewrote a Markdown log instead of appending to it. JSONL plus append-only tooling makes that failure less likely, although the file can still be overwritten by a process with write access. A schema line defines the format, and Claude reads the last five entries for recent context.
Episodic Memory
The memory/decisions.jsonl file captures major technical decisions with date, the decision itself, context, options considered, reasoning, and outcome. Not just “we use Next.js” but why. So Claude can reference past reasoning for similar decisions instead of giving generic advice unsuitable to a scenario.
Getting Started Without Overwhelm
Torres offers three tips for people who want to start but feel overwhelmed. I find the first one is the most important:
You don’t have to get here overnight. Start with the stop and capture rule. Build context files incrementally, not all at once. The worst thing you can do is spend a weekend building an elaborate system and then never maintain it.
Minimum viable structure. At a minimum, separate work and personal folders. That’s it. Add more structure as you go.
Think like a delegator. For every task you do, ask: “How can Claude help?” Some tasks you want augmented: Claude as research assistant while you write. Some you want automated: pushing receipts to your finance system. The distinction drives what context Claude needs.
Torres notes she has 10 years of experience delegating to a human admin, which made her naturally good at identifying what to delegate and writing standard operating procedures. The same skill transfers directly: if you wouldn’t hand a task to a new employee without explaining the process, don’t hand it to Claude without context.
Zandl recommends 15 minutes every Friday to review the knowledge base. Check what’s stale, what’s missing, what needs updating. Without this, the system rots. Stale context is arguably worse than no context, because it gives Claude confident-sounding but outdated guidance.
So What Now?
Both systems are built on one insight: memory is a design problem. A new session does not automatically contain the full reasoning from earlier work, so you have to decide what deserves durable storage and how it should be loaded.
If you take away one thing, let it be the stop-and-capture rule. Next time you find yourself explaining something to Claude that you’ve explained before, stop. Capture it.
The next session can then spend its context on the problem rather than reconstructing the same database decision.