Upgrade to SmartMemory 2.0

What changes when you move to SmartMemory 2.0.0, and the steps to move your code, agents and self-hosted install across.

Not released yet. SmartMemory 2.0.0 has not been released. This page describes the planned upgrade so you can prepare. Behavior is final only when 2.0.0 ships.

SmartMemory 2.0.0 is a normal upgrade, not an opt-in preview. Every caller moves at the same time. It is a major version because some calls change shape and some are removed. Every breaking change is listed on one page: Breaking changes in 2.0.0.

Four changes are planned for 2.1 and are not in 2.0.0: the quick 202 save return, the removal of /memory/ingest/full and /ingest/async/{run_id}, and the revision check on content edits.

Later 2.x releases add features without breaking callers.

Who needs to do something

You use	What you do
The Python or JS SDK	Read the save receipt instead of an id string. See the receipt change.
The REST API directly	Move off the removed routes. In 2.0.0 that is the public `/memory/ingest/structured` route. The quick `202` save return and the removal of `/memory/ingest/full` and `/ingest/async/{run_id}` are planned for 2.1. See the removed routes.
MCP with hooks, prompts or saved agent instructions	Rename six save tools on upgrade day. See the MCP save tools.
The public pipeline-stage calls	Await each stage receipt before the next stage. See the stage chain.
A self-hosted install	Move MongoDB to a single-node replica set. See self-hosted MongoDB.
Only the hosted web app	Nothing in your code to change. First-party clients migrate with the release.

Before you upgrade

Search your code, hooks and prompts for the items in the breaking changes table.
Search for the six old MCP save tool names (memory_add, memory_ingest, memory_ingest_structured, memory_ingest_conversation, memory_ingest_document, memory_distill). They stop working at 2.0.0 with no aliases.
If you call the public /memory/ingest/structured, plan the replacement now, because 2.0.0 removes it with no alias. If you call /memory/ingest/full or /ingest/async/{run_id}, they keep working in 2.0.0. Removing them is planned for 2.1, so you can plan their replacements then.
Self-hosted: back up MongoDB and plan a short window with writers stopped.

What happens to your existing data

Existing items stay. At the cutover every existing item gets a stable current revision and a status you can read. Items with no recorded processing history show the label "legacy processing status unavailable" instead of a guess.
Unfinished background work is drained first. Old save admission is fenced, work already in flight is brought to a recorded outcome, and only then does the new path switch on. Saves keep working. Background processing pauses for a short, bounded time.
Old facts with no stored owner stay hidden. They are not guessed into an owner. Items with no recorded origin stay visible and are treated as legacy.
No automatic re-upload. Obsidian adopts an existing item by id without saving it again. Capture never uploads an unmatched clip on its own.

Retry keys last 30 days

A retry with the same idempotency key always resolves to the original request for 30 days after the server first accepted the key. After that the server rejects the retry with a typed "retry key expired, cannot match" error. It never silently creates a second save.

If you see that error, show the unsent draft to the person and ask whether to save it as new. The first-party clients (Capture, Obsidian, the Python and JS SDKs, local and hosted MCP, Maya) keep the draft and ask.

Self-hosted MongoDB

2.0.0 needs MongoDB running as a single-node replica set so that a save can be admitted in one transaction. 2.0.0 detects a standalone MongoDB at startup and either refuses it or upgrades it.

The change to your database container is small:

mongod starts with --replSet rs0 --bind_ip_all --oplogSize 2048.
One member, set name rs0, on the same data volume. Your data files do not move.
The health check becomes db.hello().isWritablePrimary.
An app connection string with no replica-set options keeps working from inside the container network.
From outside that network, connect with directConnection=true.

Stop everything that writes to MongoDB, take a logical backup with mongodump, then restart with the new flags. A full step-by-step runbook with rollback accompanies the 2.0.0 install docs.

Breaking changes in 2.0.0
The existing Migration and Upgrade page covers earlier renames.