Getting Started

Migrating from Zep

Zep organises memory around sessions holding messages. MemorySync separates who a memory belongs to from which conversation produced it, which is the one idea worth understanding before you start.

The one difference that matters

Key differences

Zep	MemorySync	What it means for your code
`session.create()` before writing	No setup call	Scope is a header on the write itself.
`memory.add(session_id, ...)`	`POST /memory/add`	Send the statement worth keeping, not every turn.
`memory.search(session_id, {text, limit})`	`POST /memory/query` with `query` and `k`	Reads span the end user, and `session_id` narrows when you want that.
`memory.get(session_id)`	`GET /memory/export`	Returns records readable in the current scope.
Messages with roles	Records with `source` and `metadata`	Role becomes descriptive context you can filter on.

Install the client

python -m pip install memorysync==1.1.1

import os
from memorysync import MemorySyncClient

client = MemorySyncClient(
    api_key=os.environ["MEMORYSYNC_API_KEY"],
    base_url="https://api.memorysync.io",
    project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
    end_user_id="user-123",
)

Operation by operation

session = client.session.create(
    session_id="thread_42",
    user_id="user_123",
)

client.memory.add("thread_42", {
    "content": "I love Python",
    "role": "user",
})

results = client.memory.search("thread_42", {
    "text": "programming",
    "limit": 3,
})

Move your existing sessions

1List the sessions you want to bring across, and read each session’s user id. That id becomes the end-user scope.
2Filter the messages down to statements worth remembering. A full transcript imported turn by turn retrieves poorly, because most turns are not durable facts.
3Import per session, carrying the role in metadata and the session id in session_id.
4Check the per-item results, then query as one migrated user to confirm the scope is right.

import os
from memorysync import MemorySyncClient

# messages and user_id come from your Zep export
def import_session(session_id: str, user_id: str, messages: list[dict]) -> None:
    client = MemorySyncClient(
        api_key=os.environ["MEMORYSYNC_API_KEY"],
        base_url="https://api.memorysync.io",
        project_id=os.environ["MEMORYSYNC_PROJECT_ID"],
        end_user_id=user_id,
    )

    items = [
        {
            "text": message["content"],
            "source": "import",
            "metadata": {"role": message.get("role"), "zep_uuid": message.get("uuid")},
        }
        for message in messages
        if message.get("content", "").strip()
    ]

    result = client.bulk_add(items, deduplicate=True)
    print(session_id, result.created, "created,", result.skipped, "skipped")

Next steps

Memory Fundamentals

What makes a record retrieve well.

Scopes & End Users

What a session id splits into.

Bulk Add

Per-item outcomes and the 207 contract.

Plans

Current limits and what each plan includes.

← Previous

From Supermemory

Memory Fundamentals