> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memanto.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# memanto migrate
> Migrate memories from other providers (Mem0, Letta, Supermemory), an OKF bundle, or Langfuse observability signal into Memanto.
# memanto migrate
Import your memories from another provider into a Memanto agent. Each
subcommand pulls (or loads) the provider's export, maps the source records
onto Memanto memory types, and bulk-writes them into the target agent.
```bash theme={null}
memanto migrate PROVIDER [OPTIONS]
```
**Providers:**
* `mem0` - Migrate a Mem0 account
* `letta` - Migrate Letta archival passages
* `supermemory` - Migrate a Supermemory account
* `okf` - Import an [Open Knowledge Format](/integrations/okf) bundle from disk (see [OKF import](#okf-import) below)
* `langfuse` - Sync [Langfuse](/integrations/langfuse) errors, failed evals, and latency/cost anomalies (see [Langfuse sync](#langfuse-sync) below)
**Options:**
* `--api-key TEXT` - Provider API key (saved to `~/.memanto/.env`). Can also be supplied via the provider's environment variable.
* `-f, --file PATH` - Use an existing provider export JSON instead of pulling a live export.
* `-a, --agent TEXT` - Target Memanto agent ID (defaults to the active agent).
* `--dry-run` - Preview the mapping and savings report without writing anything.
* `--report` - Also write the token/latency/storage savings report on a real run.
The API key for each provider is read from these environment variables when
`--api-key` is not passed:
| Provider | Environment variable |
| ------------- | ------------------------------------------------------------------------------------------------- |
| `mem0` | `MEM0_API_KEY` |
| `letta` | `LETTA_API_KEY` |
| `supermemory` | `SUPERMEMORY_API_KEY` |
| `langfuse` | `LANGFUSE_API_KEY` (as `public_key:secret_key`), or `LANGFUSE_PUBLIC_KEY` + `LANGFUSE_SECRET_KEY` |
If no key is found, you are prompted for one and it is saved to `~/.memanto/.env`.
## How it works
1. **Load** the provider export — either from disk (`--file`) or by pulling a live export with your API key.
2. **Map** the source records onto Memanto memory types.
3. **Import** the mapped memories into the target agent in batches of up to 100.
4. **Report** (optional) — render a token/storage/latency savings report.
Empty source records are skipped. On a real run the target agent must be
resolvable (pass `--agent` or activate one first); a dry run does not need a
target agent.
## Examples
Preview a Mem0 migration without writing anything (also renders the savings report):
```bash theme={null}
memanto migrate mem0 --dry-run
```
Migrate a previously exported file into the active agent:
```bash theme={null}
memanto migrate mem0 --file ./mem0_export.json
```
Migrate Letta into a specific agent and write the savings report:
```bash theme={null}
memanto migrate letta --agent my-agent --report
```
Migrate Supermemory, providing the API key inline:
```bash theme={null}
memanto migrate supermemory --api-key sk-...
```
## OKF import
The `okf` subcommand imports an [Open Knowledge Format](/integrations/okf)
bundle — a local directory of markdown files (or a single `.md` file) — rather
than a hosted provider account. It takes a path instead of an API key, and does
not produce a savings report.
```bash theme={null}
memanto migrate okf PATH [OPTIONS]
```
**Options:**
* `-a, --agent TEXT` - Target Memanto agent ID (defaults to the active agent).
* `--dry-run` - Preview the mapping without writing anything.
**Behavior:**
* Fields that don't map onto a Memanto column are preserved in a bounded
`[Supporting data]` footer, so nothing is lost.
* OKF's free-form `type` is auto-classified when it isn't one of Memanto's 13
types (the original value is kept in the footer).
* When the bundle has a `memories/` folder, import is scoped to it — the
`daily-summaries/`, `sessions/`, and `metrics/` context sections are ignored,
so they are never re-ingested as memories.
Examples:
```bash theme={null}
# Preview the mapping without writing
memanto migrate okf ./okf-bundle --dry-run
# Import a bundle into a specific agent
memanto migrate okf ./okf-bundle --agent my-agent
```
See the [OKF integration guide](/integrations/okf) for the bundle layout, the
field-mapping table, and round-trip behavior.
## Langfuse sync
The `langfuse` subcommand is different from the others: it is a **repeatable
sync**, not a one-shot import. Observability signal — errored spans, failed
evaluations, latency and cost anomalies — is grouped into **one memory per
error signature** rather than one per occurrence, and a ledger makes re-running
safe.
```bash theme={null}
memanto migrate langfuse [OPTIONS]
```
**Options:**
* `--discover` - Report this project's score names, latency/cost spread, and error labels. Writes nothing.
* `--save` - Store the supplied capture settings for this Langfuse project.
* `-c, --capture TEXT` - What to capture; repeatable or comma-separated: `errors`, `low-score`, `slow`, `costly`, `success`. Default `errors`.
* `--score-fail TEXT` - Rule marking a score as a failure; repeatable. e.g. `'correctness<0.7'`.
* `--score-pass TEXT` - Rule marking a score as a success; repeatable.
* `--latency-ms FLOAT` - Fixed latency budget in ms.
* `--latency-percentile FLOAT` - Latency budget as a percentile of each operation's own traffic (e.g. `95`).
* `--cost-usd FLOAT` - Fixed cost budget in USD.
* `--cost-percentile FLOAT` - Cost budget as a percentile of each operation's own traffic.
* `--group-by TEXT` - Group on a stable field instead of the error message, e.g. `metadata.error_code`.
* `--since-days INTEGER` - Look back this many days. Defaults to the last sync time, or 7 days on a first run.
* `--host TEXT` - Langfuse base URL (`LANGFUSE_HOST`). Default `https://cloud.langfuse.com`.
* `--api-key TEXT` - Langfuse keys as `'public_key:secret_key'` (`LANGFUSE_API_KEY`). The vendor-native `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` pair is also accepted.
* `-a, --agent TEXT` - Target Memanto agent ID (defaults to the active agent).
* `-f, --file PATH` - Replay an existing Langfuse export JSON.
* `--dry-run` - Preview the grouping and the write/update plan without writing.
Langfuse Cloud is **regional** and keys are not valid across regions. If your
project is on US, pass `--host https://us.cloud.langfuse.com` once (it is
remembered) or set `LANGFUSE_HOST`. A region mismatch appears as
`401 Invalid credentials`.
**Only `errors` works with no configuration** — `level` is the one field every
Langfuse project populates the same way. Score names, their value ranges, and
what counts as slow or expensive are project-specific, so those modes stay
inert until you supply a rule or a budget, and the run tells you so:
```
! 'slow' captured nothing: no latency budget set — use --latency-ms for a
fixed budget, or --latency-percentile 95 to calibrate from your own traffic
```
Start with discovery:
```bash theme={null}
memanto migrate langfuse --discover
```
```
Name Type Count Observed Suggested rule
rating NUMERIC 60 1.0 … 5.0 --score-fail 'rating<3.4'
user-thumbs BOOLEAN 3 0.0 … 1.0 --score-fail 'user-thumbs=false'
Operation Count p50 ms p95 ms p99 ms cost p95
generate-response 300 2000 2000 40000 $0.002409
```
Then configure and sync:
```bash theme={null}
# Save what you want captured for this project
memanto migrate langfuse --capture errors,slow --latency-percentile 95 --save
# Preview, then sync
memanto migrate langfuse --dry-run
memanto migrate langfuse
```
Running the sync again reports `New: 0 · Unchanged: N` — nothing is duplicated.
A recurring failure is **updated in place** with its new occurrence count.
**Settings and state:**
* `~/.memanto/migrate/langfuse/config.json` — capture settings, per Langfuse project (written by `--save` or the UI tile).
* `~/.memanto/migrate/langfuse/state.json` — the sync ledger, scoped by Langfuse project **and** destination agent.
The [`langfuse-memanto`](/integrations/langfuse) SDK shares both files, so live
capture from your app and this sync compose without duplicating.
See the [Langfuse integration guide](/integrations/langfuse) for capture modes,
score-rule syntax, and the live SDK handler.
## Output
Results are written to a timestamped run directory under
`~/.memanto/migrate///`, containing:
* `mapped_preview.json` - the mapped Memanto payloads (always written, so a dry run is fully inspectable).
* `migrate-report.md` - the savings report (written on a dry run, or on a real run with `--report`).
The command also prints a summary panel with the source record count, the
number of mapped memories, a per-type breakdown, and — on a real run — the
imported / failed / batch counts and the target agent.
**Notes:**
* The savings report includes a short LLM-written narrative generated through the active agent. If no agent is active, the narrative is skipped (the rest of the report is still produced).
* Migrating into Memanto uses the same batch import as [`memanto remember --batch`](/cli/data/remember).
* `okf` and `langfuse` produce no savings report — one is a local file format, the other an observability backend, so neither is a memory store to benchmark against. `langfuse` additionally writes `config.json` and `state.json` beside its run directories, and its summary panel reports **new / changed / unchanged** rather than imported / skipped.