Persistent memory for Claude Code, across every session.

The short answer

Claude Code has instructions that persist and knowledge that doesn't. CLAUDE.md is reloaded into every session, so your rules survive. Everything the agent worked out during a session — why an approach was rejected, what actually caused a bug, which deployment constraint bit you — lives in the context window and is gone when the session ends or the context is compacted.

Fixing that means putting knowledge somewhere outside the context window that Claude Code can search on demand. That's what an MCP memory server is for, and Claude Code has first-class support for connecting to one:

claude mcp add --transport http knownbase https://knownbase.dev/mcp

The first tool call opens a browser to sign in. After that, Claude Code can write what it learns and read it back in any later session.

Why Claude Code forgets

It's worth being precise about this, because "the AI has no memory" is too coarse to act on. There are three separate mechanisms, and they fail differently.

1. The session boundary

A conversation is the unit of memory. Close the terminal, start a new task, come back tomorrow — that's a new context, populated only by your project files, your CLAUDE.md, and whatever you type. Two hours of reasoning from yesterday isn't in there, because nothing wrote it anywhere durable.

2. Context compaction

Long sessions don't end cleanly; they get compacted. When the context window fills, earlier turns are summarized down to make room. Summarization is lossy by construction, and it's lossy in the worst possible direction for engineering work: it keeps the shape of the conversation and drops the specifics. "We investigated the flaky test" survives; "the flaky test was parseDate treating a naive timestamp as UTC" often doesn't. More on exactly what compaction drops.

3. The instruction file ceiling

The obvious fix is to write everything into CLAUDE.md. That works for a while and then stops, because CLAUDE.md is loaded in full, on every turn. A 200-line file is cheap. A 2,000-line file costs real context on every message, crowds out the code the agent needs to read, and buries the three lines that matter for today's task in 1,997 that don't. Instruction files scale by staying small; project knowledge only ever grows. The full comparison.

What actually persists today

These aren't competing. The working setup is a short CLAUDE.md for rules plus a memory server for everything that accumulates.

A concrete example

A real one, of the shape that costs the most time. Monday, Claude Code spends forty minutes chasing an intermittent failure in a payment reconciliation job. The conclusion: the upstream provider returns timestamps without a timezone offset, and the parser assumes UTC, so every transaction between midnight and 05:00 local reconciles against the wrong day.

Without persistent memory: the fix lands in a commit titled "fix reconciliation date handling". Three weeks later a different agent (or the same one, new session) touches the same parser for an unrelated reason, sees the explicit timezone handling, reads it as redundant defensive code, and simplifies it away. The bug returns. Nobody connects the two.

With persistent memory: at the end of Monday's session the agent writes a note:

upsert_note({
  project: "payments-api",
  title: "Provider timestamps have no timezone offset",
  tags: ["debugging", "constraint", "reconciliation"],
  body: "The settlement feed returns naive timestamps in provider-local time.\n" +
        "parseSettlementDate() must apply the provider's offset explicitly.\n" +
        "Symptom when this is wrong: transactions between 00:00-05:00 local\n" +
        "reconcile against the previous day.\n" +
        "Do not 'simplify' the offset handling in src/settlement/parse.js:88."
})

Three weeks later, the agent about to touch that file runs search_notes({ project: "payments-api", query: "settlement parse timezone" }), gets the note back, and leaves the offset handling alone. The forty minutes were spent once.

That's the whole mechanism. It isn't clever; it's just durable.

Setting it up

1. Create a free workspace — 3 projects, 300 notes, 2 MCP keys, no card.
2. Connect Claude Code:

   claude mcp add --transport http knownbase https://knownbase.dev/mcp

3. Run /mcp in Claude Code to confirm the server is listed, then make any request that needs it — the first tool call opens a browser for sign-in.
4. Tell Claude Code when to use it. One paragraph in your CLAUDE.md is enough:

   ## Project memory
   
   This project has persistent memory via the `knownbase` MCP server.
   
   - At the start of a task, `search_notes` for prior decisions, constraints,
     and debugging findings related to what you're about to touch.
   - When you make an architecture decision, find a non-obvious root cause,
     hit an environment constraint, or rule out an approach, save it with
     `upsert_note` under project "<your-project>".
   - Keep code in git. Store the reasoning here.

Full details, including the API-key path for clients that can't do OAuth, are on the Claude Code integration page and in the docs.

The tools Claude Code gets

• search_notes — find notes by query, project, tag, status, or last-modified date. Lean by default (snippets, not full bodies) so a search costs few tokens.
• get_note / get_notes — read one note in full, or up to 50 by id in a single call.
• upsert_note — create or update. Updates are partial, so fixing one field can't wipe the rest.
• list_projects — every project with note counts by status.
• list_note_revisions / get_note_revision — how a note changed over time.
• delete_note — soft delete, restorable from the dashboard.

When you don't need this

Worth stating plainly, because the honest answer sometimes is "not yet". If your project is a few weeks old, fits comfortably in a short CLAUDE.md, and you're the only person working on it with one tool, built-in memory is probably fine. Persistent project memory starts paying for itself when at least one of these is true:

• The project has been going long enough that you've forgotten your own decisions.
• You've watched an agent re-diagnose something you already solved.
• Your CLAUDE.md is past a few hundred lines and still growing.
• More than one agent or more than one person works on the codebase.
• Sessions routinely run long enough to compact.

Keep reading

• Claude Code keeps forgetting your project? How to add persistent memory
• How to make Claude Code remember project context across sessions
• Claude Code context compaction: what gets lost, and how to keep it
• CLAUDE.md vs persistent project memory: when you need both
• How to share project context between Claude Code and Codex
• MCP memory servers: the category explained

FAQ

Does Claude Code have memory between sessions?

Partly. Claude Code loads CLAUDE.md into every session and can record short memories, so standing instructions and a handful of facts do carry over. What does not carry over is the bulk of what a session discovers: the reasoning behind a decision, the root cause of a bug, the approach that failed. That lives in the conversation and ends with it. A persistent memory server gives Claude Code somewhere durable and searchable to put it.

Why does Claude Code forget my project architecture?

It never stored it. Everything Claude Code knows about your architecture came from reading files and from what you told it during that session. When the session ends, or when the context is compacted to make room, that understanding is gone and has to be rebuilt from the same files next time.

Is CLAUDE.md enough on its own?

For rules, yes. CLAUDE.md is the right home for standing instructions: coding conventions, commands, what not to touch. It is the wrong home for accumulated knowledge, because it is loaded in full on every single turn — so it has to stay short, and short is the opposite of what a two-year-old project's knowledge looks like. Keep CLAUDE.md for rules and put the growing pile somewhere Claude Code can search.

How do I add persistent memory to Claude Code?

Run: claude mcp add --transport http knownbase https://knownbase.dev/mcp. Claude Code opens a browser for OAuth sign-in on the first tool call, then has search_notes, get_note and upsert_note available. No API key to paste and no local server to run.

Does this work with Claude Desktop and Claude.ai too?

Yes. Any MCP client can connect to the same workspace. In Claude Desktop or Claude.ai, add a custom connector pointing at https://knownbase.dev/mcp. The notes Claude Code writes are the same notes Claude Desktop reads.

Where is my project data stored?

In your own workspace on Knownbase, isolated from every other tenant. API keys can be made read-only or restricted to a single project, and your content is never used to train models. You can export everything as a ZIP or delete it at any time.