Transfer and Graft

Transfer and Graft copy memories from one Memory Key to another.

Both operations are non-destructive to the source. They write copies into the destination. These endpoints copy the selected embedding model's core vault, not isolated session vaults or reflection tiers.

Use them when you need to move memory between keys:

• Transfer: copy the source core memories to another key. Use this for core-vault migration or duplication, not an all-tier or all-session backup.
• Graft: search one key, filter by similarity score, and copy only matching memories to another key. Use this to seed a team or org key from a personal key without copying unrelated memories.

The authenticated key is always the source key. destination_key is the key that receives the copied memories.

Base URL: https://api.memoryrouter.ai

Prerequisites

Create a MemoryRouter account, then choose an active source key and a different writable destination key in the dashboard. Only copy data you are authorized to share with destination-vault users. Use curl for the API examples below, or the ready-to-run Python setup to enter keys without echoing them.

This API guide is distinct from the guided ChatGPT-to-Claude profile transfer. Find it in the integrations directory.

Recommended workflow: dry run first

Always start with dry_run: true.

A dry run returns the memories that would be copied, including snippets, scores for graft, count, and estimated tokens. It does not write to the destination.

curl -X POST https://api.memoryrouter.ai/v1/memory/graft \
  -H "Authorization: Bearer $SOURCE_MEMORY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_key": "mk_destination",
    "queries": ["architecture decisions", "deployment process", "customer context"],
    "threshold": 0.5,
    "dry_run": true
  }'

Response:

{
  "dry_run": true,
  "operation": "graft",
  "source_key": "mk_abc…123456",
  "destination_key": "mk_def…789012",
  "queries": ["architecture decisions", "deployment process", "customer context"],
  "threshold": 0.5,
  "count": 3,
  "estimated_tokens": 420,
  "memories": [
    {
      "id": 184,
      "snippet": "[USER] We decided to keep auth in the worker and avoid client-side provider keys...",
      "role": "user",
      "timestamp": 1781191200000,
      "score": 0.78,
      "estimated_tokens": 86
    }
  ]
}

If the preview looks right, send the same request with dry_run: false or omit dry_run.

Transfer all memories

POST /v1/memory/transfer

Copies memories in the source key's core vault to the destination key, up to 10,000 source core memories. Larger sources return 413; the endpoint does not silently copy a partial source.

curl -X POST https://api.memoryrouter.ai/v1/memory/transfer \
  -H "Authorization: Bearer $SOURCE_MEMORY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_key": "mk_destination",
    "dry_run": true
  }'

Request body

Successful write response

{
  "dry_run": false,
  "operation": "transfer",
  "source_key": "mk_abc…123456",
  "destination_key": "mk_def…789012",
  "copied": 128,
  "deduped_or_skipped": 0,
  "failed": 0,
  "estimated_tokens": 18420,
  "provenance": {
    "origin_key": "mk_abc…123456",
    "transferred_at": "2026-06-11T17:30:00.000Z"
  }
}

Graft selected memories

POST /v1/memory/graft

Runs one or more semantic searches against the source key. Memories with a score greater than or equal to threshold are copied to the destination key.

curl -X POST https://api.memoryrouter.ai/v1/memory/graft \
  -H "Authorization: Bearer $SOURCE_MEMORY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination_key": "mk_org_team",
    "queries": [
      "business strategy for MemoryRouter",
      "Claude Code integration decisions",
      "customer onboarding lessons"
    ],
    "threshold": 0.55,
    "dry_run": false
  }'

Request body

Successful write response

{
  "dry_run": false,
  "operation": "graft",
  "source_key": "mk_abc…123456",
  "destination_key": "mk_org…789012",
  "queries": [
    "business strategy for MemoryRouter",
    "Claude Code integration decisions",
    "customer onboarding lessons"
  ],
  "threshold": 0.55,
  "copied": 24,
  "deduped_or_skipped": 3,
  "failed": 0,
  "estimated_tokens": 6120,
  "provenance": {
    "origin_key": "mk_abc…123456",
    "transferred_at": "2026-06-11T17:30:00.000Z"
  }
}

Threshold guidance

Start broad, then tighten.

Use multiple focused queries instead of one vague query. For example, use deployment process, customer objections, and pricing decisions instead of business stuff.

Dedupe behavior

Transfer and Graft are safe to re-run.

The destination vault dedupes by memory content hash. If the same memory is copied again, it is skipped instead of written a second time. The response reports skipped duplicates in deduped_or_skipped.

This makes retry safe after partial failure.

Provenance behavior

Copied memories are stamped with provenance metadata:

• origin_key: a safe truncated form of the source key
• transferred_at: the time the copy operation wrote the memory

Provenance is stored as metadata on the copied memory. It is not added to the memory text, so it does not pollute future retrieval context.

Permissions

The authenticated key is the source key.

Source requirements:

• The source key must be valid and active.
• :read source keys are allowed because they can read memory.
• :off source keys are rejected.

Destination requirements:

• destination_key must be valid and active.
• destination_key must be writable.
• mk_xxx:read is rejected.
• mk_xxx:off is rejected.
• Source and destination cannot be the same key.

Possession of both valid keys permits this API operation. A personal/org label is not an additional copy boundary. Confirm the source owner's permission and the destination's membership before sharing memories.

Errors

Example same-key error:

{
  "error": "destination_key must be different from the source key"
}

When to use each

Use Transfer when:

• You are migrating a key.
• You want a copy of the source core memories, not a full account backup.
• You are consolidating selected core vaults into a new key.

Use Graft when:

• You want to seed a team or org key from personal memory.
• You need only business memories, project memories, or client memories.
• You want to avoid copying unrelated personal context.

For team onboarding, the best pattern is:

1. Each team member runs a dry-run graft from their personal key into the shared org key.
2. They tune queries and threshold until the preview is clean.
3. They run the real graft.
4. The org key starts useful on day one.

Cross-session proof

Use two dedicated test vaults. In a source-connected AI conversation, explicitly save the synthetic fact: For the fictional Cedar launch, the review phrase is copper-orbit-482. This is test data. Approve the exact save and confirm it is searchable.

Dry-run a graft for Cedar launch review phrase, inspect the matches, then repeat the reviewed request with dry_run: false. Check copied, deduped_or_skipped, and failed.

In a fresh AI conversation connected to the destination key, ask: Use MemoryRouter to search this vault. What was the review phrase for the fictional Cedar launch? Quote the matching memory. Do not include the answer in that prompt. The returned source content should contain copper-orbit-482, and the original should still exist in the source vault.

Limitations and troubleshooting

• These operations copy core memories only. They do not constitute a full reflection-tier, session-vault, settings, or account backup.
• Graft has no supported result-count limit field. Its query and threshold select matches; a threshold is not a privacy classifier.
• A dry run is a point-in-time preview, not a locked approval snapshot. Review again if source data changes before the real copy.
• The API defaults to a real write unless dry_run is exactly true. Use explicit previews first.
• For 413, use focused grafts or contact support about a batched migration. Do not expect a transfer to copy more than 10,000 source core memories.
• For zero matches, check the source core vault and embedding selection, then adjust queries or threshold in a dry run.
• For partial failure, inspect failed and errors, fix the reported cause, and retry the same copy. Deduplication preserves already copied content.
• For missing destination recall, check the destination connection and retrieval scope, request an explicit MemoryRouter search, and let indexing finish.

See the step-by-step vault transfer guide for the complete setup and error checklist. Create an account to start with a dedicated test vault.