Resource Types & Shared Resources

Everything lettactl manages — agents, memory blocks, folders, archives, tools, and MCP servers — all powered by the Letta platform's stateful agent infrastructure.

Letta Under the Hood

Every resource lettactl manages maps directly to Letta's server-side primitives. Agents are Letta agents with persistent memory. Blocks are Letta's core memory system — structured scratchpads loaded into the context window every turn. Folders use Letta's file attachment API with grep and semantic search. Archives use Letta's archival memory with vector search. Tools are Letta tool registrations. lettactl doesn't reinvent any of this — it gives you declarative, version-controlled access to what Letta already provides.

Agents

The core resource. Each agent has a name, description, LLM config, system prompt, and optional memory blocks, tools, folders, and archives. Agent names must match `[a-zA-Z0-9_-]+` and can't use reserved words like `agents`, `blocks`, `tools`, `files`, or `archives`.

Memory Blocks

Letta's core memory system — structured blocks that persist across conversations and are loaded into the agent's context window every turn. Two ownership modes: `agent_owned: true` means the Letta agent reads and writes the block via memory tools (lettactl won't overwrite it on redeploy). `agent_owned: false` means the YAML is the source of truth and lettactl will reset it on each apply. Content can come from `value` (inline), `from_file` (local path), or `from_bucket` (cloud storage).

Memory blocks
memory_blocks:
  - name: customer_data
    description: "What I know about the customer"
    agent_owned: true   # Agent writes here
    limit: 5000
  - name: product_info
    description: "Current product catalog"
    agent_owned: false  # YAML is source of truth
    limit: 3000
    from_file: "memory/products.md"

Shared Blocks

Memory blocks defined once at the top level and referenced by multiple agents. When you update a shared block's content, every agent that references it gets the update on next apply. Shared blocks are always agent-readable.

Folders

File attachments for agents. Can be agent-owned or shared. Files can come from local paths or cloud storage (Supabase buckets). Useful for giving agents access to documents, knowledge bases, or reference materials.

Folders
shared_folders:
  - name: knowledge_base
    files:
      - "docs/faq.md"
      - "docs/policies.md"
      - from_bucket:
          provider: supabase
          bucket: docs
          path: "handbook/"

Archives

Letta's long-term archival memory with vector search. Each agent can have at most one archive. Archives persist across conversations and are searchable via Letta's `archival_memory_search` tool. Unlike core memory blocks, archival memory isn't loaded into the context window — the agent queries it on demand. Useful for building up large knowledge stores over time.

Tools

Functions the Letta agent can call during conversations. Letta provides built-in tools for memory management (memory_insert, memory_replace, memory_rethink), archival search (archival_memory_search, archival_memory_insert), file operations (grep_files, semantic_search_files), and web access (web_search, fetch_webpage). You can also register custom tools on your Letta server. Tools are referenced by name in the agent config.

MCP Servers

Model Context Protocol server connections. Three transport types: `sse` (Server-Sent Events), `stdio` (subprocess), and `streamable_http`. Each agent can selectively attach specific tools from MCP servers or use `all` to attach everything.

MCP servers
mcp_servers:
  - name: github
    type: sse
    server_url: "http://localhost:3001/sse"

agents:
  - name: dev-agent
    # ...
    mcp_tools:
      - server: github
        tools: ["search_repos", "create_issue"]

Shared Blocks

When 50 agents all need the same brand guidelines, you don't want to copy the content 50 times. Shared blocks are defined once at the top level of your YAML under `shared_blocks` and referenced by name in each agent. Letta creates a single block on the server and attaches it to every referencing agent — deduplication is automatic. Content can come from inline `value`, `from_file`, or `from_bucket`.

Shared blocks
shared_blocks:
  - name: brand_voice
    description: "Brand guidelines and tone"
    limit: 5000
    from_file: "memory/brand.md"

agents:
  - name: support-agent
    shared_blocks: [brand_voice]
  - name: sales-agent
    shared_blocks: [brand_voice]

Shared Folders

File collections shared across agents. Defined under `shared_folders` at the top level. Files can be local paths or cloud storage references. When you update files in a shared folder, every referencing agent gets the changes on next apply. Letta's file API handles the storage — lettactl handles the lifecycle.

Shared folders
shared_folders:
  - path: "knowledge/"
    description: "Company knowledge base"
    files:
      - "docs/faq.md"
      - "docs/policies.md"
      - from_bucket:
          provider: supabase
          bucket: company-docs
          path: "handbook/"

Resolution Order

During apply, shared resources are processed before agents. The pipeline: validate config → process shared blocks → process shared folders → process MCP servers → process each agent. This ensures all shared resources exist on the Letta server before any agent tries to reference them. If two agents reference the same shared block, only one Letta block is created — both agents get a reference to the same block ID.