Compound Agent

compound-agent is a Claude Code plugin that ships a self-improving development factory into your repository — persistent memory, structured multi-agent workflows, and autonomous loop execution. Fully local. Everything in git.

AI coding agents forget everything between sessions. Each session starts with whatever context was prepared for it — nothing more. Because agents carry no persistent state, that state must live in the codebase itself, and any agent that reads the same well-structured context should be able to pick up where another left off. Compound Agent implements this: it captures mistakes once, retrieves them precisely when relevant, and can hand entire systems to an autonomous loop that processes epic by epic with no human intervention.

What gets installed

ca setup injects a complete development environment into your repository:

| Component | What ships | |-----------|-----------| | 16 slash commands | /compound:architect, cook-it, spec-dev, plan, work, review, compound, learn-that, check-that, and more | | 26 agent role skills | TDD pair, drift detector, audit, research specialist, external reviewers, and more | | 7 automatic hooks | Fire on session start, prompt submit, tool use, tool failure, pre-compact, phase guard, and session stop | | 5 phase skill files | Full workflow instructions for architect, spec-dev, cook-it, work, and review | | 5 deployed docs | Workflow reference, CLI reference, skills guide, integration guide, and overview |

This is not a memory plugin bolted onto a text editor. It is the environment your agents run inside.

How it works

Two memory systems persist across sessions:

• Lessons — mistakes, corrections, and patterns stored as git-tracked JSONL, indexed in SQLite FTS5 with local embeddings for hybrid search. Retrieved at the start of each task, captured at the end.
• Knowledge — project documentation chunked and embedded for semantic retrieval. Any phase can query it on demand.

Each task runs through five phases, with review findings looping back to rework. Each phase runs as its own slash command so instructions are re-injected fresh (surviving context compaction):

Each cycle through the loop makes the next one smarter. The architect step is optional — use it for systems too large for a single feature cycle.

Three principles

These constraints follow from how AI agents work, and each one maps to a layer of the architecture.

| Principle | Without it | Layer | |-----------|-----------|-------| | Memory | Same mistakes every session. Architectural decisions re-derived from scratch. Knowledge locked in human heads where agents cannot reach it. | Semantic Memory | | Feedback loops | Agents cannot verify their own work. Manual review is the only quality gate. Drift is the default at agent-scale output. | Structured Workflows | | Navigable structure | Context windows fill with orientation work. Agents make unverifiable assumptions about dependencies and ordering. | Beads Foundation |

The three are not independent. Memory without feedback loops is unreliable. Feedback without navigable structure fires blindly. The system works as a whole or not at all.

Is this for you?

"It keeps making the same mistake every session." Capture it once. Compound Agent surfaces it automatically before the agent repeats it.

"I explained our auth pattern three sessions ago. Now it's reimplementing from scratch." Architectural decisions persist as searchable lessons. Next session, they inject into context before planning starts.

"My agent uses pandas when we standardised on Polars months ago." Preferences survive across sessions and projects. Once captured, they appear at the right moment.

"Code reviews keep catching the same class of bugs." 24 specialised review agents (security, performance, architecture, test coverage) run in parallel. Findings feed back as lessons that become test requirements in future work.

"I have no idea what my agent actually learned or if it's reliable." ca list shows all captured knowledge. ca stats shows health. ca wrong <id> invalidates bad lessons. Everything is git-tracked JSONL — you can read, diff, and audit it.

"I want structured phases, not just 'go build this'." Five workflow phases (spec-dev, plan, work, review, compound) with mandatory gates between them. Each phase searches memory and docs for relevant context before starting.

"My agent doesn't read the project docs before making decisions." ca knowledge "auth flow" runs hybrid search (vector + keyword) over your indexed docs. Agents query it automatically during planning — ADRs, specs, and standards surface before code gets written.

"I want to hand a large system spec to the machine and walk away." /compound:architect decomposes it into epics. ca loop processes them autonomously.

Levels of use

Level 1 — Memory only

Two minutes to set up. Works in any session without changing your existing workflow.

