How to give Claude Code persistent memory (with MCP)

Claude Code is extraordinary within a session — and amnesiac between sessions. Every time you open a new one, the agent doesn't remember the decisions you made together yesterday, the project's conventions, or the bug you already solved once. This tutorial fixes that in about 10 minutes, using the open MCP protocol and SoluCortex as the memory engine.

What you'll get

By the end, your agent will do this in every session, on its own:

1. At task start: retrieve your project's approved decisions, conventions, risks and architecture, ranked by semantic relevance.
2. During: answer questions like "how do we implement authentication?" by querying memory instead of re-deriving (or inventing).
3. At close: propose what was learned as typed memories, which you approve or reject.

Requirements

• Claude Code installed (Cursor, Claude Desktop or any MCP client also works).
• A SoluCortex account with a project — creating it gives you your API key (scx_…), which is all you need.

Step 1 — Connect the agent (one command)

claude mcp add --transport http solucortex https://mcp.solucortex.ai/mcp \
  --header "Authorization: Bearer scx_your_api_key"

That's it: nothing to install. Your key travels with each request to the hosted server, which never stores it. Prefer running the server locally? There's an alternative at the end.

Restart Claude Code and check with /mcp: you should see solucortex connected with 4 tools.

Step 2 — First test

Ask your agent:

Recall this project's context before starting.

It should call solucortex_recall and return the project's memories. A new project will be nearly empty — that's normal: memory is built by working.

Step 3 — The loop that changes everything

Here's the neat part: the MCP server hands your agent the full methodology in the handshake (as protocol instructions), so there's nothing else to configure — no rules files, no special prompts. The agent knows to:

• solucortex_recall at the start of each task, before touching code.
• solucortex_search for specific questions mid-task.
• solucortex_remember at close, when something is worth keeping.

Each memory carries a type (decision, convention, risk, bug history, tech debt, sensitive module, learning, architecture, external integration) and an importance (1-10). Crucially: depending on your project's governance, what the agent proposes can stay pending until you approve it — memory gets curated, not hoarded.

Step 4 — Work normally and watch

Ship a couple of real tasks. You'll see the pattern: the agent opens by recalling context ("I see you chose pgvector over Pinecone, and the payments module is sensitive…") and closes proposing memories ("saving as decision: webhook retries are idempotent"). The next session — or the next agent, or your teammate — inherits everything.

We build SoluCortex this way: a 40-plus task deliverable was resumed across sessions without re-explaining context once.

What NOT to store

A rule the server also teaches the agent: never secrets. Tokens, passwords or .env values don't go in a memory — record the location and type, never the value.

Alternative: local server (stdio)

If you'd rather run everything on your machine:

claude mcp add solucortex \
  -e SOLUCORTEX_API_KEY=scx_your_api_key \
  -- uvx solucortex-mcp

The connector is open source (MIT) and listed in the official MCP registry.

Next steps

• The full setup guide (Claude Desktop, Cursor, Docker, variables).
• The 4-tool reference.
• Teams? Each project gets its own memory and governance — start free.