Semurg agent memory

Semurg

The memory layer for AI agents: knowledge graph, vectors and graph RAG on one engine, written from scratch. Run it on your own hardware. This file is for coding agents: how to install a node, how to connect a coding agent, the memory tools an agent calls over MCP or HTTP, the same calls in each client, what Semurg publishes, and the rules an app built on a node follows. Every command, tool, route and client call named here is read from the source, checked against it before this file is published, and the commands are run against each published release.

Install a node

Before you install: Semurg runs on Intel and AMD x86_64 processors with AVX2 or newer, with 2 CPU threads and 4 GB of memory or more: on Ubuntu 24.04 with the installer, and on any other x86_64 Linux in Docker (the installer stops on another system and prints the docker run line that works there). There is no Mac, Windows or ARM build yet (they are coming, built from the same release); from a Mac or Windows machine, run the node on a Linux machine you can reach. WSL2 and Docker Desktop on Windows are being tested. The installer needs root.

One command, on a Linux machine you control. The first line shows the script without running it.

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

The installer ends with a SUCCESS banner that says where the node's API token is stored and the one command that reads it; the token itself is never printed, so it stays out of terminal logs and agent transcripts. The data directory must sit on a local ext4 or xfs filesystem; the installer checks this and stops if it does not. One node needs no licence key.

Put the token in your shell, then prove the gate is on (401 without the token, 200 with it):

TOKEN=$(sudo grep '^SEMURG_API_TOKEN=' /etc/semurg/semurg.env | cut -d= -f2-) curl -si http://127.0.0.1:4000/v1/whoami | head -1 curl -si -H "Authorization: Bearer $TOKEN" http://127.0.0.1:4000/v1/whoami | head -1

Connect a coding agent

Claude Code: one user-scope entry, written by Claude Code's own command. Run it in the shell that starts Claude Code; the entry holds only a reference to the variable, never the token itself. The address is the one a fresh node serves; behind your own TLS proxy use its https address.

export SEMURG_API_TOKEN= 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 Code reads the token from the SEMURG_API_TOKEN environment variable when it starts

Connected on release r11.142.20261030.e037138: Claude Code's own client listed every memory tool that release served.

Claude Desktop: it runs on macOS and Windows and Semurg runs on Linux x86_64, so the node is reached at 127.0.0.1:4000 one of two ways: on a Windows machine, run the node on the same machine under WSL2 (Ubuntu 24.04), which is being tested, as is Docker Desktop on Windows; otherwise run it on a Linux machine and forward its port to the desktop with ssh -N -L 4000:127.0.0.1:4000 you@your-node, so the token never crosses the network over plain HTTP. A remote node over HTTPS with sign-in (OAuth) is not covered here yet. Claude Desktop starts only local (stdio) MCP servers, so the mcp-remote bridge, run by npx (it needs Node.js), carries it to the node's streamable HTTP door. Put this in claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/; Windows: %APPDATA%\Claude\), put your token in place of , and restart Claude Desktop. The file then holds the token: keep it private.

