Persistent Memory

Persistent Memory

Persistent memory gives agents a MEMORY.md file stored in the backend that survives across sessions. Memory is auto-loaded into the system prompt and writable via tools.

Quick Start

from pydantic_deep import create_deep_agent

agent = create_deep_agent(include_memory=True)

The agent gets three memory tools:

Memory is also automatically injected into the system prompt (first 200 lines) so the agent sees it without needing to call read_memory.

Configuration

Storage Layout

Each agent gets its own memory file:

/.deep/memory/
  main/MEMORY.md          # Main agent's memory
  code-reviewer/MEMORY.md # Subagent's memory
  test-writer/MEMORY.md   # Another subagent's memory

How It Works

System Prompt Injection

When memory exists, the [AgentMemoryToolset][pydantic_deep.toolsets.memory.AgentMemoryToolset] injects it into the system prompt via get_instructions():

## Agent Memory (main)

- User prefers TypeScript over JavaScript
- Project uses PostgreSQL with Prisma ORM
- Always run `npm test` before committing

Only the first 200 lines are included to stay within token budget. If truncated, a marker is added:

... [50 more lines in memory] ...

Writing Memory

The agent appends to memory when it learns something worth remembering:

Agent: I notice you always prefer functional programming patterns.
       Let me save this to memory.
       [calls write_memory("- User prefers functional patterns over OOP")]

Updating Memory

The agent can find-and-replace text to correct or update entries:

Agent: The project switched from MySQL to PostgreSQL.
       [calls update_memory("Uses MySQL", "Uses PostgreSQL")]

Subagent Memory

When include_memory=True, all subagents automatically get their own memory files. Each subagent writes to {memory_dir}/{subagent_name}/MEMORY.md.

Disabling Memory for Specific Subagents

Use extra={"memory": False} in the subagent config:

from pydantic_deep import SubAgentConfig

subagents = [
    SubAgentConfig(
        name="code-reviewer",
        description="Reviews code",
        instructions="...",
        # Memory enabled by default
    ),
    SubAgentConfig(
        name="ephemeral-worker",
        description="One-off tasks",
        instructions="...",
        extra={"memory": False},  # No memory for this subagent
    ),
]

agent = create_deep_agent(
    include_memory=True,
    subagents=subagents,
)

Custom Max Lines per Subagent

SubAgentConfig(
    name="code-reviewer",
    description="Reviews code",
    instructions="...",
    extra={"memory_max_lines": 50},  # Only inject 50 lines
)

!!! warning "Multi-User Applications" Memory writes to the backend at {memory_dir}/{agent_name}/MEMORY.md. If multiple users share the same backend instance, they share the same memory files. For multi-user apps, give each user a separate backend instance. See Multi-User Guide.

Standalone Usage

Use AgentMemoryToolset directly for custom setups:

from pydantic_deep.toolsets.memory import AgentMemoryToolset

memory_toolset = AgentMemoryToolset(
    agent_name="my-agent",
    memory_dir="/.custom/memory",
    max_lines=100,
)

Components

Next Steps

• Context Files — Project context (DEEP.md, AGENTS.md)
• Hooks — Claude Code-style lifecycle hooks
• Checkpointing — Save and rewind conversation state