Shared Memory Blocks

Overview

Memory blocks can be shared between multiple agents, enabling powerful multi-agent collaboration patterns. When a block is shared, all attached agents can read and write to it, creating a common workspace for coordinating information and tasks.

This tutorial demonstrates how to:

• Create memory blocks that multiple agents can access
• Build collaborative workflows where agents contribute different information
• Use read-only blocks to provide shared context without allowing modifications
• Understand how memory tools handle concurrent updates

By the end of this guide, you’ll understand how to build simple multi-agent systems where agents work together by sharing memory.

Note

This tutorial uses Letta Cloud. Generate an API key at app.letta.com/api-keys and set it as LETTA_API_KEY in your environment. Self-hosted servers only need an API key if authentication is enabled.

The web_search tool used in this tutorial requires an EXA_API_KEY environment variable when self-hosting. You can learn more about self-hosting here.

What You’ll Learn

• Creating standalone memory blocks for sharing
• Attaching the same block to multiple agents
• Building collaborative workflows with shared memory
• Using read-only blocks for policies and system information
• Understanding how memory tools handle concurrent updates

Prerequisites

You will need to install letta-client to interface with a Letta server:

TypeScript

bash TypeScript npm install @letta-ai/letta-client bash Python pip install letta-client

Steps

Step 1: Initialize Client

TypeScript

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

// Initialize the Letta client using LETTA_API_KEY environment variable
const client = new LettaClient({ token: process.env.LETTA_API_KEY });

// If self-hosting, specify the base URL:
// const client = new LettaClient({ baseUrl: "http://localhost:8283" });

Python

from letta_client import Letta
import os

# Initialize the Letta client using LETTA_API_KEY environment variable
client = Letta(token=os.getenv("LETTA_API_KEY"))

# If self-hosting, specify the base URL:
# client = Letta(base_url="http://localhost:8283")

Step 2: Create a Shared Memory Block

Create a standalone memory block that will be shared between multiple agents. This block will serve as a collaborative workspace where both agents can contribute information.

We’re going to give the block the label “organization” to indicate that it contains information about some organization. The starting value of this block is “Organization: Letta” to give the agents a starting point to work from.

TypeScript

// Create a memory block that will be shared between agents
// API Reference: https://docs.letta.com/api-reference/blocks/create
const block = await client.blocks.create({
  label: "organization",
  value: "Organization: Letta",
  limit: 4000,
});

console.log(`Created shared block: ${block.id}\n`);

Python

# Create a memory block that will be shared between agents
# API Reference: https://docs.letta.com/api-reference/blocks/create
block = client.blocks.create(
    label="organization",
    value="Organization: Letta",
    limit=4000,
)

print(f"Created shared block: {block.id}\n")

Step 3: Create Agents with Shared Block

Create two agents that will both have access to the same memory block. You can attach blocks during creation using block_ids or later using the attach method.

We’ll provide each agent with the web_search tool to search the web for information. This tool is built-in to Letta. If you are self-hosting, you will need to set an EXA_API_KEY environment variable for either the server or the agent to use this tool.

TypeScript

// Create first agent with block attached during creation
// API Reference: https://docs.letta.com/api-reference/agents/create
const agent1 = await client.agents.create({
  name: "agent1",
  model: "openai/gpt-4o-mini",
  blockIds: [block.id],
  tools: ["web_search"],
});
console.log(`Created agent1: ${agent1.id}`);

// Create second agent and attach block afterward
const agent2 = await client.agents.create({
  name: "agent2",
  model: "openai/gpt-4o-mini",
  tools: ["web_search"],
});
console.log(`Created agent2: ${agent2.id}`);

// Attach the shared block to agent2
// API Reference: https://docs.letta.com/api-reference/agents/blocks/attach
await client.agents.blocks.attach(agent2.id, block.id);
console.log(`Attached block to agent2\n`);

Python

# Create first agent with block attached during creation
# API Reference: https://docs.letta.com/api-reference/agents/create
agent1 = client.agents.create(
    name="agent1",
    model="openai/gpt-4o-mini",
    block_ids=[block.id],
    tools=["web_search"],
)
print(f"Created agent1: {agent1.id}")

