Shared memory blocks

Shared memory blocks let multiple agents access and update the same memory. When one agent updates the block, all others see the change immediately. This enables real-time coordination without explicit agent-to-agent messaging.

graph TD
    subgraph Supervisor
        S[Persona: I am a supervisor]
        SS[Organization: Letta]
    end

    subgraph Worker
        W1[Persona: I am a worker]
        W1S[Organization: Letta]
    end

    SS -.->|shared block| W1S

Shared memory coordinates agents through shared state - great for broadcasting information or maintaining consistent context. For request/response workflows where you need acknowledgment, use agent-to-agent messaging instead.

Quick start

Create a block, then attach it to multiple agents using block_ids:

Python

from letta_client import Letta
import os

client = Letta(api_key=os.getenv("LETTA_API_KEY"))

# Create a shared block
shared_block = client.blocks.create(
    label="organization",
    description="Shared information between all agents.",
    value="Company policies and procedures..."
)

# Attach to multiple agents
supervisor = client.agents.create(
    model="anthropic/claude-haiku-4-5-20251001",
    memory_blocks=[{"label": "persona", "value": "I am a supervisor"}],
    block_ids=[shared_block.id]
)

worker = client.agents.create(
    model="anthropic/claude-haiku-4-5-20251001",
    memory_blocks=[{"label": "persona", "value": "I am a worker"}],
    block_ids=[shared_block.id]  # Same block = shared memory
)

TypeScript

import Letta from "@letta-ai/letta-client";

const client = new Letta({ apiKey: process.env.LETTA_API_KEY });

// Create a shared block
const sharedBlock = await client.blocks.create({
  label: "organization",
  description: "Shared information between all agents.",
  value: "Company policies and procedures...",
});

// Attach to multiple agents
const supervisor = await client.agents.create({
  model: "anthropic/claude-haiku-4-5-20251001",
  memoryBlocks: [{ label: "persona", value: "I am a supervisor" }],
  blockIds: [sharedBlock.id],
});

const worker = await client.agents.create({
  model: "anthropic/claude-haiku-4-5-20251001",
  memoryBlocks: [{ label: "persona", value: "I am a worker" }],
  blockIds: [sharedBlock.id], // Same block = shared memory
});

Managing blocks

Attach to existing agent

Python

client.agents.blocks.attach(
    agent_id=agent.id,
    block_id=shared_block.id
)

TypeScript

await client.agents.blocks.attach(agent.id, {
  blockId: sharedBlock.id,
});

Detach from agent

Python

client.agents.blocks.detach(
    agent_id=agent.id,
    block_id=shared_block.id
)

TypeScript

await client.agents.blocks.detach(agent.id, {
  blockId: sharedBlock.id,
});

List agents using a block

Python

agents = client.blocks.agents.list(block_id=shared_block.id)
for agent in agents:
    print(f"{agent.name} has access")

TypeScript

const agents = await client.blocks.agents.list(sharedBlock.id);
for (const agent of agents) {
  console.log(`${agent.name} has access`);
}

Update from external sources

Sync data into shared blocks from databases, webhooks, or scheduled jobs:

Python

# Sync CRM data to a shared block
crm_data = fetch_from_crm()
client.blocks.update(
    block_id=shared_block.id,
    value=f"Customer list (updated {datetime.now()}):\n{crm_data}"
)

TypeScript

// Sync CRM data to a shared block
const crmData = await fetchFromCRM();
await client.blocks.update(sharedBlock.id, {
  value: `Customer list (updated ${new Date().toISOString()}):\n${crmData}`,
});

blocks.update() replaces the entire block content - it does not append. All agents with access see changes immediately.

Read-only blocks

Protect blocks from agent modification by setting read_only=True:

policy_block = client.blocks.create(
    label="company_policies",
    value="Our company policies...",
    read_only=True
)

Agents can read the block but memory tools will refuse to modify it. Use this for reference data, policies, or any content that should stay constant.

Read-only applies to the entire block, not per-agent. You cannot make a block read-only for some agents but writable for others.

When to use shared blocks

• Multiple agents need the same context (user info, domain knowledge)
• Handoff scenarios where context must persist between agents
• Global config/state that shouldn’t be duplicated

Common patterns

Supervisor/Worker State

• Block: task_queue
• Attached to: Supervisor + all workers
• Pattern: Supervisor writes tasks, workers read and update status

Shared Knowledge Base

• Block: domain_knowledge
• Attached to: Multiple specialized agents
• Pattern: Any agent can append learnings, all benefit

User Profile (Multi-Agent)

• Block: user_preferences
• Attached to: All agents serving same user
• Pattern: Agents read for personalization, sleeptime agent curates

Coordination/Handoff

• Block: handoff_context
• Attached to: Agent A + Agent B
• Pattern: Agent A writes before handoff, Agent B reads on pickup

Global Config

• Block: system_config (read-only)
• Attached to: All agents in deployment
• Pattern: Updated externally via API, agents only read

Concurrency

Operation	Use when	Concurrent-safe?
memory_insert	Appending new info	Yes (append-only)
memory_replace	Targeted edits	Mostly (fails if target string changed)
memory_rethink	Full rewrites	No (last-writer-wins)

Designate one agent (or sleeptime) as the “owner” for heavy edits. Other agents append via memory_insert.

Anti-pattern: Multiple agents doing memory_rethink on the same block simultaneously leads to lost updates.

Troubleshooting

Agent can’t see updates - Verify both agents have the same block_id attached. Check that updates completed (agent finished its turn). Ensure character limit wasn’t exceeded.

Block limit exceeded - Increase limit with client.blocks.update(block_id=id, limit=10000). Archive old content to a separate block. Have an agent periodically summarize.

Race conditions - Design blocks so each agent updates their own section. Use timestamps and agent IDs in content. Consider separate blocks for high-contention data.

Next steps

Shared memory tutorial Step-by-step guide to multi-agent coordination

Memory blocks overview Understanding core memory and block types

Multi-agent overview Patterns for building multi-agent systems

Sleeptime agents Background memory processing