Metadata-Version: 2.4
Name: semurg
Version: 0.1.0
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.

## 1. Start a node

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

```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
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` and `delete_user`, over HTTP. The same seven tools are served
over MCP for agent frameworks: see [one.semurg.io/agents](https://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.