# Create second agent and attach block afterward
agent2 = client.agents.create(
    name="agent2",
    model="openai/gpt-4o-mini",
    tools=["web_search"],
)
print(f"Created agent2: {agent2.id}")

# Attach the shared block to agent2
# API Reference: https://docs.letta.com/api-reference/agents/blocks/attach
agent2 = client.agents.blocks.attach(
    agent_id=agent2.id,
    block_id=block.id,
)
print(f"Attached block to agent2: {agent2.id}")

Step 4: Have Agents Collaborate via Shared Memory

Now let’s have both agents research different topics and contribute their findings to the shared memory block.

• Agent 1: Searches for information about the connection between memory blocks and Letta.
• Agent 2: Searches for information about the origin of Letta.

We’re going to ask each agent to search for different information and insert what they learn into the shared memory block, prepended with the agent’s name (either Agent1: or Agent2:).

TypeScript

// Agent1 searches for information about memory blocks
// API Reference: https://docs.letta.com/api-reference/agents/messages/create
const response1 = await client.agents.messages.create(
  agent1.id,
  {
    messages: [
      {
        role: "user",
        content: `Find information about the connection between memory blocks and Letta.
Insert what you learn into the memory block, prepended with "Agent1: ".`,
      },
    ],
  },
  {
    timeoutInSeconds: 120, // Web search can take time
  },
);

for (const msg of response1.messages) {
  if (msg.messageType === "assistant_message") {
    console.log(`Agent1 response: ${msg.content}`);
  }
  if (msg.messageType === "tool_call_message") {
    console.log(
      `Tool call: ${msg.toolCall.name}(${JSON.stringify(msg.toolCall.arguments)})`,
    );
  }
}

// Agent2 searches for information about Letta's origin
const response2 = await client.agents.messages.create(
  agent2.id,
  {
    messages: [
      {
        role: "user",
        content: `Find information about the origin of Letta.
Insert what you learn into the memory block, prepended with "Agent2: ".`,
      },
    ],
  },
  {
    timeoutInSeconds: 120, // Web search can take time
  },
);

for (const msg of response2.messages) {
  if (msg.messageType === "assistant_message") {
    console.log(`Agent2 response: ${msg.content}`);
  }
  if (msg.messageType === "tool_call_message") {
    console.log(
      `Tool call: ${msg.toolCall.name}(${JSON.stringify(msg.toolCall.arguments)})`,
    );
  }
}

Python

# Agent1 searches for information about memory blocks
# API Reference: https://docs.letta.com/api-reference/agents/messages/create
response = client.agents.messages.create(
    agent_id=agent1.id,
    messages=[{"role": "user", "content": """
    Find information about the connection between memory blocks and Letta.
    Insert what you learn into the memory block, prepended with "Agent1: ".
"""}],
)

for msg in response.messages:
    if msg.message_type == "assistant_message":
        print(f"Agent1 response: {msg.content}")
    if msg.message_type == "tool_call_message":
        print(f"Tool call: {msg.tool_call.name}({msg.tool_call.arguments})")

# Agent2 searches for information about Letta's origin
response = client.agents.messages.create(
    agent_id=agent2.id,
    messages=[{"role": "user", "content": """
    Find information about the origin of Letta.
    Insert what you learn into the memory block, prepended with "Agent2: ".
"""}],
)

for msg in response.messages:
    if msg.message_type == "assistant_message":
        print(f"Agent2 response: {msg.content}")
    if msg.message_type == "tool_call_message":
        print(f"Tool call: {msg.tool_call.name}({msg.tool_call.arguments})")

Step 5: Inspect the Shared Memory

Let’s retrieve the shared memory block to see both agents’ contributions:

TypeScript

// Retrieve the shared block to see what both agents learned
// API Reference: https://docs.letta.com/api-reference/blocks/retrieve
const updatedBlock = await client.blocks.retrieve(block.id);

console.log("==== Updated block ====");
console.log(updatedBlock.value);
console.log("=======================\n");

