Memory API

Persistent agent memory gives an agent a long-lived MEMORY.md file it can read and update across runs. Enable it via include_memory=True (default) on create_deep_agent. See Memory for the conceptual overview.

MemoryFile

pydantic_deep.toolsets.memory.MemoryFile dataclass

A loaded agent memory file.

agent_name instance-attribute

Agent that owns this memory: "main", "code-reviewer", etc.

path instance-attribute

Full path in backend: "/.deep/memory/main/MEMORY.md".

content instance-attribute

Memory file content.

AgentMemoryToolset

pydantic_deep.toolsets.memory.AgentMemoryToolset

Bases: FunctionToolset[Any]

Toolset for persistent agent memory.

Provides system prompt injection (via get_instructions()) and tools for reading, appending, and updating memory.

Memory is stored as a MEMORY.md file in the backend at {memory_dir}/{agent_name}/MEMORY.md.

Tools

• read_memory: Read full memory content
• write_memory: Append new content to memory
• update_memory: Find and replace text in memory

__init__(*, agent_name='main', memory_dir=DEFAULT_MEMORY_DIR, max_lines=DEFAULT_MAX_MEMORY_LINES, descriptions=None)

Initialize the memory toolset.

Parameters:

Name	Type	Description	Default
agent_name	str	Name of the agent (used for path and prompt label).	'main'
memory_dir	str	Base directory for memory files in the backend.	DEFAULT_MEMORY_DIR
max_lines	int	Max lines to inject into system prompt.	DEFAULT_MAX_MEMORY_LINES
descriptions	dict[str, str] | None	Optional mapping of tool name to custom description. Supported keys: read_memory, write_memory, update_memory. Any key not present falls back to the built-in description constant.	None

get_instructions(ctx) async

Load and inject memory into system prompt.

Parameters:

Name	Type	Description	Default
ctx	RunContext[Any]	The run context with access to backend via deps.	required

Returns:

Type	Description
list[InstructionPart] | None	Formatted memory prompt, or None if no memory exists.

load_memory

pydantic_deep.toolsets.memory.load_memory(backend, path, agent_name='main')

Load memory file from backend.

Returns None when the file is genuinely missing or empty. Raises MemoryAccessError when the backend denies access to the path, so a misconfigured memory directory is not silently reported as empty memory (issue #135).

Parameters:

Name	Type	Description	Default
backend	BackendProtocol	Backend to read from.	required
path	str	Full path to the memory file.	required
agent_name	str	Name of the agent owning this memory.	'main'

Returns:

Type	Description
MemoryFile | None	MemoryFile if found, None if missing or empty.

Raises:

Type	Description
MemoryAccessError	If the backend denied access to the path.

format_memory_prompt

pydantic_deep.toolsets.memory.format_memory_prompt(memory, max_lines)

Format memory content for system prompt injection.

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

Parameters:

Name	Type	Description	Default
memory	MemoryFile	Loaded memory file.	required
max_lines	int	Maximum number of lines to include.	required

Returns:

Type	Description
str	Formatted system prompt section.

get_memory_path

pydantic_deep.toolsets.memory.get_memory_path(memory_dir, agent_name)

Compute the memory file path for an agent.

Parameters:

Name	Type	Description	Default
memory_dir	str	Base directory for memory files.	required
agent_name	str	Agent name (e.g., "main", "code-reviewer").	required

Returns:

Type	Description
str	Full path like "/.deep/memory/main/MEMORY.md".