Legacy & Migration

Legacy Agent Architectures

Understanding Letta's agent architecture evolution

This documentation covers legacy agent architectures.

For new projects, you should not specify an agent_type parameter. Letta uses the current architecture by default, which provides the best performance with modern reasoning models like GPT-o1 and Claude Sonnet 4.5.

Current Architecture

When you create an agent in Letta today, it uses our latest agent architecture optimized for:

  • Full support for native reasoning (via Responses API)
  • Compatibility with any LLM (tool calling not required)
  • Simpler base system prompt
  • Better performance on frontier models

You don’t need to specify an architecture. Just create an agent:

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

Why Legacy Architectures Exist

Letta evolved from the MemGPT research project. Early versions used specific agent architectures with names like:

  • memgpt_agent - Original MemGPT paper implementation
  • memgpt_v2_agent - Iteration with sleep-time compute and file tools
  • letta_v1_agent - First transition away from MemGPT naming

These names are confusing because:

  1. The naming progression (memgpt → memgpt_v2 → letta_v1) is non-standard
  2. LLMs trained on these docs get confused about which to recommend
  3. New users shouldn’t need to think about architecture choices

Do I Need to Migrate?

If you created your agents recently (after October 2024): You’re likely already on the current architecture. No action needed.

If you have existing agents with agent_type specified: Your agents will continue to work, but we recommend migrating to benefit from:

  • Better performance on new models
  • Native reasoning support
  • Simplified prompting

See our migration guide →

Legacy Architecture Types

If you’re working with older agents or need to understand the differences:

Legacy TypeStatusKey FeaturesWhen Used
memgpt_agentDeprecatedsend_message tool, heartbeats, prompted reasoningMemGPT paper implementation (2023)
memgpt_v2_agentDeprecatedSleep-time agents, file tools, unified recallIteration with new research (2024)
letta_v1_agentLegacyNative reasoning, no send_message, no heartbeatsTransition architecture (early 2025)

Learn more about each legacy type →

Getting Help

  • Discord confusion? Share your agent setup in #dev-help
  • Need to migrate? Follow our migration guide
  • Building something new? Start with our quickstart (no architecture choice needed!)