compound-agent 1.4.3 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (20) hide show
  1. package/CHANGELOG.md +90 -32
  2. package/LICENSE +1 -1
  3. package/README.md +80 -138
  4. package/context7.json +21 -0
  5. package/dist/cli.js +1494 -820
  6. package/dist/cli.js.map +1 -1
  7. package/dist/index.d.ts +1 -1
  8. package/dist/index.js +34 -5
  9. package/dist/index.js.map +1 -1
  10. package/docs/research/index.md +12 -0
  11. package/docs/research/security/auth-patterns.md +138 -0
  12. package/docs/research/security/data-exposure.md +185 -0
  13. package/docs/research/security/dependency-security.md +91 -0
  14. package/docs/research/security/injection-patterns.md +249 -0
  15. package/docs/research/security/overview.md +81 -0
  16. package/docs/research/security/secrets-checklist.md +92 -0
  17. package/docs/research/security/secure-coding-failure.md +297 -0
  18. package/llms.txt +31 -0
  19. package/package.json +24 -8
  20. package/scripts/postinstall.mjs +102 -0
package/CHANGELOG.md CHANGED
@@ -9,6 +9,61 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
9
9
 
10
10
  ## [Unreleased]
11
11
 
12
+ ## [1.5.0] - 2026-02-24
13
+
14
+ ### Added
15
+
16
+ - **Gemini CLI compatibility adapter**: `ca setup gemini` scaffolds `.gemini/` directory with hook scripts, TOML slash commands, and inlined skills -- bridging compound-agent to work with Google's Gemini CLI via the Adapter Pattern
17
+ - **Gemini hooks**: Maps SessionStart, BeforeAgent, BeforeTool, AfterTool to compound-agent's existing hook pipeline (`ca prime`, `ca hooks run user-prompt`, `ca hooks run phase-guard`, `ca hooks run post-tool-success`)
18
+ - **Gemini TOML commands**: Auto-generates `.gemini/commands/compound/*.toml` using `@{path}` file injection to maintain a single source of truth with Claude commands
19
+ - **Gemini skills proxying**: Inlines phase and agent role skill content into `.gemini/skills/` with YAML frontmatter
20
+ - **23 integration tests** for the Gemini adapter covering hooks, settings.json, TOML commands, skills, and dry-run mode
21
+
22
+ ### Fixed
23
+
24
+ - **Gemini hook stderr leak**: Corrected `2>&1 > /dev/null` (leaks stderr to stdout, corrupting JSON) to `> /dev/null 2>&1`
25
+ - **Gemini TOML file injection syntax**: Changed `@path` to `@{path}` (Gemini CLI requires curly braces)
26
+ - **Gemini skill file injection**: Skills now inline content instead of using `@{path}` which only works in TOML prompt fields, not SKILL.md
27
+ - **Gemini phase guard always allowing**: Hook now checks `ca hooks run phase-guard` exit code and returns structured `{"decision": "deny"}` on failure (exit 0, not exit 2, so Gemini parses the reason from stdout)
28
+ - **Gemini BeforeTool matcher incomplete**: Added `create_file` to BeforeTool and AfterTool matchers alongside `replace` and `write_file`
29
+ - **TOML description escaping**: `parseDescription` now escapes `\` and `"` to prevent malformed TOML output
30
+ - **Flaky embedding test**: Added 15s timeout to `isModelUsable` test
31
+
32
+ ## [1.4.4] - 2026-02-23
33
+
34
+ ### Added
35
+
36
+ - **Security arc with P0-P3 severity model**: Security-reviewer promoted from generic OWASP checker to mandatory core-4 reviewer with P0 (blocks merge), P1 (requires ack), P2 (should fix), P3 (nice to have) classification
37
+ - **5 on-demand security specialist skills**: `/security-injection`, `/security-secrets`, `/security-auth`, `/security-data`, `/security-deps` -- spawned by security-reviewer via SendMessage within the review AgentTeam for deep trace analysis
38
+ - **6 security reference docs** (`docs/research/security/`): overview, injection-patterns, secrets-checklist, auth-patterns, data-exposure, dependency-security -- distilled from the secure-coding-failure PhD survey into actionable agent guides
39
+ - **Native addon build injection** (`scripts/postinstall.mjs`): Postinstall script auto-patches consumer `package.json` with `pnpm.onlyBuiltDependencies` config for `better-sqlite3` and `node-llama-cpp`. Handles indent preservation, BOM stripping, atomic writes
40
+ - **CLI preflight diagnostics** (`src/cli-preflight.ts`): Catches native module load failures before commands run, prints PM-specific fix instructions (pnpm: 3 options; npm/yarn: rebuild + build tool hints)
41
+ - **`ca doctor` pnpm check**: Verifies `onlyBuiltDependencies` is configured correctly for pnpm projects, recognizes wildcard `["*"]` as valid
42
+ - **Escalation-wiring tests**: 7 new tests verifying security-reviewer mentions all 5 specialists, each specialist declares "Spawned by security-reviewer", P0 documented as merge-blocking, each specialist has `npx ca knowledge` and references correct research doc
43
+ - **better-sqlite3 injection patterns**: Added project-specific `db.exec()` vs `db.prepare().run()` examples to `injection-patterns.md`
44
+
45
+ ### Fixed
46
+
47
+ - **Noisy `node-llama-cpp` warnings on headless Linux**: Vulkan binary fallback and `special_eos_id` tokenizer warnings no longer print during `ca search` / `ca knowledge` -- GPU auto-detection preserved via `progressLogs: false` + `logLevel: error`
48
+ - **Resource leak in `isModelUsable()`**: `Llama` and `LlamaModel` instances are now properly disposed after the preflight usability check
49
+ - **Wildcard `onlyBuiltDependencies`**: Doctor and postinstall now recognize `["*"]` as fully configured (no false positive)
50
+ - **Infinity loop marker injection**: `--model` validated against shell metacharacters; grep patterns anchored (`^EPIC_COMPLETE`, `^EPIC_FAILED`) to prevent false-positive matches from prompt echo in logs
51
+ - **Template-to-deployed SKILL.md drift**: Backported all deployed specialist improvements (output fields, collaboration notes, `npx ca knowledge` lines) into source templates so `ca setup --update` no longer regresses
52
+ - **SSRF citations**: 3 OWASP references in `secure-coding-failure.md` corrected from A01 (Broken Access Control) to A10 (SSRF)
53
+ - **Stale verification docs**: Exit criteria updated from 6 to 8 categories (added Security Clear + Workflow Gates); closed-loop review process updated with security check in Stage 4 flowchart
54
+ - **Broken dual-path reference** in `subagent-pipeline.md`: Now documents both `docs/research/security/` (source repo) and `docs/compound/research/security/` (consumer repos)
55
+ - **Incomplete OWASP mapping** in `overview.md`: Completed from 5/10 to 10/10 (added A04, A05, A07, A08, A09)
56
+
57
+ ### Changed
58
+
59
+ - **`getLlama()` initialization hardened**: Both call sites (`nomic.ts`, `model.ts`) now pass `build: 'never'` to prevent silent compilation from source on exotic platforms; set `NODE_LLAMA_CPP_DEBUG=true` to re-enable verbose output
60
+ - **Review skill wired to security arc**: P0 added to severity overview, security specialist skills listed as on-demand members, quality criteria include P0/P1 checks
61
+ - **WORKFLOW template**: Severity classification updated from P1/P2/P3 to P0-P3 with "Fix all P0/P1 findings"
62
+ - **Zero-findings instruction**: All 6 security templates (reviewer + 5 specialists) now include "return CLEAR" instruction when no findings detected
63
+ - **Scope-limiting instruction**: `security-injection` prioritizes files with interpreter sinks over pure data/config for large diffs (500+ lines)
64
+ - **Non-web context**: `security-auth` includes step for CLI/API-only projects without web routes
65
+ - **Graceful audit skip**: `security-deps` handles missing `pnpm audit` / `pip-audit` gracefully instead of failing
66
+
12
67
  ## [1.4.3] - 2026-02-23