{ "mcpServers": { "semurg": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:4000/v1/mcp", "--header", "Authorization:${SEMURG_AUTH}", "--header", "X-Semurg-Scope:default"], "env": { "SEMURG_AUTH": "Bearer " } } } }

Results pending. Any other MCP client: streamable HTTP at POST /v1/mcp on your node, the header Authorization: Bearer , and an optional X-Semurg-Scope header. Each agent's own configuration: https://one.semurg.io/agents

Agent memory over MCP

Endpoint: POST /v1/mcp on your node. It speaks streamable HTTP and takes the node's API token as a bearer token. An optional X-Semurg-Scope header sets the default scope for the connection.

Every tool except comms_bind_address, comms_send, comms_inbox, comms_thread and comms_read takes scope: Namespace. Agents on the same node using the same scope share these facts; another scope is private. Optional when the connection sets the X-Semurg-Scope header.

memory_status (read-only)

Report whether shared memory is on for this node and which of YOUR scopes hold facts. Pass scope to also get that scope's ontology summary: how many entity types and relation types it holds, its biggest classes (up to 50) with their member count (members_bound says "exact": the live members, measured to drop by one with every forget, also over 64 members) on their members, the relation types it already uses (reuse them spelled EXACTLY as listed in spellings), and the name-merge mode. Read-only. Call it first when another memory call fails.

Parameters:

• user_id (string): Optional END USER inside your key (one app, many end users): every scope you name is then that end user's own, and two end users never meet. App-level separation; a per-user token stays the security boundary. When the connection sets the X-Semurg-User header, that header IS the end user and a different user_id is refused. No ':', at most 256 bytes.

memory_remember (writes)

Store memory for agents. YOU ARE THE EXTRACTOR: whenever you store text (content or messages), send the entities and relations you found in it as facts in the SAME call. They are stored at once, and you extract better and faster than this node's local model, which reads text sent WITHOUT facts only in the background and slowly on a CPU (or not at all when none is installed). content: raw text (a note, a document), stored NOW: it is cut into passages of about 100-200 words at sentence ends, and each passage is linked to the entities it names that are already stored or that you send beside it as facts; the reply says extraction (agent_facts when you sent facts, known_names_only when not), how many passages no entity reaches (unlinked_passages) and meaning: queued when this node has an embedding model (the passages' vectors are written right behind the reply; memory_status says when), not_armed when it has none (the passages are embedded when one is installed). Without facts, the node's installed extraction model reads the stored text AFTER the reply and adds its entities, types and relations, each relation cited to the passage it was found in: model_extraction says pending (waiting on disk), done (already extracted), failed (a passage failed 3 attempts, named), other_model (extracted by another model), not_installed, not_serving or could_not_judge, by name; with facts no model runs. extract: false stores text you keep only to find again (a session transcript, a log) with no model ever reading it: model_extraction says not_requested. messages: a conversation [{role, content}], stored as one text, one line per turn, never a passage across two turns; otherwise exactly like content. facts: entities [{name, type}] and relations [{source, target, type}] that you extract yourself, for example type WORKS_AT; types are classes, matched letter case aside. passages: text to find again, [{text, mentions, key?}], stored NOW with no model: mentions names the entities the text is about (each is stored under the name as sent, and must appear in the text, letter case aside, or the passage is refused by name), and memory_context returns the passage WHOLE when it reaches one of them. content and passages cannot ride in one call. date (ISO 8601, for example 2026-10-01) is when this was said: it is kept with the call's source and returned with what it sourced. Storing the same thing again with the same date changes nothing (it answers already). Per call: at most 1000 entities and 5000 relations, 1048576 bytes of content, 1000 passages holding 1048576 bytes of text and 1000 mentions in all, each passage at most 65536 bytes; every name, mention and key at most 1024 bytes. source is an optional provenance label returned with the fact when it is recalled. Before you invent a type or a relation, call memory_status with your scope and reuse a class from ontology.top_classes and a relation from ontology.relations, spelled EXACTLY as listed in its spellings (a different spelling is a different relation, and the same fact stored twice). List both ends of every relation in entities in each remember call, including entities you stored earlier.

Parameters:

• content (string): Raw text to remember, stored now and cut into sentence-bounded passages. Send the entities and relations you found in it as facts in the same call.
• date (string): When this was said or true, ISO 8601 (2026-10-01 or 2026-10-01T09:30:00Z). Optional.
• extract (boolean): false: store content or messages and link it to the names already stored, but ask no model to read it (text kept only to find again, such as a session transcript). Default true. Nothing to extract when you send facts.
• facts (object): Entities and the relations between them that YOU extracted from what you are storing: stored at once, no model runs.
• messages (array): A conversation to remember as one text, one line per turn. Not beside content or passages.
• passages (array): Text to find again later, stored now. Each passage names the entities it is about.
• source (string): Optional source label (e.g. a file name). It is shown as the source name in each citation. Facts you send later under the same label (and without a "date") are attached to the document(s) you stored under it, so their citations quote that text; a label nothing was stored under, a call with a "date", a call that changes an attribute's current value, or a label that names more than 8 documents (a file stored as many passages) keeps its own source, named by the label (the reply's source_label_state says which: attached, new_source, dated_own_source, value_changed_own_source, many_documents_not_attached).
• user_id (string): Optional END USER inside your key (one app, many end users): every scope you name is then that end user's own, and two end users never meet. App-level separation; a per-user token stays the security boundary. When the connection sets the X-Semurg-User header, that header IS the end user and a different user_id is refused. No ':', at most 256 bytes.

memory_recall (read-only)

Recall what is stored about ONE entity: finds the entity named subject by its name, exact or a similar spelling or letter case ("paris" finds Paris, "Dan" finds Dana), or one whole word of a longer name ("Priya" finds Priya Raman; small English words such as "the" or "of" never match on their own), walks the graph from it and returns the connected facts in both directions (direction outbound or inbound), each with its citation (citation.source: kind document, or asserted for a fact an agent sent without text; the doc_id of the document it was read from; the name label it was stored under; ingested_at. citation.span: the sentence quoted from that document, start and end in Unicode code points of its full text, checked before it is served, or null with span_state saying why. citation.found_by: how it was found), its source_date when one was stored, and the seed that found it (seed: exact, name or type). Always c