[FEATURE] Add memory field support to AgentDefinition #585

[tomoki-takahashi-oisix]

Feature Request

The AgentDefinition dataclass is missing the memory field that is supported by the Claude Code CLI's --agents flag and file-based subagent frontmatter.

Background

Claude Code CLI v2.1.33 added support for the memory frontmatter field in agents, which enables persistent cross-session learning with three scope options: user, project, or local.

The official documentation shows that the --agents flag accepts JSON with the same frontmatter fields as file-based subagents, including memory:

memory: Persistent directory scope for this subagent (user, project, or local). Enables the subagent to build up knowledge over time.

However, the Python SDK's AgentDefinition dataclass currently only supports description, prompt, tools, and model.

Use Case

When defining subagents programmatically via the Python SDK, we need the ability to give them persistent memory so they can learn and improve over time (e.g., remembering codebase patterns, business metrics definitions, or domain-specific conventions).

Proposed Solution

Add an optional memory field to AgentDefinition:

@dataclass
class AgentDefinition:
    description: str
    prompt: str
    tools: list[str] | None = None
    model: Literal["sonnet", "opus", "haiku", "inherit"] | None = None
    memory: Literal["user", "project", "local"] | None = None  # NEW

Related Issues

This is part of a broader pattern where AgentDefinition is missing several frontmatter fields that the CLI supports:

• The AgentDefinition is missing the mcpServers attribute. #569 — mcpServers field missing
• [Feature] Add skills field support to AgentDefinition for programmatic subagent definition #476 — skills field missing
• output_format support for AgentDefinition (subagents)? #440 — output_format field missing

Note: This is not related to #552 (Claude API Memory Tool). This is specifically about the agent frontmatter memory field.

[Br1an67]

I'd like to work on this. Added an optional memory field to AgentDefinition accepting 'user', 'project', or 'local', matching the CLI's --agents frontmatter support.

PR: #618