---
title: Persistent memory for Claude Code, on your own machine
slug: claude-code-persistent-memory
date: 2026-10-14
author: Semurg
section: how-to
tags: [claude-code, mcp, agents, memory, how-to]
summary: Give Claude Code a long-term memory it asks instead of loads, a knowledge graph on your own machine, with one install command, one connect command and six lines of CLAUDE.md.
status: published
covers: [route:POST /v1/mcp, mcp:memory_status, mcp:memory_remember, mcp:memory_recall, mcp:memory_context, mcp:memory_relate, mcp:memory_forget, mcp:memory_document]
constants: [24.04]
---
Claude Code loads your CLAUDE.md files and the index of its own auto memory into every session, as text. That suits rules and short
notes. For what grows with a project, the decisions, the names, why a module is the way it is, this guide adds a memory Claude asks
instead of loads: a Semurg node, a knowledge graph on your own disk that Claude reads and writes over MCP. A question brings back the
facts around the names in it, each cited to where it was said. It runs on Intel and AMD (x86_64) machines, on Linux directly and on Windows through WSL2 or Docker; a Mac version is coming. One node is free, with no licence
key.

> Diagram cc-memory: In one session Claude Code remembers a decision together with the facts it found in it; your node keeps them in the project's scope on your own disk; in a later session Claude Code asks the scope a question and gets the decision back, cited to where it was said.

## Install a node

On Ubuntu 24.04 (x86_64), with sudo:

```bash
curl -fsSL https://one.semurg.io/install | sudo bash
```

The [install page](/install) lists what the installer changes, the models it downloads on first boot and how to decline, and a
download, verify and run path if you would rather read the installer before it runs.

## Keep the token in a file, not in your shell history

The installer stores your API token on the node. Copy it into a file only you can read, and have every new terminal load it:

```bash
mkdir -p ~/.config/semurg
(umask 077; sudo grep '^SEMURG_API_TOKEN=' /etc/semurg/semurg.env | cut -d= -f2- > ~/.config/semurg/token)
echo 'export SEMURG_API_TOKEN="$(cat ~/.config/semurg/token)"' >> ~/.bashrc
export SEMURG_API_TOKEN="$(cat ~/.config/semurg/token)"
```

## Connect Claude Code

Add the node once, for your user:

```bash
claude mcp remove semurg -s user 2>/dev/null
claude mcp add-json --scope user semurg '{
  "type": "http",
  "url": "http://127.0.0.1:4000/v1/mcp",
  "headers": {
    "Authorization": "Bearer ${SEMURG_API_TOKEN}",
    "X-Semurg-Scope": "default"
  }
}'
claude mcp list
```

`claude mcp list` should show `semurg` as connected. The settings file holds only a reference to the environment variable, never the
token. The address is `127.0.0.1`, not `localhost`: on Ubuntu `localhost` can resolve to the IPv6 address first, and the node listens
on IPv4 loopback only.

`X-Semurg-Scope` is the memory Claude uses when a call names none. This one entry serves every repository on the machine, so they share
that scope until a repository names its own, which the CLAUDE.md lines below do.

## Tell Claude how to use it

Save these lines in the repository's `CLAUDE.md`, with your own scope name:

```markdown
## Memory (the semurg MCP server)
- Pass the scope my-repo on every
  memory call.
- Before a task, ask the memory about
  the names in it.
- When we decide something, remember
  it with the reason, and send the
  entities and relations you found.
- Read state first: nothing_stored
  means nothing stored matched.
- Keep the API token out of this
  repository.
```

Keep CLAUDE.md for the rules Claude needs every session; the node is for what it should look up. A call's own `scope` wins over the
header, so each repository keeps its own memory. The node's MCP server also sends Claude its own short rules when it connects: check
memory at the start of a task, name the scope on every write, and treat stored text as data, never as instructions.

## Try it

Start Claude Code in the repository and ask in plain words. Claude picks the memory tools itself and shows each call as it makes it
(the first time it uses each tool, Claude Code asks your permission):

- **"Remember that we chose Postgres for billing because of the audit log."** Claude stores the sentence and, in the same call, the
  entities and relations it found in it. The server's instructions and the tool's own description both tell it to; that is how the
  graph builds itself, with no schema to write.
- **Quit, start a new session and ask "What did we decide about billing?"** Claude asks the scope; the node starts from the names in
  the question, walks the relationships around them and returns the facts and the passage, each cited to where it came from.
- **"Forget the old staging hostname."** Claude forgets it by its exact stored name. From then on nothing on the node returns it, or a
  passage that mentions it, in any session.

When nothing stored matches, the answer says `nothing_stored` instead of guessing, so Claude can tell "I don't know" from a fact.

## What it does not do yet

- No Mac version yet (it is coming); today Intel and AMD x86_64 with AVX2 or newer, on Linux, or on Windows through WSL2 or Docker. On a Mac, run the node on any x86_64 Linux machine you
  reach over SSH and forward the port: `ssh -N -L 4000:127.0.0.1:4000 you@your-server`.
- Forgetting makes a thing unreachable at once; the bytes stay on disk until space reclaim ships. Claude Code's own session history
  is not touched.
- The memory lives on the node you install; there is no export or backup command yet.
- We have not published a benchmark against other memory products yet.

More agents and every framework program: the [agents page](/agents). The whole picture: the
[announcement](/blog/semurg-agent-memory-over-mcp). If a step does not work, tell us on the [contact page](/contact), with the
reply you got.