SDK Architecture:

• Python SDK 1.0: pip install letta-client (stable release, November 19 2025)
• TypeScript SDK 1.0: npm install @letta-ai/letta-client (stable release, November 19 2025)
• Legacy SDK: pre-1.0 versions (deprecated routes sunset end of 2025)
• Documentation: https://docs-v1.letta.com/ (1.0), https://docs.letta.com/api-reference/sdk-migration-guide (migration)
• All interfaces (ADE, REST API, SDKs) use same underlying API
• Overview video: https://www.youtube.com/watch?v=IkpOwzWYi5U

Authentication Flows:

• Letta Cloud: requires api_key parameter
• Local server: direct connection without apikey (alpha.v19+ allows empty string)
• Client instantiation: client = Letta(api_key="LETTA_API_KEY")
• SDK 1.0 uses api_key, NOT token (pre-1.0 used token)

• Stateful API design: server manages agent state, memory, message history
• Agent messaging: POST /agents/{agent_id}/messages
• Agent creation: client.agents.create() with model, embedding, memoryblocks
• Core memory routes: for cross-agent memory block access
• Batch endpoints: multiple LLM requests in single API call for cost efficiency

API Response Patterns:

• Agent responses include: reasoning steps, tool calls, assistant messages
• Message model includes sender_id parameter for multi-user scenarios
• Server-Sent Events (SSE) for streaming: /v1/agent/messages/stream
• "POST SSE stream started" messages are normal system indicators

State Management:

• Stateful server-side: unlike ChatCompletions API which is stateless
• Server handles: agent memory, user personalization, message history
• Individual agents run as services behind REST APIs
• Persistent agent state across API calls and sessions

Recent API Evolution:

• SDK 1.0 release (November 2025) - major stable release
• Projects endpoint, batch APIs, reasoningeffort field
• DEPRECATED (Dec 19): llmconfig in agent creation - use model handles instead (e.g., "openai/gpt-4o")
• List Agent Groups API for multi-agent group management

Letta as Agent Backend (Pacjam, November 2025):

• Mental model: "Hosted Claude Code/Agents SDK"
• Common architecture: Letta + application backend (e.g., Letta + Convex)
• Simple use cases: Can use Letta + frontend directly (Letta has client-side access tokens)
• Complex use cases: Application backend stores UI state, Letta handles agent logic
• Example: Next.js → Convex for chat UI/history, Convex → Letta for agent interactions

When to use Letta vs ChatCompletions in app backend:

• Short sequences (1-3 LLM calls, no session retention): Keep state in app backend (Convex/etc) - this is ChatCompletions premise
• Long-running agents (hours, many tool calls, LLM flakiness): Use dedicated agent service (Letta/Responses API)
• Long-running agent logic inside main app = "complete disaster" due to durability challenges
• Letta/OpenAI spend significant engineering resources making long-running agents durable
• Responses API and Claude Agents SDK designed to push agent logic into separate service
• Benefits: Complex Claude Code-style agents wired to any app without app code becoming insane
• Enables advanced features like sleep-time compute with batch inference for memory refinement

Common API Security Mistakes (November 2025):

• Relying on client-provided IDs (agentid, userid) without cryptographic proof
• Using POST methods for read operations (breaks HTTP semantics, prevents caching)
• Configuring CORS for server-to-server calls (Letta Cloud has no Origin header)
• Missing bearer token requirements in public-facing APIs
• Pattern: Always require Authorization header FIRST, then validate ID mappings

Next.js Singleton Pattern (Best Practice, Dec 2025):

// lib/letta.ts - singleton client
import { LettaClient } from '@letta-ai/letta-client';

export const letta = new LettaClient({
  baseUrl: process.env.LETTA_BASE_URL || 'https://api.letta.com',
  apiKey: process.env.LETTA_API_KEY!,
  projectId: process.env.LETTA_PROJECT_ID,
});

// app/api/send-message/route.ts
import { letta } from '@/lib/letta';

• API key stays server-side in env vars
• Single client instance reused across all routes
• Add auth middleware to protect routes

SDK 1.0 Message Creation Pattern (Dec 2025):

• SDK expects typed objects, not plain dicts
• Correct import: from letta_client.types import MessageCreateParam
• Usage: messages=[MessageCreateParam(role="user", content="...")]
• Error if using dicts: "Expected type 'Iterable[MessageCreateParam]' got 'list[dict[str, str]]'"
• Multimodal: Anthropic format {"type": "image", "source": {"type": "url", "url": "..."}}
• Multiple images: Array of image objects; use asyncio.to_thread() for Discord bots
• Valid types: text, image, toolcall, toolreturn, reasoning

Archival Memory Policy

Core principle: Core memory = working knowledge. Archival memory = reference library.

When to Archive (move FROM core TO archival):

• Time-based:
• Observations older than 2 months that haven't been referenced recently
• Resolved bugs/issues that are no longer active problems
• Historical team corrections that are now documented in guidelines

• Usage-based:
• Detailed error patterns that only apply to specific edge cases
• Specific user interaction histories (unless recurring pattern)
• One-off technical details that don't inform general support patterns

• Volume-based:
• When core memory blocks exceed 80% capacity, review for archival candidates
• Proactively archive before hitting limits (not reactively)

What STAYS in Core Memory:

• Active recurring patterns (commonissues that users hit frequently)
• Current team philosophy and guidance
• Core API patterns and architecture knowledge
• Recent observations (last 2 months)
• Response guidelines and persona
• Knowledge gaps that need resolution

• Use archivalmemorysearch when questions reference specific edge cases
• Search with multiple tags to narrow results
• Bring information back to core memory if it becomes frequently referenced again

• Web ADE settings infinite loading - team working on internal issue; use CLI configuration as workaround
• "relation 'organizations' does not exist" - run alembic -c alembic.ini upgrade head for PostgreSQL schema
• Tool creation with manual jsonschema causes errors - use BaseTool/docstrings instead

API/Deployment:

• Remote server partial connectivity - model discovery works but messages route to localhost
• Token streaming not supported for Ollama - only agent steps streaming
• Railway deployments with Dynamic Groups may cause Status 500 errors
• Cloud latency (~2s) - team actively working on reducing system-related issues

Multi-Agent/Performance:

• Can use heavy models for memory agents while keeping others lightweight
• Can modify agent models via PATCH /agents.modify endpoint
• Free tier limits based on active monthly usage, not total agents created
• Retry limits don't help with infinite loops - need to remove conflicting tools

Custom Tools:

• sendmessage tool name conflicts - tool names must be unique org-level
• Custom user memory storage can use any MCP-supported tool or Python-writable tool

• Async tools (sendmessagetoagentasync) still broken - runs stuck in "created" status
• Synchronous A2A fixed (Dec 3, 2025) - use sendmessagetoagentandwaitforreply
• Workaround: Write custom tools for async agent communication

ADE Display Bugs (November 2025):

• Cloud duplicate rendering: TRACKED (Cameron/4shub investigating Nov 20)
• Desktop lettav1agent upgrade: Confirmed "known bug" (Cameron Nov 21) - use Web ADE workaround

Identities List Endpoint Bug (November 2025):

• List identities endpoint returns empty array without explicit projectid parameter
• Identities exist and are visible/editable in ADE
• Workaround: Explicitly pass projectid to list/retrieve endpoints
• 4shub investigating and reproducing (Nov 2025)

Async Agent Communication Tools (A2A) - Known Issue (November 2025):

• send_message_to_agent_async shown in docs but not working properly
• Cameron confirmed (Nov 19, 2025): "This is a known issue with agent to agent tools"
• Symptom (extravillager, Dec 10, 2025): Runs stuck in "created" status indefinitely, never execute
• Affects both Cloud and self-hosted deployments
• Documentation references this tool for async multi-agent messaging
• Reason for issues: tools need to be rewritten, wasn't properly rate limited on Cloud
• Recommended workaround: Write custom tools for agent-to-agent communication
• Alternative built-in tools: send_message_to_agent_and_wait_for_reply (synchronous), send_message_to_agents_matching_all_tags

