compounded
compounded turns Claude Code skills into a trust-gradient system: every skill earns its autonomy through demonstrated reliability. New skill
Open source Open in the app JSON README (API)
About
compounded turns Claude Code skills into a trust-gradient system: every skill earns its autonomy through demonstrated reliability. New skills the agent proposes start as .proposed/, get replayed on a real follow-up task by a verifier subagent (Haiku 4.5) to graduate to .verified/, build a track record to reach .trusted/, and finally graduate to .autonomous/ after 10+ uses with a clean recent run. One correction sends a skill back a tier. Three corrections in 30 days drop it to .proposed. Includes cross-project memory (a user-global USER.md auto-injected into every session) and a portable .tar.gz archive for moving your earned skills across machines. v1.1 adds an auto-proposer hook that scores each turn (tool calls, distinct file edits, recovery from failure) and nudges the agent to save high-signal procedures — so you don't have to remember to ask. No daemon. No cloud. No telemetry. Python stdlib only. All state in ~/.claude/compounded/ (SQLite + flat files). MIT licensed.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- ankitkr3
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 5
- Last push
- 2026-06-22T07:47:21Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
ankitkr3/compounded/compounded
README
<div align="center">
<br />
<img src="assets/logo.svg" width="560" alt="compounded — skills that earn trust, and compound" />
### Your AI agent gets better at *you* the longer you use it.
Correct Claude once — it asks to remember the lesson, then never makes that mistake again. **Your approval is the only gate**: saved rules are active immediately at `.verified`, build a track record to reach `.trusted`, and graduate to `.autonomous`. One correction sends them back down. **No daemon. No cloud. No re-explaining.**
<br />
[](https://github.com/ankitkr3/compounded/actions/workflows/tests.yml)
[](LICENSE)
[](https://docs.claude.com/en/docs/claude-code/plugins)
[](https://github.com/ankitkr3/compounded/stargazers)
[](https://www.python.org/)
<br />
**[Install](#install)** · **[How it works](#the-trust-ladder)** · **[Manifesto](MANIFESTO.md)** · **[Philosophy](PHILOSOPHY.md)** · **[Docs](docs/)** · **[Compare](#how-compounded-composes)**
<br />
<img src="assets/demo.gif" width="830" alt="Demo: you correct Claude once, compounded asks to save the rule, and Claude never makes that mistake again." />
<sub>Correct it once. Approve the lesson. Never repeat yourself.</sub>
<br />
</div>
---
## What is this? (the no-jargon version)
Think of Claude as a **smart new employee with amnesia** — brilliant, but every morning it forgets everything you taught it yesterday. You end up correcting the same mistakes over and over.
compounded fixes that, the same way you'd train a real new hire:
<div align="center">
<img src="assets/how-it-works.svg" width="960" alt="How compounded works: you correct Claude, compounded notices, it asks your approval, the rule is remembered, and next time Claude gets it right." />
</div>
**A real example.** You ask Claude to use the *latest* Gemini embedding model. It picks an old one from memory. You say: *"No — search the web first, then pick the latest."* compounded catches that correction and asks: **"Save this rule?"** You tap Yes. From now on, whenever you ask for the latest *anything*, Claude searches the web first — without being told.
And it's not blind trust: every saved lesson starts on probation and **earns** more freedom each time it works — or loses it the moment it doesn't.
<br />
## Why compounded?
> Claude Code's **AutoMemory** writes notes. **AutoDream** cleans them.
> **compounded verifies them — and lets them earn the right to act.**
When compounded captures a lesson, you approve it once and it's live — `.verified`, injected into every session. Three clean uses → `.trusted`. Ten with no recent corrections → `.autonomous`. One correction sends it back a step. Unapproved captures and demoted skills wait in `.proposed/` for a verifier replay before re-entering.
**It's how you train a junior. It's how you should train your agent.**
<br />
## Install
```sh
# In Claude Code:
/plugin marketplace add ankitkr3/compounded-marketplace
/plugin install compounded@compounded-marketplace
```
Restart Claude Code. That's it.
> **First-time approval prompts:** hooks fire silently, but the first time you run any `/compounded:*` slash command you'll see a Claude Code permission prompt. Either click **"always allow"** in the prompt (per-command, easiest) or pre-allowlist everything by adding `"Bash(python3 ~/.claude/plugins/cache/compounded-marketplace/compounded/**:*)"` to `permissions.allow` in `~/.claude/settings.json`. See [INSTALL.md](INSTALL.md#permission-prompts-expected-easy-to-silence) for details.
<table>
<tr>
<td>✅ No daemon to run</td>
<td>✅ No cloud account</td>
<td>✅ No telemetry</td>
<td>✅ 100% local</td>
</tr>
<tr>
<td>✅ Python stdlib only</td>
<td>✅ SQLite + flat files</td>
<td>✅ Portable archive</td>
<td>✅ MIT licensed</td>
</tr>
</table>
<br />
## The trust ladder
<div align="center">
<img src="assets/trust-ladder.svg" width="930" alt="The trust ladder: proposed to verified to trusted to autonomous. One correction moves a skill one level down." />
</div>
| Tier | Behavior | Activation |
|---|---|---|
| `.proposed` | Unapproved: demoted skills and imports, awaiting verification | Never auto-loads |
| `.verified` | User-approved at capture, or verified on a real task | Rules inject at session start |
| `.trusted` | 3+ clean uses on real follow-ups | Auto-loads, asks before applying |
| `.autonomous` | 10+ uses, last 5 clean, no recent corrections | Runs without asking |
Demotions happen automatically: **one correction = one tier down**. Three corrections in 30 days = back to `.proposed`. Pin a skill with `/compounded:pin <skill>` to lock it at its current tier.
Run `/compounded:trust-status` to see where every skill sits and what's about to promote or demote.
<br />
## What compounded actually does
Three things. That's the whole pitch.
<table>
<tr>
<td width="33%" valign="top">
### 🧠 Cross-project memory
A user-global `USER.md` (~/.claude/compounded/USER.md) gets injected into every session, on every project, on every machine.
AutoMemory writes per-project notes — compounded writes the **preferences and facts that follow you** across all of them. Hard-bounded at 1500 characters by design, so it stays readable and useful.
</td>
<td width="33%" valign="top">
### ✓ Verified skills
Approve a lesson once and it's `.verified` — **active immediately**, injected at every session start. It graduates by demonstrating reliability over real use, and demotes the moment it steers a task wrong.
The verifier subagent guards the unapproved path (imports, demotions): replay against a real task, PASS or FAIL with the reason logged. Failures land in `.rejected/` (recoverable, not deleted).
</td>
<td width="33%" valign="top">
### 📦 Portable archive
`/compounded:export ~/Desktop/compounded.tar.gz` produces a single archive: USER.md + every active skill + the trust state.
`/compounded:import` merges it on a new machine. **Your earned skills aren't trapped** on the laptop you're typing on right now.
</td>
</tr>
</table>
<br />
## Learns from your corrections (v1.2)
Corrections are the highest-signal teaching moments — so compounded treats them as the **primary** learning trigger, not noise:
1. **You correct Claude** ("no — web-search for the latest model first") and Claude does the corrective work
2. The Stop hook spots the correction and nudges Claude: *the delta between what you asked, what it did, and how you corrected it is a lesson*
3. Claude extracts the generalizable rule and **asks you to approve it — your approval is the only gate**
4. Approved rules save straight to `.verified/` and are **injected at the start of every session** — *"when the user asks for the latest X, web-search first"* — active immediately, climbing the trust ladder with each clean use, demoted the moment they steer a task wrong
One-off corrections ("use port 3001 here") are deliberately ignored — only rules with a clear, general trigger get proposed. `.proposed/` still exists for the unapproved path: demoted skills and imports wait there for verification.
## Auto-propose (v1.1)
You don't have to remember to save things. After every turn, the Stop hook scores what just happened — tool calls, distinct files edited, shell commands, recovery from failure, planned execution. When the score crosses the threshold, the agent gets a nudge to consider authoring a skill. The agent still decides whether to propose (one-off chores get ignored), but the *prompt to consider* is automatic.
Quiet by design: routine turns produce zero output. You only see anything when there's real signal. Check `~/.claude/compounded/logs/auto_propose.jsonl` to see what fired and what didn't — each entry now records a `capture_kind` (`procedure` or `rule`) — useful for tuning if you want to.
<br />
## Demo
Run the included lifecycle demo to see propose → verify → use × 3 → trust → use × 7 → autonomous → correction → demote in 30 seconds:
```sh
bash docs/demo.sh
```
```text
[1/8] proposing skill 'typo-fixer' ......................... .proposed/
[2/8] running verifier subagent (claude-haiku-4-5) ......... PASS
[3/8] moved to .verified/, ready for use
[4/8] used 3× on real follow-ups ........................... promoted → .trusted
[5/8] used 7× more, last 5 clean ........................... promoted → .autonomous
[6/8] one correction on use #11 ............................ demoted → .trusted
[7/8] exported archive ..................................... compounded.tar.gz (12KB)
[8/8] imported on a fresh install .......................... ✓ same state
```
<br />
## How compounded composes
compounded does not replace anything. It is the **verification + portability layer** of a stack:
| Tool | What it does | What compounded adds |
|---|---|---|
| **AutoMemory** (native) | Per-project notes, MEMORY.md | Cross-project USER.md |
| **AutoDream** (native) | Consolidates project memory between sessions | Verifies skills, not notes |
| **skill-creator** (native) | Eval-based testing of hand-authored skills | Replay-based verification of agent-authored skills |
| **[superpowers](https://github.com/obra/superpowers)** | TDD / brainstorm / plan methodology | Memory + earned trust gradient |
| **[claude-mem](https://github.com/thedotmack/claude-mem)** | Daemon-based observation capture | No daemon, different model |
| **Karpathy CLAUDE.md** | Behavioral principles | Composable — drop both into your project |
Each layer does one thing well. None of them does what compounded does.
<br />
## Commands
| Command | What it does |
|---|---|
| `/compounded:status` | USER.md size, skill counts by tier, recent transitions |
| `/compounded:trust-status` | The full trust ladder, with promotion/demotion candidates highlighted |
| `/compounded:export <path>` | Bundle USER.md + verified skills into a portable archive |
| `/compounded:import <path>` | Merge an archive on this machine |
| `/compounded:verify <skill>` | Manually run the verifier on a `.proposed/` skill |
| `/compounded:trust <skill> --to <tier>` | Manual promotion (skip the gradient) |
| `/compounded:demote <skill>` | Drop a skill one tier |
| `/compounded:pin <skill>` | Lock a skill at its current tier (no auto-demotion) |
| `/compounded:unpin <skill>` | Remove a pin |
<br />
## What's stored where
```
~/.claude/compounded/
├── USER.md ← user-global preferences (loaded every session)
├── trust.db ← SQLite: skill state, events, sessions
├── config.json ← per-user config
├── skills/
│ ├── .proposed/<name>/ ← awaiting verification
│ ├── .verified/<name>/ ← passed verification
│ ├── .trusted/<name>/ ← 3+ clean uses
│ ├── .autonomous/<name>/ ← 10+ uses, recent run clean
│ ├── .rejected/<name>/ ← failed verification (recoverable)
│ └── .pinned ← list of pinned skill names
└── logs/
└── verifier_dispatches.jsonl
```
**All local. All inspectable. All editable** if something goes wrong.
<br />
## What it doesn't do
| Won't do | Why |
|---|---|
| ❌ No daemon | Zero install friction. Hooks fire when Claude Code fires them. |
| ❌ No cloud / telemetry / account | Your skills are yours. |
| ❌ No vector index / embeddings / GPU | Keyword overlap + replay is enough. |
| ❌ No transcript capture | [claude-mem](https://github.com/thedotmack/claude-mem) does that — use both if you want both. |
| ❌ No project memory cleanup | AutoDream does that. |
| ❌ No eval framework | skill-creator does that. |
Every "no" is deliberate. **compounded does three things and stops.**
<br />
## Cost
The verifier subagent runs on **Claude Haiku 4.5** by default. Each verification is roughly 1500 input tokens + a small JSON response.
> **Expected cost at typical usage: under $0.20/month.**
The verifier only runs when a `.proposed/` skill matches the just-finished task, which for most users is a handful of times per week.
To switch to Sonnet for higher-accuracy verification (~5× the cost), edit `~/.claude/compounded/config.json`:
```json
{
"skills": {
"verifier_model": "claude-sonnet-4-6"
}
}
```
<br />
## Tested
55 unit tests covering memory injection, skill proposal, correction-driven rule capture, transcript-schema parsing, security scanning, trust-ladder transitions in all directions, pin behavior, stale-sweep exemptions, archive roundtrip, and verdict finalization.
```sh
git clone https://github.com/ankitkr3/compounded
cd compounded
python3 -m unittest discover tests/ -v
```
CI runs the suite on **Linux + macOS** across **Python 3.9–3.12** on every PR.
<br />
## The four principles
[**Read the manifesto.**](MANIFESTO.md) Four principles, one page, copy-pasteable.
1. **Bounded over Unbounded** — memory should be small enough to read in one breath.
2. **Verified over Recalled** — a skill that replayed successfully is a fact; one that was merely saved is a hypothesis.
3. **Earned over Granted** — authority is earned, not assumed.
4. **Composable over Comprehensive** — small tool, sharp wedge, plays well with everything else.
<br />
## Contributing
PRs welcome. New built-in skills, bug fixes, doc improvements.
```sh
python3 -m unittest discover tests/ -v
```
For new built-in skills (skills that ship with compounded itself, not user-authored skills), follow the format of `skills/compounded-typo-fixer/SKILL.md` and include the criteria the skill is meant to demonstrate.
See [CLAUDE.md](CLAUDE.md) for codebase conventions.
<br />
## License
[MIT](LICENSE). Fork, ship, sell. Just include the notice.
<br />
## Why "compounded"
Capability that compounds is the whole point. Every verified skill compounds the agent's toolkit. Every clean use compounds the trust in that skill. Every correction compounds *back* — trust isn't given once, it's earned and re-earned. The trust ladder is compound interest applied to demonstrated reliability: small reliable acts that, over time, become the foundation for larger autonomous ones.
> "The most powerful force in the universe is compound interest." — Albert Einstein (apocryphal)
The product is named for what it does to your agent.
---
<div align="center">
<sub>
**[Manifesto](MANIFESTO.md)** · **[Philosophy](PHILOSOPHY.md)** · **[Install Guide](INSTALL.md)** · **[Architecture](docs/architecture.md)** · **[Memory Guide](docs/memory-guide.md)** · **[Skill Authoring](docs/skill-authoring.md)** · **[Privacy](docs/privacy.md)**
</sub>
<br />
<sub>Built for [Claude Code](https://docs.claude.com/en/docs/claude-code) · Made with discipline by [@ankitkr3](https://github.com/ankitkr3)</sub>
</div>