Python

# Retrieve the shared block to see what both agents learned
# API Reference: https://docs.letta.com/api-reference/blocks/retrieve
updated_block = client.blocks.retrieve(block.id)

print(f"==== Updated block ====")
print(updated_block.value)
print(f"=======================")

The output should be something like this:

Organization: Letta

Agent1: Memory blocks are integral to the Letta framework for managing context in large language models (LLMs). They serve as structured units that enhance an agent’s ability to maintain long-term memory and coherence across interactions. Specifically, Letta utilizes memory blocks to organize context into discrete categories, such as “human” memory (user preferences and facts) and “persona” memory (the agent’s self-concept and traits). This structured approach allows agents to edit and persist important information, improving performance, personalization, and controllability. By effectively managing the context window through these memory blocks, Letta enhances the overall functionality and adaptability of its LLM agents.

Agent2: Letta originated as MemGPT, a research project focused on building stateful AI agents with long-term memory capabilities. It evolved into a platform for building and deploying production-ready agents.

Note that each agent has placed their information into the block, prepended with their name. This is a simple way to identify who contributed what to the block. You don’t have to prepend agent identifiers to the block, we only did this for demonstration purposes.

Note

Understanding concurrent updates: Memory tools handle concurrent updates differently: - memory_insert is additive and the most robust for multi-agent systems. Multiple agents can insert content simultaneously without conflicts, as each insert simply appends to the block. - memory_replace validates that the exact old content exists before replacing it. If another agent modifies the content being replaced, the tool call fails with a validation error, preventing accidental overwrites. - memory_rethink performs a complete rewrite of the entire block and follows “most recent write wins.” This is a destructive operation - use cautiously in multi-agent systems as it can overwrite other agents’ contributions.

Step 6: Using Read-Only Blocks

Read-only blocks are useful for sharing policies, system information, or terms of service that agents should reference but not modify.

TypeScript

// Create a read-only block for policies or system information
// API Reference: https://docs.letta.com/api-reference/blocks/create
const readOnlyBlock = await client.blocks.create({
  label: "read_only_block",
  value: "This is a read-only block.",
  readOnly: true,
});

// Attach the read-only block to an agent
const readOnlyAgent = await client.agents.create({
  name: "read_only_agent",
  model: "openai/gpt-4o-mini",
  blockIds: [readOnlyBlock.id],
});

console.log(`Created read-only agent: ${readOnlyAgent.id}`);

Python

# Create a read-only block for policies or system information
# API Reference: https://docs.letta.com/api-reference/blocks/create
read_only_block = client.blocks.create(
    label="read_only_block",
    value="This is a read-only block.",
    read_only=True,
)

# Attach the read-only block to an agent
read_only_agent = client.agents.create(
    name="read_only_agent",
    model="openai/gpt-4o-mini",
    block_ids=[read_only_block.id],
)

print(f"Created read-only agent: {read_only_agent.id}")

Note

Agents can see read-only blocks in their context but cannot modify them using memory tools. This is useful for organizational policies, system configuration, or any information that should be reference-only.

Complete Example

Here’s the full code in one place that you can run:

TypeScript

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