# Capture a mistake or preference
ca learn "Always use Polars, not pandas in this project" --severity high
ca learn "Auth 401 fix: add X-Request-ID header" --type solution

# Search manually anytime
ca search "polars"

# Or let hooks surface it automatically — no command needed

Level 2 — Structured workflow

One command runs all five phases on a single feature: spec-dev, plan, work (TDD + agent team), review (24 agents), and compound (capture lessons).

/compound:cook-it "Add rate limiting to the API"

Run phases individually when you want more control:

/compound:spec-dev "Add rate limiting"    # Socratic dialogue → EARS spec → Mermaid diagrams
/compound:plan                            # Tasks enriched by memory search
/compound:work                            # TDD with agent team
/compound:review                          # 24 parallel agents with severity gates
/compound:compound                        # Capture what was learned

Level 3 — Factory mode

For systems too large for a single feature cycle. /compound:architect decomposes the system; ca loop processes the resulting epics autonomously.

# Step 1: decompose the system into epics
/compound:architect "Multi-tenant SaaS: auth, billing, API, admin dashboard"
# → Socratic dialogue → system-level EARS spec → DDD decomposition
# → N epics with dependency graph, interface contracts, and scope boundaries

# Step 2: generate and run the loop
ca loop --reviewers claude-sonnet --review-every 3
./.compound-agent/infinity-loop.sh
# → Processes each epic in dependency order: spec-dev → plan → work → review → compound
# → Captures lessons after every cycle, improving subsequent cycles

The infinity loop

ca loop generates a bash script that processes your beads epics sequentially, running the full cook-it cycle on each one. No human intervention required between epics.

# Generate script for all ready epics
ca loop

# With periodic review every 3 epics
ca loop --reviewers claude-sonnet --review-every 3

# Target specific epics
ca loop --epics "beads-abc,beads-def,beads-ghi" --max-retries 2

# Run it
./.compound-agent/infinity-loop.sh

The loop respects beads dependency graphs — it only processes epics whose dependencies are complete. If an epic fails after --max-retries attempts, it stops and reports before proceeding.

Current maturity: the loop works and has been used to ship real projects, including compound-agent itself. Two things still required human involvement: specifications had to be written before the loop started, and a human applied fixes after the first review pass surfaced real problems (missing error handling, a migration gap, insufficient test coverage). Fully unattended long-duration runs across many epics are the current area of hardening.

The improvement loop

