# Migrate from Zep

Mapping Zep concepts to SurrealDB Agent Memory's unified graph.

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

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

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

## Further reading

- [REST API](/docs/agent-memory/reference/rest-api.md)
- [Eight pillars](/docs/agent-memory/architecture/eight-pillars-and-categories.md)
- [Unified substrate](/docs/agent-memory/mental-model/two-layer-architecture.md)