async function main() {
  // Initialize client
  const client = new LettaClient({ token: process.env.LETTA_API_KEY });

  // Create shared block
  const block = await client.blocks.create({
    label: "organization",
    value: "Organization: Letta",
    limit: 4000,
  });

  console.log(`Created shared block: ${block.id}\n`);

  // Create agents with shared block
  const agent1 = await client.agents.create({
    name: "agent1",
    model: "openai/gpt-4o-mini",
    blockIds: [block.id],
    tools: ["web_search"],
  });

  const agent2 = await client.agents.create({
    name: "agent2",
    model: "openai/gpt-4o-mini",
    tools: ["web_search"],
  });

  await client.agents.blocks.attach(agent2.id, block.id);

  console.log(`Created agents: ${agent1.id}, ${agent2.id}\n`);

  // Agent1 contributes information
  const response1 = await client.agents.messages.create(
    agent1.id,
    {
      messages: [
        {
          role: "user",
          content: `Find information about the connection between memory blocks and Letta.

Insert what you learn into the memory block, prepended with "Agent1: ".`,
        },
      ],
    },
    {
      timeoutInSeconds: 120, // Web search can take time
    },
  );

  // Agent2 contributes information
  const response2 = await client.agents.messages.create(
    agent2.id,
    {
      messages: [
        {
          role: "user",
          content: `Find information about the origin of Letta.

Insert what you learn into the memory block, prepended with "Agent2: ".`,
        },
      ],
    },
    {
      timeoutInSeconds: 120, // Web search can take time
    },
  );

  // Inspect the shared memory
  const updatedBlock = await client.blocks.retrieve(block.id);
  console.log("==== Updated block ====");
  console.log(updatedBlock.value);
  console.log("=======================\n");

  // Create read-only block
  const readOnlyBlock = await client.blocks.create({
    label: "policies",
    value: "Company Policy: Always be helpful and respectful.",
    readOnly: true,
  });

  const readOnlyAgent = await client.agents.create({
    name: "policy_agent",
    model: "openai/gpt-4o-mini",
    blockIds: [readOnlyBlock.id],
  });

  console.log(`Created read-only agent: ${readOnlyAgent.id}`);
}

main();

Python

from letta_client import Letta
import os

# Initialize client
client = Letta(token=os.getenv("LETTA_API_KEY"))

# Create shared block
block = client.blocks.create(
    label="organization",
    value="Organization: Letta",
    limit=4000,
)

print(f"Created shared block: {block.id}\n")

# Create agents with shared block
agent1 = client.agents.create(
    name="agent1",
    model="openai/gpt-4o-mini",
    block_ids=[block.id],
    tools=["web_search"],
)

agent2 = client.agents.create(
    name="agent2",
    model="openai/gpt-4o-mini",
    tools=["web_search"],
)

agent2 = client.agents.blocks.attach(
    agent_id=agent2.id,
    block_id=block.id,
)

print(f"Created agents: {agent1.id}, {agent2.id}\n")

# Agent1 contributes information
response = client.agents.messages.create(
    agent_id=agent1.id,
    messages=[{"role": "user", "content": """
    Find information about the connection between memory blocks and Letta.
    Insert what you learn into the memory block, prepended with "Agent1: ".
"""}],
)

# Agent2 contributes information
response = client.agents.messages.create(
    agent_id=agent2.id,
    messages=[{"role": "user", "content": """
    Find information about the origin of Letta.
    Insert what you learn into the memory block, prepended with "Agent2: ".
"""}],
)

# Inspect the shared memory
updated_block = client.blocks.retrieve(block.id)
print(f"==== Updated block ====")
print(updated_block.value)
print(f"=======================")

# Create read-only block
read_only_block = client.blocks.create(
    label="policies",
    value="Company Policy: Always be helpful and respectful.",
    read_only=True,
)

read_only_agent = client.agents.create(
    name="policy_agent",
    model="openai/gpt-4o-mini",
    block_ids=[read_only_block.id],
)

print(f"Created read-only agent: {read_only_agent.id}")

Key Concepts

Shared Memory

Multiple agents can access the same memory block, enabling collaboration and information sharing

Flexible Attachment

Blocks can be attached during agent creation with block_ids or later using the attach method

Concurrent Updates

Memory tools handle concurrent updates differently - insert is additive, replace validates, rethink overwrites

Read-Only Blocks

Prevent agent modifications while still providing shared context like policies or system information

Use Cases

Multi-Agent Research

Have multiple agents research different topics and contribute findings to a shared knowledge base.

Organizational Policies

Create read-only blocks with company policies, terms of service, or system guidelines that all agents reference.

Task Coordination

Use shared blocks as a coordination layer where agents update task status and communicate progress.

Collaborative Problem Solving

Enable agents with different specializations to work together by sharing context and intermediate results.

Next Steps

Memory Blocks Guide

Learn more about memory blocks, including managing and updating them

Attaching and Detaching Blocks

Understand how to dynamically control agent access to memory blocks