memmesh-migrate
Move an existing memory setup onto MemMesh with a reviewable, reversible plan.
Canonical sources (fetch first)
Step 1 — audit the incumbent
Detect what's in use and record .memmesh-migration/audit.md:
- Vendor & SDK (Mem0
MemoryClient / Memory, Zep, Letta, LangChain memory,
bare Qdrant/pgvector, …).
- Call sites — every
add / search / get_all / update / delete.
- Scoping — how
user_id / agent_id / run_id / session map today.
- Data volume — roughly how many memories, and where they live.
Step 2 — API mapping (cite in the plan)
| Incumbent (e.g. Mem0) |
MemMesh equivalent |
Notes |
client.add(text, user_id=…) |
memory.observe({ text, userId }) |
MemMesh's engine decides what to save — you can stop pre-filtering. |
client.search(q, user_id=…) |
memory.search({ query, userId }) |
Same shape; MemMesh adds scope hierarchy + status lifecycle. |
client.get_all(user_id=…) |
memory.list({ userId }) |
|
client.update(id, text) |
memory.observe(new) + memory.supersede(oldId, newId) |
Correction keeps provenance instead of destructive overwrite. |
client.delete(id) |
memory.delete({ id }) (soft) / hard:true (GDPR) |
|
| user / agent / run scoping |
userId / agentId / sessionId (+ projectId, platformId) |
6-level hierarchy. |
| (no equivalent) |
lattice.predict / predictTarget, behaviors.discover, context.queryGraph |
This is why you're migrating — calibrated prediction the source can't do. |
Step 3 — data migration
- Export from the incumbent (its export API or a
get_all dump to JSONL).
- Transform each record to a MemMesh
observe (preferred — lets the engine
re-extract and build the graph) OR a memory.save with an explicit id when
you must preserve exact rows.
- Import in batches; keep a checkpoint file so a re-run is idempotent.
- Reconcile — count source vs destination, sample-search for known facts,
write
.memmesh-migration/reconcile.md.
For Local → Hosted: set sync.url in ~/.thinkfleet-memory/config.toml and
let the CRDT-style bi-temporal sync push; or export the SQLite items and observe
them into the hosted tenant. Reconcile the same way.
Step 4 — cutover (gated)
Keep the incumbent behind the old flag; bring MemMesh up behind MEMMESH_ENABLED.
Run both in shadow (dual-write) for a window, compare retrieval quality, then flip
the default. Never hard-delete the source until reconciliation passes.
Step 5 — show the upgrade
After parity, add one prediction call at a real decision point so the user sees
what they gained: a calibrated confidence + provenance + honest abstention that
their previous vendor could not produce. Consider running the benchmark skill to
put numbers on the retrieval-quality / cost delta.
Definition of done
Reconciled counts match, known facts retrievable on MemMesh, dual-write window
clean, and a rollback note (how to fall back to the incumbent) in the plan.
1---2name: memmesh-migrate3description: Migrate an existing memory setup ONTO MemMesh — either from another vendor (Mem0, Zep, Letta/MemGPT, a raw vector store) or from MemMesh Local (SQLite) up to MemMesh Hosted. Audits the current usage, produces a reviewable migration plan (API mapping + data export/import), and executes it on approval. Maps add→observe, search→search, and shows what MemMesh adds that the source lacked (prediction, calibration, bi-temporal graph). TRIGGER when: user says "migrate from mem0", "switch from zep to memmesh", "move my memory to memmesh", "replace mem0 with memmesh", or "move local memmesh to the hosted platform". DO NOT TRIGGER for: a fresh integration with no incumbent (use memmesh-integrate) or general SDK questions (use memmesh-sdk).4license: Apache-2.05---67# memmesh-migrate89Move an existing memory setup onto MemMesh with a reviewable, reversible plan.1011## Canonical sources (fetch first)1213- Docs / API mapping: https://docs.memmesh.ai/llms.txt14- Delegate call-site code to: `memmesh-sdk` (hosted) / `memmesh-cli` (local)1516## Step 1 — audit the incumbent1718Detect what's in use and record `.memmesh-migration/audit.md`:1920- **Vendor & SDK** (Mem0 `MemoryClient` / `Memory`, Zep, Letta, LangChain memory,21 bare Qdrant/pgvector, …).22- **Call sites** — every `add` / `search` / `get_all` / `update` / `delete`.23- **Scoping** — how `user_id` / `agent_id` / `run_id` / `session` map today.24- **Data volume** — roughly how many memories, and where they live.2526## Step 2 — API mapping (cite in the plan)2728| Incumbent (e.g. Mem0) | MemMesh equivalent | Notes |29|---|---|---|30| `client.add(text, user_id=…)` | `memory.observe({ text, userId })` | MemMesh's engine decides what to save — you can stop pre-filtering. |31| `client.search(q, user_id=…)` | `memory.search({ query, userId })` | Same shape; MemMesh adds scope hierarchy + status lifecycle. |32| `client.get_all(user_id=…)` | `memory.list({ userId })` | |33| `client.update(id, text)` | `memory.observe(new)` + `memory.supersede(oldId, newId)` | Correction keeps provenance instead of destructive overwrite. |34| `client.delete(id)` | `memory.delete({ id })` (soft) / `hard:true` (GDPR) | |35| user / agent / run scoping | `userId` / `agentId` / `sessionId` (+ `projectId`, `platformId`) | 6-level hierarchy. |36| *(no equivalent)* | `lattice.predict` / `predictTarget`, `behaviors.discover`, `context.queryGraph` | **This is why you're migrating** — calibrated prediction the source can't do. |3738## Step 3 — data migration39401. **Export** from the incumbent (its export API or a `get_all` dump to JSONL).412. **Transform** each record to a MemMesh `observe` (preferred — lets the engine42 re-extract and build the graph) OR a `memory.save` with an explicit id when43 you must preserve exact rows.443. **Import** in batches; keep a checkpoint file so a re-run is idempotent.454. **Reconcile** — count source vs destination, sample-search for known facts,46 write `.memmesh-migration/reconcile.md`.4748For **Local → Hosted**: set `sync.url` in `~/.thinkfleet-memory/config.toml` and49let the CRDT-style bi-temporal sync push; or export the SQLite items and `observe`50them into the hosted tenant. Reconcile the same way.5152## Step 4 — cutover (gated)5354Keep the incumbent behind the old flag; bring MemMesh up behind `MEMMESH_ENABLED`.55Run both in shadow (dual-write) for a window, compare retrieval quality, then flip56the default. Never hard-delete the source until reconciliation passes.5758## Step 5 — show the upgrade5960After parity, add one prediction call at a real decision point so the user *sees*61what they gained: a calibrated confidence + provenance + honest abstention that62their previous vendor could not produce. Consider running the `benchmark` skill to63put numbers on the retrieval-quality / cost delta.6465## Definition of done6667Reconciled counts match, known facts retrievable on MemMesh, dual-write window68clean, and a rollback note (how to fall back to the incumbent) in the plan.
thinkfleetai