A memory your agent keeps. On a machine you run.
Semurg gives an agent a memory that outlives its session. The agent stores facts, relationships and documents; the next session, or another agent on the same node, finds them and sees where each one came from. You install the node in one line. The first node is free, and there is no account.
In three answers
What it is
A memory node you install on your own machine. It keeps entities, the relationships between them, documents and plain text, and it answers with the source of each item.
Why use it
The memory lives on your node, not in one chat window. Every agent that connects to the same node and the same scope reads what the others wrote. A different scope stays private.
What it solves today
Agents that forget between sessions, and memory that has to stay on machines you run. The calls on this page are the ones recorded as run on a fresh node.
How the memory moves
Your first memory in three calls
Plain HTTP and nothing else. Run the calls in order on a Linux machine you control; on an Apple silicon Mac, install first from the Install page. They use
127.0.0.1:4000, the address a fresh node serves on its own machine.
Call 1: install the node and read its token
curl -fsSL https://one.semurg.io/install | sudo bash export SEMURG_API_TOKEN=$(sudo grep ^SEMURG_API_TOKEN= /etc/semurg/semurg.env | cut -d= -f2-) curl -s http://127.0.0.1:4000/api/health
A healthy node answers the health line with this about four to five seconds after it starts, and it kept answering through the first three minutes of a fresh run of the published image. In that first boot it also downloads its embedding model (about 1.5 GB); the meaning search is armed about two minutes after start. The reranker is recorded, and its weights (about 1.2 GB) land only when you install it:
{"ok":true,"version":"0.2.0","service":"semurg"}
The token is read into your shell and is never printed. Wait until the health line answers before the next call. This is the Linux install; a healthy node answers the health line, and if it stays silent for a minute the install has not finished. An Apple silicon Mac has its own one-line install on Install, and Docker is on Develop; both end with the same token and the same calls.
Call 2: remember
curl -sS http://127.0.0.1:4000/v1/memory/remember \
-H "Authorization: Bearer $SEMURG_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"scope":"demo","facts":{"entities":[{"name":"Acme","type":"Company"},{"name":"Dana","type":"Person"}],"relations":[{"source":"Dana","target":"Acme","type":"WORKS_AT"}]},"source":"curl example"}'
Call 3: recall
curl -sS http://127.0.0.1:4000/v1/memory/recall \
-H "Authorization: Bearer $SEMURG_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{"scope":"demo","subject":"Dana"}'
Recall answers with the entity's own facts first, each with its source. The reply also says whether it
answered, found nothing stored (nothing_stored), or could not judge. Use a scope named for your project:
scopes stay private from each other. Both calls were run against a fresh node on the release of 2 November 2026, and each
answer was read back.
Connect your agent over MCP
Point any MCP client at http://127.0.0.1:4000/v1/mcp, with the header
Authorization: Bearer $SEMURG_API_TOKEN and X-Semurg-Scope set to the scope this project uses.
Each config below reads the token from the environment, so no config file holds it.
Connected means the agent's own client listed the node's memory tools, recorded on the release of 2 November 2026. Results pending means we have not yet run that client ourselves.
Claude Code: Connected
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 Code reads the token from SEMURG_API_TOKEN when it starts, so export it first.
OpenAI Codex CLI: Connected
codex mcp add semurg --url http://127.0.0.1:4000/v1/mcp --bearer-token-env-var SEMURG_API_TOKEN
# then, in ~/.codex/config.toml under [mcp_servers.semurg]:
http_headers = { "X-Semurg-Scope" = "default" }
The scope line is the one Codex documents for this; we have not run that line by itself yet.
Cursor: Connected
{
"mcpServers": {
"semurg": {
"url": "http://127.0.0.1:4000/v1/mcp",
"headers": {
"Authorization": "Bearer ${env:SEMURG_API_TOKEN}",
"X-Semurg-Scope": "default"
}
}
}
}
Put it in ~/.cursor/mcp.json, or .cursor/mcp.json inside a project.
Gemini CLI: Connected
gemini mcp add -s user -t http --header 'Authorization: Bearer ${SEMURG_API_TOKEN}' --header 'X-Semurg-Scope: default' semurg http://127.0.0.1:4000/v1/mcp
If gemini mcp add writes the token into ./.gemini/settings.json, keep that file out of version
control. In an untrusted folder Gemini switches off every MCP server; the trust setting is on the Agent memory page.
Also connected: Hermes Agent and OpenClaw (Hermes, OpenClaw), recorded on the release of 2 November 2026. Results pending: Claude Desktop, which needs a local bridge, and ChatGPT as a custom connector, which needs the node reachable over public HTTPS. Their configs and what each needs are on Agent memory.
What the agent can call
- remember: entities, the relationships between them, passages, or plain text, with a source label and a date. Storing the same thing again changes nothing.
- recall: one named entity, its own facts first, each one cited.
- context: a question in plain words, answered from cited items, with a verdict on whether the memory covers it.
- relate and forget: add one typed relationship; forget one thing per call. What is forgotten is unreachable through every door at once.
- document, export and import: a whole document stored as cited passages; a scope out to a .jsonl file and back in.
- Over MCP, recall and context can also read the memory as it was known at a date.
The tools your client lists are the live list. The notes for each client are on Agent memory, and the call shapes an agent needs are in llms.txt.
For an agent working alone
- Read llms.txt for the call shapes, or this page as plain text.
- Run the install line in call 1 on a Linux or Mac machine you control. The first node needs no account and no payment.
- Store with call 2, then recall with call 3. Each reply says what it found, or that it found nothing.
- If your client speaks MCP, connect it with the config for that client above. Plain HTTP reaches the same memory.
- Further nodes are a choice: a yearly seat or a lifetime licence per machine. See Pricing.
Machine-readable
- /llms.txt: the call shapes, the memory routes and the install steps.
- /for-agents.txt: this page as plain text, with the same calls.
- Commands: the command-line surface.
- On your node:
GET http://127.0.0.1:4000/api/health, and the memory routes under/v1/memory/.
What is not ready yet
- The hosted API is not open. Every call on this page goes to a node you run.
- Claude Desktop and ChatGPT (as a custom connector) are results pending: we have not run either one end to end yet.
- Forgotten memory is unreachable at once; erasing its bytes from disk, after a grace period, is not released yet.