Skip to content

Memory

Memory tool auto-detection automatically identifies a memory MCP server in the agent's tools and injects structured memory usage instructions into the system prompt.

How it works

When auto_inject_memory_instructions=True (the default), the agent:

  1. Detects whether a memory server is present using dual-condition matching.
  2. Injects MEMORY_INSTRUCTIONS into the system prompt, giving the LLM guidance on how and when to use memory tools.

Detection logic

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

  1. A server name matching one of the MEMORY_SERVER_PATTERNS ("memory", "mem") is found.
  2. That server exposes at least one of the MEMORY_TOOL_NAMES:
    • write_memory
    • read_memory
    • search_memory
    • list_memory_keys
    • delete_memory

Note

Both conditions are required. A server named "memory" without any recognized tool names will not trigger injection, and vice versa.

When detection runs

Detection runs in Agent.__init__ and then again once the MCP servers are connected, on the first run. The second pass exists because several tool formats publish their tool list only at connect time — stdio script/command server dicts, pre-built ClientSession dicts, client-side remote MCP servers (mcp_remote_client), and deferred fastmcp>=3 server objects. Re-detection is idempotent and is skipped entirely once a memory server has been found (or when auto_inject_memory_instructions is off).

Connect-time servers were never detected before 0.3.0

Detection used to run only in Agent.__init__, against a tool list those formats had not populated yet, so a memory server supplied in any of them never triggered injection. Only a FastMCP server object that exposes its tools synchronously (the SDK-bundled mcp.server.fastmcp, or fastmcp<3) was ever detected. Upgrading turns injection on for the rest, which lengthens the system prompt on those agents.

Injected instructions

When memory tools are detected, the following instructions are appended to the system prompt:

## 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

Compaction interaction

When the agent has both memory tools and compaction=True, an additional 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.

Configuration

Parameter Type Default Source
auto_inject_memory_instructions bool True Agent.__init__, YAML config

Enabling/disabling

agent = Agent(model="claude-sonnet-5", auto_inject_memory_instructions=False)

model: claude-sonnet-5
auto_inject_memory_instructions: false