Skip to main content
How-To11 min read

How we give Claude Code a memory that survives every session

Claude Code, like every large language model, starts each session as a blank slate. Close the terminal, open it tomorrow, and it has forgotten your preferences, your project's quirks, and every correction you made the day before. The context window is short-term memory only, and it resets. To make an AI assistant genuinely useful over weeks and months, you have to give it long-term memory that you operate on purpose. Here is the layered setup I run across all my projects, and the handful of rules that decide whether it compounds or quietly rots.

Updated 6 November 2026. This note was first published in May 2026. Five months of daily use changed three things: the index moved out of the rules file into its own capped file, a nightly cleanup pass now proposes what to merge and delete, and the memory grew to 1,457 files. The sections below describe the setup as it runs today, and the lessons are at the end. If you want the short version, there is a two-page checklist (PDF).

Why "just keep chatting" does not work

The obvious idea is to keep one long conversation and never start fresh. It fails for three reasons. The context window is finite, so old turns fall off the back. Every token you carry forward costs money and slows the model down on every single request. And recall actually gets worse as the conversation fills with noise, because the signal you need is buried under thousands of lines of resolved back-and-forth. Memory is not about keeping everything. It is about keeping the few things that matter and being able to find them.

The three layers

Layer one: an always-loaded index

Claude Code reads a file called CLAUDE.md at the start of every session. That is the anchor. In May it held both the rules and the index. Today those are two files, because they grow at different rates and for different reasons. The rules file holds the always-apply rules (how I want it to work, the safety lines it must never cross) and stays short. The memory index is a separate file, one line per memory with a link out to the detail, under a hard cap of 200 lines. Dense topics, one stack or one domain each, get their own sub-index that loads only when a task touches that topic. The discipline here is ruthless brevity. These files are paid for in context tokens on every session, so when the index fills up, entries are relocated to a sub-index rather than deleted. A bloated always-on file is the most common way these setups go wrong: it feels thorough, and it silently taxes every request you ever make.

Layer two: one fact per file

The actual memories live as small individual files, one fact each, loaded only when relevant. Each carries a short frontmatter block so the system can decide whether to surface it: a name, a one-line description used for recall, and a type. I sort everything into four types:

  • user: who the person is. Role, expertise, fixed preferences.
  • feedback: working-style guidance and corrections, with the reason why, so the lesson survives rather than just the rule.
  • project: the state of ongoing work that you cannot read off the code or git history.
  • reference: pointers to external resources, dashboards, and reusable patterns.

Each file's body is the fact, followed by why it matters and how to apply it, and it links to related memories by name. That cross-linking turns a pile of notes into something closer to a graph, where pulling one memory naturally suggests the others next to it.

Layer three: a searchable deep store

The long tail of history, every decision and small learning from months of work, does not belong in either of the layers above. It lives in a separate searchable store that gets queried on demand at the start of a task, not loaded by default. In my case this is a small custom server that Claude can search, but the principle holds with any vector or keyword store: keep the bulk of memory out of context, and retrieve only the slice the current task needs.

The rules that keep it useful

The architecture is the easy part. These operating rules are what decide whether the memory helps a year from now or becomes a swamp of stale half-truths.

  • Do not store what the code already records. Structure, past fixes, and git history are all readable on demand. Memory is for the non-obvious: the why behind a decision, a preference, a constraint that lives in someone's head.
  • Convert relative dates to absolute. "Last week" rots the moment it is written. "2026-05-20" stays true forever.
  • Update, do not duplicate. Before saving, check for an existing file on the same topic and edit that. Two memories that disagree are worse than none.
  • Treat recalled memory as context, not gospel. A note that names a file or a feature flag may describe something that has since changed. Verify it still exists before acting on it.
  • Separate always-apply rules from situational ones. Posture and safety rules stay in the always-loaded file. Tool-specific gotchas live in files that load only when you are doing that kind of work, so they do not tax unrelated sessions.
  • Prune. Delete memories that turn out to be wrong. A memory system you never garden becomes one you stop trusting.

Automating the save

The weakest link in any note-taking system is remembering to take the note. Claude Code supports hooks that fire on events, and the one that matters here runs when a session ends. I use a Stop hook that prompts the assistant to checkpoint the session: the decisions made, the corrections received, the reusable patterns discovered, filed into the right layer automatically. The result is that memory accrues as a side effect of working, instead of depending on me to stop and journal. Capture has to be automatic, or it does not happen.

The nightly cleanup pass

Capture solves half the problem. The other half is that a memory written in May can be wrong by November, and nobody re-reads 1,400 files by hand. So a scheduled job runs every morning and does three things. It reads an access log that records which memory files were opened in recent weeks. That is the decay signal: a fact nobody has read in months is a candidate to go. It looks for pairs of files on the same topic and proposes a merge. And it looks for facts that contradict each other and proposes which one survives, with the date that settles it.

Two rules make this safe. The pass proposes only. It writes a report and a set of proposed edits, and never touches a memory file on its own. I read the report and apply it in an interactive session, where each change is shown as a diff and approved one by one. And each pass replaces the previous proposal instead of queueing behind it, so a week of skipped reviews leaves one current proposal, not seven stale ones.

Why not just point retrieval at everything

A fair question: why curate at all, when you could index every transcript and let retrieval sort it out? Because curation is the whole point. A search over raw conversation logs returns the place a topic was discussed, including all the wrong turns and abandoned ideas along the way. A search over atomic, deliberately written facts returns the conclusion you actually settled on. The first floods the context with noise and makes recall less reliable; the second is dense signal. The few seconds it takes to write a clean one-line memory pays for itself every time that memory is recalled instead of a thousand lines of chat.

The honest limits

This is not magic. Memories go stale, and a setup with no pruning slowly fills with facts that were true once. Two memories can quietly contradict each other until something forces the conflict into the open. And a recalled memory reflects what was true when it was written, not necessarily now, which is exactly why the verify-before-acting rule matters. Treated as a living system that needs occasional gardening, it is one of the highest-leverage things you can build around an AI assistant. Treated as a write-only archive, it becomes a liability you stop reading.

What five months of this taught me

  • Relocate before you trim. When the index hits its cap, the temptation is to delete the oldest lines. Move them to a sub-index first. A line deleted from the index is a memory that still exists and can never be found again.
  • Two sessions writing the index at once will clobber it. With several terminals open, each one rewrites the whole index from its own copy, and the last writer wins. Keep index edits small, and move the content into its own file before touching the index line, so a lost line never loses the fact.
  • Every memory needs the why. A rule without its reason gets argued with in a later session. "Never do X" lasts a week. "Never do X, because on this date it caused Y" lasts.
  • Count usage, not size. The number of files is not a health metric. The share of files that were read recently is, which is why the access log exists.
  • Links between memories do more than tidy. A memory that names its related memories gets recalled with them, so one fact surfaces its neighbours. A link to a name that does not exist yet marks something worth writing.

The bottom line

Long-term memory for an AI assistant is not one clever trick, it is a small system run with discipline: a lean always-loaded index, atomic one-fact files sorted by type, a searchable store for the deep history, an automatic save on every session, and a nightly pass that proposes the cleanup for a human to approve. The rules matter more than the tools. Keep the always-on layer tiny, store only the non-obvious, date everything absolutely, and prune without mercy. Do that and the assistant stops re-introducing itself every morning and starts picking up exactly where you left off.

If you want an AI assistant or agent wired into your own business with memory that compounds instead of resetting, send a brief and I'll scope it with you. It is the difference between a clever demo and a tool that actually gets better the longer you use it.

More questions?

Easier on WhatsApp than in a blog post.

I reply myself, during KL working hours