The storage configuration defines how agent interactions, messages, and tool usage are logged. It's defined at the root level of the manifest.

Configuration Reference¶

SQL Storage¶

SQL database storage configuration.

SQL Storage (YAML)
- type: sql
  url: sqlite:////home/runner/.local/share/agentpool/history.db  # Database URL (e.g. sqlite:///history.db)
  pool_size: 5  # Connection pool size
  auto_migration: true  # Whether to automatically add missing columns
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

File Storage¶

File storage configuration.

File Storage (YAML)
- type: file
  path: /data/storage.json  # Path to storage file (extension determines format unless specified)
  format: auto  # Storage format (auto=detect from extension)
  encoding: utf-8  # File encoding of the storage file.
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

Memory Storage¶

In-memory storage configuration for testing.

Memory Storage (YAML)
- type: memory
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

Claude Storage¶

Claude Code native storage format configuration.

Reads/writes to Claude Code's native JSONL format in ~/.claude/projects/. Useful for sharing conversation history between agentpool and Claude Code CLI.

Claude Storage (YAML)
- type: claude
  path: ~/.claude  # Path to Claude data directory (default: ~/.claude)
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

OpenCode Storage¶

OpenCode native storage format configuration.

Reads from OpenCode's native JSON format in ~/.local/share/opencode/storage/. Useful for importing conversation history from OpenCode.

OpenCode Storage (YAML)
- type: opencode
  path: ~/.local/share/opencode/storage  # Path to OpenCode storage directory.
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

Zed Storage¶

Zed IDE native storage format configuration.

Reads from Zed's native SQLite + zstd-compressed JSON format. Useful for importing conversation history from Zed's AI assistant.

This is a READ-ONLY provider - it cannot write back to Zed's format.

Zed Storage (YAML)
- type: zed
  path: ~/.local/share/zed/threads/threads.db  # Path to Zed threads database (or parent directory).
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

ACP Storage¶

ACP server storage configuration.

Read-only provider that queries a connected ACP server for session history. The connection is established at runtime by the agent, not from config.

ACP Storage (YAML)
- type: acp
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

Codex Storage¶

Codex server storage configuration.

Read-only provider that queries a connected Codex server for session history. The connection is established at runtime by the agent, not from config.

Codex Storage (YAML)
- type: codex
  log_messages: true  # Whether to log messages
  agents: null  # Optional set of agent names to include. If None, logs all agents.
  log_sessions: true  # Whether to log conversations
  log_commands: true  # Whether to log command executions

Overview¶

Storage providers define how agent interactions, messages, and tool usage are persisted. The system supports multiple providers including SQL databases, file storage, text logs, and in-memory storage.

Key features:

Multiple Providers: Use multiple storage backends simultaneously
Agent Filtering: Control which agents are logged per provider
Flexible Logging: Configure what gets logged (messages, conversations, commands, context)
Provider Selection: Automatic or explicit provider selection for queries

Usage Example¶

agents.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
storage:
  # Global settings
  agents: ["planner", "executor"]
  filter_mode: "and"
  log_messages: true
  log_sessions: true
  default_provider: "sql"

  providers:
    - type: "sql"
      url: "sqlite:///history.db"
      pool_size: 5
      auto_migration: true

    - type: "text_file"
      path: "logs/chat.log"
      format: "chronological"

Configuration Notes¶

Multiple providers can be used simultaneously
Agent filtering works at both global and provider levels
Provider flags are combined with global flags using AND logic
SQL provider is recommended for production use
Memory provider is useful for testing
Text logs support custom Jinja2 templates for flexible formatting