13
68
 
14
69
  ### Fixed
@@ -728,35 +783,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
728
783
  - Vitest test suite
729
784
  - tsup build configuration
730
785
 
731
- [Unreleased]: https://github.com/Nathandela/learning_agent/compare/v1.4.1...HEAD
732
- [1.4.1]: https://github.com/Nathandela/learning_agent/compare/v1.4.0...v1.4.1
733
- [1.4.0]: https://github.com/Nathandela/learning_agent/compare/v1.3.9...v1.4.0
734
- [1.3.9]: https://github.com/Nathandela/learning_agent/compare/v1.3.8...v1.3.9
735
- [1.3.8]: https://github.com/Nathandela/learning_agent/compare/v1.3.7...v1.3.8
736
- [1.3.7]: https://github.com/Nathandela/learning_agent/compare/v1.3.3...v1.3.7
737
- [1.3.3]: https://github.com/Nathandela/learning_agent/compare/v1.3.2...v1.3.3
738
- [1.3.2]: https://github.com/Nathandela/learning_agent/compare/v1.3.1...v1.3.2
739
- [1.3.1]: https://github.com/Nathandela/learning_agent/compare/v1.3.0...v1.3.1
740
- [1.3.0]: https://github.com/Nathandela/learning_agent/compare/v1.2.11...v1.3.0
741
- [1.2.11]: https://github.com/Nathandela/learning_agent/compare/v1.2.10...v1.2.11
742
- [1.2.10]: https://github.com/Nathandela/learning_agent/compare/v1.2.9...v1.2.10
743
- [1.2.9]: https://github.com/Nathandela/learning_agent/compare/v1.2.7...v1.2.9
744
- [1.2.7]: https://github.com/Nathandela/learning_agent/compare/v1.2.6...v1.2.7
745
- [1.2.6]: https://github.com/Nathandela/learning_agent/compare/v1.2.5...v1.2.6
746
- [1.2.5]: https://github.com/Nathandela/learning_agent/compare/v1.2.4...v1.2.5
747
- [1.2.4]: https://github.com/Nathandela/learning_agent/compare/v1.2.1...v1.2.4
748
- [1.2.1]: https://github.com/Nathandela/learning_agent/compare/v1.2.0...v1.2.1
749
- [1.2.0]: https://github.com/Nathandela/learning_agent/compare/v1.1.0...v1.2.0
750
- [1.1.0]: https://github.com/Nathandela/learning_agent/compare/v1.0.0...v1.1.0
751
- [1.0.0]: https://github.com/Nathandela/learning_agent/compare/v0.2.9...v1.0.0
752
- [0.2.9]: https://github.com/Nathandela/learning_agent/compare/v0.2.8...v0.2.9
753
- [0.2.8]: https://github.com/Nathandela/learning_agent/compare/v0.2.7...v0.2.8
754
- [0.2.7]: https://github.com/Nathandela/learning_agent/compare/v0.2.6...v0.2.7
755
- [0.2.6]: https://github.com/Nathandela/learning_agent/compare/v0.2.5...v0.2.6
756
- [0.2.5]: https://github.com/Nathandela/learning_agent/compare/v0.2.4...v0.2.5
757
- [0.2.4]: https://github.com/Nathandela/learning_agent/compare/v0.2.3...v0.2.4
758
- [0.2.3]: https://github.com/Nathandela/learning_agent/compare/v0.2.2...v0.2.3
759
- [0.2.2]: https://github.com/Nathandela/learning_agent/compare/v0.2.1...v0.2.2
760
- [0.2.1]: https://github.com/Nathandela/learning_agent/compare/v0.2.0...v0.2.1
761
- [0.2.0]: https://github.com/Nathandela/learning_agent/compare/v0.1.0...v0.2.0
762
- [0.1.0]: https://github.com/Nathandela/learning_agent/releases/tag/v0.1.0
786
+ [Unreleased]: https://github.com/Nathandela/compound-agent/compare/v1.4.4...HEAD
787
+ [1.4.4]: https://github.com/Nathandela/compound-agent/compare/v1.4.3...v1.4.4
788
+ [1.4.3]: https://github.com/Nathandela/compound-agent/compare/v1.4.2...v1.4.3
789
+ [1.4.2]: https://github.com/Nathandela/compound-agent/compare/v1.4.1...v1.4.2
790
+ [1.4.1]: https://github.com/Nathandela/compound-agent/compare/v1.4.0...v1.4.1
791
+ [1.4.0]: https://github.com/Nathandela/compound-agent/compare/v1.3.9...v1.4.0
792
+ [1.3.9]: https://github.com/Nathandela/compound-agent/compare/v1.3.8...v1.3.9
793
+ [1.3.8]: https://github.com/Nathandela/compound-agent/compare/v1.3.7...v1.3.8
794
+ [1.3.7]: https://github.com/Nathandela/compound-agent/compare/v1.3.3...v1.3.7
795
+ [1.3.3]: https://github.com/Nathandela/compound-agent/compare/v1.3.2...v1.3.3
796
+ [1.3.2]: https://github.com/Nathandela/compound-agent/compare/v1.3.1...v1.3.2
797
+ [1.3.1]: https://github.com/Nathandela/compound-agent/compare/v1.3.0...v1.3.1
798
+ [1.3.0]: https://github.com/Nathandela/compound-agent/compare/v1.2.11...v1.3.0
799
+ [1.2.11]: https://github.com/Nathandela/compound-agent/compare/v1.2.10...v1.2.11
800
+ [1.2.10]: https://github.com/Nathandela/compound-agent/compare/v1.2.9...v1.2.10
801
+ [1.2.9]: https://github.com/Nathandela/compound-agent/compare/v1.2.7...v1.2.9
802
+ [1.2.7]: https://github.com/Nathandela/compound-agent/compare/v1.2.6...v1.2.7
803
+ [1.2.6]: https://github.com/Nathandela/compound-agent/compare/v1.2.5...v1.2.6
804
+ [1.2.5]: https://github.com/Nathandela/compound-agent/compare/v1.2.4...v1.2.5
805
+ [1.2.4]: https://github.com/Nathandela/compound-agent/compare/v1.2.1...v1.2.4
806
+ [1.2.1]: https://github.com/Nathandela/compound-agent/compare/v1.2.0...v1.2.1
807
+ [1.2.0]: https://github.com/Nathandela/compound-agent/compare/v1.1.0...v1.2.0
808
+ [1.1.0]: https://github.com/Nathandela/compound-agent/compare/v1.0.0...v1.1.0
809
+ [1.0.0]: https://github.com/Nathandela/compound-agent/compare/v0.2.9...v1.0.0
810
+ [0.2.9]: https://github.com/Nathandela/compound-agent/compare/v0.2.8...v0.2.9
811
+ [0.2.8]: https://github.com/Nathandela/compound-agent/compare/v0.2.7...v0.2.8
812
+ [0.2.7]: https://github.com/Nathandela/compound-agent/compare/v0.2.6...v0.2.7
813
+ [0.2.6]: https://github.com/Nathandela/compound-agent/compare/v0.2.5...v0.2.6
814
+ [0.2.5]: https://github.com/Nathandela/compound-agent/compare/v0.2.4...v0.2.5
815
+ [0.2.4]: https://github.com/Nathandela/compound-agent/compare/v0.2.3...v0.2.4
816
+ [0.2.3]: https://github.com/Nathandela/compound-agent/compare/v0.2.2...v0.2.3
817
+ [0.2.2]: https://github.com/Nathandela/compound-agent/compare/v0.2.1...v0.2.2
818
+ [0.2.1]: https://github.com/Nathandela/compound-agent/compare/v0.2.0...v0.2.1
819
+ [0.2.0]: https://github.com/Nathandela/compound-agent/compare/v0.1.0...v0.2.0
820
+ [0.1.0]: https://github.com/Nathandela/compound-agent/releases/tag/v0.1.0
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 Nathan Delacrétaz
3
+ Copyright (c) 2025-2026 Nathan Delacrétaz
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,64 +1,61 @@
1
1
  # Compound Agent
