semurg

The Python client for Semurg: memory for AI agents (a knowledge graph and vector search in one engine) that runs on your own hardware. Zero dependencies: it uses only the standard library.

Quick start (needs Docker)

python3 -m venv .venv && . .venv/bin/activate   # Ubuntu 24.04 and Homebrew Python refuse a system-wide pip install
pip install semurg

import semurg

mem = semurg.open()   # starts a local Semurg node with Docker, or reuses the one already running
mem.remember(scope="demo", content="Ada Lovelace works at Acme on the analytics team.")
print(mem.recall(scope="demo", subject="Ada Lovelace"))          # what is stored about one entity, with its source
print(mem.context(scope="demo", query="Where does Ada work?"))  # passages and facts for a question

The first open() downloads the Semurg image; later ones reuse the running node. The node listens on 127.0.0.1 only, keeps its data in a Docker volume (semurg-default-data) and the client reads its API token for you. mem.stop() stops the node and keeps the data; semurg.remove() deletes the node and its data. semurg.open("work") runs a second, separate node.

From a shell, python -m semurg up starts the node and prints export SEMURG_URL=... and export SEMURG_API_TOKEN=... for other tools; python -m semurg down stops it.

Connect to a node you run yourself

1. Start a node

With Docker on an Intel or AMD x86_64 machine (Linux, or Windows through WSL2 with Ubuntu 24.04; Docker Desktop on Windows and Mac is being tested):

docker run -d --name semurg -p 127.0.0.1:4000:4000 \
  --ulimit memlock=-1 --ulimit nofile=1048576:1048576 --security-opt seccomp=unconfined \
  -v semurg-data:/var/lib/semurg one.semurg.io/semurg
until docker logs semurg 2>&1 | grep -q 'Your API token'; do sleep 1; done
export SEMURG_API_TOKEN=$(docker exec semurg cat /var/lib/semurg/.api_token)

Or install a node on Ubuntu 24.04: curl -fsSL https://one.semurg.io/install | sudo bash (what it needs). The first node is free.

2. Install

python3 -m venv .venv && . .venv/bin/activate   # Ubuntu 24.04 and Homebrew Python refuse a system-wide pip install
pip install semurg

3. Remember and recall

import os
from semurg import Client

with Client("http://127.0.0.1:4000", token=os.environ["SEMURG_API_TOKEN"]) as mem:
    mem.remember(scope="demo", content="Ada Lovelace works at Acme on the analytics team.")
    print(mem.recall(scope="demo", subject="Ada Lovelace"))          # what is stored about one entity, with its source
    print(mem.context(scope="demo", query="Where does Ada work?"))  # passages and facts for a question

A scope is a separate, named memory. Send user_id to keep each of your end users' memories apart.

Your agent can also send the entities and relations it found, so they are stored as a graph at once:

mem.remember(
    scope="demo",
    facts={"entities": [{"name": "Acme", "type": "Company"}, {"name": "Dana", "type": "Person"}],
           "relations": [{"source": "Dana", "target": "Acme", "type": "WORKS_AT"}]},
    passages=[{"text": "Dana works at Acme.", "mentions": ["Dana", "Acme"]}],
)

The memory calls

memory_status, remember, recall, context, relate, forget (every form: an entity, a fact, a passage, a source, a whole scope or one attribute) and document, over HTTP, plus delete_user (HTTP only), which deletes one end user's whole memory. Over MCP the node serves the same seven memory tools to agent frameworks: see one.semurg.io/agents.

Load a graph and walk it

Edges are written as storage containers built by semurg.container; an edge's id is its content address, so writing the same edge twice stores it once.

from semurg import container

mem.ingest([container.edge(1, 2), container.edge(2, 3), container.edge(3, 4)])
walk = mem.query("traverse", {"seeds": [1], "hops": 3})
print(walk["result"])   # the nodes reached, the edges walked, and a witness per level

Links

• Developer guide: https://one.semurg.io/develop
• Agent frameworks and MCP: https://one.semurg.io/agents
• Benchmarks: https://one.semurg.io/benchmark

Licence: Apache-2.0 (this client). The Semurg engine is licensed separately; the first node is free.