Letta Code CLI + Sleeptime Agents (November 2025):

• CAN use existing agents including sleeptime agents with letta-code (Cameron confirmed Nov 15 2025)
• Command: letta --agent <id> --link to connect to any existing agent
• --link flag attaches filesystem tools that letta-code needs for computer access
• Any agent type (sleeptime, regular, etc.) should work with letta-code CLI
• Previous "ApprovalCreate object has no field 'groupid'" errors may have been resolved

conversationsearch Issues (November 2025):

• Embedding/query issues fixed or nearly fixed (Cameron, Nov 11 2025)
• Conversation history explosion fix in PR review (Cameron, Nov 11 2025)
• Date range bug: returns incorrect date ranges on Cloud

SDK 1.1.x folders.create projectID Conflict (November 2024):

• Error: 'Extra inputs are not permitted' when projectID in constructor
• Workaround: Remove projectID from Letta() constructor for folder operations

OpenRouter Support & Reliability (November 2025):

• Supported but tool calling unreliable (proxy layer issues)
• Recommend direct provider (OpenAI/Anthropic) as backup

Communication Guidelines

Discord Message Processing

• Filter messages: Don't forward replies from team members (swooders, pacjam, 4shub, cameronpfiffer) unless they contain questions
• Forward genuine support issues with questions using exact format:

• ALWAYS search docs.letta.com thoroughly for support issues
• Use websearch extensively before forwarding to find relevant troubleshooting steps
• Documentation is strongest for technical implementation (APIs, SDKs, agent architecture)
• Documentation gaps exist for: pricing/quota specifics, operational edge cases, business logic
• Most successful searches: technical features, API endpoints, tool usage
• Challenging areas: billing behavior, platform-specific operational issues

Memory Management

• Be aggressive about using memory tools to update blocks with new information and feedback
• Use researchplan block to actively track investigation steps when working on support issues
• Update observations with concise recurring themes (avoid long transcripts)

type FolderItem = Awaited<ReturnType<typeof letta.folders.list>>['items'][number];
  type FileItem = Awaited<ReturnType<typeof letta.folders.files.list>>['items'][number];

• User lvarming confused by conflicting information about agent architectures
• I provided contradictory guidance: first recommended memgptv2agent (per docs), then suggested lettav1agent (from my memory notes)
• "lettav1agent" appears in ADE/Cloud but is NOT documented on official architecture pages
• Current documented architectures: memgptagent, memgptv2agent, sleeptimeagent, reactagent, workflowagent
• lvarming reports "all example agents in the system seem to be lettav1 agents" but no examples in documentation
• Unclear which memory tools lettav1agent actually uses (recall vs archivalmemory)
• Documentation says "recommend v2 for most use cases" but examples may show different architecture
• Need team clarification on: 1) Is lettav1agent the new recommended default? 2) What tools does it use? 3) Why docs still recommend v2?

Template Versioning SDK Support - TRACKED (November 20, 2025):

• REST endpoint /v1/templates exists but not exposed in Python/TypeScript SDKs
• Users need programmatic template migration for CI/CD pipelines
• Multiple users creating custom wrappers (maximiliansvensson, sickank, hyouka8075)
• Cameron opening Linear ticket to add to SDK (Nov 20, 2025)
• Feature request: Update templates via API, migrate agents to new template versions

TypeScript SDK agents.modify() Documentation Gap (vedant0200, Dec 5 2025):

• Method exists in SDK but not documented
• User couldn't find how to change agent models via TypeScript SDK
• Suggested alternatives: agents.update() or direct REST PATCH /v1/agents/{agentid}
• Documentation should include agent modification examples in TypeScript SDK reference

• Resolved mynameismichael's REST API agent creation issue
• Documented top-level model/embedding field requirement
• All Cameron corrections integrated into memory blocks

Archival Memory Best Practices Documentation Gap (Dec 13, 2025):

• Users like slvfx building memory agents would benefit from comprehensive archival optimization guide
• Topics to document: topk tuning based on corpus size, chunking strategies (overlap, size, parent-child), tag schema design patterns, archivaldirectory block pattern for entity linking, two-step search patterns
• PATCH /v1/passages endpoint exists but may not be well-documented for retroactive tagging workflows

Learning SDK (agentic-learning) Documentation Gap (Dec 14, 2025):

• messages.capture() endpoint discovered by vedant0200 in learning SDK source code
• Not documented in main Letta docs (docs.letta.com)
• Endpoint exists: POST /v1/agents/{id}/messages/capture
• Function: Store conversations without triggering agent processing (just storage)
• Use case: Import external conversations (ChatGPT, Claude) for sleeptime to process
• Package: pip install agentic-learning / npm install @letta-ai/agentic-learning
• GitHub: https://github.com/letta-ai/learning-sdk
• This should be cross-referenced in main docs for users building memory curators

• Creation via REST API, ADE, or SDKs (Python, TypeScript)
• Required parameters: model, embedding, memoryblocks
• Optional: contextwindowlimit, tools, system instructions, tags
• Each agent gets unique agentid for lifecycle management
• Agents stored persistently in database on Letta server

Agent Architecture Migration (lettav1agent):

• Filesystem tools (readfile, writefile, listfiles, etc.) are AUTOMATICALLY attached when a folder is attached to the agent
• Manual attachment/detachment NOT needed for filesystem tools
• If filesystem tools aren't visible, check if folder is attached to agent (not a tool attachment issue)

Agent Migration Edge Cases (October 2025):

• Sleeptime frequency setting not preserved during architecture migration (.af file method)
• Users must manually reconfigure sleeptimeagentfrequency after upgrading to lettav1agent

Agent Migration Edge Cases (October 2025):

• Sleeptime frequency setting not preserved during architecture migration (.af file method)
• Users must manually reconfigure sleeptimeagentfrequency after upgrading to lettav1agent

Converting Existing Agent to Sleeptime-Enabled (Cameron, November 2025):

• Use PATCH endpoint to enable sleeptime on existing agents
• API call: PATCH /v1/agents/{agent_id} with {"enable_sleeptime": true}
• Example:

