How sanctumos/letta works
Letta is a platform for persistent, memory-enabled agents, exposed as an API and also used by a local CLI. The principal workflow is to create an agent, send it a message, and receive a response; agents may call tools and retain state across interactions. The repository also includes multi-agent groups, file and source ingestion, MCP integrations, streaming, and batch jobs. The graph captures these documented capabilities and major runtime layers; some connections are dashed where the supplied excerpts do not show the wiring.
Main entry points: agent_loop.py Agent loop · agent_manager.py Agent management · server.py Server operations · app.py REST API
Components 23
API and interfaces
- REST API
letta/server/rest_api/app.py - WebSocket API
letta/server/ws_api/server.py - Server operations
letta/server/server.py - Stream adapters
letta/adapters/simple_llm_stream_adapter.py
Agent runtime
- Agent management
letta/services/agent_manager.py - Agent loop
letta/agents/agent_loop.py - Run management
letta/services/run_manager.py - Agent memory
letta/memory.py - LLM dispatch
letta/llm_api/llm_client.py - Provider clients
letta/llm_api/llm_client_base.py
Agent capabilities
- Tool execution
letta/services/tool_executor/tool_execution_manager.py - Tool definitions
letta/schemas/tool.py - Multi-agent groups
letta/groups/dynamic_multi_agent.py - File processing
letta/services/file_processor/file_processor.py - Source connectors
letta/data_sources/connectors.py - MCP integration
letta/services/mcp_manager.py
Platform services
- Batch jobs
letta/services/llm_batch_manager.py - Relational storage
letta/server/db.py - Domain schemas
letta/schemas/agent.py - Message schemas
letta/schemas/message.py - Runtime settings
letta/settings.py - Tracing
letta/otel/tracing.py
Other components
- API user
Connections 22
- API user → REST API: creates and messages
README.md - REST API → Server operations: dispatches requests
letta/server/rest_api/app.py - Server operations → Agent management: manages agents
- Agent management → Agent loop: runs agent
- Agent loop → Run management: records runs
- Agent loop → Agent memory: uses memory
- Agent loop → LLM dispatch: requests completion
- LLM dispatch → Provider clients: selects provider
letta/llm_api/llm_client.py - Agent loop → Tool execution: invokes tools
- Tool execution → Tool definitions: executes definitions
letta/services/tool_executor/tool_execution_manager.py - Agent loop → Multi-agent groups: coordinates agents
- Agent management → File processing: supports file workflows
- Agent management → Source connectors: supports sources
- Server operations → MCP integration: uses MCP tools
- Stream adapters → Provider clients: adapts streamed output
letta/adapters/simple_llm_stream_adapter.py - Batch jobs → Relational storage: stores batch state
letta/services/llm_batch_manager.py - Agent management → Relational storage: persists agent state
letta/services/agent_manager.py - Server operations → Domain schemas: uses agent schemas
letta/server/server.py - Agent loop → Message schemas: uses message types
- Runtime settings → Provider clients: configures providers
letta/llm_api/llm_client_base.py - REST API → Tracing: instruments requests
letta/server/rest_api/app.py - WebSocket API → Server operations: dispatches operations
letta/server/ws_api/server.py