Migrate from Zep

Zep and SurrealDB Agent Memory both target durable agent memory, but SurrealDB Agent Memory uses a single SurrealDB graph, explicit reconciliation, and a focused HTTP surface (/facts, /documents, /query, /chat).

Concept mapping

Zep concept	SurrealDB Agent Memory equivalent	Notes
User	Scope path `user=…`	Scopes are hierarchical path strings
Session	Session + optional `session_id` on `/facts/batch`	Transcript introspection; batch ingest preferred
Memory context	`POST .../context`	Formatted string for prompts
Facts	Entities + attributes + relations	Extracted and reconciled
Zep Graph / knowledge	Documents + extracted graph	One unified graph
Summary	`profile`, `reflect`, consolidation	Reflection is explicit `POST .../reflect`

API mapping

Zep-style action	SurrealDB Agent Memory
Add message to session	`POST /api/v1/{ctx}/facts/batch` with `messages[]`
Search memory	`POST /api/v1/{ctx}/query`
Get memory context string	`POST /api/v1/{ctx}/context`
Add business data	`POST /api/v1/{ctx}/documents` or `/facts` with `infer: "triples"`

Auth header: Authorization: Bearer. Base path: /api/v1/{context_id}/.

SDK sketch

await client.remember_many(
    messages=[{"role": "user", "content": "I was promoted to Head of Platform."}],
    scopes=["org/acme/user/alice"],
)

hits = await client.recall(
    "What is Alice's role?",
    k=10,
    lens=["org/acme/user/alice"],
)

Behavioural differences

Reconciliation - conflicting sources emit uncertainty instead of silent overwrite.
Authoritative vs experiential - source.kind distinguishes document vs turn provenance.
Unified recall - one /query router over facts and passages.

Concept mapping

API mapping

SDK sketch

Behavioural differences

Further reading