compound-agent 1.4.4 → 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.
- package/CHANGELOG.md +55 -35
- package/LICENSE +1 -1
- package/README.md +80 -138
- package/context7.json +21 -0
- package/dist/cli.js +933 -753
- package/dist/cli.js.map +1 -1
- package/dist/index.js.map +1 -1
- package/llms.txt +31 -0
- package/package.json +22 -8
package/CHANGELOG.md
CHANGED
|
@@ -9,6 +9,26 @@ 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
|
+
|
|
12
32
|
## [1.4.4] - 2026-02-23
|
|
13
33
|
|
|
14
34
|
### Added
|
|
@@ -763,38 +783,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
|
|
|
763
783
|
- Vitest test suite
|
|
764
784
|
- tsup build configuration
|
|
765
785
|
|
|
766
|
-
[Unreleased]: https://github.com/Nathandela/
|
|
767
|
-
[1.4.4]: https://github.com/Nathandela/
|
|
768
|
-
[1.4.3]: https://github.com/Nathandela/
|
|
769
|
-
[1.4.2]: https://github.com/Nathandela/
|
|
770
|
-
[1.4.1]: https://github.com/Nathandela/
|
|
771
|
-
[1.4.0]: https://github.com/Nathandela/
|
|
772
|
-
[1.3.9]: https://github.com/Nathandela/
|
|
773
|
-
[1.3.8]: https://github.com/Nathandela/
|
|
774
|
-
[1.3.7]: https://github.com/Nathandela/
|
|
775
|
-
[1.3.3]: https://github.com/Nathandela/
|
|
776
|
-
[1.3.2]: https://github.com/Nathandela/
|
|
777
|
-
[1.3.1]: https://github.com/Nathandela/
|
|
778
|
-
[1.3.0]: https://github.com/Nathandela/
|
|
779
|
-
[1.2.11]: https://github.com/Nathandela/
|
|
780
|
-
[1.2.10]: https://github.com/Nathandela/
|
|
781
|
-
[1.2.9]: https://github.com/Nathandela/
|
|
782
|
-
[1.2.7]: https://github.com/Nathandela/
|
|
783
|
-
[1.2.6]: https://github.com/Nathandela/
|
|
784
|
-
[1.2.5]: https://github.com/Nathandela/
|
|
785
|
-
[1.2.4]: https://github.com/Nathandela/
|
|
786
|
-
[1.2.1]: https://github.com/Nathandela/
|
|
787
|
-
[1.2.0]: https://github.com/Nathandela/
|
|
788
|
-
[1.1.0]: https://github.com/Nathandela/
|
|
789
|
-
[1.0.0]: https://github.com/Nathandela/
|
|
790
|
-
[0.2.9]: https://github.com/Nathandela/
|
|
791
|
-
[0.2.8]: https://github.com/Nathandela/
|
|
792
|
-
[0.2.7]: https://github.com/Nathandela/
|
|
793
|
-
[0.2.6]: https://github.com/Nathandela/
|
|
794
|
-
[0.2.5]: https://github.com/Nathandela/
|
|
795
|
-
[0.2.4]: https://github.com/Nathandela/
|
|
796
|
-
[0.2.3]: https://github.com/Nathandela/
|
|
797
|
-
[0.2.2]: https://github.com/Nathandela/
|
|
798
|
-
[0.2.1]: https://github.com/Nathandela/
|
|
799
|
-
[0.2.0]: https://github.com/Nathandela/
|
|
800
|
-
[0.1.0]: https://github.com/Nathandela/
|
|
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
package/README.md
CHANGED
|
@@ -1,64 +1,61 @@
|
|
|
1
1
|
# Compound Agent
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Semantic memory for Claude Code -- capture mistakes once, never repeat them.**
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/compound-agent)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](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
|
-
##
|
|
13
|
+
## The Compound Loop
|
|
10
14
|
|
|
11
|
-
```
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
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
|
-
|
|
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
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
219
|
+
## FAQ
|
|
283
220
|
|
|
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
|
-
```
|
|
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
|
|
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
|
-
|
|
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
|
+
}
|