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.

1. Start a node

With Docker on an Intel or AMD x86_64 machine (Linux, or Windows with Docker Desktop or WSL2):

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

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.

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.