Configure buffer memory, persistent session storage, and shared team memory for your agents.

Memory — Conversation History & Session State

AgentBreeder's memory system gives agents access to conversation history, session state, and shared context across invocations. You configure a memory backend once and agents reference it by name — the same way they reference prompts or tools.

Memory Backends

Backend	Value	Best for
In-memory (default)	`in_memory`	Development and single-instance deployments
PostgreSQL	`postgresql`	Production — durable across restarts and replicas

Memory Types

Type	Value	Behaviour
Buffer window	`buffer_window`	Keeps the last N messages (default: 100). Oldest are evicted.
Buffer	`buffer`	Keeps all messages. No eviction. Use with caution on long sessions.

Quickstart

1 — Create a memory config

agentbreeder config memory create \
  --name support-memory \
  --backend postgresql \
  --type buffer_window \
  --max-messages 50 \
  --scope agent

Or via the API:

curl -X POST https://your-agentbreeder/api/v1/memory/configs \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "support-memory",
    "backend_type": "postgresql",
    "memory_type": "buffer_window",
    "max_messages": 50,
    "scope": "agent"
  }'

2 — Reference it in `agent.yaml`

name: support-agent
framework: claude_sdk
model:
  primary: claude-sonnet-4

memory_config: support-memory

That's it. The agent now has a sliding window of the last 50 messages per session, persisted in PostgreSQL.

Configuration Reference

Field	Default	Description
`name`	—	Registry name for this config — referenced in `agent.yaml`
`backend_type`	`in_memory`	Storage backend: `in_memory` or `postgresql`
`memory_type`	`buffer_window`	Eviction strategy: `buffer_window` or `buffer`
`max_messages`	`100`	Max messages to retain per session (buffer_window only)
`namespace_pattern`	`{agent_id}:{session_id}`	Key template — controls memory isolation
`scope`	`agent`	Who shares this memory: `agent` (available now), `team` or `global` (Phase 2 — not yet available)
`linked_agents`	`[]`	Other agents that can read from this memory config

Patterns

Single-agent conversation history

The default use case: one agent remembers the current conversation.

# agent.yaml
memory_config: my-agent-memory

agentbreeder config memory create \
  --name my-agent-memory \
  --backend postgresql \
  --type buffer_window \
  --max-messages 100 \
  --scope agent

History is namespaced to {agent_id}:{session_id} by default — each session is isolated.

Shared team memory

Phase 2 — not yet available

scope: team and scope: global are planned for a future release. Tracked in #134. Only scope: agent is available today.

Multiple agents on a team share the same context (e.g., a triage agent and a billing agent both need to see conversation history).

agentbreeder config memory create \
  --name team-shared-memory \
  --backend postgresql \
  --type buffer_window \
  --max-messages 200 \
  --scope team \
  --linked-agents triage-agent,billing-agent,technical-agent

# triage-agent/agent.yaml
memory_config: team-shared-memory

# billing-agent/agent.yaml
memory_config: team-shared-memory

When scope is team, the namespace key is shared across all linked_agents for the same session. This lets a handoff from triage → billing preserve full history.

Long-term memory (no eviction)

For agents that need to remember everything — research assistants, long-running workflows.

agentbreeder config memory create \
  --name research-full-memory \
  --backend postgresql \
  --type buffer \
  --scope agent

buffer type keeps all messages indefinitely. Monitor storage growth for long-running sessions. Use buffer_window for customer-facing agents.

Development (in-memory, no persistence)

For local development where you don't want to set up PostgreSQL:

agentbreeder config memory create \
  --name dev-memory \
  --backend in_memory \
  --type buffer_window \
  --max-messages 20 \
  --scope agent

In-memory backend loses all history on agent restart. Never use in production.

Reading and Writing Memory via API

Store a message

curl -X POST https://your-agentbreeder/api/v1/memory/configs/support-memory/messages \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "sess-abc123",
    "role": "user",
    "content": "What is my order status?"
  }'

Retrieve conversation history

curl "https://your-agentbreeder/api/v1/memory/configs/support-memory/messages?session_id=sess-abc123" \
  -H "Authorization: Bearer $TOKEN"

Search across sessions

curl "https://your-agentbreeder/api/v1/memory/configs/support-memory/search?q=order+status" \
  -H "Authorization: Bearer $TOKEN"

Get stats

curl "https://your-agentbreeder/api/v1/memory/configs/support-memory/stats" \
  -H "Authorization: Bearer $TOKEN"

{
  "data": {
    "config_id": "support-memory",
    "total_sessions": 1842,
    "total_messages": 24318,
    "avg_messages_per_session": 13.2,
    "backend_type": "postgresql",
    "memory_type": "buffer_window"
  }
}

Custom Namespace Patterns

The default namespace {agent_id}:{session_id} keeps each agent's memory isolated per session. You can override this to create custom isolation boundaries.

Pattern	Isolation
`{agent_id}:{session_id}`	Per-agent, per-session (default)
`{agent_id}:{user_id}`	Per-agent, per-user (persistent across sessions)
`{team}:{session_id}`	Team-wide, per-session
`{agent_id}`	Per-agent, global (one context for all sessions)

agentbreeder config memory create \
  --name user-history \
  --backend postgresql \
  --type buffer_window \
  --namespace-pattern "{agent_id}:{user_id}" \
  --scope agent

Framework-Specific Notes

CrewAI

CrewAI has its own memory system that runs alongside AgentBreeder's. Use the crewai.memory field in agent.yaml for CrewAI's internal memory, and memory_config for AgentBreeder's API-level memory.

framework: crewai
memory_config: support-memory   # AgentBreeder conversation history

crewai:
  memory: true                  # CrewAI internal short-term + long-term memory

Google ADK

Google ADK manages session state via its own session backends. Configure those via google_adk.session_backend. memory_config applies to AgentBreeder's conversation API on top.

framework: google_adk
memory_config: support-memory   # AgentBreeder conversation API

google_adk:
  session_backend: database     # ADK internal session state

Memory — Conversation History & Session State

On this page