Agent history import

Agent history import brings supported local conversations from Claude Code, Codex, or OpenClaw into a MemoryRouter vault. Your agent reads authorized local history and produces a message-only JSONL extract. The connector CLI validates that file, previews the destination and price, requests approval, and uploads resumable batches.

This separates two jobs: the model prepares the extract, while deterministic software handles record identity, approval, upload, and the receipt. It is not the same as installing automatic memory hooks, and it is not the official ChatGPT archive importer.

Prerequisites

• A MemoryRouter account and a writable Memory Key.
• The host agent and its MemoryRouter connector installed and configured on the machine holding the source history.
• Read access to the local conversation files you want to import, and permission to copy their content into the selected vault.
• A local output path outside your Git repository for the extract. It contains conversation plaintext and must stay private.

Complete the appropriate connector setup first:

Installing or enabling a connector does not by itself import all existing history. Use the explicit workflow below.

1. Get instructions for your host

Run one of these on the source machine:

npx -y memoryrouter-claude import --instructions
npx -y memoryrouter-codex import --instructions
openclaw mr import --instructions

The command fetches the server-authored extraction prompt for that platform. Give it to the corresponding agent in a local session. Tell the agent which history locations it is authorized to read and which conversations or date ranges to exclude.

The prompt directs the agent to discover supported history files, preserve original message identifiers and timestamps, keep visible user/final assistant text, and omit tool chatter, thinking, injected memory, credentials, and duplicate or partial records.

Review the extract before uploading. The agent's access to local files is not proof that you intended to import all of them, and model-authored extraction is not a completeness guarantee.

Optional headless extraction

Claude Code and Codex can execute the extraction prompt themselves:

npx -y memoryrouter-claude import --instructions --run
npx -y memoryrouter-codex import --instructions --run

This launches the host CLI's headless mode and can consume that host's inference allowance. Inspect the instructions and authorize the local read scope first. OpenClaw uses the prompt in the active agent session rather than this headless flag.

2. Inspect the JSONL format

Each line is exactly one supported message, not a summary. A synthetic Claude Code line looks like:

{"external_id":"claude-code:demo-session:message-1:v1","content":"For the fictional Cedar launch, the review phrase is copper-orbit-482. This is test data.","timestamp":1788912000000,"role":"user"}

Valid platform prefixes are claude-code, codex, and openclaw; they must match the uploader. Preserve source IDs across retries. Do not replace real IDs with random values to avoid validation errors. Let the current extraction instructions handle IDs containing reserved separators.

No extra fields are accepted. Real extracts should not contain the synthetic example unless you are deliberately testing with a separate vault.

3. Preview, approve, and upload

Choose the command for the source platform:

npx -y memoryrouter-claude import --file /private/path/extract.jsonl
npx -y memoryrouter-codex import --file /private/path/extract.jsonl
openclaw mr import --file /private/path/extract.jsonl

The uploader validates locally, prints message counts and date coverage, obtains the current server price quote, and asks for explicit approval before uploading. Confirm the destination and contents before accepting. Do not use --yes for an unreviewed extract; it is explicit non-interactive write approval, not a dry-run switch.

Batches contain up to 200 records. Keep the final receipt and reconcile stored, duplicate, skipped, and failed counts. If interrupted, run the same --file command again against the same file and vault. Stable IDs let committed batches replay without duplicate billing or storage.

Cross-session proof with synthetic data

Use a separate test vault, not a customer or shared team vault.

1. Create a private extract.jsonl containing the single synthetic line above. For Codex or OpenClaw, change only the platform prefix to match the host.
2. Run that host's import --file command, review the one-message preview and price, then explicitly approve.
3. Confirm the receipt reports the record as stored, or as an already stored duplicate after a deliberate rerun.
4. Start a fresh AI conversation connected to the same vault. Do not paste the JSONL line or its answer token.
5. Ask: Use MemoryRouter to search the imported core vault. What was the review phrase for the fictional Cedar launch? Quote the matching memory.

The retrieved memory should contain copper-orbit-482. A model guessing the phrase is not proof. Use an explicit MCP memory search if the host's normal hooks are configured for an isolated project/session scope rather than the imported core vault.

Limitations and privacy

• Extraction quality depends on the host model and local history format. The deterministic uploader proves what it accepted, not that the agent found every source message.
• This workflow imports message text, not a full machine backup, tool execution log, file tree, image archive, or host configuration.
• Local extraction can send source text to the host agent's configured model provider. Review that provider's data handling before processing sensitive history.
• The JSONL extract contains plaintext even though upload manifests and receipts do not contain the raw Memory Key. Keep it outside repositories and shared folders.
• Imported history uses the destination core vault. A separate project/session partition is not automatically the same retrieval scope.
• OpenClaw's mr upload workspace uploader is a different operation. Its behavior should not be substituted for this import workflow's approval and receipt contract.
• New conversations continue to use the connector's normal capture rules. Importing a file does not enable a perpetual historical sync job.

Troubleshooting

Next steps

• Agent history import in the integrations directory
• Historical import reference
• Move selected memories between vaults
• Create your MemoryRouter account