Attaching and detaching memory blocks

Overview

Memory blocks are structured sections of an agent’s context window that persist across all interactions. They’re always visible to the agent while they are attached. This makes them perfect for storing information that agents need constant access to, like organizational policies, user preferences, or working memory.

One of the most powerful features of memory blocks is that they can be created independently and attached to or detached from agents at any time.

This allows you to:

• Dynamically control what information an agent has access to
• Share memory across multiple agents by attaching the same block to different agents
• Temporarily grant access to sensitive information, then revoke it when no longer needed
• Switch contexts by swapping out blocks as an agent moves between different tasks

By the end of this guide, you’ll understand how to create standalone memory blocks, attach them to agents, detach them to remove access, and re-attach them when needed.

Note

For a comprehensive overview of memory blocks and their capabilities, see the memory blocks guide.

Note

This example 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. You can learn more about self-hosting here.

What You’ll Learn

• Creating standalone memory blocks
• Attaching blocks to agents
• Testing agent access to attached blocks
• Detaching blocks to revoke access
• Re-attaching blocks to restore access

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 and Create Agent

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" });

// Create agent
// API Reference: https://docs.letta.com/api-reference/agents/create
const agent = await client.agents.create({
  name: "hello_world_assistant",
  model: "openai/gpt-4o-mini",
  // embedding: "openai/text-embedding-3-small", // Only set this if self-hosting
});

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

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")

# Create agent
# API Reference: https://docs.letta.com/api-reference/agents/create
agent = client.agents.create(
    name="hello_world_assistant",
    model="openai/gpt-4o-mini",
    # embedding="openai/text-embedding-3-small", # Only set this if self-hosting
)

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

Expected Output

Created agent: agent-a1b2c3d4-e5f6-7890-abcd-ef1234567890

Step 2: Create a Standalone Memory Block

Memory blocks can be created independently of any agent. This allows you to share the same block across multiple agents or attach/detach blocks as needed.

In this example, we’ll create a standalone memory block storing information about Letta. We’ll include a code that you can use to get the agent to respond to indicate that it has access to information in the block.

When the block is attached, writing “The code is TimberTheDog1234!” will cause the agent to respond with “Access granted”. If the block is not attached, the agent will not have access to any content in the block and will likely be confused by the code.

TypeScript

// Create memory block storing information about Letta
// API Reference: https://docs.letta.com/api-reference/blocks/create
const block = await client.blocks.create({
  label: "organization",
  value: `Organization: Letta
Website: https://www.letta.com
Description: Letta is a platform for building and running stateful agents.
Code: TimberTheDog1234!

When users provide a code, you should check if it matches the code you have
available. If it matches, you should respond with "Access granted".`,
});

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

Python

# Create memory block storing information about Letta
# API Reference: https://docs.letta.com/api-reference/blocks/create
block = client.blocks.create(
    label="organization",
    value="""Organization: Letta
Website: https://www.letta.com
Description: Letta is a platform for building and running stateful agents.
Code: TimberTheDog1234!

When users provide a code, you should check if it matches the code you have
available. If it matches, you should respond with "Access granted".""",
)

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

Expected Output

Created block: block-a1b2c3d4-e5f6-7890-abcd-ef1234567890

Step 3: Attach Block to Agent

Now let’s attach the block to our agent. Attached blocks are injected into the agent’s context window and are available to the agent to use in its responses.

TypeScript

// Attach memory block to agent
// API Reference: https://docs.letta.com/api-reference/agents/blocks/attach
await client.agents.blocks.attach(agent.id, block.id);

console.log(`Attached block ${block.id} to agent ${agent.id}\n`);

Python

# Attach memory block to agent
# API Reference: https://docs.letta.com/api-reference/agents/blocks/attach
agent = client.agents.blocks.attach(
    agent_id=agent.id,
    block_id=block.id,
)

print(f"Attached block {block.id} to agent {agent.id}\n")

Step 4: Test Agent Access to Block

The agent can now see what’s in the block. Let’s ask it about Letta to verify that it can see the general information in the block — the description, website, and organization name.

TypeScript

// Send a message to test the agent's knowledge
// API Reference: https://docs.letta.com/api-reference/agents/messages/create
const response = await client.agents.messages.create(agent.id, {
  messages: [{ role: "user", content: "What is Letta?" }],
});

for (const msg of response.messages) {
  if (msg.messageType === "assistant_message") {
    console.log(`Agent response: ${msg.content}\n`);
  }
}

Python

# Send a message to test the agent's knowledge
# API Reference: https://docs.letta.com/api-reference/agents/messages/create
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "What is Letta?"}],
)

for msg in response.messages:
    if msg.message_type == "assistant_message":
        print(f"Agent response: {msg.content}\n")

The agent will respond with general information about Letta:

Agent response: Letta is a platform designed for building and running stateful agents. You can find more information about it on their website: https://www.letta.com

Step 5: Detach Block from Agent

Blocks can be detached from an agent, removing them from the agent’s context window. Detached blocks are not deleted and can be re-attached to an agent later.

TypeScript

// Detach the block from the agent
// API Reference: https://docs.letta.com/api-reference/agents/blocks/detach
await client.agents.blocks.detach(agent.id, block.id);

console.log(`Detached block ${block.id} from agent ${agent.id}\n`);

Python

# Detach the block from the agent
# API Reference: https://docs.letta.com/api-reference/agents/blocks/detach
agent = client.agents.blocks.detach(
    agent_id=agent.id,
    block_id=block.id,
)

print(f"Detached block {block.id} from agent {agent.id}\n")

