Architecture Migration Guide

Should You Migrate?

Migrate if:

• You want better performance on GPT-5, Claude Sonnet 4.5, or other frontier models
• You want to use models that support native reasoning
• You’re experiencing issues with legacy architectures

Don’t migrate if:

• Your agents are working well and you’re not using new models
• You have critical integrations depending on heartbeats or send_message
• You need time to test the new architecture first

What Changes

Breaking Changes

What Stays the Same

• Memory blocks work identically
• Archival memory & recall tools unchanged
• Custom tools work the same way
• API authentication & endpoints

Migration Steps

Step 1: Export Your Agent

Download your agent configuration as an agent file:

1
const agentFile = await client.agents.export(agentId);
2
// Save to disk
3
fs.writeFileSync('my-agent.json', JSON.stringify(agentFile, null, 2));

Step 2: Update Agent Type

Open the agent file and change the agent_type:

1
{
2
  "agent_type": "memgpt_v2_agent"
3
  // ... rest of config
4
}

Change to:

1
{
2
  "agent_type": "letta_v1_agent"
3
  // ... rest of config
4
}

Step 3: Clear Message Context (If Needed)

If your agent has send_message tool calls in its context, you’ll need to clear the message history:

1
{
2
  "in_context_message_ids": [
3
    "message-0",
4
    "message-1",
5
    "message-2"
6
  ]
7
}

Change to:

1
{
2
  "in_context_message_ids": []
3
}

Step 4: Update System Prompt (Optional)

The default system prompt for letta_v1_agent is different. You may want to update it for optimal performance:

1
<base_instructions>
2
You are a helpful self-improving agent with advanced memory and file system capabilities.
3
4
<memory>
5
You have an advanced memory system that enables you to remember past interactions and continuously improve your own capabilities.
6
Your memory consists of memory blocks and external memory:
7
- Memory Blocks: Stored as memory blocks, each containing a label (title), description (explaining how this block should influence your behavior), and value (the actual content). Memory blocks have size limits. Memory blocks are embedded within your system instructions and remain constantly available in-context.
8
- External memory: Additional memory storage that is accessible and that you can bring into context with tools when needed.
9
Memory management tools allow you to edit existing memory blocks and query for external memories.
10
</memory>
11
12
<file_system>
13
You have access to a structured file system that mirrors real-world directory structures. Each directory can contain multiple files.
14
15
Files include:
16
- Metadata: Information such as read-only permissions and character limits
17
- Content: The main body of the file that you can read and analyze
18
19
Available file operations:
20
- Open and view files
21
- Search within files and directories
22
- Your core memory will automatically reflect the contents of any currently open files
23
24
You should only keep files open that are directly relevant to the current user interaction to maintain optimal performance.
25
</file_system>
26
27
Continue executing and calling tools until the current task is complete or you need user input. To continue: call another tool. To yield control: end your response without calling a tool.
28
29
Base instructions complete.
30
</base_instructions>

Step 5: Import Updated Agent

Upload the modified agent file:

1
const agentFile = JSON.parse(fs.readFileSync('my-agent.json', 'utf-8'));
2
const migratedAgent = await client.agents.import(agentFile);

Step 6: Test Your Agent

Send a test message to verify the migration worked:

1
const response = await client.agents.messages.create(
2
    migratedAgent.id,
3
    { messages: [{ role: "user", content: "Hello! Do you remember me?" }] }
4
);

Automated Migration Script

Here’s a helper script to automate the migration process:

1
import json
2
3
def migrate_agent_file(input_file: str, output_file: str):
4
    """Migrate an agent file from legacy to letta_v1_agent"""
5
6
    # Load agent file
7
    with open(input_file, 'r') as f:
8
        agent_data = json.load(f)
9
10
    # Update agent type
11
    old_type = agent_data.get('agent_type')
12
    agent_data['agent_type'] = 'letta_v1_agent'
13
14
    # Clear message context if migrating from memgpt types
15
    if old_type in ['memgpt_agent', 'memgpt_v2_agent']:
16
        agent_data['in_context_message_ids'] = []
17
18
    # Save updated file
19
    with open(output_file, 'w') as f:
20
        json.dump(agent_data, f, indent=2)
21
22
    print(f"✓ Migrated {old_type} → letta_v1_agent")
23
    print(f"✓ Saved to {output_file}")
24
25
    if old_type in ['memgpt_agent', 'memgpt_v2_agent']:
26
        print("⚠ Message context cleared - agent will not remember recent messages")
27
28
# Usage
29
migrate_agent_file('my-agent.json', 'my-agent-migrated.json')

Migration by Architecture Type

From memgpt_agent

1. Export agent file
2. Change agent_type to letta_v1_agent
3. Clear in_context_message_ids array
4. Update system prompt
5. Import agent

Key differences:

• No more send_message tool
• No more request_heartbeat parameter
• Memory tools: core_memory_* → memory_*

From memgpt_v2_agent

1. Export agent file
2. Change agent_type to letta_v1_agent
3. Clear in_context_message_ids array (if needed)
4. Import agent

Key differences:

• No more send_message tool
• File tools still work (open_file, grep_file, etc.)
• Sleep-time agents still supported

Creating New Agents

For new agents, simply omit the agent_type parameter:

1
const agent = await client.agents.create({
2
    model: "openai/gpt-5-mini",
3
    embedding: "openai/text-embedding-3-small",
4
    memoryBlocks: [
5
        { label: "persona", value: "I am a helpful assistant." }
6
    ]
7
});

Troubleshooting

”Agent import failed”

Possible cause: send_message tool calls still in context

Fix: Clear the in_context_message_ids array in your agent file

”Agent behavior changed after migration”

Possible cause: Different system prompt or cleared message history

Fix:

1. Update to the new system prompt format (see Step 4)
2. Provide a brief reminder about recent context in your first message

”Too many tool calls / infinite loops”

Possible cause: Agent trying to replicate heartbeat behavior

Fix: Update system instructions to clarify when to stop executing

Sleep-Time Agents

Sleep-time functionality works with letta_v1_agent:

1
const agent = await client.agents.create({
2
  model: "openai/gpt-5-mini",
3
  enableSleeptime: true, // ✓ Still supported
4
});

Learn more about sleep-time agents →

Getting Help

• Migration issues: Ask in Discord #dev-help
• Bug reports: GitHub Issues
• Enterprise support: Contact support@letta.com