compound-agent 1.4.4 → 1.6.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.
- package/CHANGELOG.md +115 -35
- package/LICENSE +1 -1
- package/README.md +104 -149
- package/context7.json +21 -0
- package/dist/cli.js +5426 -4415
- package/dist/cli.js.map +1 -1
- package/dist/index.d.ts +149 -15
- package/dist/index.js +1984 -1368
- package/dist/index.js.map +1 -1
- package/llms.txt +31 -0
- package/package.json +22 -8
package/CHANGELOG.md
CHANGED
|
@@ -9,6 +9,85 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
9
9
|
|
|
10
10
|
## [Unreleased]
|
|
11
11
|
|
|
12
|
+
## [1.6.0] - 2026-03-02
|
|
13
|
+
|
|
14
|
+
### Added
|
|
15
|
+
|
|
16
|
+
- **`ca watch` command**: Live pretty-printer for infinity loop trace files. Tails `agent_logs/trace_*.jsonl` and formats stream-json events (tool calls, text deltas, token usage, epic markers) with colored output. Supports `--epic <id>` to watch a specific epic and `--no-follow` for one-shot reads.
|
|
17
|
+
- **Stream-json micro logging**: Generated infinity loop scripts now use `--output-format stream-json --include-partial-messages` to capture structured JSONL event traces alongside the existing macro text log. Trace files written to `agent_logs/trace_<epic>-<ts>.jsonl` with `.latest` symlink for easy discovery.
|
|
18
|
+
- **`/compound:learn-that` slash command**: Conversation-aware lesson capture with user confirmation before saving
|
|
19
|
+
- **`/compound:check-that` slash command**: Search lessons and proactively apply them to current work
|
|
20
|
+
- **Eager knowledge embedding**: Knowledge chunks from `docs/` are now embedded for semantic search when the model is available
|
|
21
|
+
- `ca index-docs --embed` embeds chunks after indexing
|
|
22
|
+
- `ca init` now downloads the embedding model (with `--skip-model` opt-out) and installs the post-commit hook
|
|
23
|
+
- Background embedding spawns after `ca init`/`ca setup` so users can start working immediately
|
|
24
|
+
- PID-based lock file prevents concurrent embedding processes
|
|
25
|
+
- Status file (`embed-status.json`) tracks background embedding progress
|
|
26
|
+
- **New modules**: `embed-chunks.ts`, `embed-lock.ts`, `embed-status.ts`, `embed-background.ts` with full test coverage
|
|
27
|
+
|
|
28
|
+
### Removed
|
|
29
|
+
|
|
30
|
+
- **`/compound:learn` slash command**: Replaced by `/compound:learn-that` with conversation-aware capture and user confirmation
|
|
31
|
+
- **`ca worktree` command family**: All five subcommands (`create`, `merge`, `list`, `cleanup`, `wire-deps`) removed. Claude Code now provides native `EnterWorktree` support. Running `ca worktree` prints a deprecation notice.
|
|
32
|
+
- **`/compound:set-worktree` slash command**: Use Claude Code's native worktree workflow instead.
|
|
33
|
+
- **Conditional Merge gate in `verify-gates`**: Only Review and Compound gates remain.
|
|
34
|
+
- **`shortId` utility**: Dead code after worktree removal, cleaned up.
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
|
|
38
|
+
- **Loop script uses piped stream splitting**: Claude invocation changed from `&>` capture to a `tee | extract_text` pipeline. Raw JSONL streams to trace file while extracted text feeds the macro log for marker detection. Backwards compatible — all existing markers (EPIC_COMPLETE, EPIC_FAILED, HUMAN_REQUIRED) still work.
|
|
39
|
+
- **`ca setup --update` now cleans deprecated paths**: Automatically removes stale worktree skill/command files from `.claude/` and `.gemini/` directories.
|
|
40
|
+
- **`ca setup` also cleans deprecated paths**: Fresh setup runs now remove stale files from prior versions.
|
|
41
|
+
- **SKILLS.md template**: Command inventory now lists all 11 slash commands (was 7).
|
|
42
|
+
|
|
43
|
+
### Fixed
|
|
44
|
+
|
|
45
|
+
- **Eager embedding hardening** (production readiness fixes from triple review):
|
|
46
|
+
- **P0**: Background worker spawn now resolves `dist/cli.js` deterministically instead of relying on `npx ca` (which failed silently in dev/built contexts)
|
|
47
|
+
- **P0**: `embed-worker` command hidden from `ca --help` output
|
|
48
|
+
- **P1**: Stale lock recovery uses atomic delete-then-`wx` to prevent two processes both reclaiming
|
|
49
|
+
- **P1**: DB connection opened after lock acquisition to prevent leak on contention
|
|
50
|
+
- **P1**: `--embed` now throws when model unavailable (was silently returning 0)
|
|
51
|
+
- **P2**: Batch embedding (16 chunks per call) with per-batch SQLite transactions (was 1 fsync per row)
|
|
52
|
+
- **P2**: `EmbedStatus` rewritten as discriminated union; removed dead `chunksTotal` field
|
|
53
|
+
- **P2**: `readLock` validates JSON shape instead of blind `as` cast
|
|
54
|
+
- **P2**: Vector batch length assertion guards against short responses from embedding backend
|
|
55
|
+
- **P3**: Extracted `indexAndSpawnEmbed()` shared helper — `init.ts` and `all.ts` no longer duplicate logic
|
|
56
|
+
- **P3**: `ca setup` now prints feedback when background embedding spawns
|
|
57
|
+
- **P3**: `filesErrored` count shown in `ca index-docs` output
|
|
58
|
+
- **P3**: Barrel re-exports consolidated through `./memory/knowledge/index.js`
|
|
59
|
+
- **`EPIC_ID_PATTERN` duplication**: `loop.ts` now uses distinctly named `LOOP_EPIC_ID_PATTERN` to avoid confusion with the canonical pattern in `cli-utils.ts`.
|
|
60
|
+
- **Stale worktree lesson invalidated**: Memory item `Ld204372e` marked invalid to prevent irrelevant context injection.
|
|
61
|
+
|
|
62
|
+
### Performance
|
|
63
|
+
|
|
64
|
+
- **Eliminate double model initialization**: `ca search` now uses `isModelAvailable()` (fs.existsSync, zero cost) instead of `isModelUsable()` which loaded the 278MB native model just to probe availability, then loaded it again for actual embedding
|
|
65
|
+
- **Bulk-read cached embeddings**: `getCachedEmbeddingsBulk()` replaces N individual `getCachedEmbedding()` SQLite queries with a single bulk read
|
|
66
|
+
- **Eliminate redundant JSONL parsing**: `searchVector()` and `findSimilarLessons()` now use `readAllFromSqlite()` after `syncIfNeeded()` instead of re-parsing the JSONL file
|
|
67
|
+
- **Float32Array consistency**: Lesson embedding path now keeps `Float32Array` from node-llama-cpp instead of converting via `Array.from()` (4x memory savings per vector)
|
|
68
|
+
- **Pre-warm lesson embedding cache**: `ca init` now pre-computes embeddings for all lessons with missing or stale cache entries, eliminating cold-start latency on first search
|
|
69
|
+
- **Graceful embedding fallback**: `ca search` falls back to keyword-only search on runtime embedding failures instead of crashing
|
|
70
|
+
|
|
71
|
+
## [1.5.0] - 2026-02-24
|
|
72
|
+
|
|
73
|
+
### Added
|
|
74
|
+
|
|
75
|
+
- **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
|
|
76
|
+
- **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`)
|
|
77
|
+
- **Gemini TOML commands**: Auto-generates `.gemini/commands/compound/*.toml` using `@{path}` file injection to maintain a single source of truth with Claude commands
|
|
78
|
+
- **Gemini skills proxying**: Inlines phase and agent role skill content into `.gemini/skills/` with YAML frontmatter
|
|
79
|
+
- **23 integration tests** for the Gemini adapter covering hooks, settings.json, TOML commands, skills, and dry-run mode
|
|
80
|
+
|
|
81
|
+
### Fixed
|
|
82
|
+
|
|
83
|
+
- **Gemini hook stderr leak**: Corrected `2>&1 > /dev/null` (leaks stderr to stdout, corrupting JSON) to `> /dev/null 2>&1`
|
|
84
|
+
- **Gemini TOML file injection syntax**: Changed `@path` to `@{path}` (Gemini CLI requires curly braces)
|
|
85
|
+
- **Gemini skill file injection**: Skills now inline content instead of using `@{path}` which only works in TOML prompt fields, not SKILL.md
|
|
86
|
+
- **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)
|
|
87
|
+
- **Gemini BeforeTool matcher incomplete**: Added `create_file` to BeforeTool and AfterTool matchers alongside `replace` and `write_file`
|
|
88
|
+
- **TOML description escaping**: `parseDescription` now escapes `\` and `"` to prevent malformed TOML output
|
|
89
|
+
- **Flaky embedding test**: Added 15s timeout to `isModelUsable` test
|
|
90
|
+
|
|
12
91
|
## [1.4.4] - 2026-02-23
|
|
13
92
|
|
|
14
93
|
### Added
|
|
@@ -763,38 +842,39 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
763
842
|
- Vitest test suite
|
|
764
843
|
- tsup build configuration
|
|
765
844
|
|
|
766
|
-
[Unreleased]: https://github.com/Nathandela/
|
|
767
|
-
[1.
|
|
768
|
-
[1.4.
|
|
769
|
-
[1.4.
|
|
770
|
-
[1.4.
|
|
771
|
-
[1.4.
|
|
772
|
-
[1.
|
|
773
|
-
[1.3.
|
|
774
|
-
[1.3.
|
|
775
|
-
[1.3.
|
|
776
|
-
[1.3.
|
|
777
|
-
[1.3.
|
|
778
|
-
[1.3.
|
|
779
|
-
[1.
|
|
780
|
-
[1.2.
|
|
781
|
-
[1.2.
|
|
782
|
-
[1.2.
|
|
783
|
-
[1.2.
|
|
784
|
-
[1.2.
|
|
785
|
-
[1.2.
|
|
786
|
-
[1.2.
|
|
787
|
-
[1.2.
|
|
788
|
-
[1.
|
|
789
|
-
[1.
|
|
790
|
-
[0.
|
|
791
|
-
[0.2.
|
|
792
|
-
[0.2.
|
|
793
|
-
[0.2.
|
|
794
|
-
[0.2.
|
|
795
|
-
[0.2.
|
|
796
|
-
[0.2.
|
|
797
|
-
[0.2.
|
|
798
|
-
[0.2.
|
|
799
|
-
[0.2.
|
|
800
|
-
[0.
|
|
845
|
+
[Unreleased]: https://github.com/Nathandela/compound-agent/compare/v1.5.0...HEAD
|
|
846
|
+
[1.5.0]: https://github.com/Nathandela/compound-agent/compare/v1.4.4...v1.5.0
|
|
847
|
+
[1.4.4]: https://github.com/Nathandela/compound-agent/compare/v1.4.3...v1.4.4
|
|
848
|
+
[1.4.3]: https://github.com/Nathandela/compound-agent/compare/v1.4.2...v1.4.3
|
|
849
|
+
[1.4.2]: https://github.com/Nathandela/compound-agent/compare/v1.4.1...v1.4.2
|
|
850
|
+
[1.4.1]: https://github.com/Nathandela/compound-agent/compare/v1.4.0...v1.4.1
|
|
851
|
+
[1.4.0]: https://github.com/Nathandela/compound-agent/compare/v1.3.9...v1.4.0
|
|
852
|
+
[1.3.9]: https://github.com/Nathandela/compound-agent/compare/v1.3.8...v1.3.9
|
|
853
|
+
[1.3.8]: https://github.com/Nathandela/compound-agent/compare/v1.3.7...v1.3.8
|
|
854
|
+
[1.3.7]: https://github.com/Nathandela/compound-agent/compare/v1.3.3...v1.3.7
|
|
855
|
+
[1.3.3]: https://github.com/Nathandela/compound-agent/compare/v1.3.2...v1.3.3
|
|
856
|
+
[1.3.2]: https://github.com/Nathandela/compound-agent/compare/v1.3.1...v1.3.2
|
|
857
|
+
[1.3.1]: https://github.com/Nathandela/compound-agent/compare/v1.3.0...v1.3.1
|
|
858
|
+
[1.3.0]: https://github.com/Nathandela/compound-agent/compare/v1.2.11...v1.3.0
|
|
859
|
+
[1.2.11]: https://github.com/Nathandela/compound-agent/compare/v1.2.10...v1.2.11
|
|
860
|
+
[1.2.10]: https://github.com/Nathandela/compound-agent/compare/v1.2.9...v1.2.10
|
|
861
|
+
[1.2.9]: https://github.com/Nathandela/compound-agent/compare/v1.2.7...v1.2.9
|
|
862
|
+
[1.2.7]: https://github.com/Nathandela/compound-agent/compare/v1.2.6...v1.2.7
|
|
863
|
+
[1.2.6]: https://github.com/Nathandela/compound-agent/compare/v1.2.5...v1.2.6
|
|
864
|
+
[1.2.5]: https://github.com/Nathandela/compound-agent/compare/v1.2.4...v1.2.5
|
|
865
|
+
[1.2.4]: https://github.com/Nathandela/compound-agent/compare/v1.2.1...v1.2.4
|
|
866
|
+
[1.2.1]: https://github.com/Nathandela/compound-agent/compare/v1.2.0...v1.2.1
|
|
867
|
+
[1.2.0]: https://github.com/Nathandela/compound-agent/compare/v1.1.0...v1.2.0
|
|
868
|
+
[1.1.0]: https://github.com/Nathandela/compound-agent/compare/v1.0.0...v1.1.0
|
|
869
|
+
[1.0.0]: https://github.com/Nathandela/compound-agent/compare/v0.2.9...v1.0.0
|
|
870
|
+
[0.2.9]: https://github.com/Nathandela/compound-agent/compare/v0.2.8...v0.2.9
|
|
871
|
+
[0.2.8]: https://github.com/Nathandela/compound-agent/compare/v0.2.7...v0.2.8
|
|
872
|
+
[0.2.7]: https://github.com/Nathandela/compound-agent/compare/v0.2.6...v0.2.7
|
|
873
|
+
[0.2.6]: https://github.com/Nathandela/compound-agent/compare/v0.2.5...v0.2.6
|
|
874
|
+
[0.2.5]: https://github.com/Nathandela/compound-agent/compare/v0.2.4...v0.2.5
|
|
875
|
+
[0.2.4]: https://github.com/Nathandela/compound-agent/compare/v0.2.3...v0.2.4
|
|
876
|
+
[0.2.3]: https://github.com/Nathandela/compound-agent/compare/v0.2.2...v0.2.3
|
|
877
|
+
[0.2.2]: https://github.com/Nathandela/compound-agent/compare/v0.2.1...v0.2.2
|
|
878
|
+
[0.2.1]: https://github.com/Nathandela/compound-agent/compare/v0.2.0...v0.2.1
|
|
879
|
+
[0.2.0]: https://github.com/Nathandela/compound-agent/compare/v0.1.0...v0.2.0
|
|
880
|
+
[0.1.0]: https://github.com/Nathandela/compound-agent/releases/tag/v0.1.0
|
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,64 +1,73 @@
|
|
|
1
1
|
# Compound Agent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Memory. Knowledge. Structure. Accountability. For AI coding agents.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/compound-agent)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](https://www.typescriptlang.org/)
|
|
8
|
+
|
|
9
|
+
- **Memory** -- capture mistakes once, surface them forever
|
|
10
|
+
- **Knowledge** -- hybrid vector search over your project docs
|
|
11
|
+
- **Structure** -- 5-phase workflows with 35+ specialized agents
|
|
12
|
+
- **Accountability** -- git-tracked issues, multi-agent reviews, quality gates
|
|
13
|
+
|
|
14
|
+
Fully local. Fully offline. Everything in git.
|
|
4
15
|
|
|
5
16
|
## Overview
|
|
6
17
|
|
|
7
|
-
|
|
18
|
+
AI coding agents forget everything between sessions. Compound Agent fixes this with a three-layer system: issue tracking at the foundation, semantic memory with vector search in the middle, and structured workflows with multi-agent review on top. It captures knowledge from corrections, discoveries, and completed work, then retrieves it precisely when relevant. Every cycle through the loop makes subsequent cycles smarter.
|
|
8
19
|
|
|
9
|
-
|
|
20
|
+
```mermaid
|
|
21
|
+
graph LR
|
|
22
|
+
B[BRAINSTORM] --> P[PLAN]
|
|
23
|
+
P --> W[WORK]
|
|
24
|
+
W --> R[REVIEW]
|
|
25
|
+
R --> C[COMPOUND]
|
|
26
|
+
C --> M[(MEMORY)]
|
|
27
|
+
M --> P
|
|
10
28
|
|
|
29
|
+
style M fill:#f9f,stroke:#333
|
|
11
30
|
```
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
31
|
+
|
|
32
|
+
```mermaid
|
|
33
|
+
block-beta
|
|
34
|
+
columns 1
|
|
35
|
+
block:L3["Workflows"]
|
|
36
|
+
A["5-phase cycle"] B["35+ specialized agents"] C["Multi-model review"]
|
|
37
|
+
end
|
|
38
|
+
block:L2["Semantic Memory"]
|
|
39
|
+
D["Vector search"] E["Hybrid retrieval"] F["Cross-cutting patterns"]
|
|
40
|
+
end
|
|
41
|
+
block:L1["Foundation"]
|
|
42
|
+
G["Issue tracking"] H["Git-backed sync"] I["Quality gates"]
|
|
43
|
+
end
|
|
44
|
+
|
|
45
|
+
L3 --> L2
|
|
46
|
+
L2 --> L1
|
|
25
47
|
```
|
|
26
48
|
|
|
27
|
-
|
|
49
|
+
## Is this for you?
|
|
28
50
|
|
|
29
|
-
|
|
30
|
-
|
|
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)
|
|
41
|
-
```
|
|
51
|
+
**"It keeps making the same mistake every session."**
|
|
52
|
+
Capture it once. Compound Agent surfaces it automatically before the agent repeats it.
|
|
42
53
|
|
|
43
|
-
|
|
54
|
+
**"I explained our auth pattern three sessions ago. Now it's reimplementing from scratch."**
|
|
55
|
+
Architectural decisions persist as searchable lessons. Next session, they inject into context before planning starts.
|
|
44
56
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
PLAN --> creates context for --> WORK
|
|
51
|
-
|
|
|
52
|
-
produces for
|
|
53
|
-
|
|
|
54
|
-
REVIEW
|
|
55
|
-
|
|
|
56
|
-
generates for
|
|
57
|
-
|
|
|
58
|
-
COMPOUND
|
|
59
|
-
```
|
|
57
|
+
**"My agent uses pandas when we standardized on Polars months ago."**
|
|
58
|
+
Preferences survive across sessions and projects. Once captured, they appear at the right moment.
|
|
59
|
+
|
|
60
|
+
**"Code reviews keep catching the same class of bugs."**
|
|
61
|
+
35+ specialized review agents (security, performance, architecture, test coverage) run in parallel. Findings feed back as lessons that become test requirements in future work.
|
|
60
62
|
|
|
61
|
-
|
|
63
|
+
**"I have no idea what my agent actually learned or if it's reliable."**
|
|
64
|
+
`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.
|
|
65
|
+
|
|
66
|
+
**"I want structured phases, not just 'go build this'."**
|
|
67
|
+
Five workflow phases (brainstorm, plan, work, review, compound) with mandatory gates between them. Each phase searches memory and docs for relevant context before starting.
|
|
68
|
+
|
|
69
|
+
**"My agent doesn't read the project docs before making decisions."**
|
|
70
|
+
`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.
|
|
62
71
|
|
|
63
72
|
## Installation
|
|
64
73
|
|
|
@@ -76,7 +85,7 @@ npx ca setup --skip-model
|
|
|
76
85
|
### Requirements
|
|
77
86
|
|
|
78
87
|
- Node.js >= 20
|
|
79
|
-
- ~278MB disk space for the embedding model
|
|
88
|
+
- ~278MB disk space for the embedding model (one-time download, shared across projects)
|
|
80
89
|
- ~150MB RAM during embedding operations
|
|
81
90
|
|
|
82
91
|
### pnpm Users
|
|
@@ -95,19 +104,6 @@ If you prefer to configure manually, add to your `package.json`:
|
|
|
95
104
|
|
|
96
105
|
Then run `pnpm install`.
|
|
97
106
|
|
|
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
107
|
## Quick Start
|
|
112
108
|
|
|
113
109
|
The five-phase workflow:
|
|
@@ -136,9 +132,9 @@ The CLI binary is `ca` (alias: `compound-agent`).
|
|
|
136
132
|
|
|
137
133
|
| Command | Description |
|
|
138
134
|
|---------|-------------|
|
|
139
|
-
| `ca learn "<insight>"` | Capture a
|
|
135
|
+
| `ca learn "<insight>"` | Capture a lesson manually |
|
|
140
136
|
| `ca learn "<insight>" --trigger "<context>"` | Capture with trigger context |
|
|
141
|
-
| `ca learn "<insight>" --severity high` | Set severity
|
|
137
|
+
| `ca learn "<insight>" --severity high` | Set severity (low/medium/high) |
|
|
142
138
|
| `ca learn "<insight>" --citation src/api.ts:42` | Attach file provenance |
|
|
143
139
|
| `ca capture --input <file>` | Capture from structured input file |
|
|
144
140
|
| `ca detect --input <file>` | Detect correction patterns in input |
|
|
@@ -175,16 +171,6 @@ The CLI binary is `ca` (alias: `compound-agent`).
|
|
|
175
171
|
| `ca rules check` | Run repository-defined rule checks |
|
|
176
172
|
| `ca test-summary` | Run tests and output a compact summary |
|
|
177
173
|
|
|
178
|
-
### Worktree
|
|
179
|
-
|
|
180
|
-
| Command | Description |
|
|
181
|
-
|---------|-------------|
|
|
182
|
-
| `ca worktree create <epic-id>` | Create isolated worktree for an epic |
|
|
183
|
-
| `ca worktree wire-deps <epic-id>` | Wire Review/Compound as merge blockers |
|
|
184
|
-
| `ca worktree merge <epic-id>` | Two-phase merge back to main |
|
|
185
|
-
| `ca worktree list` | List active worktrees with status |
|
|
186
|
-
| `ca worktree cleanup <epic-id>` | Remove worktree and clean up (--force for dirty) |
|
|
187
|
-
|
|
188
174
|
### Automation
|
|
189
175
|
|
|
190
176
|
| Command | Description |
|
|
@@ -195,7 +181,12 @@ The CLI binary is `ca` (alias: `compound-agent`).
|
|
|
195
181
|
| `ca loop --max-retries <n>` | Max retries per epic on failure (default: 1) |
|
|
196
182
|
| `ca loop --force` | Overwrite existing script |
|
|
197
183
|
|
|
198
|
-
|
|
184
|
+
### Knowledge
|
|
185
|
+
|
|
186
|
+
| Command | Description |
|
|
187
|
+
|---------|-------------|
|
|
188
|
+
| `ca knowledge "<query>"` | Hybrid search over indexed project docs |
|
|
189
|
+
| `ca index-docs` | Index docs/ directory into knowledge base |
|
|
199
190
|
|
|
200
191
|
### Setup
|
|
201
192
|
|
|
@@ -213,24 +204,8 @@ Generated scripts detect three markers: `EPIC_COMPLETE` (success), `EPIC_FAILED`
|
|
|
213
204
|
| `ca about` | Show version, animation, and recent changelog |
|
|
214
205
|
| `ca doctor` | Verify external dependencies and project health |
|
|
215
206
|
|
|
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
207
|
## Memory Types
|
|
231
208
|
|
|
232
|
-
All types share one store, one schema, one search mechanism. A query returns the most relevant items regardless of type.
|
|
233
|
-
|
|
234
209
|
| Type | Trigger means | Insight means | Example |
|
|
235
210
|
|------|---------------|---------------|---------|
|
|
236
211
|
| `lesson` | What happened | What was learned | "Polars 10x faster than pandas for large files" |
|
|
@@ -238,35 +213,6 @@ All types share one store, one schema, one search mechanism. A query returns the
|
|
|
238
213
|
| `pattern` | When it applies | Why it matters | `{ bad: "await in loop", good: "Promise.all" }` |
|
|
239
214
|
| `preference` | The context | The preference | "Use uv over pip in this project" |
|
|
240
215
|
|
|
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
216
|
### Retrieval Ranking
|
|
271
217
|
|
|
272
218
|
```
|
|
@@ -279,26 +225,22 @@ recency_boost: last 30d=1.2, older=1.0
|
|
|
279
225
|
confirmation_boost: confirmed=1.3, unconfirmed=1.0
|
|
280
226
|
```
|
|
281
227
|
|
|
282
|
-
|
|
228
|
+
## FAQ
|
|
283
229
|
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
"related": [],
|
|
299
|
-
"citation": { "file": "src/api/client.ts", "line": 42 }
|
|
300
|
-
}
|
|
301
|
-
```
|
|
230
|
+
**Q: How is this different from mem0?**
|
|
231
|
+
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.
|
|
232
|
+
|
|
233
|
+
**Q: Does this work offline?**
|
|
234
|
+
A: Yes, completely. Embeddings run locally via node-llama-cpp. No network requests after the initial model download.
|
|
235
|
+
|
|
236
|
+
**Q: How much disk space does it need?**
|
|
237
|
+
A: ~278MB for the embedding model (one-time download, shared across projects) plus negligible space for lessons.
|
|
238
|
+
|
|
239
|
+
**Q: Can I use it with other AI coding tools?**
|
|
240
|
+
A: The CLI (`ca`) works standalone with any tool. Full hook integration is available for Claude Code and Gemini CLI. The TypeScript API can be integrated into other tools.
|
|
241
|
+
|
|
242
|
+
**Q: What happens if the embedding model isn't available?**
|
|
243
|
+
A: Search gracefully falls back to keyword-only mode. Other commands that require embeddings will tell you what's missing. Run `npx ca doctor` to diagnose issues.
|
|
302
244
|
|
|
303
245
|
## Development
|
|
304
246
|
|
|
@@ -309,18 +251,14 @@ pnpm dev # Watch mode (rebuild on changes)
|
|
|
309
251
|
pnpm lint # Type check + ESLint
|
|
310
252
|
```
|
|
311
253
|
|
|
312
|
-
### Test Scripts
|
|
313
|
-
|
|
314
254
|
| Script | Duration | Use Case |
|
|
315
255
|
|--------|----------|----------|
|
|
316
|
-
| `pnpm test:fast` | ~6s | Rapid feedback during development
|
|
256
|
+
| `pnpm test:fast` | ~6s | Rapid feedback during development |
|
|
317
257
|
| `pnpm test` | ~60s | Full suite before committing |
|
|
318
258
|
| `pnpm test:changed` | varies | Only tests affected by recent changes |
|
|
319
259
|
| `pnpm test:watch` | - | Watch mode for TDD workflow |
|
|
320
260
|
| `pnpm test:all` | ~60s | Full suite with model download |
|
|
321
261
|
|
|
322
|
-
**Recommended**: Use `pnpm test:fast` while coding, `pnpm test` before committing.
|
|
323
|
-
|
|
324
262
|
## Technology Stack
|
|
325
263
|
|
|
326
264
|
| Component | Technology |
|
|
@@ -339,12 +277,29 @@ pnpm lint # Type check + ESLint
|
|
|
339
277
|
|
|
340
278
|
| Document | Purpose |
|
|
341
279
|
|----------|---------|
|
|
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
|
-
|
|
280
|
+
| [docs/ARCHITECTURE-V2.md](https://github.com/Nathandela/compound-agent/blob/main/docs/ARCHITECTURE-V2.md) | Three-layer architecture design |
|
|
281
|
+
| [docs/MIGRATION.md](https://github.com/Nathandela/compound-agent/blob/main/docs/MIGRATION.md) | Migration guide from learning-agent |
|
|
282
|
+
| [CHANGELOG.md](https://github.com/Nathandela/compound-agent/blob/main/CHANGELOG.md) | Version history |
|
|
283
|
+
| [AGENTS.md](https://github.com/Nathandela/compound-agent/blob/main/AGENTS.md) | Agent workflow instructions |
|
|
284
|
+
|
|
285
|
+
## Acknowledgments
|
|
286
|
+
|
|
287
|
+
Compound Agent builds on ideas and patterns from these projects:
|
|
288
|
+
|
|
289
|
+
| Project | Influence |
|
|
290
|
+
|---------|-----------|
|
|
291
|
+
| [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. |
|
|
292
|
+
| [Beads](https://github.com/steveyegge/beads) | Git-backed JSONL + SQLite hybrid storage model, hash-based conflict-free IDs, dependency graphs |
|
|
293
|
+
| [OpenClaw](https://github.com/openclaw/openclaw) | Claude Code integration patterns and hook-based workflow architecture |
|
|
294
|
+
|
|
295
|
+
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.
|
|
296
|
+
|
|
297
|
+
## Contributing
|
|
298
|
+
|
|
299
|
+
Bug reports and feature requests are welcome via [Issues](https://github.com/Nathandela/compound-agent/issues). Pull requests are not accepted at this time -- see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
|
|
347
300
|
|
|
348
301
|
## License
|
|
349
302
|
|
|
350
|
-
MIT
|
|
303
|
+
MIT -- see [LICENSE](LICENSE) for details.
|
|
304
|
+
|
|
305
|
+
> 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
|
+
}
|