2
2
 
3
- Semantically-intelligent workflow plugin for Claude Code. Every unit of work compounds -- mistakes become lessons, solutions become searchable knowledge, and each cycle makes subsequent work smarter.
3
+ **Semantic memory for Claude Code -- capture mistakes once, never repeat them.**
4
+
5
+ [![npm version](https://img.shields.io/npm/v/compound-agent)](https://www.npmjs.com/package/compound-agent)
6
+ [![license](https://img.shields.io/npm/l/compound-agent)](LICENSE)
7
+ [![TypeScript](https://img.shields.io/badge/TypeScript-5.3+-blue)](https://www.typescriptlang.org/)
4
8
 
5
9
  ## Overview
6
10
 
7
- Claude Code forgets everything between sessions. Compound Agent fixes this with a three-layer system: issue tracking (Beads) at the foundation, semantic memory with vector search in the middle, and structured workflow phases on top. It captures knowledge from corrections, discoveries, and completed work, then retrieves it precisely when relevant -- at session start, during planning, and before architectural decisions.
11
+ Claude Code forgets everything between sessions. Compound Agent fixes this with a three-layer system: issue tracking (Beads) at the foundation, semantic memory with vector search in the middle, and structured workflow phases on top. It captures knowledge from corrections, discoveries, and completed work, then retrieves it precisely when relevant -- at session start, during planning, and before architectural decisions. Every cycle through the loop makes subsequent cycles smarter.
8
12
 
9
- ## Architecture
13
+ ## The Compound Loop
10
14
 
11
- ```
12
- LAYER 3: WORKFLOWS
13
- /compound:brainstorm, /compound:plan, /compound:work,
14
- /compound:review, /compound:compound, /compound:lfg
15
- Agent teams at each phase with inter-communication
16
-
17
- LAYER 2: SEMANTIC MEMORY
18
- 4 types: lesson | solution | pattern | preference
19
- JSONL source of truth + SQLite FTS5 index + vector embeddings
20
- Ranked retrieval: similarity * severity * recency * confirmation
21
-
22
- LAYER 1: BEADS (Foundation)
23
- Issue tracking + dependency graph
24
- Git-backed persistence + distributed sync
15
+ ```mermaid
16
+ graph LR
17
+ B[BRAINSTORM] --> P[PLAN]
18
+ P --> W[WORK]
19
+ W --> R[REVIEW]
20
+ R --> C[COMPOUND]
21
+ C --> M[(MEMORY)]
22
+ M --> P
25
23
  ```
26
24
 
27
- ### Storage Layout
25
+ A bug found in review becomes a lesson. That lesson surfaces during planning of similar work. The plan accounts for the known issue. Work avoids the mistake.
28
26
 
29
- ```
30
- project_root/
31
- +-- AGENTS.md <- Workflow instructions for Claude
32
- +-- .claude/
33
- +-- settings.json <- Claude Code hooks
34
- +-- .ca-phase-state.json <- LFG phase tracking (generated)
35
- +-- .ca-failure-state.json <- Hook failure counters (generated)
36
- +-- lessons/
37
- | +-- index.jsonl <- Source of truth (git-tracked)
38
- | +-- archive/ <- Compacted old items
39
- +-- .cache/
40
- +-- lessons.sqlite <- Rebuildable index (.gitignore)
27
+ ## Architecture
28
+
29
+ ```mermaid
30
+ block-beta
31
+ columns 1
32
+ block:L3["Layer 3: Workflows"]
33
+ A["Slash commands"] B["Agent teams"] C["5-phase cycle"]
34
+ end
35
+ block:L2["Layer 2: Semantic Memory"]
36
+ D["JSONL source of truth"] E["SQLite FTS5 index"] F["Vector embeddings"]
37
+ end
38
+ block:L1["Layer 1: Beads"]
39
+ G["Issue tracking"] H["Git-backed sync"] I["Dependency graph"]
40
+ end
41
+
42
+ L3 --> L2
43
+ L2 --> L1
41
44
  ```
42
45
 
43
- ### The Compound Loop
46
+ Four memory types -- `lesson`, `solution`, `pattern`, `preference` -- share one store, one schema, and one ranked retrieval mechanism combining vector similarity, severity, recency, and confirmation status.
44
47
 
45
- ```
46
- COMPOUND --> writes to --> MEMORY
47
- |
48
- searched by
49
- |
50
- PLAN --> creates context for --> WORK
51
- |
52
- produces for
53
- |
54
- REVIEW
55
- |
56
- generates for
57
- |
58
- COMPOUND
59
- ```
48
+ ## Why Not Just X?
60
49
 
61
- Every cycle through the loop makes subsequent cycles smarter. A bug found in review becomes a lesson. That lesson surfaces during planning of similar work. The plan accounts for the known issue. Work avoids the mistake.
50
+ | Feature | `.claude/CLAUDE.md` | Claude Reflect | mem0 | Compound Agent |
51
+ |---------|---------------------|----------------|------|----------------|
52
+ | Persists across sessions | Manual edits | Yes | Yes | Yes |
53
+ | Semantic search | No | No (regex) | Yes (cloud) | Yes (local) |
54
+ | Quality gate on capture | No | No | No | Yes (novelty + specificity) |
55
+ | Runs fully offline | Yes | Yes | No (API) | Yes |
56
+ | Git-tracked knowledge | Yes | No | No | Yes (JSONL) |
57
+ | Structured workflow phases | No | No | No | Yes (5 phases) |
58
+ | Claude Code native integration | N/A | Yes | No | Yes (hooks + commands) |
62
59
 
63
60
  ## Installation
64
61
 
@@ -76,7 +73,7 @@ npx ca setup --skip-model
76
73
  ### Requirements
77
74
 
78
75
  - Node.js >= 20
79
- - ~278MB disk space for the embedding model
76
+ - ~278MB disk space for the embedding model (one-time download, shared across projects)
80
77
  - ~150MB RAM during embedding operations
81
78
 
82
79
  ### pnpm Users
@@ -95,19 +92,6 @@ If you prefer to configure manually, add to your `package.json`:
95
92
 
96
93
  Then run `pnpm install`.
97
94
 
98
- ### What `setup` Does
99
-
100
- | Action | Location | Purpose |
101
- |--------|----------|---------|
102
- | Create lessons store | `.claude/lessons/` | JSONL + cache directory |
103
- | Install AGENTS.md | project root | Workflow instructions for Claude |
104
- | Configure hooks | `.claude/settings.json` | SessionStart, PreCompact, UserPromptSubmit, PostToolUseFailure, PostToolUse hooks |
105
- | Install git pre-commit hook | `.git/hooks/pre-commit` | Lesson capture reminder before commits |
106
- | Install workflow commands | `.claude/commands/compound/` | Slash commands for each phase |
107
- | Install agent definitions | `.claude/agents/compound/` | Specialized agent roles |
108
- | Install phase skills | `.claude/skills/compound/` | Process instructions per phase |
109
- | Download embedding model | `~/.node-llama-cpp/models/` | First-use only, ~278MB |
110
-
111
95
  ## Quick Start
112
96
 
113
97
  The five-phase workflow:
@@ -195,8 +179,6 @@ The CLI binary is `ca` (alias: `compound-agent`).
195
179
  | `ca loop --max-retries <n>` | Max retries per epic on failure (default: 1) |
196
180
  | `ca loop --force` | Overwrite existing script |
197
181
 
198
- Generated scripts detect three markers: `EPIC_COMPLETE` (success), `EPIC_FAILED` (retry then stop), `HUMAN_REQUIRED: <reason>` (skip and continue). Run with `LOOP_DRY_RUN=1` to preview.
199
-
200
182
  ### Setup
201
183
 
202
184
  | Command | Description |
@@ -213,24 +195,8 @@ Generated scripts detect three markers: `EPIC_COMPLETE` (success), `EPIC_FAILED`
213
195
  | `ca about` | Show version, animation, and recent changelog |
214
196
  | `ca doctor` | Verify external dependencies and project health |
215
197
 
216
- ## Workflow Commands
217
-
218
- Installed to `.claude/commands/compound/` during setup. Invoked as slash commands in Claude Code.
219
-
220
- | Command | Phase | Description |
221
- |---------|-------|-------------|
222
- | `/compound:brainstorm` | Brainstorm | Explore the problem, iterate with user, create beads epic |
223
- | `/compound:plan` | Plan | Create detailed plan with memory retrieval + research agents |
224
- | `/compound:work` | Work | Execute with agent teams, adaptive TDD per task complexity |
225
- | `/compound:review` | Review | Multi-agent review (security, architecture, performance, tests, simplicity) |
226
- | `/compound:compound` | Compound | Capture lessons, solutions, patterns into memory |
227
- | `/compound:lfg` | All | Chain all phases sequentially |
228
- | `/compound:set-worktree` | Setup | Create isolated git worktree for an epic |
229
-
230
198
  ## Memory Types
231
199
 
232
- All types share one store, one schema, one search mechanism. A query returns the most relevant items regardless of type.
233
-
234
200
  | Type | Trigger means | Insight means | Example |
235
201
  |------|---------------|---------------|---------|
236
202
  | `lesson` | What happened | What was learned | "Polars 10x faster than pandas for large files" |
@@ -238,35 +204,6 @@ All types share one store, one schema, one search mechanism. A query returns the
238
204
  | `pattern` | When it applies | Why it matters | `{ bad: "await in loop", good: "Promise.all" }` |
239
205
  | `preference` | The context | The preference | "Use uv over pip in this project" |
240
206
 
241
- ## Memory Item Schema
242
-
243
- All memory items share a common schema with a discriminated union on the `type` field.
244
-
245
- ### Required Fields
246
-
247
- | Field | Type | Description |
248
- |-------|------|-------------|
249
- | `id` | string | Hash-based unique identifier |
250
- | `type` | `"lesson"` \| `"solution"` \| `"pattern"` \| `"preference"` | Item type |
251
- | `trigger` | string | What caused/prompted this |
252
- | `insight` | string | What was learned |
253
- | `tags` | string[] | Categorization tags |
254
- | `source` | string | How captured: `user_correction`, `self_correction`, `test_failure`, `manual` |
255
- | `context` | `{ tool, intent }` | Capture context |
256
- | `created` | ISO string | Creation timestamp |
257
- | `confirmed` | boolean | Whether user confirmed |
258
- | `supersedes` | string[] | IDs of items this replaces |
259
- | `related` | string[] | IDs of related items |
260
-
261
- ### Optional Fields
262
-
263
- | Field | Type | Description |
264
- |-------|------|-------------|
265
- | `evidence` | string | Supporting evidence |
266
- | `severity` | `"high"` \| `"medium"` \| `"low"` | Importance level |
267
- | `citation` | `{ file, line?, commit? }` | File/line provenance |
268
- | `pattern` | `{ bad, good }` | Code pattern (required for `pattern` type) |
269
-
270
207
  ### Retrieval Ranking
271
208
 
272
209
  ```
@@ -279,26 +216,22 @@ recency_boost: last 30d=1.2, older=1.0
279
216
  confirmation_boost: confirmed=1.3, unconfirmed=1.0
280
217
  ```
281
218
 
282
- ### Example
219
+ ## FAQ
283
220
 
284
- ```json
285
- {
286
- "id": "Sa1b2c3d4",
287
- "type": "solution",
288
- "trigger": "API returned 401 despite valid JWT token",
289
- "insight": "Auth API requires X-Request-ID header in all requests",
290
- "evidence": "Traced in network tab, discovered missing header requirement",
291
- "severity": "high",
292
- "tags": ["api", "auth", "headers"],
293
- "source": "test_failure",
294
- "context": { "tool": "fetch", "intent": "API authentication" },
295
- "created": "2026-01-15T10:30:00.000Z",
296
- "confirmed": true,
297
- "supersedes": [],
298
- "related": [],
299
- "citation": { "file": "src/api/client.ts", "line": 42 }
300
- }
301
- ```
221
+ **Q: How is this different from mem0?**
222
+ A: mem0 is a cloud memory layer for general AI agents. Compound Agent is local-first, designed specifically for Claude Code, with git-tracked storage and local embeddings -- no API keys or cloud services needed.
223
+
224
+ **Q: Does this work offline?**
225
+ A: Yes, completely. Embeddings run locally via node-llama-cpp. No network requests after the initial model download.
226
+
227
+ **Q: How much disk space does it need?**
228
+ A: ~278MB for the embedding model (one-time download, shared across projects) plus negligible space for lessons.
229
+
230
+ **Q: Can I use it with other AI coding tools?**
231
+ A: The CLI (`ca`) works standalone, but hooks and slash commands are Claude Code specific. The TypeScript API can be integrated into other tools.
232
+
233
+ **Q: What happens if the embedding model isn't available?**
234
+ A: Compound Agent hard-fails rather than silently degrading. Run `npx ca doctor` to diagnose issues.
302
235
 
303
236
  ## Development
304
237
 
@@ -309,18 +242,14 @@ pnpm dev # Watch mode (rebuild on changes)
309
242
  pnpm lint # Type check + ESLint
310
243
  ```
311
244
 
312
- ### Test Scripts
313
-
314
245
  | Script | Duration | Use Case |
315
246
  |--------|----------|----------|
316
- | `pnpm test:fast` | ~6s | Rapid feedback during development (skips CLI integration tests) |
247
+ | `pnpm test:fast` | ~6s | Rapid feedback during development |
317
248
  | `pnpm test` | ~60s | Full suite before committing |
318
249
  | `pnpm test:changed` | varies | Only tests affected by recent changes |
319
250
  | `pnpm test:watch` | - | Watch mode for TDD workflow |
320
251
  | `pnpm test:all` | ~60s | Full suite with model download |
321
252
 
322
- **Recommended**: Use `pnpm test:fast` while coding, `pnpm test` before committing.
323
-
324
253
  ## Technology Stack
325
254
 
326
255
  | Component | Technology |
@@ -339,12 +268,25 @@ pnpm lint # Type check + ESLint
339
268
 
340
269
  | Document | Purpose |
341
270
  |----------|---------|
342
- | [docs/ARCHITECTURE-V2.md](docs/ARCHITECTURE-V2.md) | Three-layer architecture design |
343
- | [docs/MIGRATION.md](docs/MIGRATION.md) | Migration guide from learning-agent |
344
- | [CHANGELOG.md](CHANGELOG.md) | Version history |
345
- | [AGENTS.md](AGENTS.md) | Agent workflow instructions |
346
- | [.claude/CLAUDE.md](.claude/CLAUDE.md) | Claude Code project instructions |
271
+ | [docs/ARCHITECTURE-V2.md](https://github.com/Nathandela/compound-agent/blob/main/docs/ARCHITECTURE-V2.md) | Three-layer architecture design |
272
+ | [docs/MIGRATION.md](https://github.com/Nathandela/compound-agent/blob/main/docs/MIGRATION.md) | Migration guide from learning-agent |
273
+ | [CHANGELOG.md](https://github.com/Nathandela/compound-agent/blob/main/CHANGELOG.md) | Version history |
274
+ | [AGENTS.md](https://github.com/Nathandela/compound-agent/blob/main/AGENTS.md) | Agent workflow instructions |
275
+
276
+ ## Acknowledgments
277
+
278
+ Compound Agent builds on ideas and patterns from these projects:
279
+
280
+ | Project | Influence |
281
+ |---------|-----------|
282
+ | [Compound Engineering Plugin](https://github.com/EveryInc/compound-engineering-plugin) | The "compound" philosophy -- each unit of work makes subsequent units easier. Multi-agent review workflows and skills as encoded knowledge. |
283
+ | [Beads](https://github.com/steveyegge/beads) | Git-backed JSONL + SQLite hybrid storage model, hash-based conflict-free IDs, dependency graphs |
284
+ | [OpenClaw](https://github.com/openclaw/openclaw) | Claude Code integration patterns and hook-based workflow architecture |
285
+
286
+ Also informed by research into [Reflexion](https://arxiv.org/abs/2303.11366) (verbal reinforcement learning), [Voyager](https://github.com/MineDojo/Voyager) (executable skill libraries), and production systems from mem0, Letta, and GitHub Copilot Memory.
347
287
 
348
288
  ## License
349
289
 
350
- MIT
290
+ MIT -- see [LICENSE](LICENSE) for details.
291
+
292
+ > The embedding model (EmbeddingGemma-300M) is downloaded on-demand and subject to Google's [Gemma Terms of Use](https://ai.google.dev/gemma/terms). See [THIRD-PARTY-LICENSES.md](THIRD-PARTY-LICENSES.md) for full dependency license information.
package/context7.json ADDED
@@ -0,0 +1,21 @@
1
+ {
2
+ "name": "Compound Agent",
3
+ "description": "Semantic memory plugin for Claude Code that captures lessons from mistakes and retrieves them with local embeddings and hybrid search",
4
+ "include": [
5
+ "README.md",
6
+ "AGENTS.md",
7
+ "CHANGELOG.md",
8
+ "CONTRIBUTING.md",
9
+ "docs/ARCHITECTURE-V2.md",
10
+ "docs/MIGRATION.md",
11
+ "docs/RESOURCE_LIFECYCLE.md",
12
+ "docs/LANDSCAPE.md",
13
+ "docs/adr/ADR-001-jsonl-with-sqlite-index.md",
14
+ "docs/adr/ADR-002-local-embeddings.md",
15
+ "docs/adr/ADR-003-zod-schema-validation.md",
16
+ "docs/adr/ADR-004-hybrid-search.md",
17
+ "src/index.ts",
18
+ "src/memory/types.ts"
19
+ ],
20
+ "versions": []
21
+ }