ca improve generates a bash script that iterates over improve/*.md program files, spawning Claude Code sessions to make focused improvements. Each program file defines what to improve, how to find work, and how to validate changes.

# Scaffold an example program file
ca improve init
# Creates improve/example.md with a linting template

# Generate the improvement script
ca improve

# Filter to specific topics
ca improve --topics lint tests --max-iters 3

# Preview without generating
ca improve --dry-run

# Run the generated script
./.compound-agent/improvement-loop.sh

# Preview without executing Claude sessions
IMPROVE_DRY_RUN=1 ./.compound-agent/improvement-loop.sh

Each iteration makes one focused improvement, commits it, and moves on. If an iteration finds nothing to improve or fails validation, it reverts cleanly and moves to the next topic. The loop tracks consecutive no-improvement results and stops early to avoid diminishing returns.

Monitor progress with ca watch --improve to see live trace output from improvement sessions.

Automatic hooks

Once installed, seven Claude Code hooks fire without any commands:

| Hook | When it fires | What it does | |------|--------------|--------------| | SessionStart | Every new session | Loads high-severity lessons into context before you type anything | | PreCompact | Before context compression | Saves phase state so cook-it survives compaction | | UserPromptSubmit | Every prompt | Injects relevant memory items into context | | PreToolUse | During cook-it | Enforces phase gates — prevents jumping ahead | | PostToolUse | After tool success | Clears failure tracking state | | PostToolUseFailure | After tool failure | Tracks failures; suggests memory search after repeated errors | | Stop | Session end | Enforces phase gates — prevents skipping required steps |

No configuration needed. ca setup wires them into your .claude/settings.json.

/compound:architect

AI agents work best on well-scoped problems. When a task exceeds what fits comfortably in one context window, quality degrades — not from lack of capability but from too many competing concerns pulling in different directions.

/compound:architect addresses this before the cook-it cycle begins. It takes a large system description and produces cook-it-ready epics via a structured 4-phase process:

1. Socratic — builds a domain glossary and discovery mindmap; classifies decisions by reversibility
2. Spec — produces system-level EARS requirements, C4 architecture diagrams, and a scenario table
3. Decompose — runs 6 parallel subagents (bounded context mapping, dependency analysis, scope sizing, interface design, STPA hazard analysis, structural-semantic gap analysis) then synthesises into a proposed epic structure
4. Materialise — creates beads epics with scope boundaries, interface contracts, and wired dependencies

Three human approval gates separate the phases. Each output epic is sized for one cook-it cycle and includes an EARS subset for traceability back to the system spec.

/compound:architect "Build a data pipeline: ingestion, transformation, storage, and API layer"

Installation

# Install as dev dependency
pnpm add -D compound-agent

# One-shot setup (creates dirs, hooks, templates)
npx ca setup

Requirements

• Node.js >= 18 (for npx wrapper — the CLI itself is a Go binary)
• ~278MB disk space for the embedding model (one-time download, shared across projects)
• Embedding runs via ca-embed Rust daemon (nomic-embed-text-v1.5 ONNX)

Windows Users

Compound-agent runs natively on Windows (amd64 and arm64). Install and use it the same way as on macOS/Linux:

pnpm add -D compound-agent
npx ca setup

Note: The embedding daemon (ca-embed) is not available on Windows. Search automatically falls back to keyword-only mode (FTS5). All other features work identically. WSL2 users get full functionality including vector search.

CLI Reference

The CLI binary is ca (alias: compound-agent).

Capture

| Command | Description | |---------|-------------| | ca learn "<insight>" | Capture a lesson manually | | ca learn "<insight>" --trigger "<context>" | Capture with trigger context | | ca learn "<insight>" --severity high | Set severity (low/medium/high) | | ca learn "<insight>" --citation src/api.ts:42 | Attach file provenance | | ca capture --input <file> | Capture from structured input file | | ca detect --input <file> | Detect correction patterns in input |

Retrieval

| Command | Description | |---------|-------------| | ca search "<query>" | Keyword search across memory (FTS5) | | ca list | List all memory items | | ca list --invalidated | List only invalidated items | | ca check-plan --plan "<text>" | Semantic search for plan-time retrieval | | ca load-session | Load high-severity items for session start |

Management

| Command | Description | |---------|-------------| | ca show <id> | Display item details | | ca update <id> --insight "..." | Modify item fields | | ca delete <id> | Soft-delete an item | | ca wrong <id> | Mark item as invalid | | ca wrong <id> --reason "..." | Mark invalid with reason | | ca validate <id> | Re-enable an invalidated item | | ca stats | Database health and age distribution | | ca rebuild | Rebuild SQLite index from JSONL | | ca compact | Archive old items, remove tombstones | | ca export | Export items as JSON | | ca import <file> | Import items from JSONL file | | ca prime | Load workflow context (used by hooks) | | ca verify-gates <epic-id> | Verify review + compound tasks exist and are closed | | ca phase-check | Manage cook-it phase state (init/status/clean/gate) | | ca audit | Run audit checks against the codebase | | ca rules check | Run repository-defined rule checks | | ca test-summary | Run tests and output a compact summary |

Automation

| Command | Description | |---------|-------------| | ca loop | Generate infinity loop script for autonomous epic processing | | ca loop --epics "id1,id2,id3" | Target specific epic IDs (comma-separated) | | ca loop -o <path> | Custom output path (default: ./.compound-agent/infinity-loop.sh) | | ca loop --max-retries <n> | Max retries per epic on failure (default: 1) | | ca loop --force | Overwrite existing script | | ca loop --reviewers <names...> | Enable review phase with specified reviewers (claude-sonnet, claude-opus, gemini, codex) | | ca loop --review-every <n> | Review every N completed epics (0 = end-only, default: 0) | | ca loop --max-review-cycles <n> | Max review/fix iterations (default: 3) | | ca loop --review-blocking | Fail loop if review not approved after max cycles | | ca loop --review-model <model> | Model for implementer fix sessions (default: claude-opus-4-6[1m]) | | ca improve | Generate improvement loop script from improve/*.md programs | | ca improve --topics <names...> | Run only specific topics | | ca improve --max-iters <n> | Max iterations per topic (default: 5) | | ca improve --time-budget <seconds> | Total time budget, 0=unlimited (default: 0) | | ca improve --dry-run | Validate and print plan without generating | | ca improve --force | Overwrite existing script | | ca improve init | Scaffold an example improve/*.md program file | | ca watch | Tail and pretty-print live trace from loop sessions | | ca watch --epic <id> | Watch a specific epic trace | | ca watch --improve | Watch improvement loop traces | | ca watch --no-follow | Print existing trace and exit (no live tail) | | ca polish | Generate polish loop script for iterative refinement | | ca polish --spec-file <path> | Specify the spec file for polish review | | ca polish --reviewers <names> | Comma-separated reviewer models | | ca polish --cycles <n> | Number of polish cycles (default: 1) | | ca polish --force | Overwrite existing script | | ca info | Show project status, phase, and telemetry summary | | ca info --open | Open project dashboard in browser | | ca info --json | Output as JSON | | ca health | Check project health and dependencies | | ca feedback | Submit feedback about compound-agent |

Knowledge

| Command | Description | |---------|-------------| | ca knowledge "<query>" | Hybrid search over indexed project docs | | ca index-docs | Index docs/ directory into knowledge base |

Setup

| Command | Description | |---------|-------------| | ca setup | One-shot setup (hooks + templates) | | ca setup --skip-hooks | Setup without installing hooks | | ca setup --json | Output result as JSON | | ca setup claude | Install Claude Code hooks only | | ca setup claude --status | Check Claude Code integration health | | ca setup claude --uninstall | Remove Claude hooks only | | ca setup claude --dry-run | Preview what would change without writing | | ca init | Initialize compound-agent in current repo | | ca init --skip-agents | Skip AGENTS.md and template installation | | ca init --skip-claude | Skip Claude Code hooks installation | | ca download-model --json | Download embedding model with JSON output | | ca about | Show version, animation, and recent changelog | | ca doctor | Verify external dependencies and project health |

Memory Types

| Type | Trigger means | Insight means | Example | |------|---------------|---------------|---------| | lesson | What happened | What was learned | "Polars 10x faster than pandas for large files" | | solution | The problem | The resolution | "Auth 401 fix: add X-Request-ID header" | | pattern | When it applies | Why it matters | { bad: "await in loop", good: "Promise.all" } | | preference | The context | The preference | "Use uv over pip in this project" |

Retrieval Ranking

boost  = severity_boost * recency_boost * confirmation_boost
         clamped to max 1.8
score  = vector_similarity(query, item) * boost

severity_boost:     high=1.5, medium=1.0, low=0.8
recency_boost:      last 30d=1.2, older=1.0
confirmation_boost: confirmed=1.3, unconfirmed=1.0

FAQ

Q: How is this different from mem0? A: mem0 is a cloud memory layer for general AI agents. Compound Agent is local-first with git-tracked storage and local embeddings — no API keys or cloud services needed. It also goes beyond memory with structured workflows, multi-agent review, and issue tracking.

Q: Does this work offline? A: Yes, completely. Embeddings run locally via the ca-embed Rust daemon (nomic-embed-text-v1.5 ONNX). No network requests after the initial model download.

Q: How much disk space does it need? A: ~278MB for the embedding model (one-time download, shared across projects) plus negligible space for lessons.

Q: Can I use it with other AI coding tools? A: The CLI (ca) works standalone with any tool. Full hook integration is available for Claude Code and Gemini CLI.

Q: What happens if the embedding model isn't available? A: Search gracefully falls back to keyword-only mode. Other commands that require embeddings will tell you what's missing. Run ca doctor to diagnose issues.

Q: Is the loop production-ready? A: The loop works and has been used to ship real projects, including compound-agent itself. Long-duration autonomous runs across many epics are the current area of hardening. For 3–5 epic sequences, it is reliable today.

Development

cd go && go build ./cmd/ca   # Build CLI binary
cd go && go test ./...       # Full test suite
cd go && go vet ./...        # Static analysis

Technology Stack

| Component | Technology | |-----------|------------| | Language | Go | | Package Manager | Go modules (+ pnpm for npm wrapper) | | Build | go build with CGO_ENABLED=0 (pure Go) | | Testing | go test + table-driven tests | | Storage | modernc.org/sqlite + FTS5 (pure Go, no CGO) | | Embeddings | ca-embed (Rust daemon via IPC) | | CLI | Cobra | | Release | GoReleaser | | Issue Tracking | Beads (bd) |

Architecture

graph TD
    subgraph "Claude Code Session"
        H[Hooks] -->|SessionStart| P[ca prime]
        H -->|UserPromptSubmit| UP[user-prompt hook]
        H -->|PostToolUseFailure| TF[failure tracker]
        H -->|PreToolUse| PG[phase guard]
        H -->|Stop| SA[stop audit]
    end

    subgraph "CLI (Go + Cobra)"
        CA[ca binary] --> LEARN[ca learn]
        CA --> SEARCH[ca search]
        CA --> LOOP[ca loop]
        CA --> SETUP[ca setup]
        CA --> DOCTOR[ca doctor]
    end

    subgraph "Storage"
        JSONL[".claude/lessons/index.jsonl<br/>(git-tracked source of truth)"]
        SQLITE[".claude/.cache/lessons.sqlite<br/>(FTS5 search index)"]
        JSONL -->|rebuild| SQLITE
    end

    subgraph "Embeddings"
        EMBED["ca-embed (Rust daemon)"] -->|IPC via Unix socket| VEC[Vector similarity]
    end

    UP -->|inject lessons| SEARCH
    TF -->|suggest search| SEARCH
    LEARN --> JSONL
    SEARCH --> SQLITE
    SEARCH --> VEC

Three layers work together:

• Portable storage: JSONL in git for conflict-free collaboration
• Fast index: SQLite + FTS5 for keyword search, rebuilt from JSONL on demand
• Semantic search: Rust embedding daemon for vector similarity, falls back to keyword-only if unavailable

Documentation

| Document | Purpose | |----------|---------| | docs/ARCHITECTURE-V2.md | Three-layer architecture design | | docs/MIGRATION.md | Migration guide from learning-agent | | CHANGELOG.md | Version history | | AGENTS.md | Agent workflow instructions |

The most direct way to explore the system is to open this repository with an AI agent and ask it to walk you through the design — the project is structured precisely for that.

Acknowledgments

Compound Agent builds on ideas and patterns from these projects:

| Project | Influence | |---------|-----------| | Compound Engineering Plugin | The "compound" philosophy — each unit of work makes subsequent units easier. Multi-agent review workflows and skills as encoded knowledge. | | Beads | Git-backed JSONL + SQLite hybrid storage model, hash-based conflict-free IDs, dependency graphs | | OpenClaw | Claude Code integration patterns and hook-based workflow architecture |

Also informed by research into Reflexion (verbal reinforcement learning), Voyager (executable skill libraries), and production systems from mem0, Letta, and GitHub Copilot Memory.

Contributing

Bug reports and feature requests are welcome via Issues. Pull requests are not accepted at this time — see CONTRIBUTING.md for details.

License

MIT — see LICENSE for details.

The embedding model (nomic-embed-text-v1.5) is downloaded on-demand from Hugging Face under the Apache 2.0 license. See THIRD-PARTY-LICENSES.md for full dependency license information.