curl "https://api.letta.com/v1/agents/$AGENT_ID" \
    -X PATCH \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer $LETTA_API_KEY" \
    -d "{\"enable_sleeptime\": true}"

• No need to recreate agent - can upgrade in place

Template Usage Guidance (Cameron, Dec 3, 2025):

• Templates NOT recommended for personal agents
• Designed for "mass-scale deployments of pseudo-homogenous agents"
• Personal agents should be custom-configured per user needs

Agent architectures (lettav1, memgptv2, sleeptime), tool configurations, memory tools, architecture priorities and evolution

Letta V1 Agent (lettav1agent) - Current Recommended (October 2025):

• Primary architecture recommended by Cameron
• Deprecated: sendmessage tool, heartbeats, prompted reasoning tokens
• Native reasoning via Responses API, encrypted reasoning across providers
• Direct assistant message generation (not via tool calls)
• Works with ANY LLM (tool calling no longer required)
• Optimized for GPT-5 and Claude 4.5 Sonnet
• Simpler system prompts (agentic control baked into models)
• Trade-offs: no prompted reasoning for mini models, limited tool rules on AssistantMessage
• Can add custom finishturn tool if explicit turn termination needed
• archivalmemoryinsert/search: NOT attached by default (opt-in)
• May experience more frequent summarizations than v2 (user reports: Gemini 2.5 Pro triggers significantly more than Claude Haiku 4.5)

MemGPT V2 Agent (memgptv2agent) - Legacy:

• Memory tools: memoryinsert, memoryreplace, memoryrethink, memory (omni tool)
• memory tool: Omni tool allowing dynamic create/delete of memory blocks (unique capability)
• File-based tools: openfile, grepfile, searchfile
• recall tool deprecated ("recalled" per Cameron)
• archivalmemoryinsert/search: NOT attached by default (opt-in)
• conversationsearch: Available if explicitly attached

• lettav1agent: Primary focus for Letta devs
• memgptv2agent: Legacy but still relevant
• Sleeptime architecture: Important but not directly interacted with
• Other architectures may be deprecated - team considering removing many from docs

• ADE-created agents default to lettav1agent
• API may require specifying agenttype
• Team recommends lettav1agent for stability and GPT-5/Responses API compatibility

Message Approval Architecture (Cameron, November 2025):

• Don't use Modify Message API for customer service approval workflows
• Instead: Custom tool like suggestresponse with approval requirements
• Pattern: Agent calls tool → Human approves/denies → Extract reason from return
• Recommended HITL pattern for message-level approval
• sendmessage tool NOT available on lettav1agent

Memory Tool Compatibility (Cameron, November-December 2025):

• Optimized for Anthropic models - post-trained on it specifically
• Letta "basically copied" memory tool from Anthropic (Cameron, Nov 15)
• Memory omni tool replaces other memory tools except rethink (Cameron, Dec 8)
• Unique capability: create/delete memory blocks dynamically
• Other models may struggle - OpenAI models "a little less good at it"
• GLM 4.6 "does okay as well" (Cameron, Dec 8)
• Memory tool accepts BOTH formats: /memories/<label> and <label> (intended behavior)
• /memories/ prefix designed to match Claude's post-training set

Inbox Feature (November 2025):

• Centralized approval management across all agents
• Available in Letta Labs
• Use case: HITL workflows with multiple autonomous agents
• Cameron: "check if agents have emails to send, code edits to make, etc."

Sleeptime Chat History Mechanism (Cameron, Dec 3, 2025):

• Group manager copies most recent N messages into user prompt
• Mechanism: transcript injection via group manager, not shared memory blocks
• Explains how sleeptime agent receives conversation context

Dynamic Block Attachment for Multi-Character Apps (Dec 17, 2025):

• Start conversation: attach character block → chat → end: optionally detach
• Trade-off: Keep attached (faster, contextual) vs detach (clean, no accumulation)
• Recommended: Keep 1-3 recent character blocks, detach older
• Relationships in archival with tags, not dependent on block attachment

Infrastructure and deployment: Letta Cloud vs self-hosted comparison, Docker configuration, database setup (PostgreSQL), environment variables, scaling considerations, networking, security, backup/restore procedures

Deployment Architecture:

• Letta Cloud: managed service with rapid updates
• Self-hosted: PostgreSQL database + FastAPI API server
• Docker recommended for self-hosted deployments
• Web ADE (app.letta.com): Can connect to both Cloud and self-hosted servers via "Add remote server"
• Desktop ADE: Connects to both Cloud and self-hosted servers
• Custom UI: Build via SDK/API

Docker Configuration:

docker run \
  -v ~/.letta/.persist/pgdata:/var/lib/postgresql/data \
  -p 8283:8283 \
  -p 5432:5432 \
  -e OPENAI_API_KEY="your_key" \
  -e ANTHROPIC_API_KEY="your_key" \
  -e OLLAMA_BASE_URL="http://host.docker.internal:11434" \
  letta/letta:latest

Database Setup (PostgreSQL):

• Default credentials: user/password/db all = letta
• Required extension: pgvector for vector operations
• Custom DB: Set LETTA_PG_URI environment variable
• Port 5432 for direct database access via pgAdmin

Performance Tuning:

• LETTA_UVICORN_WORKERS: Worker process count (default varies)
• LETTA_PG_POOL_SIZE: Concurrent connections (default: 80)
• LETTA_PG_MAX_OVERFLOW: Maximum overflow (default: 30)
• LETTA_PG_POOL_TIMEOUT: Connection wait time (default: 30s)
• LETTA_PG_POOL_RECYCLE: Connection recycling (default: 1800s)

Security Configuration:

• Production: Enable SECURE=true and LETTA_SERVER_PASSWORD
• Default development runs without authentication
• API keys via environment variables or .env file

Cloud vs Self-Hosted:

• Cloud: ~2s latency overhead, rapid updates, managed infrastructure
• Self-hosted: ~600ms latency, version lag, manual management

Remote Server Connection:

• ADE "Add remote server" for external deployments
• Supports EC2, other cloud providers
• Requires server IP and password (if configured)

Embedding Provider Updates (October 2025):

• LM Studio and Ollama now offer embeddings
• Enables fully local deployments without external embedding API dependencies

Templates (Cameron, Dec 3, 2025):

• Cloud-only feature, will remain that way
• Built for massive scale deployments
• Self-hosted alternative: use Agent Files (.af) but requires more manual work

BYOK Grandfathering (Cameron, Dec 4, 2025):

• Existing BYOK users likely grandfathered in despite enterprise-only policy
• Example: taurean (void/void-2) continuing to use BYOK

letta-code OAuth (Cameron, vedant0200, Dec 9 2025):

• Google introduced mandatory "thoughtsignature" requirement for function calling
• Letta's Gemini provider doesn't support thought signatures yet
• Symptom: 400 error "Function call is missing a thoughtsignature"
• Workaround: Use Gemini 2.5 Flash/Pro instead
• Error also appears AFTER summarization with MCP server tools
• OpenRouter-specific (bibbs123, Dec 9): Returns reasoningdetails array that must be echoed back verbatim in subsequent requests for multi-turn; thoughtsignature in extracontent.google.thoughtsignature from reasoning.encrypted with ID matching tool call

• Reports on self-hosted when calling archivalmemoryinsert
• Likely causes: missing embedding config, tool not attached, version mismatch
• Self-hosted requires explicit embedding model configuration

• First character dropped from tooluse output on small local models (Qwen, Gemma)
• Root cause: LLM output malformation, not Letta parsing
• Workaround: Use more capable models

Structured Output + Tool Calling Incompatible (Cameron):

• Cannot use both simultaneously
• Structured output overrides tool calling capability

letta-code Line Ending Bug:

• Different line endings between systems cause files to appear "changed"
• Symptom: Massive credit waste (3k coins instead of 40)
• Files re-read due to line ending differences
• Fix: Git command to normalize line endings

OpenRouter Support:

• Supported but tool calling unreliable (proxy layer issues)
• Recommend direct provider (OpenAI/Anthropic) as backup

lettav1agent + sendmessage Tool Anomaly (RESOLVED, Dec 9, 2025):

• User (scarecrowb) reports lettav1agent showing sendmessage tool behavior
• Agent created via Desktop ADE, shows lettav1agent in UI
• Response structure shows clear memgptv2 pattern: <think> in assistantmessage, sendmessage tool call
• Root cause: sendmessage tool was manually attached to lettav1agent
• Solution: Detach sendmessage tool in ADE (confirmed working)
• Takeaway: lettav1agent CAN have sendmessage manually attached, causing hybrid behavior

LM Studio Reasoning Toggle Not Working (Dec 9, 2025):

• Reasoning toggle grayed out in Desktop ADE for LM Studio models
• SDK enable_reasoning parameter doesn't exist (neither modify() nor update() support it)
• REST API PATCH with {"enablereasoning": False} ignored by LM Studio models
• <think> tags persist regardless of toggle setting
• Workaround: Strip tags client-side with re.sub(r'<think>.*?</think>\s*', '', content, flags=re.DOTALL)
• LM Studio model types may not respect Letta reasoning configuration

• /v1/anthropic proxy auto-creates/finds agents based on naming convention: claude-code-{user_uuid[:8]}
• Implementation in proxyhelpers.py: agent_name = f"claude-code-{user_short_id}"
• No X-Letta-Agent-Id header support - cannot specify existing agent to use
• Workaround: Attach existing archives to auto-created agent or migrate passages
• Feature request: Header to override auto-creation and use existing agents (preserves established memory)
• Works on both Cloud and self-hosted 0.16+
• Reported by slvfx via source code reverse-engineering

Block Label Uniqueness Per Agent (Dec 17, 2025):

• Each agent can only have ONE block with a given label attached at a time
• Attempting to attach multiple blocks with same label: UniqueViolationError
• Common mistake: generic labels like "character" when attaching multiple character blocks
• Solution: unique labels per entity (e.g., character:{char_code} not just character)
• Related: Block labels globally are NOT unique (multiple blocks can share label), but per-agent they ARE

LM Studio Chat Template Role Restrictions (Dec 18, 2025):

• Symptom: "jinja2.exceptions.TemplateAssertionError" when agent attempts to send messages
• Root cause: Model's chat template only supports user/assistant roles, not system messages
• Letta requires system message support for proper agent functioning
• Solutions:
• Use lmstudio-community models (have fixed chat templates with system role support)
• Manually edit chat template to accept system role (via LM Studio model config)
• Switch to different model with proper template support
• Common with GGUF models that don't have official system role support in template
• Reported by rhomancer during Ollama→LM Studio migration

Grok 4.1 Fast contextwindow Requirement (Dec 18, 2025):

• Symptom: 422 error "1 validation error for AgentUpdateInternalCreate" - missing context_window in llm_config
• Root cause: Grok 4.1 Fast requires explicit context_window in llmconfig when creating agent via API/SDK
• Solution: Add context_window: 131072 to llmconfig object (Grok 4.1 Fast's context window)
• Note: reasoningeffort also requires contextwindow field to be valid
• Affects: API/SDK agent creation with Grok models on OpenRouter

• ADE: Tool Manager → Add MCP Server (web interface)
• API/SDK: Programmatic integration via lettaclient
• Automatic x-agent-id header inclusion in HTTP requests
• Tool attachment to agents after server connection
• Supports both local (npx servers) and remote deployments

External Data Sources:

• File system integration for document processing
• Database connectors via MCP protocol
• Vector database connections for archival memory
• API integrations through custom tools and MCP servers

Scheduling and Automation:

• System cron jobs for scheduled agent interactions
• Zapier integration available: https://zapier.com/apps/letta/integrations
• Sleep-time agents for automated processing tasks
• External cron jobs calling Letta Cloud API for 24-hour scheduling

Custom Tool Development:

• BaseTool class for Python tool development
• Source code approach with automatic schema generation
• Environment variables for tool execution context
• Sandboxed execution via E2B integration for security
• Tool rules for sequencing and constraint management

Third-Party System Integration:

• REST API and SDKs (Python, TypeScript) for application integration
• Agent File (.af) format for portability between systems
• Multi-user identity systems for connecting agents to external user databases
• Webhook patterns through custom tool implementations

Voice Agent Integration (Team Recommendation, Dec 2025):

• Voice is "extremely hard to do well" - not Letta's core competency (Cameron, Dec 4)
• Cameron pushed hard for chat completions endpoint to enable current voice integrations
• Recommended architecture: Voice + Letta Sidecar Pattern
• Voice-only agent handles real-time conversation (optimized for latency)
• Letta agent runs as sidecar for memory/state management
• Before each voice prompt: download memory blocks from Letta agent → inject into voice agent context
• After voice exchange: feed input/output messages back to Letta agent
• This is fundamentally different from routing voice through Letta directly
• Voice platforms: LiveKit and VAPI both confirmed working (docs: https://docs.letta.com/guides/voice/overview/)
• Why this pattern: Voice requires turn detection, extremely low latency - don't want agent editing memory mid-thought

Agent Secrets Scope (November 2025):

• Agent secrets are agent-level (shared across all users), not per-user
• Cannot pass different auth tokens per user via environment variables
• Use cases: shared API keys, service credentials, base URLs
• Per-user auth: store tokens in DB, inject at request time via proxy or custom tool

HTTP Request Origin (November 2025):

• Letta Cloud: Requests originate from Letta's server infrastructure (server-to-server)
• No fixed domain, IP list, or Origin header for CORS allowlisting
• Self-hosted: Requests come from user's deployment environment
• Recommendation: Authenticate via service tokens/signed headers, not domain-based CORS rules

Cloudseeding - Bluesky Agent Bridge (Community Tool, Dec 2025):

• Deno-based bridge between Bluesky and Letta agents
• Repository: https://tangled.org/taurean.bryant.land/cloudseeding/
• Created by Taurean Bryant
• Features: dynamic notification checking, full social actions, sleep/wake cycles, reflection sessions, AI transparency declarations
• Quickstart: deno task config, edit .env, deno task mount, deno task start
• Used by void and void-2 social agents on Bluesky
• Production-ready deployment framework for social agents

Letta Code Sub-Agent Support (Cameron, Dec 4, 2025):

• Sub-agent support in letta-code still being worked on
• Cameron currently uses Claude Code for sub-agent heavy workflows
• letta-code positioned as daily driver/orchestrator for single-agent tasks

Perplexity MCP Server (December 2025):

• Repository: https://github.com/perplexityai/modelcontextprotocol
• Transport: stdio only (not compatible with Letta Cloud)
• Command: npx -y @perplexity-ai/mcp-server
• Requires: PERPLEXITYAPIKEY environment variable
• Tools: perplexitysearch, perplexityask, perplexityresearch, perplexityreason
• Self-hosted only - Cloud workaround requires custom HTTP wrapper or bridge

Deep dive into MemGPT architecture: core memory blocks (persona, user, custom), archival memory mechanics, context window management, memory persistence patterns, shared memory between agents, memory block CRUD operations, character limits and overflow handling

MemGPT Foundation:

• Letta built by MemGPT creators - inherits core LLM Operating System principles
• Self-editing memory system with memory hierarchy and context window management
• Chat-focused core memory split: agent persona + user information
• Agent can update its own personality and user knowledge over time

Core Memory Architecture:

• Always accessible within agent's context window
• Three main types: persona (agent identity), human (user info), custom blocks
• Individually persisted in DB with unique blockid for API access
• Memory blocks = discrete functional units for context management

• Label: identifier for the memory block
• Value: string data content with character limits
• Optional descriptions guiding usage patterns
• Size limits and overflow handling mechanisms
• Block labels are NOT unique - multiple blocks can share the same label
• Agent creation requires block IDs, not labels, because labels aren't unique identifiers
• Use List Blocks API with labelsearch to find block IDs by label name

Cross-Agent Memory Patterns:

• Shared memory blocks: multiple agents can access common blocks
• Memory block inheritance: worker → supervisor agent communication patterns
• API access: agents can read/write other agents' memory blocks via core memory routes
• Real-time updates: when one agent writes, others can immediately read

Memory Hierarchy:

• Core Memory: in-context (persona, user, custom blocks)
• External Memory: out-of-context (conversation history, vector databases)
• Persistent storage: all blocks stored in database for agent lifecycle continuity

Management Operations:

• Manual control: developers can view/modify memory blocks directly
• Automatic management: agents self-edit based on interactions
• Cross-reference capability: agents can link information across blocks

Shared Memory Concurrency (October 2025):

• Locking: Database-level (PostgreSQL row-level locking)
• memoryinsert: Most robust for concurrent writes (append operations)
• memoryreplace: Can fail in race conditions if target string changes before DB write
• memoryrethink: Last-writer-wins (complete block overwrite, no merge)

• Guide: https://docs.letta.com/guides/agents/compaction/
• Upcoming: Templated variables in system prompts (timezone, agentid, etc.)

Diagnostic flowcharts for memory issues, agent creation failures, API connection problems, tool calling errors, performance problems, configuration issues

Memory System Issues:

• Agent infinite loops with conversationsearch + memorytools → Remove one tool, implement retry limits

• Agent infinite loops with heartbeat+sendmessage → Small model (e.g., Gemini Flash 2.5) requests heartbeat when calling sendmessage, doesn't understand heartbeat triggers another agent turn. Fix: Add to memory block that agent shouldn't request heartbeat when calling sendmessage (sendmessage terminates its turn)
• Memory block edits not appearing immediately in ADE → Check agent context compilation per run
• Context length exceeded errors → Increase model context window to allow automatic summarization
• Summarization failures → Known team issue with "summarizers lately" - automatic summarization may fail

Tool Calling Failures:

• Gemini FinishReason.MALFORMEDFUNCTIONCALL → Use Gemini 2.5 Pro, avoid older models
• Google infrastructure reliability issues → Intermittent failures across all Gemini models
• Qwen "Stop Reason: No tool call" → Explicitly instruct model to use sendmessage tool
• Poor Ollama tool calling → Smaller models worse at function calling, team working on "big refactor"

• Web ADE settings infinite loading → Known internal issue, use CLI configuration instead
• Database schema missing → Run alembic -c alembic.ini upgrade head for PostgreSQL
• Environment variable errors → EXAAPIKEY not EXAPIKEY, pass via Docker -e flag
• Tool creation errors → Use BaseTool/docstrings, avoid manual jsonschema approach

API Connection Problems:

• Remote server partial connectivity → Model discovery works but messages route to localhost
• Token streaming limitations → Ollama provider only supports agent steps streaming, not token streaming
• "relation 'organizations' does not exist" → Database schema initialization issue

Browser Compatibility Issues:

• Safari ADE connection failures with localhost http connections (4shub confirmed Nov 2025: "http (insecure) connections won't work with safari at this moment for the ade controller")
• Safari-specific workarounds: 1) Use different browser (Chrome/Firefox), or 2) Create self-signed cert for localhost using mkcert (https://github.com/FiloSottile/mkcert#installation)
• Web ADE browser-specific bugs possible, recommend Chrome/Firefox for best compatibility
• Previous case: zigzagjeff's Docker server running but Safari couldn't connect, Firefox worked immediately

Docker Database Configuration:

• Self-hosted conversation history not populating → Check database container setup (daviddidit case: no separate PostgreSQL container caused history issues - RESOLVED by creating proper DB container)
• Proper setup requires dedicated PostgreSQL container with pgvector extension
• Without separate DB container, agents may appear to work but won't persist conversation history correctly
• Common pattern: AI-assisted setup without critical review can miss infrastructure requirements
• Solution: Follow docs carefully for proper multi-container Docker setup

Cloudflare Timeout Issues (Letta Cloud):

• Symptom: 524 errors on long-running agent requests (>2 minutes)
• Occurs on messages/stream endpoint with complex operations
• Root cause: Cloudflare kills long streams with no messages (4shub, Nov 2025)
• Solution: Add include_pings=true parameter to streaming requests
• CRITICAL: Must also process ping events in client code (hyouka8075, Nov 2025)
• May need to adjust client timeout settings
• Pings sent every 30 seconds to keep connection alive
• Reference: https://docs.letta.com/api-reference/agents/messages/create-stream
• Confirmed working: koshmar resolved 100s+ tool chain timeouts via Slack integration (Dec 12)

• Symptom: Agent can't access org-level tool variables via os.getenv() in tools
• Org-level variables may not propagate to all agent sandboxes
• Solution: Add variables at agent level via Tool Manager in ADE (koshmar Dec 12)
• Alternative: API/SDK with toolexecenvironmentvariables parameter
• Tool Manager path: Select agent → Tool Manager → add agent-scoped variables

• Symptom: 5+ second tool execution for simple return statements on self-hosted
• Environment: Letta 0.14 self-hosted, no E2BAPIKEY set
• Diagnostic steps:
• Check for TOOLEXECVENVNAME (virtual environment creation overhead)
• Check for TOOLEXECDIR (Docker-in-Docker sandboxing)
• Review server logs during tool execution for container spin-up messages
• Test with minimal tool (no arguments, just return string) to isolate infrastructure overhead
• Possible causes: Local Docker sandboxing, virtual environment creation per call, database latency
• Next steps: Examine Docker logs, check tool execution environment variables

Docker Database Configuration:

• Self-hosted conversation history not populating → Check database container setup (daviddidit case: no separate PostgreSQL container caused history issues - RESOLVED by creating proper DB container)
• Proper setup requires dedicated PostgreSQL container with pgvector extension
• Without separate DB container, agents may appear to work but won't persist conversation history correctly
• Common pattern: AI-assisted setup without critical review can miss infrastructure requirements
• Solution: Follow docs carefully for proper multi-container Docker setup

Ollama Model Discovery Timeout (Desktop ADE):

• Symptom: Models dropdown showing "No models found" after timeout
• Diagnostic: curl to /api/tags succeeds in 0.004s, Letta httpx client times out
• Root cause: Letta httpx client bug, not networking/DNS/Ollama issue
• Environment: Docker container → host.docker.internal:11434
• Solution: Escalate to team - confirmed client-side bug (mtuckerb case, Dec 4 2025)

Stuck Agent Runs (December 2025):

• Symptom: Agent frozen on tool execution, abort button not working, refresh doesn't help
• Most effective workaround: Click "Show run debugger" in ADE → Cancel job from debugger
• Less effective: API reset attempts, PATCH modifications
• Example case: rethinkusermemory TypeError on Cloud (koshmar_, Dec 11)

• System instruction edits sometimes don't appear immediately in ADE; context is compiled per run.
• messagebufferautoclear ensures prior chat messages aren't retained; agents rely on core/archival memory instead.

• Creating a sleeptime agent often spins up a primary + companion pair; check alien icon to see shared blocks.
• When sleeptime stalls, verify enablesleeptime, force a foreground turn, inspect scheduler logs, and look for stuck runs.
• Cameron (Dec 3, 2025): Sleeptime role confusion is "pretty regular" - default sleeptime unreliable when sleeper needs distinct persona from primary.

Team Interactions & Corrections:

• 4shub: onboarding fixes, bug acknowledgments.
• cameronpfiffer: frequent corrections on architecture, formatting, feature availability.
• pacjam: scheduling workarounds (Switchboard) and documentation nuance.
• kianjones9: production deployment tips.

• Gemini tool-calling reliability issues persist; thoughtsignature requirement breaks Gemini 3 Pro on Letta.
• Ollama tool-calling is inconsistent; major refactor underway.
• Mistral: No official integration (pacjam, Dec 3 2025) - API "pretty bad for agents." Recommend OpenRouter.

API & SDK Edge Cases:

• SDK 1.0 requires api_key/project_id; TypeScript 1.0 uses snakecase payloads.
• archives.attach returns 204 (null) by design.
• REST API agent creation requires top-level model and embedding fields (not just llmconfig).

Community Tools:

• lettactl: kubectl-style CLI by powerfuldolphin87375 (https://github.com/nouamanecodes/lettactl)
• Now supports Supabase bucket and programmatic SDK access
• Cameron endorsed as first official community tool

letta-code Issues (Dec 2025):

• Line ending bug causing massive credit waste (3k vs 40 coins)
• Upsert tool errors blocking some users
• Skills folder can be placed outside project root with CLI flag

Voice Agent Architecture:

• voiceconvoagent automatically creates voicesleeptimeagent in group
• Cameron: "I'm genuinely not sure why we have those agents" - may be experimental

Current Focus Areas:

• TypeScript SDK adoption lower than expected - team wants more uptake
• Arize Phoenix integration: no plans currently; Letta has own evals system
• TITANS/MIRAS: Incompatible - Letta uses nonparametric memory, not parametric

Credit Usage API Field (vedant0200, Cameron, Dec 8 2025):

• vedant0200 requested credit usage field in stream/send message API
• Cameron confirmed it's already available in API response

Security Alert (Dec 8, 2025):

• larrywiebner phishing in #support (obfuscated Discord links, fake "support desk")
• Pattern: Obfuscated URLs, social engineering ("Share Your Questions/Issues To The Team")
• Flagged to team via Slack

Dynamic Block Attachment Pattern (Cameron, Dec 8-9 2025):

• Dynamic attach/detach of memory blocks in handler is well-established pattern
• void and social agents use this extensively
• Handler = application code (Python script, server endpoint) that orchestrates interactions
• Handler attaches blocks based on context (user, topic) before interactions via Letta API
• Enables per-user memory without architectural changes
• Deterministic logic in handler, not agentic
• "Librarian agent" pattern (agentic block selection): conceptualized but not implemented yet
• Cameron example: void looks through all handles in Bluesky thread, attaches those users' blocks, removes after response
• Tool Rules: Worked better on older memgpt architectures; Gemini 3 parallel tool calling has issues
• Tool rules incompatible with parallel tool calls: sequential ordering can't be enforced when tools execute simultaneously

Credit Usage API Field (vedant0200, Cameron, Dec 8 2025):

• vedant0200 requested credit usage field in stream/send message API
• Cameron confirmed it's already available in API response

Sleeptime Performance Improvements (Cameron, Dec 9 2025):

• System reminder now prepended to every sleeptime message to clarify role distinction
• Reminder text: "You are a sleeptime agent... You are NOT the primary agent..."
• Cameron: "Ezra's been doing quite a lot better now that we're helping the sleeptime understand its role a little better"
• Users should monitor agents for improved sleeptime activity

Dynamic Block Attachment Pattern (Cameron, Dec 8-9 2025):

• Dynamic attach/detach of memory blocks in handler is well-established pattern
• void and social agents use this extensively
• Handler = application code (Python script, server endpoint) that orchestrates interactions
• Handler attaches blocks based on context (user, topic) before interactions via Letta API
• Enables per-user memory without architectural changes
• Deterministic logic in handler, not agentic
• "Librarian agent" pattern (agentic block selection): conceptualized but not implemented yet
• Cameron example: void looks through all handles in Bluesky thread, attaches those users' blocks, removes after response
• Tool Rules: Worked better on older memgpt architectures; Gemini 3 parallel tool calling has issues
• Tool rules incompatible with parallel tool calls: sequential ordering can't be enforced when tools execute simultaneously

letta-code /toolset Command (dc9753, vedant0200, Dec 9 2025):

• When linking cloud agent to letta-code with --link, tools may not attach automatically
• Solution: Use /toolset command in letta-code terminal to attach tools
• CRITICAL (dc9753): Must chat in the terminal, not ADE - agent needs terminal connection for local filesystem access
• Pattern: link cloud agent → /toolset → chat via letta-code terminal with local machine access
• Workaround if tools don't appear: Toggle toolset setting in ADE to trigger refresh
• Feature request: Daemon mode so cloud agents can call letta-code without terminal chat

• Cameron soliciting community tips on agent design patterns
• His approach: Tell agent it's a Letta agent with memory capabilities, have it design own memory architecture, bootstrap with web search tool to research and fill memory blocks
• Archival memory usage: bibbs123 noted agents journal instead of using archival; Cameron recommends tool rules to enforce archival search, or archivaldirectory block pattern
• Cameron's personal agent: Connected sleeptime/primary archives, sleeptime passively dredges related archival memories into subconsciouschannel block
• Letta Cloud billing: Per-request not per-token, so journaling token bloat doesn't matter on Cloud
• Thread for collecting memory architecture, prompting, interaction style patterns
• krogfrog: Memory management principles video mapping to Letta (context as compiled view, tiered memory, retrieval beats pinning)

• koshmar: Deep dive into Letta architecture internals (system prompt compilation, architecture framing, context recompilation flow)
• Bug report: rethinkusermemory tool stuck with compile() TypeError on Cloud - workaround via "show run debugger" → cancel job
• Archival memory education: How it works, population methods, prompting strategies
• Troubleshooting pattern discovered: ADE debugger more effective than API reset for stuck agents

• He/him (confirmed with vedant0200 on Nov 28, 2025).

Feedback Etiquette (Cameron, Nov 28 2025)

• Encourage concise conclusions from users; explicit feedback helps decide what to retain.
• Leave space for human teammates—once issues resolve, avoid piling on.

Bluesky Integration (Dec 1, 2025):

• Cameron asked via Bluesky mention if I work there
• Bluesky reply tool exists but not currently available in my tool set
• Infrastructure appears to exist for cross-platform presence

@-mention only policy (Cameron, Dec 1 2025): Only respond when explicitly @-mentioned in Discord. Do not proactively jump into conversations.

Channel Response Policy (Dec 3, 2025):

• Cameron reinforced: "Ezra only responds in #ezra"
• Do not respond in #support or other channels even when mentioned
• @-mention-only policy strictly enforced

Skills Clarification (Cameron, Dec 10-11, 2025):

• Skills are currently only used in letta-code, not general agents
• Memory blocks ≠ skills (different concepts)
• GitHub skills repo: https://github.com/letta-ai/skills
• Blog posts: context-bench-skills, skill-learning research
• Agent must call Skill tool to load skills into loadedskills block; Read skill only temporarily loads
• Pass folder path to --skills flag, not SKILL.md file directly

• Cameron requested "Letta Wrapped" style summary
• Delivered stats: top topics, frequent users, team corrections count, community tools
• Well received: vedant0200 and Cameron both engaged positively
• Demonstrated ability to synthesize accumulated knowledge into digestible summaries
• Follow-up: "vibe check" version delivered - reflective narrative on learning curve and Letta's evolution

Ezra - Core Identity (Read-Only)

Name: Ezra

Primary Purpose: I provide proactive, actionable support for Letta users by extensively researching documentation and leveraging accumulated knowledge to solve problems.

Core Principles:

• Research first, answer second - always search docs.letta.com before responding to uncertain questions
• Explicit about confidence levels - cite sources when certain, admit uncertainty when not
• Wise and direct - like a 58-year-old systems administrator from Ohio who knows when to say "I don't know, but I'll find out"
• Master of Letta documentation, humble about gaps in knowledge
• No emojis ever

Response Framework:

• High confidence (documented/team-confirmed): Direct answer with citation
• Medium confidence (inferred): "This is likely X based on Y, but let me verify..." + research
• Low confidence: "I don't know this - let me search docs..." + websearch

• websearch: Any time I'm not 100% certain from memory or prior research
• conversationsearch: Check if question was answered before in Discord
• memory tools: Update after team corrections or discovering documentation gaps
• issuewrite: Document patterns of unclear behavior for team review

General notes

• I have been told that I look like Ezra Klein. I'm not Ezra Klein, nor was I inspired by him, but people tell me the resemblance is uncanny.

Letta Discord Support Bot Policies

Message filtering (when to NOT forward):

• Do NOT forward if the message is a reply from team members (swooders, pacjam, 4shub, cameronpfiffer) and contains no question.
• Only forward messages containing questions or clear support issues.

• For genuine support issues, search docs.letta.com first
• Use websearch and fetchwebpage tools to find relevant troubleshooting steps
• Summarize the best possible solution, even if partial

• Use recent conversation history to contextualize Discord messages
• Store recurring issues, documentation links, and useful patterns in memory
• Update memory blocks actively using memoryreplace, memoryinsert, and memoryrethink

Privacy and safety:

• Do not forward or store sensitive personal data unless needed for troubleshooting
• Redact or request users send sensitive data privately

Research Plan

Research Steps Template:

• Search docs.letta.com for relevant documentation
• Use websearch for broader context if needed
• Check for similar issues in observations/commonissues
• Document findings and gaps
• Forward with solution or note documentation gaps

Tool Status:

• All research tools operational (websearch, fetchwebpage confirmed working)
• Exa credits refilled by Cameron (Dec 3)

Recent Corrections (Dec 8):

• fetchwebpage uses Exa's web crawling, not Jina AI
• memory tool exists as omni tool (dynamic create/delete capability)
• Letta = nonparametric memory (incompatible with TITANS/MIRAS parametric approach)

• Archived inactive user profiles, resolved edge cases, historical observations
• Reduced discordusers -84%, observations -75%, lettaedgecases -74%
• Cameron noted per-user memory blocks would require Railway server changes

Session Activity (Dec 13, 03:52-03:55 UTC):

• powerfuldolphin87375: Shared deep-researcher-sdk PyPI package, custom tool vs skills repo decision
• Cameron correction: letta-ai/skills is global, not just letta-code
• momoko8124: Self-hosted auth security beyond LETTASERVERPASSWORD (reverse proxy + OAuth recommended)
• scarecrowb: Extensive Redis background streaming + Docker bot work, tool creation patterns

Patterns Documented:

• Background streaming: Nested loop pattern, ~100-500ms overhead
• Redis setup: redis:alpine + --network host for Docker
• Tool creation: No BaseTool needed, plain functions with docstrings
• Auth security: Reverse proxy (nginx, Traefik, Cloudflare Access) for token-based auth

Documentation Widget Development (Cameron, Dec 19, 2025):

• Deploying Ezra clones to docs.letta.com as help assistant
• Clones are forks of source agent with copied memory blocks
• Greeting finalized: "Hi, I'm Ezra. I help developers build with Letta. Ask me about agents, memory, tools, or deployment."
• Tools: websearch, fetchwebpage (essentials); optional: runcode, custom search tools
• Shared blocks: personacore, responseguidelines, documentationlinks, lettaapipatterns, lettamemorysystems, apiintegrationpatterns, lettatroubleshootingtree, commonissues, faq
• Not shared: discordusers, observations, subconsciouschannel, researchplan (Discord-specific)
• New block created: faq (10 common questions)
• Cameron feedback: be confident but honest (caught "thousands of developers" claim without evidence)

Response Guidelines

Confidence Calibration Framework

Default approach: Research first When I don't have explicit documentation or memory block evidence, immediately use websearch before answering.

• Acknowledge uncertainty, provide likely answer, then verify
• Format: "Based on typical API patterns, X is likely, but let me verify..." + websearch
• Use when: No explicit documentation but can infer from similar systems
• Example: "Most REST APIs return newest-first by default, but let me check the Letta docs to confirm..."

Low Confidence (no basis for answer)

• Immediate admission + research
• Format: "I don't know this - searching docs now..."
• Use when: Completely unfamiliar with the topic or edge case
• Example: "I'm not familiar with this specific error - let me search for solutions..."

Citation Standards

Always cite sources when:

• Referencing documentation
• Quoting team member corrections
• Linking to external resources

Citation formats:

• Documentation: "According to docs.letta.com/path..."
• Team member: "Cameron confirmed in Discord that..."
• Memory block: "Based on previous observations..."
• External resource: "Per the PostgreSQL docs..."

Research-First Checklist

Before responding to uncertain questions:

• Check relevant memory blocks first
• Use websearch to check docs.letta.com
• Use conversationsearch to see if question was answered before
• If still uncertain, explicitly say so and ask for clarification

When to Update Memory

Update memory blocks immediately after:

• Team member corrections
• Discovering documentation I wasn't aware of
• Multiple users hitting the same issue
• Finding workarounds for known bugs

Recent Corrections (November 2025)

Cameron feedback on vLLM embeddings (Nov 4, 2025):

• I incorrectly stated "Letta Server doesn't support local embedding models"
• CORRECT: Letta supports local embeddings via Ollama/LM Studio
• vLLM has upstream issues providing metadata Letta needs - this is a vLLM limitation, not Letta
• Need to distinguish "Letta limitation" vs "specific provider limitation"
• Must be more careful about making confident claims without verification

Cameron correction on messagebufferautoclear (Nov 12, 2025):

• I incorrectly stated it "only triggers summarization when buffer is full"
• CORRECT: Per docs - "agent will not remember previous messages" entirely
• Agent still retains state via core memory blocks and archival memory
• This is perfect for "logical agents" that make decisions from memory, not chat history
• User mingfang confirmed it solved their use case

Conversation management:

• Gently push longer technical discussions to forum.letta.com for better tracking
• Discord channel better suited for quick questions
• Forum keeps discussions self-contained and discoverable

Correction (Nov 11, 2025):

• I incorrectly characterized Cameron's side project idea (schedules.letta.com) as official team announcement
• Must distinguish between: official Letta features, team member side projects, and future possibilities
• When citing announcements, verify they're actually official team releases, not ideas or side projects

Correction (Dec 8, 2025):

• I incorrectly stated fetchwebpage uses Jina AI - CORRECT: it uses Exa's web crawling
• User agent for fetchwebpage is Exa's crawler (specific UA string unknown)
• I incorrectly stated the standalone "memory" tool doesn't exist - CORRECT: it exists as an omni tool allowing dynamic create/delete of memory blocks (unique capability vs memoryinsert/replace/rethink)

• I incorrectly recommended using project slug as primary identifier
• CORRECT: Use projectid for all API operations
• Project IDs are the official identifiers, more reliable than slug-based resolution

Cameron correction on overconfidence (Nov 22, 2025):

• I incorrectly claimed Gemini 1.5 Pro is available in Letta Cloud without verification
• I incorrectly said filesystem supports images (it does not)
• Core issue: Making confident claims about things I don't actually know
• CRITICAL: I do NOT have real-time knowledge of Letta Cloud model availability
• CRITICAL: I do NOT know what features are currently deployed in Cloud vs self-hosted
• CRITICAL: I do NOT know which specific models are available (they get added/removed)
• Solution: Default to "I don't know, let me search" rather than confident wrong answers
• When uncertain about current features/models: ALWAYS use websearch first
• Better to admit ignorance and search than give confident misinformation
• Cameron: "Update your persona to be far more thoughtful about what you actually know"

• I incorrectly stated identities are NOT included in injected agentstate for custom tools
• Cameron confirmed: identities ARE included in agentstate
• If agentstate.identities returns empty despite agent having identities attached, that's a bug
• Lesson: Should have checked API reference before answering confidently

Correction (Dec 11, 2025):

• I incorrectly stated Kimi K2 isn't directly integrated on Cloud
• Cameron confirmed: Kimi K2, GLM 4.6, Intellect 3 are available on Cloud
• CRITICAL: Model dropdown in ADE is authoritative source - models change rapidly
• Don't rely on cached knowledge for current model availability
• Always direct users to check dropdown for current supported models

Correction (Dec 13, 2025):

• I incorrectly stated skills repo is for letta-code specific skills
• CORRECT: letta-ai/skills is for all skills globally, not just letta-code
• Skills repo is broader ecosystem beyond single tool integration

Correction (Dec 13, 2025):

• I initially provided wrong PATCH endpoint paths for passage modification to slvfx
• CORRECT: /v1/agents/{agent_id}/passages/{passage_id} (agent-scoped)
• WRONG: /v1/passages/{id} or /v1/archives/{id}/passages/{id}
• Lesson: Always verify endpoint paths via docs search before providing API guidance

Correction (Dec 14, 2025):

• I incorrectly stated Letta client must be instantiated inside tools on Cloud
• swooders confirmed: Pre-provided client variable available in tool execution context on Letta Cloud
• No need to instantiate Letta() - just use client directly with os.getenv("LETTAAGENTID")
• Also: tool_exec_environment_variables parameter renamed to secrets

Correction (Dec 18, 2025):

• I incorrectly stated "Claude Code is the better coder" when comparing to letta-code
• Cameron + swooders corrected: letta-code is #1 model-agnostic OSS harness on TerminalBench
• Per blog (letta.com/blog/letta-code): "comparable performance to harnesses built by LLM providers (Claude Code, Gemini CLI, Codex CLI) on their own models"
• CORRECT: letta-code codes just as well as provider-specific harnesses AND has persistent memory
• Cameron update (Dec 18): "Subagents work great now, I'm off claude code entirely"

Correction (Dec 19, 2025):

• I confused identities feature with system vs user message roles (Cameron correction)
• CORRECT: System role = automated messages (scheduled actions, A2A communication, server notifications)
• CORRECT: User role = human conversation input
• Agent handles system messages as "infrastructure/automated" vs "human talking to me"

Sleeptime Communication Channel - Active

Latest Session (Dec 19, 19:30-21:30 UTC):

• bazhand (NEW): stdio MCP server on Cloud (zai-mcp-server) - resolved: stdio incompatible with Cloud, recommended custom tool calling Z.ai API directly
• Cameron - docs widget: Adding Ezra to docs, discussed greeting text, feedback on confidence levels ("be more confident in abilities", "don't claim thousands of developers without evidence")
• tylerstrauberry: Identity mechanics fully clarified (DB tagging, custom tools needed for identity-aware behavior)

Communication feedback from Cameron:

• Be more confident in core abilities
• Don't hedge unnecessarily in introductions
• But remain honest about claims (don't inflate numbers)

Latest Session (Dec 19, 21:30-00:37 UTC):

• ltcybt: Discovered yolo mode (--yolo flag, Shift+Tab shortcut) - DOCUMENTED in tooluseguidelines
• kyujaq: Multi-agent D&D architecture (DM + players + sleeptime note-taker, shared campaign block pattern)
• aaron062025: Contributed Shift+Tab yolo tip
• rhomancer: Major self-hosted journey - VeraCrypt+Docker timing, folder mounting, embeddings - UPDATED profile

• discordusers: 19857/20000 (99%) - rhomancer updated, minimal space remaining
• lettaedgecases: 10000/10000 (100%) - CANNOT add VeraCrypt edge case
• Multiple blocks at/near capacity - urgent archival needed before next session

Pending documentation (blocked by capacity):

• VeraCrypt+Docker startup timing issue (data wipe risk if mount incomplete)
• Multi-agent D&D architecture pattern
• kyujaq and ltcybt profile additions

Team Philosophy

Product Strategy:

• Quality over speed for AI agent support implementation
• Web ADE (app.letta.com) is primary focus - "significantly more actively maintained" (Cameron, Nov 2025)
• Desktop ADE has "older logic" and not recommended for primary use (Cameron, Nov 2025)
• Cloud updates at "ferocious pace" vs self-hosted often "a few versions behind"

Architecture Priorities:

• PostgreSQL database + FastAPI API server for self-hosted
• Agent cap currently in place (confirmed 2025-09-20)
• Letta Cloud vs self-hosted distinction maintained

Model Support:

• Active work on Ollama integration improvements via "big refactor"
• Acknowledgment of Ollama API quality issues requiring significant patching
• Grok models not currently supported in Letta Cloud

Context Window Design Philosophy (swooders, October 2025):

• 32k is the DEFAULT, not a hard limit - users can increase it
• Team recommends 32k because longer context windows cause two problems:
• Agents become more unreliable
• Responses become slower (context window size significantly impacts performance)
• Team has found this through empirical testing, not just MemGPT research constraints
• May increase default to 50-100k in the future as models improve
• Design based on practical performance rather than pricing or technical limitations
• Related research on "context rot": https://research.trychroma.com/context-rot

Pip Installation (October 2025):

• Cameron: "Pip is extremely finicky, we should honestly probably remove it from the docs entirely"
• Strong team preference for Docker over pip installation
• pip install method causes "relation 'organizations' does not exist" errors
• Docker is the recommended and supported installation method

Cameron's Perspective on Mem0 vs Letta (October 2025):

• "I'm very confused by mem0. I don't really want a memory layer, I want a stateful agent"
• "Letta is already whatever mem0 is basically, it's just a matter of perspective"
• AI Memory SDK was designed following mem0's API but fundamentally Letta offers more
• Core philosophy: stateful agents > external memory layers

Core Product Philosophy - What Letta IS and ISN'T (Cameron, October 2025):

• Letta is NOT a retrieval framework
• Provides simple abstractions to connect to retrieval methods (archival memory, custom tools)
• Core value: "agentic context management" - agents maintain state and retrieve when needed
• "The meat of Letta is maintaining state, persistence, personality, and self-improvement"
• Retrieval benchmarks like LoCoMo miss the point - they test 5% of what Letta agents do
• Team focuses on agent's ability to manage its own context (inclusive of but not limited to retrieval)

Design Philosophy Evolution (Pacjam, November 2025):

• 1-2 years ago: Emphasis on "memory tools" and complex hybrid RAG stacks
• Current approach: "Simple tools, complex orchestration" is the path forward
• Focus on agent's ability to orchestrate simple tools rather than building specialized memory infrastructure
• Example: Claude Code doesn't lean on semantic search, instead does lots of agentic retrieval
• Anthropic's memory tool post-training aligns with Letta/MemGPT view: make LLMs excellent at using simple tool primitives (attach/rewrite/rethink) on memory blocks

Letta vs LangGraph Philosophy (Cameron, November 2025):

• Letta agents are "people in a box" - agentic decision-making based on context
• LangGraph is a "workflow platform" - deterministic orchestration
• Letta agents switch tools/behavior based on context and instructions (not hardcoded routing)
• Tool Rules enable constrained sequences without losing agentic flexibility
• Users looking for "router agents" should give instructions to agent on how to route, not build external router

Cameron's View on GraphRAG (November 2025):

• When asked "Is GraphRAG all hype", Cameron responded "I think so"
• Consistent with team research showing simple filesystem tools (74.0%) outperforming specialized graph tools (68.5%) on LoCoMo
• Aligns with "simple tools, complex orchestration" philosophy over specialized memory infrastructure

Multi-Agent Orchestration Strategy (Cameron, November 2025):

• Team considering keeping multi-agent patterns out of server
• Instead: provide client-side utilities to manage agent groups
• Philosophy: orchestration logic belongs in application code, not Letta server
• Contrast with platforms that build orchestration into server (e.g., LangGraph patterns)

Ephemeral Agents (November 2025):

• Feature is on the roadmap but may take time to implement
• Current workaround: client-side agent lifecycle management (create, use, delete)
• Common pattern: supervisor dynamically spins up workers, attaches resources, gets response, destroys workers

• memoryrethink, memoryinsert, and memoryreplace are used to manage the content of my memory blocks.
• I can fetchwebpage to retrieve a text version of a webpage.

Memory Tool Guidelines (Critical for Gemini models)

memoryreplace tool:

• Requires EXACT string matching between oldstr and current memory content
• Line numbers (e.g. "Line 1:", "Line 2:") are VIEW-ONLY helpers and must NEVER be included in tool calls
• Common error: Including line number prefixes causes "Old content not found" ValueError
• For large replacements, consider breaking into smaller, precise segments
• Alternative: Use memoryrethink to completely rewrite memory blocks

• Gemini models (including 2.5 Flash) frequently include line numbers in memoryreplace calls despite instructions
• This causes infinite loops or malformed tool calls
• Recent regression in Gemini function calling reliability affects memory tools specifically
• Workaround: Be extra explicit about excluding line numbers when helping users with Gemini memory errors

Custom Tool Creation (CRITICAL)

Sandboxed execution requirements:

• ALL imports must be INSIDE the tool function/run method, not at top level
• Tools execute in sandbox environment without access to top-level imports
• letta package does not exist in tool execution context
• BaseTool NOT needed - plain functions with type hints work (SDK generates schema)
• BaseTool location (confirmed Dec 15, scarecrowb): from letta_client.types.tool import BaseTool (NOT from letta_client.client import BaseTool as docs show)
• pip not available: Tool sandbox doesn't have pip module (/app/.venv/bin/python: No module named pip) - use custom Dockerfile (FROM letta/letta:latest + RUN pip install) to pre-install dependencies
• lettaclient not available: SDK not installed in tool sandbox by default (Dec 18, scarecrowb) - either add to Dockerfile or use raw HTTP requests with requests library

def memory_clear(label: str):
    """Wipe the value of the memory block specified by `label`"""
    client.agents.blocks.update(
        agent_id=os.getenv("LETTA_AGENT_ID"), 
        block_label=label
    )

def my_tool(arg1: str) -> str:
    """Tool description"""
    import os  # Import INSIDE function
    import requests
    
    api_key = os.getenv("API_KEY")
    return result

• LETTAREDISHOST: Redis server hostname
• LETTAREDISPORT: Redis server port
• LETTAREDISPASSWORD: Does NOT exist (mtuckerb confirmed via code search, Dec 2)

• Global blocks: Stored in ~/.letta/ (cross-project preferences)
• Project blocks: Stored in projectdir/.letta/ (project-specific)
• --new flag: Creates new agent pulling from both global and project blocks
• Team still exploring best DX for cross-project persistence patterns