# sanctumos/letta architecture

> Architecture diagram of the GitHub repository sanctumos/letta, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanctumos/letta
- Repository: https://github.com/sanctumos/letta

## Overview

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: [`letta/agents/agent_loop.py`](https://github.com/sanctumos/letta/blob/main/letta/agents/agent_loop.py) (Agent loop), [`letta/services/agent_manager.py`](https://github.com/sanctumos/letta/blob/main/letta/services/agent_manager.py) (Agent management), [`letta/server/server.py`](https://github.com/sanctumos/letta/blob/main/letta/server/server.py) (Server operations), [`letta/server/rest_api/app.py`](https://github.com/sanctumos/letta/blob/main/letta/server/rest_api/app.py) (REST API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and interfaces"]
  node_rest["REST API<br/>[app.py]"]
  node_ws["WebSocket API<br/>[server.py]"]
  node_server["Server operations<br/>[server.py]"]
  node_streaming["Stream adapters"]
end

subgraph group_agents["Agent runtime"]
  node_agent_mgr["Agent management<br/>[agent_manager.py]"]
  node_agent_runtime["Agent loop<br/>[agent_loop.py]"]
  node_run_mgr["Run management<br/>[run_manager.py]"]
  node_memory["Agent memory<br/>[memory.py]"]
  node_llm_factory["LLM dispatch<br/>[llm_client.py]"]
  node_llm_clients["Provider clients<br/>[llm_client_base.py]"]
end

subgraph group_capabilities["Agent capabilities"]
  node_tool_exec["Tool execution"]
  node_tool_types["Tool definitions<br/>[tool.py]"]
  node_groups["Multi-agent groups"]
  node_files["File processing<br/>[file_processor.py]"]
  node_sources["Source connectors<br/>[connectors.py]"]
  node_mcp["MCP integration<br/>[mcp_manager.py]"]
end

subgraph group_platform["Platform services"]
  node_batch["Batch jobs"]
  node_db[("Relational storage<br/>[db.py]")]
  node_models["Domain schemas<br/>[agent.py]"]
  node_message_schema["Message schemas<br/>[message.py]"]
  node_config["Runtime settings<br/>[settings.py]"]
  node_tracing["Tracing<br/>[tracing.py]"]
end

node_developer(("API user"))

node_developer -->|"creates and messages"| node_rest
node_rest -.->|"dispatches requests"| node_server
node_server -.->|"manages agents"| node_agent_mgr
node_agent_mgr -.->|"runs agent"| node_agent_runtime
node_agent_runtime -.->|"records runs"| node_run_mgr
node_agent_runtime -.->|"uses memory"| node_memory
node_agent_runtime -.->|"requests completion"| node_llm_factory
node_llm_factory -->|"selects provider"| node_llm_clients
node_agent_runtime -.->|"invokes tools"| node_tool_exec
node_tool_exec -->|"executes definitions"| node_tool_types
node_agent_runtime -.->|"coordinates agents"| node_groups
node_agent_mgr -.->|"supports file workflows"| node_files
node_agent_mgr -.->|"supports sources"| node_sources
node_server -.->|"uses MCP tools"| node_mcp
node_streaming -->|"adapts streamed output"| node_llm_clients
node_batch -->|"stores batch state"| node_db
node_agent_mgr -->|"persists agent state"| node_db
node_server -->|"uses agent schemas"| node_models
node_agent_runtime -.->|"uses message types"| node_message_schema
node_config -.->|"configures providers"| node_llm_clients
node_rest -->|"instruments requests"| node_tracing
node_ws -->|"dispatches operations"| node_server

click node_rest "https://github.com/sanctumos/letta/blob/main/letta/server/rest_api/app.py"
click node_ws "https://github.com/sanctumos/letta/blob/main/letta/server/ws_api/server.py"
click node_server "https://github.com/sanctumos/letta/blob/main/letta/server/server.py"
click node_agent_mgr "https://github.com/sanctumos/letta/blob/main/letta/services/agent_manager.py"
click node_agent_runtime "https://github.com/sanctumos/letta/blob/main/letta/agents/agent_loop.py"
click node_run_mgr "https://github.com/sanctumos/letta/blob/main/letta/services/run_manager.py"
click node_memory "https://github.com/sanctumos/letta/blob/main/letta/memory.py"
click node_llm_factory "https://github.com/sanctumos/letta/blob/main/letta/llm_api/llm_client.py"
click node_llm_clients "https://github.com/sanctumos/letta/blob/main/letta/llm_api/llm_client_base.py"
click node_tool_exec "https://github.com/sanctumos/letta/blob/main/letta/services/tool_executor/tool_execution_manager.py"
click node_tool_types "https://github.com/sanctumos/letta/blob/main/letta/schemas/tool.py"
click node_groups "https://github.com/sanctumos/letta/blob/main/letta/groups/dynamic_multi_agent.py"
click node_files "https://github.com/sanctumos/letta/blob/main/letta/services/file_processor/file_processor.py"
click node_sources "https://github.com/sanctumos/letta/blob/main/letta/data_sources/connectors.py"
click node_mcp "https://github.com/sanctumos/letta/blob/main/letta/services/mcp_manager.py"
click node_streaming "https://github.com/sanctumos/letta/blob/main/letta/adapters/simple_llm_stream_adapter.py"
click node_batch "https://github.com/sanctumos/letta/blob/main/letta/services/llm_batch_manager.py"
click node_db "https://github.com/sanctumos/letta/blob/main/letta/server/db.py"
click node_models "https://github.com/sanctumos/letta/blob/main/letta/schemas/agent.py"
click node_message_schema "https://github.com/sanctumos/letta/blob/main/letta/schemas/message.py"
click node_config "https://github.com/sanctumos/letta/blob/main/letta/settings.py"
click node_tracing "https://github.com/sanctumos/letta/blob/main/letta/otel/tracing.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rest,node_ws,node_server,node_streaming,node_developer toneBlue
class node_agent_mgr,node_agent_runtime,node_run_mgr,node_memory,node_llm_factory,node_llm_clients toneAmber
class node_tool_exec,node_tool_types,node_groups,node_files,node_sources,node_mcp toneMint
class node_batch,node_db,node_models,node_message_schema,node_config,node_tracing toneRose
```

## Components

### API and interfaces

- [REST API](https://github.com/sanctumos/letta/blob/main/letta/server/rest_api/app.py): `letta/server/rest_api/app.py`
- [WebSocket API](https://github.com/sanctumos/letta/blob/main/letta/server/ws_api/server.py): `letta/server/ws_api/server.py`
- [Server operations](https://github.com/sanctumos/letta/blob/main/letta/server/server.py): `letta/server/server.py`
- [Stream adapters](https://github.com/sanctumos/letta/blob/main/letta/adapters/simple_llm_stream_adapter.py): `letta/adapters/simple_llm_stream_adapter.py`

### Agent runtime

- [Agent management](https://github.com/sanctumos/letta/blob/main/letta/services/agent_manager.py): `letta/services/agent_manager.py`
- [Agent loop](https://github.com/sanctumos/letta/blob/main/letta/agents/agent_loop.py): `letta/agents/agent_loop.py`
- [Run management](https://github.com/sanctumos/letta/blob/main/letta/services/run_manager.py): `letta/services/run_manager.py`
- [Agent memory](https://github.com/sanctumos/letta/blob/main/letta/memory.py): `letta/memory.py`
- [LLM dispatch](https://github.com/sanctumos/letta/blob/main/letta/llm_api/llm_client.py): `letta/llm_api/llm_client.py`
- [Provider clients](https://github.com/sanctumos/letta/blob/main/letta/llm_api/llm_client_base.py): `letta/llm_api/llm_client_base.py`

### Agent capabilities

- [Tool execution](https://github.com/sanctumos/letta/blob/main/letta/services/tool_executor/tool_execution_manager.py): `letta/services/tool_executor/tool_execution_manager.py`
- [Tool definitions](https://github.com/sanctumos/letta/blob/main/letta/schemas/tool.py): `letta/schemas/tool.py`
- [Multi-agent groups](https://github.com/sanctumos/letta/blob/main/letta/groups/dynamic_multi_agent.py): `letta/groups/dynamic_multi_agent.py`
- [File processing](https://github.com/sanctumos/letta/blob/main/letta/services/file_processor/file_processor.py): `letta/services/file_processor/file_processor.py`
- [Source connectors](https://github.com/sanctumos/letta/blob/main/letta/data_sources/connectors.py): `letta/data_sources/connectors.py`
- [MCP integration](https://github.com/sanctumos/letta/blob/main/letta/services/mcp_manager.py): `letta/services/mcp_manager.py`

### Platform services

- [Batch jobs](https://github.com/sanctumos/letta/blob/main/letta/services/llm_batch_manager.py): `letta/services/llm_batch_manager.py`
- [Relational storage](https://github.com/sanctumos/letta/blob/main/letta/server/db.py): `letta/server/db.py`
- [Domain schemas](https://github.com/sanctumos/letta/blob/main/letta/schemas/agent.py): `letta/schemas/agent.py`
- [Message schemas](https://github.com/sanctumos/letta/blob/main/letta/schemas/message.py): `letta/schemas/message.py`
- [Runtime settings](https://github.com/sanctumos/letta/blob/main/letta/settings.py): `letta/settings.py`
- [Tracing](https://github.com/sanctumos/letta/blob/main/letta/otel/tracing.py): `letta/otel/tracing.py`

### Other components

- **API user**

## Connections

- API user → REST API: creates and messages (evidence: `README.md`)
- REST API → Server operations: dispatches requests (evidence: `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 (evidence: `letta/llm_api/llm_client.py`)
- Agent loop → Tool execution: invokes tools
- Tool execution → Tool definitions: executes definitions (evidence: `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 (evidence: `letta/adapters/simple_llm_stream_adapter.py`)
- Batch jobs → Relational storage: stores batch state (evidence: `letta/services/llm_batch_manager.py`)
- Agent management → Relational storage: persists agent state (evidence: `letta/services/agent_manager.py`)
- Server operations → Domain schemas: uses agent schemas (evidence: `letta/server/server.py`)
- Agent loop → Message schemas: uses message types
- Runtime settings → Provider clients: configures providers (evidence: `letta/llm_api/llm_client_base.py`)
- REST API → Tracing: instruments requests (evidence: `letta/server/rest_api/app.py`)
- WebSocket API → Server operations: dispatches operations (evidence: `letta/server/ws_api/server.py`)