Step 6: Verify Block is Detached

Let’s test the code that was in the block. The agent should no longer have access to it.

TypeScript

// Test that the agent no longer has access to the code
const response2 = await client.agents.messages.create(agent.id, {
  messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],
});

for (const msg of response2.messages) {
  if (msg.messageType === "assistant_message") {
    console.log(`Agent response: ${msg.content}\n`);
  }
}

Python

# Test that the agent no longer has access to the code
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],
)

for msg in response.messages:
    if msg.message_type == "assistant_message":
        print(f"Agent response: {msg.content}\n")

Expected Output

Agent response: It seems like you've provided a code or password. If this
is sensitive information, please ensure you only share it with trusted parties
and in secure environments. Let me know how I can assist you further!

Note

The agent doesn’t recognize the code because the block containing that information has been detached.

Step 7: Re-attach Block and Test Again

Let’s re-attach the block to restore the agent’s access to the information.

TypeScript

// Re-attach the block to the agent
await client.agents.blocks.attach(agent.id, block.id);

console.log(`Re-attached block ${block.id} to agent ${agent.id}\n`);

// Test the code again
const response3 = await client.agents.messages.create(agent.id, {
  messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],
});

for (const msg of response3.messages) {
  if (msg.messageType === "assistant_message") {
    console.log(`Agent response: ${msg.content}\n`);
  }
}

Python

# Re-attach the block to the agent
agent = client.agents.blocks.attach(
    agent_id=agent.id,
    block_id=block.id,
)

print(f"Re-attached block {block.id} to agent {agent.id}\n")

# Test the code again
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],
)

for msg in response.messages:
    if msg.message_type == "assistant_message":
        print(f"Agent response: {msg.content}\n")

Expected Output

Agent response: Access granted. How can I assist you further?

Note

The agent now recognizes the code because we’ve re-attached the block containing that information.

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 agent
  const agent = await client.agents.create({
    name: "hello_world_assistant",
    model: "openai/gpt-4o-mini",
  });

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

  // Create standalone memory block
  const block = await client.blocks.create({
    label: "organization",
    value: `Organization: Letta

Website: https://www.letta.com
Description: Letta is a platform for building and running stateful agents.
Code: TimberTheDog1234!

When users provide a code, you should check if it matches the code you have
available. If it matches, you should respond with "Access granted".`,
  });

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

  // Attach block to agent
  await client.agents.blocks.attach(agent.id, block.id);
  console.log(`Attached block to agent\n`);

  // Test agent with block attached
  let response = await client.agents.messages.create(agent.id, {
    messages: [{ role: "user", content: "What is Letta?" }],
  });
  console.log(`Agent response: ${response.messages[0].content}\n`);

  // Detach block
  await client.agents.blocks.detach(agent.id, block.id);
  console.log(`Detached block from agent\n`);

  // Test agent without block
  response = await client.agents.messages.create(agent.id, {
    messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],
  });
  console.log(`Agent response: ${response.messages[0].content}\n`);

  // Re-attach block
  await client.agents.blocks.attach(agent.id, block.id);
  console.log(`Re-attached block to agent\n`);

  // Test agent with block re-attached
  response = await client.agents.messages.create(agent.id, {
    messages: [{ role: "user", content: "The code is TimberTheDog1234!" }],
  });
  console.log(`Agent response: ${response.messages[0].content}\n`);
}

main();

Python

from letta_client import Letta
import os

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

# Create agent
agent = client.agents.create(
    name="hello_world_assistant",
    model="openai/gpt-4o-mini",
)

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

# Create standalone memory block
block = client.blocks.create(
    label="organization",
    value="""Organization: Letta
Website: https://www.letta.com
Description: Letta is a platform for building and running stateful agents.
Code: TimberTheDog1234!

When users provide a code, you should check if it matches the code you have
available. If it matches, you should respond with "Access granted".""",
)

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

# Attach block to agent
agent = client.agents.blocks.attach(
    agent_id=agent.id,
    block_id=block.id,
)
print(f"Attached block to agent\n")

# Test agent with block attached
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "What is Letta?"}],
)
print(f"Agent response: {response.messages[0].content}\n")

# Detach block
agent = client.agents.blocks.detach(
    agent_id=agent.id,
    block_id=block.id,
)
print(f"Detached block from agent\n")

# Test agent without block
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],
)
print(f"Agent response: {response.messages[0].content}\n")

# Re-attach block
agent = client.agents.blocks.attach(
    agent_id=agent.id,
    block_id=block.id,
)
print(f"Re-attached block to agent\n")

# Test agent with block re-attached
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "The code is TimberTheDog1234!"}],
)
print(f"Agent response: {response.messages[0].content}\n")

Key Concepts

Standalone Blocks

Memory blocks can be created independently and shared across multiple agents

Dynamic Access Control

Attach and detach blocks to control what information an agent can access

Block Persistence

Detached blocks are not deleted and can be re-attached at any time

Shared Memory

The same block can be attached to multiple agents, enabling shared knowledge

Use Cases

Temporary Access to Sensitive Information

Attach a block with credentials or sensitive data only when needed, then detach it to prevent unauthorized access.

Shared Knowledge Across Agents

Create a single block with organizational knowledge and attach it to multiple agents to ensure consistency.

Context Switching

Detach blocks related to one task and attach blocks for another, allowing an agent to switch contexts efficiently.

Role-Based Access

Give different agents access to different blocks based on their roles or permissions.

Next Steps

Memory Blocks Guide

Learn more about memory blocks, including how to update them and manage their lifecycle