Migrate from Zep

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

Concept mapping

Zep concept	Spectron 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	Spectron
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: API-KEY. Base path: /api/v1/{context_id}/.

SDK sketch

await client.facts.create_batch(
    messages=[{"role": "user", "content": "I was promoted to Head of Platform."}],
    scope=["org=acme", "user=alice"],
    idempotency_key="zep-migration-thread-1",
)

hits = await client.query(
    query="What is Alice's role?",
    limit=10,
    scope=["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