Sleep-time Agents

Experimental

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 multi-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, set enableSleeptime: true when creating your agent. This will automatically create:

A primary agent with tools for 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.

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 will 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.

TypeScript
Python

// get a block by label
const block = await client.agents.blocks.retrieve(agentId, "persona");

// get a block by ID
const block = await client.blocks.retrieve(blockId);

# get a block by label
block = client.agents.blocks.retrieve(agent_id=agent_id, block_label="persona")

# get a block by ID
block = client.blocks.retrieve(block_id=block_id)

When sleep-time is enabled for an agent, a sleep-time agent is created to manage the memory blocks of the primary agent. The sleep-time agent runs in the background and can modify the memory blocks asynchronously. The sleep-time agent generates learned context from the conversation history to update the memory blocks of the primary agent.

Sleep-time agent for conversation

When sleep-time is enabled, a primary agent and a sleep-time agent are created as part of a multi-agent group under the hood. The sleep-time agent is responsible for generating learned context from the conversation history to update the memory blocks of the primary agent. The group ensures that for every N steps taken by the primary agent, the sleep-time agent is invoked with data containing new messages 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 sleeptime_agent_frequency parameter when creating the agent.

TypeScript
Python

import { LettaClient, SleeptimeManagerUpdate } from "@letta-ai/letta-client";

const client = new LettaClient({ token: "LETTA_API_KEY" });

// create a sleep-time-enabled agent
const agent = await client.agents.create({
  memoryBlocks: [
    { value: "", label: "human" },
    { value: "You are a helpful assistant.", label: "persona" },
  ],
  model: "anthropic/claude-3-7-sonnet-20250219",
  embedding: "openai/text-embedding-3-small",
  enableSleeptime: true,
});
console.log(`Created agent id ${agent.id}`);

// get the multi-agent group
const groupId = agent.multiAgentGroup.id;
const currentFrequency = agent.multiAgentGroup.sleeptimeAgentFrequency;
console.log(`Group id: ${groupId}, frequency: ${currentFrequency}`);

// update the frequency to every 2 steps
const group = await client.groups.modify(groupId, {
  managerConfig: {
    sleeptimeAgentFrequency: 2,
  } as SleeptimeManagerUpdate,
});

from letta_client import Letta
from letta_client.types import SleeptimeManagerUpdate

client = Letta(token="LETTA_API_KEY")

# create a sleep-time-enabled agent
agent = client.agents.create(
    memory_blocks=[
        {"value": "", "label": "human"},
        {"value": "You are a helpful assistant.", "label": "persona"},
    ],
    model="anthropic/claude-3-7-sonnet-20250219",
    embedding="openai/text-embedding-3-small",
    enable_sleeptime=True,
)
print(f"Created agent id {agent.id}")

# get the multi-agent group
group_id = agent.multi_agent_group.id
current_frequence = agent.multi_agent_group.sleeptime_agent_frequency
print(f"Group id: {group_id}, frequency: {current_frequence}")

# update the frequency to every 2 steps
group = client.groups.modify(
    group_id=group_id,
    manager_config=SleeptimeManagerUpdate(
        sleeptime_agent_frequency=2
    ),
)

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.