Skip to content

Recipe: Memory Tools

Goal

Set up an agent with a memory MCP server so it can persist information across conversations using long-term memory tools.

Prerequisites

  • A memory MCP server exposing memory tools (write_memory, read_memory, search_memory, list_memory_keys, delete_memory)

Setting up a memory MCP server

from doc_processing_toolkit import Agent

agent = Agent(
    model="claude-sonnet-5",
    instructions="You are a helpful assistant with long-term memory.",
    tools=[
        {
            "type": "mcp_script",
            "path": "memory_server.py",
            "name": "memory",
        }
    ],
)

result = await agent.run("Remember that my favorite color is blue.")
print(result.output)

When the agent detects a memory server, it automatically injects structured memory usage instructions into the system prompt — guiding the LLM on how and when to use memory tools.

How auto-detection works

Memory detection uses a dual-condition approach — both must be true:

  1. A server name matching "memory" or "mem" is present.
  2. That server exposes at least one recognized memory tool (write_memory, read_memory, search_memory, list_memory_keys, delete_memory).

If either condition is missing, memory injection is silently skipped.

Memory instructions in the system prompt

When memory tools are detected, the system prompt is augmented with:

## Long-Term Memory

You have access to long-term memory tools that allow you to persist
information across conversations.

### Available memory tools:
- **write_memory(key, value)**: Store information with a key for later retrieval
- **read_memory(key)**: Retrieve previously stored information by key
- **search_memory(query)**: Search stored memories by content
- **list_memory_keys()**: List all stored memory keys
- **delete_memory(key)**: Remove stored memories

### When to use memory:
- Store important user preferences
- Remember context from previous conversations
- Save structured data for future reference
- Track ongoing projects or tasks

### Memory best practices:
- Use descriptive keys for stored memories
- Structure data consistently
- Search before writing to avoid duplicates
- Clean up outdated memories periodically

Memory with sessions

Memory tools are especially useful with sessions, where the agent can recall information across multiple runs:

async with agent.session() as session:
    await session.run("My name is Alice and my project is called Phoenix.")
    await session.run("What do you remember about me?")

Memory + compaction interaction

When the agent has both memory tools and compaction=True, an additional compaction addendum is appended to the memory instructions:

### Context Compaction
This agent has context compaction enabled. When the conversation grows long,
older messages may be automatically summarized. Important information that should
persist beyond compaction should be saved to long-term memory using the memory
tools above.

This guides the LLM to proactively save important information to memory before it might be compacted away.

Example with both features:

agent = Agent(
    model="claude-sonnet-5",
    instructions="You are a research assistant with memory.",
    tools=[
        {
            "type": "mcp_script",
            "path": "memory_server.py",
            "name": "memory",
        },
        {
            "type": "mcp_script",
            "path": "research_tools.py",
            "name": "research",
        },
    ],
    compaction=True,
)

result = await agent.run("Research topic X and save key findings to memory.")

Disabling auto-injection

agent = Agent(
    model="claude-sonnet-5",
    auto_inject_memory_instructions=False,
    tools=[
        {
            "type": "mcp_script",
            "path": "memory_server.py",
            "name": "memory",
        }
    ],
)

from doc_processing_toolkit import AgentBuilder

agent = (
    AgentBuilder()
    .model("claude-sonnet-5")
    .add_tool({
        "type": "mcp_script",
        "path": "memory_server.py",
        "name": "memory",
    })
    .build()
)
# Note: AgentBuilder does not expose auto_inject_memory_instructions;
# use the constructor if you need to disable it.

# Or via Agent.builder():
# agent = Agent.builder().model(...).add_tool(...).build()

model: claude-sonnet-5
auto_inject_memory_instructions: false
tools:
  - type: mcp_script
    path: memory_server.py
    name: memory

When disabled, memory tools are still available but the LLM receives no guidance on how to use them.