How to Give Claude Code Persistent Memory (5-Minute Setup)

Claude Code starts every session blank, which means re-explaining the same project facts every morning. This guide gives Claude Code persistent memory in about five minutes: one install, one project key, and a quick verification pass.

Why Claude Code starts every session blank

Open a new terminal, start Claude Code, and the agent knows nothing about yesterday. It does not know that the repo uses pnpm, that migrations run through a custom script, or that the team rejected a library two weeks ago. The context window is the agent's only state, and it rebuilds from scratch on every launch.

That behavior is deliberate, and it usually works in your favor: a fresh window carries no stale assumptions. The cost is repetition. You re-explain the same conventions, the same constraints, and the same decisions, session after session. Compaction sharpens the failure mode: when the window fills, the agent summarizes older content and drops detail, and the summary lives only as long as the session. Fixing Claude Code Context Compaction explains what gets dropped and when.

The cost compounds with more than one agent. Claude Code, Codex, and OpenCode each start blank, so a decision recorded in one session is invisible to the other two unless it lives outside all three.

Persistent memory changes where the durable facts live. Instead of keeping them inside the conversation, you store them in a memory layer the agent can query. The context window becomes working space rather than the only copy, and facts stop expiring with the terminal.

Install the memory plugin for Claude Code

The plugin installs with one command:

npx @audaxic/memory-claude install

It needs a project key — a secret beginning with ak_ — to authorize data-plane requests at https://api.memory.audaxic.com. Create a project in the dashboard, copy the key once, and keep it out of the repository. One key per project is the useful default: your API and your CLI tool should not read each other's facts.

If you would rather install nothing locally, the remote MCP server is the alternative. It runs at https://memory-mcp.audaxic.com/mcp, speaks Streamable HTTP, and authenticates with a Bearer ak_... key. That path works in Claude Desktop and other MCP-compatible clients, and it lets desktop and terminal agents read the same project. The Claude plugin documentation covers both routes.

What Claude Code persistent memory stores

The layer stores facts, not transcripts. Re-importing every conversation would rebuild the context problem one level down; the point is to extract the durable part. Three categories cover most of what is worth keeping:

• Preferences and conventions — package manager, formatter, test and build commands, naming rules, review expectations.
• Project decisions — the library you chose, the approach you rejected, the migration in progress, the API shape under construction.
• Constraints and gotchas — version pins, deploy quirks, files that must not be touched, ordering requirements the code does not make obvious.

Audaxic extracts facts from the messages the agent saves. Counting follows extraction rather than calls: one /add request that extracts five memories counts as five add requests. The fact is the billing unit, which is also why entries stay short. A memory should read like a claim — "integration tests run against the staging database" — not like the paragraph of narrative around it.

What gets injected at session start

At the start of a session, the plugin injects the memories relevant to the current project rather than replaying history. Recall is scoped, and retrieval is metered in groups: the first 10 memories retrieved count as one request, and each additional 10 counts as one more. A focused store retrieves cleanly. A store full of noisy fragments returns more context than the agent needs and consumes the budget the memory layer was supposed to protect.

If the task is a billing change, the useful injection is the package manager, the auth conventions, the pinned SDK version, and the decision to keep monetary amounts in integer cents. Yesterday's debugging narrative is not useful, even though it is recent. Scoping recall to the project and extracting claims instead of transcripts is what keeps the injected set small enough to leave room for the actual task.

Two habits keep recall sharp. Store the conclusion, not the debate that produced it. And keep secrets out of memory entirely — API keys, tokens, and credentials belong in your secret manager, not in a store the agent reads back into a prompt.

Verify recall with search and list

Once Claude Code persistent memory writes to the layer, verify it in two steps. First, know the endpoints you will touch day to day:

Data-plane requests use the project key plus a date-based X-Api-Version header; the current version is 2026-09-25. The quickstart documents the request and response shapes for each endpoint if you want to script the checks.

To confirm the plugin has been writing, list the first page of memories:

curl -s "https://api.memory.audaxic.com/list?limit=20&offset=0" \
  -H "Authorization: Bearer ak_..." \
  -H "X-Api-Version: 2026-09-25"

Then open a fresh session and ask something only a previous session would know: which test command to run, or why a dependency is pinned to an old major version. If the agent answers without opening the repo, recall is working. Two false alarms are worth knowing. An empty list usually means the key points at a different project. Repeated 401s can trip the failed-authentication guard — 100 failed attempts per four hours per IP — after which requests return 429 with a Retry-After header. Waiting out the window is the workaround; fixing the key is the fix.

Memory survives compaction, /clear, and new terminals

Because memories live in the layer rather than the transcript, the usual resets do not remove them. Compaction rewrites the context window. /clear empties it. A new terminal starts a new session. The stored facts remain queryable, and the next session can pull them back in. That is the core promise of Claude Code persistent memory: the session ends, the facts do not.

It is also the difference between memory and a longer context. A larger window delays compaction; it does not make facts persistent. Treating a bigger window as a memory strategy means the same facts get summarized away again, just later and at a higher cost per token. The two mechanisms solve different problems; RAG vs memory layer explains where the boundary sits. The useful position is to have both: a large window for working state, a memory layer for facts that should outlive it. Why your coding agent forgets conventions covers the pattern from the conventions angle.

Storage stays scoped to your organization with namespace-scoped vector search, and customer data is never used for training. Servers are located in the US and EU. When a stored fact goes stale, correct it instead of working around it: PUT /update changes an entry, DELETE /delete/{memory_id} removes one, and DELETE /delete clears the scope. A store you can edit is a store you keep trusting.

Import past sessions and keep one shared layer

The plugin collects from the moment you install it, which leaves everything before that unindexed. The importer covers the gap. It reads past Claude Code, Codex, and OpenCode conversations and loads them with their correct timestamps, so older decisions do not appear newer than they are:

npm install -g @audaxic/memory-import

Timestamps matter: when two memories conflict, recency often decides which one is right — last week's decision should beat last quarter's. Import once, then let the plugin keep the store current. The full workflow is documented in Import Past Conversations: Claude Code, Codex, OpenCode to Memory.

Cost is the other thing worth checking before you install. Hobby is $0/month with 10,000 adds, 1,000 retrieves, unlimited projects, and graph memory included — no credit card required. Starter is $12/month for 50,000 adds and 5,000 retrieves, and Growth is $50/month for 200,000 adds and 20,000 retrieves. Paid plans bill a flat monthly rate with no per-token fees and no overages, so a heavy week does not change the invoice. Graph memory is included on every plan, Hobby through Enterprise.

The installation takes minutes. The habit that makes it pay off is deciding, as you work, which facts are worth keeping — and correcting the ones that go stale.

FAQ

Written by Efe — Sep 25, 2026 · More articles · X @AudaxicTech