Migrating Letta Agents the Sanctum Way

Moving a long-lived Letta agent off Letta Cloud—or from one self-hosted box to another—is not a database dump exercise. It is a contract problem: the Agent Development Environment (ADE), Broca, SMCP, and search all expect the same shapes Letta’s HTTP import/export APIs agree on. Sanctum’s production playbook treats agent files (.af), message pagination, and archival memory APIs as the migration surface—and keeps Postgres read-only except for normal Letta operation.

This post generalizes what we learned migrating multi-thousand-message agents (including persona-heavy companions) without repeating the failures that once “bricked” ADE on a host.

Three jobs people confuse

Before you touch anything, name which job you are doing:

Mixing these without updating AGENT_ID in Broca and SMCP is how Telegram, queues, and ADE end up talking to the wrong agent.

Golden rules (the short version)

1. HTTP import/export only for conversation and agent shell state—not hand-edited rows in Letta’s Postgres messages table.
2. Export may truncate embedded history; page GET /v1/agents/{id}/messages and merge before import.
3. Archival memory does not ride in the .af—backfill with archival_memory_insert (or equivalent HTTP) after import.
4. Collapse reasoning + assistant pairs into one assistant row per turn (see below)—split rows lose visible replies on Letta 0.16.x.
5. Set agent_type: letta_v1_agent on the imported shell so listed messages label visible text as assistant_message, not reasoning_message.
6. Core memory blocks and tools are separate from merged message history—copy blocks via GET …/core-memory/blocks and attach with PATCH block_ids / tool_ids after import.

Plumbing: what ADE actually needs

ADE is a browser app. If your Letta API listens on plain HTTP while the page is served over HTTPS, you get ERR_SSL_PROTOCOL_ERROR or mixed-content blocks. A workable pattern for a dedicated migration/staging host:

• DNS to the VPS (e.g. lettatest.example.org).
• nginx terminates TLS on 443 (marketing/site) and often 8283 (ADE appends the API port).
• Letta binds loopback only (e.g. 127.0.0.1:18283)—never expose the raw API on the public internet without TLS in front.
• Certbot (or your ACME flow) on the edge vhost.

Bootstrap is not “install Letta and call it done.” It is TLS + reverse proxy + loopback API so ADE and curl share one trustworthy origin.

Message shape: export ground truth vs API listing

Native GET /v1/agents/{id}/export uses one role: "assistant" row per turn when both reasoning and visible reply exist:

{
  "role": "assistant",
  "content": [
    { "type": "reasoning", "reasoning": "…", "is_native": true },
    { "type": "text", "text": "What the user should see in ADE and search" }
  ]
}

{ "role": "assistant", "content": [ { "type": "reasoning", "reasoning": "…", "is_native": true }, { "type": "text", "text": "What the user should see in ADE and search" } ] }

Source hosts often return separate API rows (reasoning_message then assistant_message). Migration must merge those into the combined export shape before POST /v1/agents/import. Two consecutive assistant rows for one turn are an anti-pattern: on 0.16.x import, the second row can be dropped—history looks complete by count but visible replies vanish.

After import, GET …/messages may still expand one embedded row into two listed types (reasoning_message + assistant_message). That expansion is normal; the import file must not use the legacy split-row format.

Other shape fixes that blocked real imports:

• Use "content": [] instead of null when there is no text but tool_calls exist.
• Tool returns: role: "tool" with content as [{"type":"text","text":""}]—raw English breaks message listing parsers.
• Sanitize JSON tool bodies with top-level "status": "error" to a neutral {"ok": false, "message": "…"} shape.
• Drop source rows with status: error before merge.
• Assign fresh synthetic message ids (message-0, …) when Cloud pagination returns duplicate ids on different rows.

Pulling memory out of the system (without SQL)

Conversation

1. GET /v1/agents/{id}/export for shell, tools metadata, partial embedded messages.
2. Page GET /v1/agents/{id}/messages?limit=1000&order=asc with after= until exhausted.
3. Merge into agents[0].messages using the collapse rules above; rewrite in_context_message_ids so every id exists in messages.
4. POST /v1/agents/import to the target base URL with the target bearer token.

Archival

GET /v1/agents/{id}/archival-memory (hyphenated path on current builds), then insert passages against the new agent id on the target—never by inserting into archival_passages via SQL.

Core memory blocks (persona, human, summaries)

The merged .af from export + messages alone does not reliably recreate core-memory blocks attached in the UI. After import:

1. GET /v1/agents/{source}/core-memory/blocks (or equivalent on your build).
2. Create or match blocks on the target (POST /v1/blocks/, etc.).
3. PATCH the new agent’s block_ids (and tool_ids for custom tools).

Stock Letta tools may reattach automatically; custom SMCP/zero1 tools must exist on the destination host before you expect tool calls to work.

Workers (Broca / SMCP)

Filesystem migration: copy ~/sanctum/agents//broca, smcp, update AGENT_ID, LETTA_AGENT_ID, and secrets from each .env. Stop Broca before copying sanctum.db if you need queue continuity.

Validation checklist

After import, verify more than message count:

Export roundtrip (GET …/export again) should show [reasoning, text] pairs, not split assistant rows.

What we stopped doing

Bulk Postgres DML to “clone” an agent was a historical mistake: it bypasses Letta’s importer contract and can corrupt ADE for every agent on that database. Sanctum’s standing rule: read-only SELECT for diagnosis; state changes through import/export and archival HTTP unless there is explicit break-glass approval for a specific statement.

Tooling and deeper references

Sanctum operators maintain:

• A migration runbook (full procedure, nginx/certbot, Broca placement).
• Agent-file pattern doc (collapse pairs, tool JSON, anti-patterns).
• Scripts such as migrate_letta_cloud_agent_to_host.py and post-import blocks/tools repair helpers in the monday-migration-redo workspace (public patterns, private credentials).

If you are building on SanctumOS: wire Broca for channel isolation, SMCP for tools, and treat Letta as the memory authority accessed only through its API—same on Cloud and self-hosted, relative to each server’s base URL and bearer token.