Context Files

Context Files

Context files (DEEP.md, AGENTS.md, CLAUDE.md, SOUL.md) are project-level configuration files that are loaded from the backend and injected into the agent's system prompt. They provide project-specific instructions, conventions, and personality.

Quick Start

=== "Explicit Paths" ```python from pydantic_deep import create_deep_agent

agent = create_deep_agent(
    context_files=["/project/DEEP.md", "/project/AGENTS.md"],
)
```

=== "Auto-Discovery" ```python from pydantic_deep import create_deep_agent

agent = create_deep_agent(context_discovery=True)
# Scans backend root for DEEP.md, AGENTS.md, CLAUDE.md, SOUL.md
```

Context File Types

Configuration

How It Works

Loading

The [ContextToolset][pydantic_deep.toolsets.context.ContextToolset] uses get_instructions() to load files from the runtime backend (ctx.deps.backend) and format them for the system prompt:

## Project Context

### DEEP.md

[content of DEEP.md]

### AGENTS.md

[content of AGENTS.md]

Missing files are silently skipped.

Truncation

Files exceeding 20,000 characters are truncated with a head/tail split (70% head, 30% tail):

[first 14,000 chars]

... [6000 chars truncated] ...

[last 6,000 chars]

Subagent Filtering

Subagents only receive DEEP.md and AGENTS.md. Sensitive files (CLAUDE.md, SOUL.md) are filtered out for security isolation:

# Main agent sees all context files
# Subagents only see DEEP.md and AGENTS.md

This filtering is automatic — no configuration needed.

Per-Subagent Context Files

Individual subagents can have their own context files:

from pydantic_deep import SubAgentConfig

subagents = [
    SubAgentConfig(
        name="code-reviewer",
        description="Reviews code for quality",
        instructions="...",
        context_files=["/project/REVIEW_GUIDELINES.md"],
    ),
]

agent = create_deep_agent(
    subagents=subagents,
    context_files=["/project/DEEP.md"],
)

Writing Context Files

Context files are simple markdown. Write them to your backend:

from pydantic_ai_backends import LocalBackend

backend = LocalBackend("/workspace")

# Write a DEEP.md file
backend.write("/DEEP.md", """
# Project: MyApp

## Architecture
- FastAPI backend with PostgreSQL
- React frontend with TypeScript

## Conventions
- Use snake_case for Python, camelCase for TypeScript
- All API endpoints return JSON
- Tests required for all new features
""".encode())

Components

Next Steps

• Memory — Persistent agent memory
• Output Styles — Control response formatting
• Hooks — Claude Code-style lifecycle hooks