agent-learning-compounder

Compound agent memory. Sessions feed it. Sessions read it.

Your repo gets sharper every time an agent works in it.

npx agent-learning-compounder --bootstrap-repo "$PWD" --verify

The loop

flowchart LR
    S(("Session<br/>fixes · experiments · mistakes"))
    H["Hook events<br/>+ transcripts<br/><small>allowlisted, scrubbed</small>"]
    D["distill_learning<br/>score · dedup · federate"]
    E[/"<b>Compact context</b><br/><br/>📄 latest-approved-gates.md<br/>📄 latest-skill-context.md<br/>📄 latest-session-context.md"/]

    S ==>|produces| H
    H ==>|feeds| D
    D ==>|writes| E
    E -.->|auto-loads at start →| S

    style E fill:#fbbf24,stroke:#b45309,color:#1f2937,stroke-width:3px
    style S fill:#0f172a,stroke:#94a3b8,color:#f1f5f9,stroke-width:2px
    style H fill:#1e293b,stroke:#475569,color:#cbd5e1
    style D fill:#1e293b,stroke:#475569,color:#cbd5e1

Loading

Three small files carry institutional memory between sessions. Nothing leaves your machine. The loop tightens every cycle.

Install — three first-class paths

📦 npm / npx npx agent-learning-compounder \ --bootstrap-repo "$PWD" --verify Anyone with Node 18+. Zero-config, auto-detects Codex vs Claude Code.

🌐 curl one-liner curl -fsSL https://raw.githubusercontent.com\ /beeard/agent-learning-compounder\ /master/bootstrap.sh \ | sh -s -- --bootstrap-repo "$PWD" --verify No Node. Just curl + tar.

🔌 Claude Code marketplace /plugin marketplace add \ beeard/agent-learning-compounder /plugin install \ agent-learning-compounder@\ agent-learning-compounder Hooks + MCP + slash commands wired automatically.

All three pass the same end-to-end validation suite. See docs/QUICKSTART.md for the walk-through.

What an agent sees on session start

## Repo profile
- Languages: typescript (1247), python (305), shell (28)
- Frameworks: nextjs, react, fastapi
- Tests: yes · Frontend: yes · Monorepo: no

## Runtime summary (last 7 days)
- Activity: 47 events from 4 actors (3 agents, 1 hook source)
- Patches: 3 applied, 1 reverted
- Judge verdicts: 5 approved, 1 rejected
- Awaiting review: 2 pending patches — triage via /alc-report

## Documentation contract
✓ STRATEGY.md  ✓ ARCHITECTURE.md  ✓ CONTEXT.md  ✓ docs/adr
✗ docs/brainstorms — generate via /ce-brainstorm

## Compound-engineering playbook
### /ce-plan — multi-step work (4× tracked)
Pair with `ce-kieran-typescript-reviewer` for the review pass.
### /ce-simplify-code — post-change cleanup (12× tracked)
Great for hook extraction and component decomposition.
…

That single injection — synthesised on demand by alc_init and refreshed by hook telemetry — is the difference between an agent starting from scratch and an agent that knows what failed last week, which skills are stale, and which patches are pending review.

Ask it what's next

The newest MCP tool, next_action (M11), computes the single best move from current state. Same synthesiser handles "what's next?", "where did I leave off?", "session end recap" — one source of truth, never drift.

You:    What's next?

Agent:  → mcp__alc__next_action(repo)
        ← "2 pending patches, last apply 6h ago, /ce-plan stale —
            suggest /ce-doc-review docs/plans/refactor-api.md"

12 MCP tools total — read surface (get_gates, get_recommendations, get_skill_context, …), propose surface (propose_gate, report_outcome), sandbox (exec_sandbox), and the new synthesiser. All auto-registered from the MCP_TOOLS catalog.

Trust model — load-bearing

Rule	Why it matters
No raw prompts, tool output, or transcript chunks ever land on disk	The validator rejects psychological/ability claims about the operator. Telemetry has a bounded allowlist. Secrets get scrubbed.
Default to read-only	Durable writes require explicit --write --personal. Hook install is manifest-only until install_runtime_hooks --apply.
The installer never touches tracked files	.agent-learning.json and runtime hook configs auto-.gitignore themselves. Backups are timestamped.

Documentation

STRATEGY.md	Target problem · users · success signals · active tracks
ARCHITECTURE.md	Five-minute mental model with diagrams
CONTEXT.md	For LLM agents landing in this repo
CHANGES.md	Release notes (latest: 2026.05.27+review7-plus2.2)
docs/QUICKSTART.md	First-time install walk-through
agent-learning-compounder/reference-lib/	Per-subsystem deep dives (architecture, threat-model, output-schema, gate-registry, hook-telemetry, …)

Verify

cd agent-learning-compounder
python3 -m unittest discover -s fixtures/tests   # 251 unit + integration
python3 -m unittest discover -s tests            # 363 post-install smoke
python3 scripts/run_pressure_tests.py            # 4 durable-write gates

License

MIT — © 2026 Tom.