Giving Claude Code a memory that persists between sessions

Claude Code is great at tasks that fit in one session. Open a project, describe a change, accept edits, commit, done. But the second you close the terminal, every architectural decision, every debugging detour, every "ah, this codebase does X differently" moment - gone.

That gap is not a tooling deficiency. It is a deliberate design choice: LLM calls are stateless, and statelessness is what makes them fast, cheap, and parallelisable. The fix is not to change the model. The fix is to own the memory layer yourself.

Here is the pattern that actually works.

The three layers you need

Persistent memory for a coding agent is not one thing. It is three overlapping layers, each solving a different problem:

RAG handles none of these cleanly. It retrieves similar-looking text, not time-stamped context. What you want is closer to how a human engineer remembers a codebase: by project, by collaborator, and by recent thread.

Layer 1 - CLAUDE.md for project memory

The simplest layer is a checked-in file the agent reads every session. Claude Code already supports this: drop a CLAUDE.md at the root of your repo and it loads on every invocation.

What belongs in it:

• Conventions that cannot be derived from the code. Import style, naming, directory purpose, test layout.
• Decisions that outlive a PR. "We chose MVCC-aware cursors because the old pool leaked on rollback - do not revert."
• Hidden foot-guns. "sudo systemctl restart nginx loses the active SSE connections - use reload instead."

What does not belong: anything you can find with grep. The agent is already good at searching code. CLAUDE.md is for the things the code cannot tell it.

One trap to avoid: CLAUDE.md becomes stale faster than code. Every time you write something like "the auth middleware is in src/auth/", you are setting up a future bug where someone moves the file and the agent confidently repeats the wrong path. Source of truth is code. CLAUDE.md is for the why, not the where.

Layer 2 - a memory server over MCP

For anything bigger than a few dozen lines of notes, you want a store the agent can query, not just read.

The Model Context Protocol makes this easy. A memory server exposes tools like memory_search, memory_write, memory_recall - the agent calls them during a session, you host the storage wherever makes sense, and the same memory travels across sessions, branches, and machines.

A minimal shape that works:

{
  "id": 1234,
  "title": "Connection pool leak fix - PR #892",
  "content": "Pool leaked on rollback because defer order was wrong. Fix: swap defer cancel() and defer pool.Put(). See pool.go:142.",
  "category": "decision",
  "project_id": "myapp",
  "created_at": "2026-04-14T09:12:03Z",
  "strength": 0.8
}

Three things make this more than a notes file:

1. Semantic search. The agent asks "why does the pool do X?" and gets hits whether the memory said "pool", "connection pool", or "MVCC cursor".
2. Decay. Memories you never touch again get weaker over time. Memories you keep recalling get stronger. The agent naturally surfaces what is actually useful, not just what was written most recently.
3. Conflict detection. When a new memory contradicts an old one, you want to know, not silently double-store both.

Layer 3 - session continuity

The last layer is the smallest but the most underrated: remembering what the current thread was trying to do before it got interrupted.

A pattern that works: at the start of every session, the agent reads the last session's summary for this project. At the end of every session, it writes one. That one sentence - "was mid-refactor of auth middleware, tests failing on JWT rotation" - turns "I need to re-explain everything" into "continue where we left off".

You do not need exotic infrastructure for this. A sessions table with summary, open_tasks, and continuation_hints is enough. A 10-line hook at session start reads the latest row; a 10-line hook at session end writes a new one.

Putting the three together

The result, once all three layers are live, is a workflow that feels qualitatively different:

• You open a new session on a repo you have not touched in a month
• The agent already knows the conventions (CLAUDE.md)
• It already knows the decisions and why they were made (memory server)
• It already knows what you were trying to do last time (session continuity)
• You skip the 10-minute warm-up and go straight to the work

The upfront cost is modest - maybe a weekend to set up a memory server, an hour to write the hooks, ten minutes to fill out CLAUDE.md. The payoff compounds every session after that.

What EON brings

EON is our productised version of this pattern. It is an MCP memory server with built-in bi-temporal facts (observed-at / valid-from / valid-to, so invalidated facts stop being surfaced), conflict detection, quality tiers, and X-Ethics scoring on every write. Browse the benchmark or read the docs.

If you would rather roll your own, that is genuinely fine - the pattern above is the important part. The only thing we really recommend is: do not skip layer 3. Session continuity is cheap to build and the return per line of code is absurd.

Writing on memory, agents, and X-aligned tooling. Read the docs or compare approaches.