How I got Claude Code to hang on to my projects and preferences, along with every correction I'd already made, so a session picks up where the last one left off and it gets a little smarter each time without me asking.
Out of the box, Claude Code has no persistent memory. You can spend a whole afternoon with it on a project, close the terminal, and when you open it again it doesn't know you were ever there.
The CLAUDE.md I had was one monolithic file that dumped about 15,000 tokens of instructions into every session, whether or not the task needed them, so I'd get deployment details while writing an email and slide rendering rules while debugging Apex. That's 7.5% of the context window gone before I'd typed a word.
And even with all that loaded I was still retyping the same opening every time, "I'm a Solution Engineer working on Salesforce, here's my project structure, don't use these words, remember the 70/30 rule..." so the first 10 minutes of a session always went to re-orientation.
What bothered me most was that nothing carried over. Claude would make the same mistake twice, reaching for a deprecated product name I'd corrected last week or suggesting a pattern I'd already rejected, because whatever it learned the day before was gone by the next session. Losing ten minutes a session was annoying, but it also meant Claude was never going to get any better at working with me, since every correction evaporated when the session closed.
The idea I built on is the LLM Wiki pattern that Andrej Karpathy described in early 2026. Rather than re-deriving knowledge on every query, you have the LLM build and maintain a persistent wiki that compounds over time, which goes right at the nothing-carries-over problem. Here's how his three layers map onto what I ended up with.
Immutable input that I curate before it goes in.
Synthesized and interlinked, and Claude maintains it as it goes.
The structure and conventions Claude and I work out between us.
His three operations lined up with things I already had. Ingest is my /ingest command, query is just every conversation, and lint is /wiki-lint.
The part of his argument that sold me is that the maintenance burden is what kills every knowledge system, because the bookkeeping is exactly what people stop doing. Claude handles the summarizing, cross-referencing, filing, and consistency-checking while I work, which leaves me the sourcing and the thinking, plus pointing it in the right direction, and I've never had to sit down and organize the wiki myself.
RAG (retrieval-augmented generation) retrieves by meaning, which is great for searching large datasets you didn't write. My preferences and project state, and every correction I've made, are things I wrote myself. Those live better in structured markdown files that Claude reads and updates directly, which is simpler and quicker to work with and doesn't drift from what I actually wrote. So I run both, a flat-file wiki for personal knowledge and pgvector RAG for corporate data like product names, customer stories, and competitive intel.
When I built this, though, Karpathy's write-up didn't deal with context window cost at all, and a wiki that keeps growing has to get loaded somehow. Loading all of it at the start of every session would have put me right back at the 15,000-token file.
So instead of one massive instruction file, I split the context into five tiers that load at different times, each with its own token cost. The counts on this page are a snapshot from when I wrote Part 1, and the May 2026 follow-up at the bottom has the later numbers for memory files, hooks, and MCP servers.
Who I am, the essential rules like anti-slop and anti-hallucination, and the wiki routing table, which is the irreducible minimum Claude carries into every run.
A Python script reads the directory, the git history, and the branch name, and suggests which wiki pages to load.
51 pages of deep reference on architecture patterns, deployment runbooks, and design systems, pulled in only when a task needs them.
128 topic files on decisions made, mistakes corrected, project status, and feedback. The MEMORY.md index loads automatically and the details get read on demand.
Security governance, architecture standards, testing quality, communication style, context-mode policy, and data protection, loaded from ~/.claude/rules/ every session.
less overhead at the start of a session, which leaves the other 97.5% of the context window for code, conversation, and output.
Every tier is a real file or folder on disk, and hooks are what make the timing happen. Each one opens up to show what's inside, and CLAUDE.md comes first because everything else gets reached through its routing table.
Here's what that looks like when I open Claude Code in my slide-generation project directory, and most of it happens before I type anything.
CLAUDE.md loads first, about 2,800 tokens, and Claude picks up who I am and what my job is, along with the essential rules and the line in the routing table saying slide work means pitch-craft.md and slide-visual-design.md. Then session-init.py fires. It notices the working directory contains "slides," checks the git log, where recent commits mention "deck" and "slide," and from that it suggests three wiki pages worth loading (pitch-craft.md, slide-visual-design.md, and golden-narrative-framework.md) for around 200 tokens.
The MEMORY.md index comes in last, about 2,000 tokens covering 128 memory entries, and the relevant ones surface right away. One flags that AI backgrounds look cheesy while solid colors read as premium (feedback-imagen-cheesy.md), and another warns Claude off using Salesforce contract timelines as Why Now drivers (feedback-seller-urgency-ban.md).
Claude reads pitch-craft.md (the golden narrative framework), slide-visual-design.md (design tokens and the layout library), and that account's memory file. It already has everything I used to spell out, solid backgrounds, the 70/30 customer-to-Salesforce ratio, the banned words, how the brand colors resolve, so there's no setup and it just starts building.
When Claude writes code, the PostToolUse validator hook checks naming conventions and security patterns on its own, so I'm not the one reviewing the basics.
Along the way Claude worked out that account's brand palette, so before closing it appends a line to wiki/inbox.md recording which colors the brand resolved to, and the next session folds that into a proper wiki entry.
The ramp-up went to zero minutes. I stopped opening with "here's my project, here are my rules, remember that thing from yesterday," because Claude already knows who I am and what I'm working on, and it has the decisions I've already made.
The 82% and the 3x measure different things. The 82% compares the old 15,000-token file with the 2,800 tokens of CLAUDE.md alone, with everything else coming in on demand, and the 3x counts all of what loads at session start (CLAUDE.md, the hook, and the memory index, about 5,000 tokens). Either way the window stays clear for actual work, and conversations run 3-4x longer before it fills.
The 128 memory files are where the corrections live. Each one is a correction or a preference (some are architectural decisions) that got saved once and keeps getting applied, which is why Claude stops making the same mistake twice. The wiki keeps growing and memory keeps accumulating with every session, so the system gets better the more I use it, and session 100 is a lot better than session 1. Without something pruning it, though, it would only keep growing, the way Karpathy's does.
Karpathy described the idea, and I tested it and then took it in five directions he hadn't covered when I built this.
Cost was the obvious one after that 15,000-token file. Tiered loading keeps 2,800 tokens always on and pulls everything else in on demand, and that's where the 82% reduction against loading the full schema every session comes from. Routing was the second. In his workflow you tell the LLM what to do each time, and I wanted that step gone, so the session-init hook reads my git state and suggests which wiki pages to load with no human in the loop.
He keeps one artifact, the wiki. I split mine into four types (wiki for reference, memory for decisions, rules for standards, and schema for routing), each loaded at a different time for a different reason.
He describes a Lint step, and I took it further with a /curate command that scans memory for staleness, works through the wiki inbox, and flags what needs attention, and because memory files carry decay rates the system can prune itself instead of only growing the way his does.
The fifth came from DDR-001 in the Agentforce Agent Harness. Karpathy's system relies on the LLM voluntarily looking things up, and DDR-001 puts the trouble with that bluntly, “agents forget to remember.” So infrastructure constraints load as rules every time, and PreToolUse hooks surface the relevant ADRs before you edit a constrained file, which puts that information in front of Claude at the moment it matters instead of hoping it goes looking.
“I think there is room here for an incredible new product instead of a hacky collection of scripts.”
I took that line seriously, and what came out of it is five named tiers, 19 commands, 10 MCP servers, automated context routing, tiered token loading, architecture guardrail hooks, and ADRs. It stopped being a hacky collection of scripts somewhere along the way, though I still wouldn't hand it to anyone as a product.
You don't need the whole system on day one. I'd start with CLAUDE.md and add the next layer when you feel the one before it running out, since each stage is useful by itself.
Day one, about 30 minutes. Create CLAUDE.md in your project root with your name, your role, and what you work on, plus your environment (OS, editor, key tools), 3-5 rules Claude should always follow, and any words or patterns to avoid. Standards you want in every project go in rules files under ~/.claude/rules/.
Week one, 1-2 hours, is memory and the start of a wiki. Enable auto-memory in your CLAUDE.md instructions and start a wiki/ directory with an index.md master catalog, 3-5 pages for your main topics, and an inbox.md auto-capture queue, then add a routing table to CLAUDE.md that maps work contexts to wiki pages.
By month one (2-3 hours total) you can add hooks to settings.json for the automated behaviors, a SessionStart context routing script, PostToolUse code validation, and Notification OS alerts. That's also when CLAUDE.md should start getting slimmer as the wiki grows. Move the detail out and keep the routing in.
After that it's about 5 minutes a week, because knowledge bases rot without maintenance. A weekly /curate archives stale session memories, processes wiki inbox items, and checks index health and routing gaps. Claude does the legwork and you just decide what stays and what goes.
# Project Context ## Owner - Name: [Your name] - Role: [Your role and team] - Context: [How you use Claude Code. What are you building?] ## Environment - OS: macOS / Windows / Linux - Editor: VS Code / JetBrains / Terminal - Key tools: [sf CLI, npm, docker, etc.] ## Rules (Always Follow) 1. [Your most important rule, e.g., "Never use deprecated APIs"] 2. [Quality standard, e.g., "All Apex must be bulk-safe"] 3. [Voice rule, e.g., "Write like an SE, not a marketing team"] 4. [Safety rule, e.g., "Never hardcode IDs or credentials"] ## Current Projects - [Project 1]: [One-line description + status] - [Project 2]: [One-line description + status] ## Preferences - [How you like to work with Claude] - [What kind of output you expect]
It's copy-paste templates and code blocks, plus a completion checklist, and it takes about 30 minutes to go from zero to done.
By May 2026 the system had grown to 220+ memory files, 186 skills, 14 hooks, 13 MCP servers, and 2.1 GB of local intelligence, and the follow-up looks at what happened once the compound learning kept going.
Read the Follow-UpOnce Claude Code remembers who you are, the next question is what you build on top of that memory. Part 2 picks up the thread with AgentScript.
Part 2: AgentScript