Core Concepts

Reeve is an AI agent platform. Before diving into configuration, it helps to understand the five building blocks that make everything work.

Agents

An agent is a persistent AI identity. Each agent has:

• A role — Coordinator, manager, worker, research, or assistant
• A model — Which LLM powers it (Claude, GPT, etc.)
• A workspace — A directory containing its configuration, memory, and context files
• Channel bindings — Which messaging platforms it responds on
• A heartbeat — Optional periodic check-in for autonomous work

Think of an agent as a teammate with a specific job. You can have one agent or dozens, each specialized for different work.

Coordinator (Opus)
  ├── Marketing Manager (Opus)
  │     ├── Content Writer (Sonnet)
  │     └── Ad Analyst (Sonnet)
  └── Engineering Manager (Opus)
        ├── Frontend Dev (Sonnet)
        └── Backend Dev (Sonnet)

Agents can spawn sub-agents, coordinate work, and communicate with each other. See Agent Management for details.

Sessions

A session is a conversation between you and an agent. Sessions track:

• Messages — The full transcript (user messages, agent replies, tool calls)
• Context window — What the agent currently "sees" (recent messages + system prompt)
• State — Active, idle, or compacting

When a session's context window fills up, Reeve compacts it — summarizing older messages to free space while preserving key information. Before compaction, agents automatically flush important notes to memory.

Sessions reset after configurable idle periods (1 hour for workers, 48 hours for managers) to keep context fresh.

Session lifecycle:
  New → Active → [Messages accumulate] → Compaction → Active → [Idle timeout] → Reset

Goals

A goal is a multi-phase objective that agents work toward. Goals provide structure for complex, long-running work.

Each goal has:

• Phases — Sequential stages of work (e.g., research → plan → execute → verify)
• Metrics — Tracked KPIs (e.g., "docs written: 4/10")
• Budget — Token or dollar limits to prevent runaway spending
• Checkpoints — Saved progress so work can resume after interruptions

Goals are especially useful for work that spans multiple sessions or agents — they act as the shared scoreboard.

{
  "title": "Rewrite landing page",
  "phases": [
    { "name": "Research", "type": "research" },
    { "name": "Draft", "type": "execution" },
    { "name": "Review", "type": "review" },
    { "name": "Deploy", "type": "execution" }
  ]
}

See Goals for the full system.

Memory

Agents have persistent memory stored as Markdown files in their workspace. Memory survives across sessions and compaction — it's how agents remember things long-term.

Two layers:

Memory is plain text — you can read and edit it yourself. Agents also have semantic search over their memory, so they can find relevant notes even when the wording differs.

See Memory for configuration and vector search setup.

Tools

Tools are capabilities that agents can use during conversations. Reeve provides a rich set of built-in tools:

Tools can be allowed or denied per-agent, and grouped into profiles (coding, messaging, minimal, full).

Your connected Connectors also provide tools:

reeve_shopify    → Shopify store data
reeve_analytics  → GA4 / PostHog analytics
reeve_ads        → Meta / Google ad campaigns
reeve_email      → Klaviyo email campaigns
reeve_revenue    → Stripe revenue metrics
reeve_social     → Social media metrics
reeve_support    → Support tickets

See Tools for the full reference.

How It All Fits Together

You ──message──→ Agent (in a Session)
                    ├── Uses Tools to take action
                    ├── Reads/writes Memory for persistence
                    ├── Progresses Goals for structured work
                    └── Spawns sub-agents for parallel tasks

The gateway orchestrates everything — it routes messages, manages sessions, enforces tool policies, and handles compaction. Whether you run the gateway locally (Desktop App or CLI) or in the cloud, the architecture is the same.