Metadata-Version: 2.4
Name: semurg
Version: 0.1.3
Summary: Python client for Semurg: memory for AI agents (knowledge graph + vector search) on your own hardware
Author: Semurg
License: Apache-2.0
Project-URL: Homepage, https://one.semurg.io
Project-URL: Documentation, https://one.semurg.io/develop
Project-URL: Agent frameworks, https://one.semurg.io/agents
Keywords: semurg,ai-memory,agent-memory,knowledge-graph,vector-search,graph-rag,mcp,llm
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Database
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# semurg

The Python client for [Semurg](https://one.semurg.io): 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)

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

```python
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):

```sh
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](https://one.semurg.io/install)).
The first node is free.

### 2. Install

```sh
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

```python
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:

```python
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](https://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.

```python
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.
