semurg-mcp

<!-- Generated from the Semurg source of release r11.88.20261014.06756f3. The canonical, always-current copy is https://one.semurg.io/llms.txt -->
# 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, on Linux directly, or on Windows through WSL2 or Docker. There is no Mac or ARM build yet (a Mac version is coming); on a Mac, run the node on a Linux machine you can reach. 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 prints the node's API token. 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=<the API token your node printed at install>
    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.87.20261014.d451f9b: 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) or with the Docker image; 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 <token>, 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 <token>" }
        }
      }
    }

Results pending. Any other MCP client: streamable HTTP at POST /v1/mcp on your node, the header Authorization: Bearer <token>, 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 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, as mem0's user_id; 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. `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 (content-addressed; 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.
- 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", or a label that names more than 8 documents (a file stored as many passages) keeps its own source (the reply's source_label_state says which: attached, new_source, dated_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, as mem0's user_id; a per-user token stays the security boundary. When the connection sets the X-Semurg-User header, that header IS the