Terminal
Terminal/Skill
Guide for designing Letta agents: choosing architecture, memory blocks, models, and tools, plus troubleshooting memory issues.
By Letta
Works with
npx skills add letta-ai/skills --skill letta-development-guideComprehensive guide for designing and building effective Letta agents with appropriate architectures, memory configurations, model selection, and tool setups.
Use this skill when:
from letta_client import Letta
client = Letta()
agent = client.agents.create(
name="my-assistant",
model="openai/gpt-4o",
embedding="openai/text-embedding-3-small",
memory_blocks=[
{"label": "persona", "value": "You are a helpful assistant."},
{"label": "human", "value": "The user's name and preferences."},
],
)
# Send a message
response = client.agents.messages.create(
agent_id=agent.id,
messages=[{"role": "user", "content": "Hello!"}],
)
print(response.messages[-1].content)
Use letta_v1_agent when:
Use memgpt_v2_agent when:
For detailed comparison, see references/architectures.md.
Memory is the foundation of effective agents. Letta provides three memory types:
Core Memory (in-context):
Archival Memory (out-of-context):
Conversation History:
See references/memory-architecture.md for detailed guidance.
Core principle: One block per distinct functional unit.
Essential blocks:
persona: Agent identity, behavioral guidelines, capabilitieshuman: User information, preferences, contextAdd domain-specific blocks based on use case:
company_policies, product_knowledge, customerproject_context, coding_standards, current_taskschedule, preferences, contactsMemory block guidelines:
See references/memory-patterns.md for domain examples and references/description-patterns.md for writing effective descriptions.
Match model capabilities to agent requirements:
For production agents:
Avoid for production:
See references/model-recommendations.md for detailed guidance.
Start minimal: Attach only tools the agent will actively use.
Common starting points:
Tool Rules: Use to enforce sequencing when needed (e.g., "always call search before answer")
Consult references/tool-patterns.md for common configurations.
When approaching character limits:
customer_profile → customer_business, customer_preferencesinteraction_history → recent_interactions, archive older to archival memorySee references/size-management.md for strategies.
When multiple agents share memory blocks or an agent processes concurrent requests:
Safest operations:
memory_insert: Append-only, minimal race conditionsRisk of race conditions:
memory_replace: Target string may change before writememory_rethink: Last-writer-wins, no mergeBest practices:
Consult references/concurrency.md for detailed patterns.
Before finalizing your agent design:
Architecture:
Memory:
Tools:
Too few memory blocks:
# Bad: Everything in one block
agent_memory: "Agent is helpful. User is John..."
Split into focused blocks instead.
Too many memory blocks: Creating 10+ blocks when 3-4 would suffice. Start minimal, expand as needed.
Poor descriptions:
# Bad
data: "Contains data"
Provide actionable guidance instead. See references/description-patterns.md.
Ignoring size limits: Letting blocks grow indefinitely until they hit limits. Monitor and manage proactively.
Python:
from letta_client import Letta
client = Letta() # Uses LETTA_API_KEY env var
# Create agent with custom memory blocks
agent = client.agents.create(
name="my-agent",
model="openai/gpt-4o", # or "anthropic/claude-sonnet-4-20250514"
embedding="openai/text-embedding-3-small",
memory_blocks=[
{"label": "persona", "value": "You are a helpful assistant..."},
{"label": "human", "value": "User preferences and context..."},
{"label": "project", "value": "Current project details..."},
],
description="Agent for helping with X",
)
print(f"Created agent: {agent.id}")
TypeScript:
import Letta from "letta-client";
const client = new Letta();
const agent = await client.agents.create({
name: "my-agent",
model: "openai/gpt-4o",
embedding: "openai/text-embedding-3-small",
memoryBlocks: [
{ label: "persona", value: "You are a helpful assistant..." },
{ label: "human", value: "User preferences and context..." },
{ label: "project", value: "Current project details..." },
],
description: "Agent for helping with X",
});
console.log(`Created agent: ${agent.id}`);
Note: Letta Code CLI (letta command) creates agents interactively. Use letta --new-agent to start fresh, then /rename and /description to configure.
For detailed information on specific topics, consult the reference materials:
references/architectures.md - Architecture comparison and selectionreferences/memory-architecture.md - Memory types and when to use themreferences/memory-patterns.md - Domain-specific memory block examplesreferences/description-patterns.md - Writing effective block descriptionsreferences/size-management.md - Managing memory block size limitsreferences/concurrency.md - Multi-agent memory sharing patternsreferences/model-recommendations.md - Model selection guidancereferences/tool-patterns.md - Common tool configurations