Sleep-time Agents

In Letta, you can create special sleep-time agents that share the memory of your primary agents, but run in the background and can modify the memory asynchronously. You can think of sleep-time agents as a special form of mulit-agent architecture, where all agents in the system share one or more memory blocks. A single agent can have one or more associated sleep-time agents to process data such as the conversation history or data sources to manage the memory blocks of the primary agent.

To enable sleep-time agents for your agent, create the agent with type sleeptime_agent. When you create an agent of this type, this will automatically create:

• A primary agent (i.e. general-purpose agent) tools for send_message, conversation_search, and archival_memory_search. This is your “main” agent that you configure and interact with.
• A sleep-time agent with tools to manage the memory blocks of the primary agent. It is possible that additional, ephemeral sleep-time agents will be created when you add data into data sources of the primary agent.

Background: Memory Blocks

Sleep-time agents specialize in generating learned context. Given some original context (e.g. the conversation history, a set of files) the sleep-time agent will reflect on the original context to iteratively derive a learned context. The learned context is should reflect the most important pieces of information or insights from the original context.

In Letta, the learned context is saved in a memory block. A memory block represents a labeled section of the context window with an associated character limit. Memory blocks can be shared between multiple agents. A sleep-time agent will write the learned context to a memory block, which can also be shared with other agents that could benefit from those learnings.

Memory blocks can be access directly through the API to be updated, retrieved, or deleted.

1
# get a block by label
2
block = client.agents.blocks.retrieve(agent_id=agent_id, block_label="persona")
3
4
# get a block by ID
5
block = client.blocks.retrieve(block_id=block_id)

When sleep-time is enabled for an agent, there will be one or more sleep-time agents create to manage the memory blocks of the primary agent. These sleep-time agents will run in the background and can modify the memory blocks of the primary agent asynchronously. One sleep-time agent (created when the primary agent is created) will generate learned context from the conversation history to update the memory blocks of the primary agent. Additional ephemeral sleep-time agents will be created when you add data into data sources of the primary agent to process the data sources in the background. These ephemeral agents will create and write to a block specific to the data source, and be deleted once they are finished processing the data sources.

Sleep-time agent for conversation

When a sleep-time-enabled agent is created, an additional sleep-time agent is created to generate learned context from the conversation history to update the memory blocks of the primary agent. Under the hood, the primary agent and sleep-time agent are part of a multi-agent group. The group ensures that for every N steps by the primary agent, the sleep-time agent is invoked with data containing new messges in the primary agent’s message history.

Configuring the frequency of sleep-time updates

The sleep-time agent will be triggered every N-steps (default 5) to update the memory blocks of the primary agent. You can configure the frequency of updates by setting the sleep_time_agent_frequency parameter when creating the agent.

1
from letta_client import Letta, SleeptimeManagerUpdate
2
3
client = Letta(base_url="http://localhost:8283")
4
5
# create a sleep-time-enabled agent
6
agent = client.agents.create(
7
    memory_blocks=[
8
        {"value": "", "label": "human"},
9
        {"value": "You are a helpful assistant.", "label": "persona"},
10
    ],
11
    model="anthropic/claude-3-7-sonnet-20250219",
12
    embedding="openai/text-embedding-ada-002",
13
    enable_sleep_time=True,
14
)
15
print(f"Created agent id {agent.id}")
16
17
# get the multi-agent group
18
group_id = agent.multi_agent_group.id
19
current_frequence = agent.multi_agent_group.sleep_time_agent_frequency
20
print(f"Group id: {group_id}, frequency: {current_frequence}")
21
22
# update the frequency to every 2 steps
23
group = client.groups.modify(
24
    group_id=group_id,
25
    manager_config=SleeptimeManagerUpdate(
26
        sleep_time_agent_frequency=2
27
    ),
28
)

We recommend keeping the frequency relatively high (e.g. 5 or 10) as triggering the sleep-time agent too often can be expensive (due to high token usage) and has diminishing returns.

Sleep-time agents for data sources

Sleep-time-enabled agents will spawn additional ephemeral sleep-time agents when you add data into data sources of the primary agent to process the data sources in the background. These ephemeral agents will create and write to a block specific to the data source, and be deleted once they are finished processing the data sources.

When a file is uploaded to a data source, it is parsed into passages (chunks of text) which are embedded and saved into the main agent’s archival memory. If sleeptime is enabled, the sleep-time agent will also process each passage’s text to update the memory block corresponding to the data source. The sleep-time agent will contrain an instructions block that contains the data source description, to help guide the learned context generation.

Below is an example of using the SDK to attach a data source to a sleep-time-enabled agent:

1
from letta_client import Letta
2
3
client = Letta(base_url="http://localhost:8283")
4
5
6
agent = client.agents.create(
7
    memory_blocks=[
8
        {"value": "", "label": "human"},
9
        {"value": "You are a helpful assistant.", "label": "persona"},
10
    ],
11
    model="anthropic/claude-3-7-sonnet-20250219",
12
    embedding="openai/text-embedding-ada-002",
13
    enable_sleep_time=True,
14
)
15
print(f"Created agent id {agent.id}")
16
17
# create a source
18
source_name = "employee_handbook"
19
source = client.sources.create(
20
    name=source_name,
21
    description="Provides reference information for the employee handbook",
22
    embedding="openai/text-embedding-ada-002" # must match agent
23
)
24
# attach the source to the agent
25
client.agents.sources.attach(
26
    source_id=source.id,
27
    agent_id=agent.id
28
)
29
30
# upload a file: this will trigger processing
31
job = client.sources.files.upload(
32
    file=open("handbook.pdf", "rb"),
33
    source_id=source.id
34
)

This code will create and attach a memory block with the label employee_handbook to the agent. An ephemeral sleep-time agent will be created to process the data source and write to the memory block, and be deleted once all the passages in the data source have been processed.