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.features.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.features.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, max_tokens=None, pin_marker=DEFAULT_PIN_END_MARKER, 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 body lines to inject into the system prompt. The most recent lines are kept (write_memory appends to the end).	DEFAULT_MAX_MEMORY_LINES
max_tokens	int | None	Optional approximate token budget for injection. When set it takes precedence over max_lines.	None
pin_marker	str	Marker whose first occurrence ends the always-injected pinned head, so foundational notes survive truncation.	DEFAULT_PIN_END_MARKER
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.features.memory.load_memory(backend, path, agent_name='main') async

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	AsyncBackendProtocol	Async 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.features.memory.format_memory_prompt(memory, max_lines, *, max_tokens=None, pin_marker=DEFAULT_PIN_END_MARKER)

Format memory content for system prompt injection.

write_memory appends new content, so the newest observations live at the end of the file. When memory exceeds the budget, the most recent lines are kept (the tail), not the oldest. Content above the first pin_marker is a pinned head that is always injected in full, so foundational notes survive truncation. If the body is truncated, a marker noting the dropped lines is inserted above the kept tail.

Parameters:

Name	Type	Description	Default
memory	MemoryFile	Loaded memory file.	required
max_lines	int	Maximum number of body lines to include.	required
max_tokens	int | None	Optional approximate token budget for the body. When set it takes precedence over max_lines, using the NUM_CHARS_PER_TOKEN heuristic used elsewhere in the library.	None
pin_marker	str	Marker whose first occurrence ends the always-injected head.	DEFAULT_PIN_END_MARKER

Returns:

Type	Description
str	Formatted system prompt section.

get_memory_path

pydantic_deep.features.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".