compound learning for Claude Code · open source · MIT · built on official Claude Code APIs · data stays on your machine
Your project knowledge
compounds and learns
across sessions.
Claude Code is stateless. Every session starts from zero. Clankbrain gives it a living memory — decisions, lessons, and patterns that grow with your project and apply automatically at every session start.
Two commands: Start Session → work → End Session. That's the whole interface.
● Sessions compound, not reset
● Skills self-improve from failure
● Mistakes never repeat
● No external dependencies
# session active /
yf@clankbrain ~ $
yf@clankbrain ~ $
get started
Five minutes to a living environment
Claude Code is the only requirement. Run one command from your project root.
IS THIS FOR YOU?
✓ You use Claude Code daily on a real ongoing project
✓ You've felt the pain of re-explaining context every session
✓ You want sessions to compound, not reset
Not for: one-off scripts, quick experiments, or people who prefer no structure.
// STEP 1 — run from your project root
$ npx clankbrain
No Node.js? Other install options ▸
Git clone:
git clone https://github.com/YehudaFrankel/clankbrain.git && cd clankbrain && python setup.py
Python one-liner:
python -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/YehudaFrankel/clankbrain/main/setup.py').read().decode())"
Manual: download and run setup.py from the repo.
// 02
Open Claude Code
Navigate to your project. Type Setup Memory — Claude runs the Python setup for you.
// 03
Type: Start Session
Memory loads from disk, drift check runs, Claude picks up exactly where you left off. First run auto-scans your project and recommends which skills apply to your stack.
// 04
Type: End Session
/learn extracts lessons. Memory saved. Next session starts smarter.
New machine? Run Install Memory — Claude scans the codebase and rebuilds all knowledge files from scratch.
OTHER TOOLS
CLANKBRAIN
skills stay static — no feedback loop
skills score themselves · /evolve patches failures
rejected approaches get re-proposed
regret guard blocks them permanently
single notes dump file
typed files: decisions · errors · lessons · regret
no team sync
shared team memory · personal stays local
API key or database required
zero dependencies — Python 3.7+
unofficial / proprietary internals
official Anthropic hooks + skills APIs
why it's different
Not a config file.
A living environment.
Most setups drop a CLAUDE.md and call it done. clankbrain ships an environment that learns your codebase, improves its own workflows, and remembers what went wrong — permanently.
01 ─────
The Environment Persists
CLAUDE.md, memory files, and hooks are configured once and loaded
automatically every session. Crash, close, switch machines —
the environment picks up exactly where it left off.
02 ─────
Skills Self-Improve
After every session, /learn scores each skill Y/N.
/evolve reads those scores, patches weak steps, and proposes
new skills from patterns it detected — without you asking.
03 ─────
Knowledge Compounds
lessons.md and decisions.md grow every session and apply at
every Start Session. Claude stops re-debating settled choices.
By session 50 it engineers alongside you, not behind you.
agentic core
The compound
learning loop
The engine that makes this agentic. Runs quietly in the background — extract lessons, score skills, patch weak steps, repeat. The environment gets smarter without you managing it.
session work
code, fixes, features
/learn
extract patterns, score skills Y/N
→ lessons.md
→ skill_scores.md
→ skill_scores.md
End Session
save memory
→ STATUS.md
→ memory/
→ memory/
/evolve
every 3-5 sessions
patches weak skills
proposes new ones
proposes new ones
Start Session
applies all lessons
Claude arrives
smarter
smarter
GETS SMARTER
lessons.md — grows every session
decisions.md — stops re-debating
regret.md — never re-proposes bad ideas
velocity.md — self-calibrating estimates
skill_scores.md — tracks what failed
error-lookup.md — known errors → exact fix
critical-notes.md — non-obvious gotchas
agreed-flow.md — locked user journeys
todo.md — current tasks in priority order
SKILL AUTO-CHAIN
fix-bug → verification-loop
Add
Claude continues without waiting.
On fail: debug-resin → retry
On pass: smoke-test → done
## Auto-Chain to any skill.Claude continues without waiting.
On fail: debug-resin → retry
On pass: smoke-test → done
AUTONOMOUS
Self-healing: retry before escalating
SessionStart hook: loads memory at session open
PostToolUse hook: drift check after every edit
PreCompact hook: saves in-flight work
PostCompact hook: re-injects memory after compact
StopFailure hook: captures state on API crash
PostToolUse hook: drift check after every edit
PreCompact hook: saves in-flight work
PostCompact hook: re-injects memory after compact
StopFailure hook: captures state on API crash
agentic toolkit
10 skills ship ready.
Generate Skills builds the rest.
Skills live in .claude/skills/ as markdown files.
Chain them with ## Auto-Chain.
Run Generate Skills — Claude scans your stack and creates skills tailored to your project.
| skill file | trigger phrase | what it does |
|---|---|---|
| /learn | /learn, extract patterns | Extract lessons from this session, score skills Y/N, update decisions.md and lessons.md |
| plan | plan [feature], I want to build X, design X | Structured planning — options with build cost/friction/payoff ratings, decision logged live, full plan auto-displayed after every update |
| /evolve | /evolve, evolve lessons into skills | Read skill_scores.md, patch weak steps, propose new skills from detected patterns |
| verification-loop | verify, run verification loop, did that work | After a code change — confirm it compiled, smoke test, self-check quality |
| search-first | search first, check if this exists | Enforce research-before-coding: search codebase before implementing anything new |
| strategic-compact | should I compact, context getting long | Evaluate whether to compact and guide through safe compaction that preserves all memory |
| java-reviewer | review this java, java review | Deep Java review against your stack's specific patterns — goes beyond generic code review |
| mode | mode develop, mode review, mode safe, mode deploy | Restrict Claude's tool access to what a task actually needs — develop (full), review (read-only), safe (no writes), deploy (shell only) |
| debug-session | debug session, structured debug, debug this error | 7-step structured debugging: reproduce → isolate → hypothesize → fix → verify — then logs cause + fix to error-lookup.md so the same bug never takes time twice. Auto-chains to verification-loop after the fix. |
| generate-guards | generate guards, add guards, what guards should I add | Mines your error-lookup.md, regret.md, and lessons.md to propose project-specific guards — converts your actual mistake history into automated prevention. Generic guards catch common patterns; these catch yours. |
// PYTHON TOOLS THAT SHIP WITH THE KIT
tools/memory.py — all lifecycle behaviors in one script (Full mode). Run via subcommand:
--check-drift — PostToolUse hook: finds undocumented functions after every file edit
--verify-edit — PostToolUse hook: requires Claude to quote changed lines verbatim before continuing
--journal — Stop hook: auto-captures session summary with timestamp
--stop-check — Stop hook: surfaces open plans, code-review nudge after significant edits
--session-start — injects memory + silent kit health check on session open
--quick-learn — fast lesson capture: writes stub immediately, prompts 1-3 lessons. No ceremony.
--kit-health — checks hooks wired, MEMORY.md present, skills installed, profile fresh
--precompact — reinjects memory into compacted context — nothing lost through /compact
--bootstrap — scans codebase, generates quick_index.md for new projects
--complexity-scan — detects stack + complexity on first Start Session, recommends skills
--regret-guard — UserPromptSubmit: keyword-matches prompt vs regret.md + decisions.md, injects warnings
--decision-guard — UserPromptSubmit: detects planning language, warns if prompt contradicts decisions.md
--error-lookup — UserPromptSubmit: matches debug prompts vs error-lookup.md, surfaces known fix instantly
--guard-check — scans codebase against all named guards in guard-patterns.md, reports violations
--context-score — scores every CLAUDE.md section by journal usage — finds dead weight in your context
--velocity-estimate — keyword-matches task to past velocity entries, reports what similar tasks actually took
--mine-patterns — clusters lessons.md by keyword frequency, surfaces recurring mistakes across sessions
--progress-report — shows compounding metrics: sessions logged, lessons, known errors, skill accuracy, velocity data points, last 3 sessions
setup.py — first-time setup (Full or Lite) · upgrade.py — Lite → Full · update.py — safe kit updater
proof of concept
160 sessions.
One living environment.
Built and validated on a production project — Java backend, vanilla JS, SQL Server. These numbers are from the actual engineering environment this kit grew out of.
cat stats.md
────────────────────────────────────────
sessions logged 160
skills in active use 23+
sessions, zero data lost160
memory files tracked 20+
decisions preserved 15+
rejected approaches logged12
dependencies zero
context reset cost zero — memory persists
setup time ~5 minutes
────────────────────────────────────────
// compare to: rwieruch/the-road-to-claude (no loop),
// anthropics/claude-code-examples (no persistence)
// nothing else ships persistent memory + compound learning loop
────────────────────────────────────────
sessions logged 160
skills in active use 23+
sessions, zero data lost160
memory files tracked 20+
decisions preserved 15+
rejected approaches logged12
dependencies zero
context reset cost zero — memory persists
setup time ~5 minutes
────────────────────────────────────────
// compare to: rwieruch/the-road-to-claude (no loop),
// anthropics/claude-code-examples (no persistence)
// nothing else ships persistent memory + compound learning loop
sync & team
Works on any machine — when you want it to
Memory stays on your machine by default. Nothing leaves unless you set this up. When you're ready to work across machines, three commands get you there.
// FIRST TIME
Setup Sync: https://github.com/you/my-memory
Creates a git repo inside
.claude/memory/ and pushes to your private repo. That's it.// AFTER EACH SESSION
Sync Memory
Pushes memory to your private repo. Run after End Session on any machine.
// NEW MACHINE
Pull Memory
Pulls everything down. Then type
Start Session — fully up to speed.// CHECK
Sync Status
Shows remote URL and any unpushed changes.
team mode — opt-in
One person debugs it. Zero cost for everyone.
One private git repo. Six shared files. When a teammate logs a bug fix in error-lookup.md, every developer on the project gets it at their next Team Pull.
// WHAT GETS SHARED
error-lookup.md
One person debugs it once — zero cost for everyone
decisions.md
Team can't re-debate what the team settled
regret.md
Rejected approaches are codebase-wide
guard-patterns.md
Guards protect the whole codebase
agreed-flow.md
User journeys are team agreements
critical-notes.md
Gotchas cost time regardless of who hits them
Personal files never leave your machine: velocity.md, skill_scores.md, session_journal.md, user_preferences.md, todo.md
Setup Team: https://github.com/team/repo
honest
This system is only as good as you are
Clankbrain is a system, not a plugin. It compounds with use — but only if you use it.
// AUTOMATIC
Drift detection after every file edit
Session journal captures what happened
Stop hook reminds you when memory is unsaved
PreCompact hook protects memory through resets
Session journal captures what happened
Stop hook reminds you when memory is unsaved
PreCompact hook protects memory through resets
// REQUIRES YOU
Running
Running
Running
Keeping memory honest — garbage in, garbage out
End Session — skipping it means lessons don't get extractedRunning
/learn — skill scores only exist if you log themRunning
/evolve every few sessions — skills don't self-patch without itKeeping memory honest — garbage in, garbage out
The compound learning loop only compounds if you close it. A developer who runs
The habit is the product. The kit is what makes the habit stick.
Start Session / End Session consistently and /evolve every few weeks will have a Claude that gets measurably better at their specific codebase over time. Someone who uses it sporadically gets marginal gains.The habit is the product. The kit is what makes the habit stick.
questions
FAQ
Does this use official Claude Code features or unofficial workarounds?
Everything is built on Anthropic's official APIs — no workarounds, no reverse engineering.
Official mechanisms used:
·
·
·
·
·
The learning loop (lessons.md, decisions.md, /learn, /evolve) is built on top of those official mechanisms — that layer is what the kit adds.
Official mechanisms used:
·
CLAUDE.md with @rules/ imports — Anthropic's documented persistent context system·
.claude/rules/ directory — now a first-class Anthropic feature with path-scoping support·
.claude/skills/<name>/SKILL.md — exact official skills path·
~/.claude/CLAUDE.md for global lessons — Anthropic's documented cross-project use case·
settings.json hooks — all 5 hook events used (SessionStart, UserPromptSubmit, PostToolUse, PreCompact, Stop) are official Anthropic event namesThe learning loop (lessons.md, decisions.md, /learn, /evolve) is built on top of those official mechanisms — that layer is what the kit adds.
Does a big CLAUDE.md actually help?
No — and the research backs this up. Large monolithic CLAUDE.md files increase token use by ~20% with only a 5% improvement in output quality, and sometimes a negative effect when the content is AI-generated.
clankbrain is built the opposite way:
The template that ships with the kit enforces this. The project-specific section is designed to stay under 50 lines. High-level principles ("plan first", "simplicity first") are omitted entirely — Claude already knows them.
clankbrain is built the opposite way:
CLAUDE.md stays lean — commands and project-specific gotchas only. Project knowledge lives in separate .claude/memory/ files that load selectively based on what's relevant to the current task. That's what the research actually recommends.The template that ships with the kit enforces this. The project-specific section is designed to stay under 50 lines. High-level principles ("plan first", "simplicity first") are omitted entirely — Claude already knows them.
What Claude plan do I need?
Any paid plan that includes Claude Code. The kit itself has no plan requirements — it's plain markdown files and Python scripts that run locally.
Longer sessions may benefit from Max due to context limits, but the PreCompact hook and Start Session recovery are specifically designed to handle those limits gracefully on any plan.
What happens if Claude Code crashes mid-session?
Memory files live on disk and in git — a crash never touches them.
Open a new session, type Start Session, and Claude picks up where you left off.
STATUS.md confirms what was last saved. Run Check Drift to find anything that happened between the last memory update and the crash.
Do I need to use git for memory sync?
No — git sync is the default but it's optional. Memory files are just markdown on disk.
You can skip the push/pull steps and use any sync method you prefer (Dropbox, rsync, etc.),
or just keep everything local.
What's the difference between Full and Lite mode?
Full: 5 typed memory files (lessons, decisions, error-lookup, critical-notes, project_status), drift detection after every edit, session journal auto-captured on every Stop. Best for complex, long-running codebases.
Lite: 3 typed memory files (notes, lessons, decisions), no drift detection, no hooks — memory updates only when you run End Session manually. Best for any project. Upgrade to Full any time with a single prompt.
Lite: 3 typed memory files (notes, lessons, decisions), no drift detection, no hooks — memory updates only when you run End Session manually. Best for any project. Upgrade to Full any time with a single prompt.
Can I add skills for my own tech stack?
Yes — type Generate Skills and Claude creates skills tailored to your files and patterns.
Or create one manually:
Create a skill called [name] that [description].
Skills are markdown files in .claude/skills/name/SKILL.md — easy to read, edit, and version-control.
What does /evolve actually do?
It reads
skill_scores.md (which /learn populates after every session with Y/N corrections),
finds steps that repeatedly needed fixing, and patches those steps. It also scans
lessons.md for recurring patterns and proposes new skills you don't have yet.
Run it every 3-5 sessions.
How do I move this to a new machine?
Clone your project and your memory repo. Open Claude Code and type Install Memory.
Claude scans the codebase and rebuilds all knowledge. If your memory is already on disk,
Start Session loads it directly.
What is the Auto-Chain feature?
Add an
## Auto-Chain section to any skill file with On pass and On fail steps.
Claude reads it and continues to the next skill automatically — no human prompt needed.
Example: fix-bug → verification-loop → smoke-test runs as one chain.
Does updating the kit overwrite my memory or project notes?
No. The updater only replaces the kit commands block in
CLAUDE.md.
Your memory files, STATUS.md, and everything below
## What This Project Is in CLAUDE.md are never touched.
The updater always shows a diff and asks "Apply update? [y/N]" before changing anything.
Is there a global lessons file that works across projects?
Yes —
~/.claude/global-lessons.md (or C:\Users\you\.claude\global-lessons.md on Windows).
Any discovery you add here gets loaded at every session start across all your projects.
Use it for things like "always check for stale .class files before debugging Java".
What Python version do I need?
Python 3.7 or newer. That's it — no external packages, no pip install.
All tools use only the standard library.
Free at python.org/downloads.
Why markdown files instead of a database?
Files you can read, diff, commit, and recover without any tooling.
Memory stored in a database is opaque — you can't grep it, review it in a PR, or restore a version from last Tuesday.
Markdown files travel with your repo, work on any machine with zero setup, and never require an API key or running service.
The constraint is the feature.
Does this work with Anthropic's native Auto Memory?
Yes — they solve different problems. Anthropic's Auto Memory captures conversational context within a session.
clankbrain persists project knowledge across sessions: your codebase structure, architectural decisions,
lessons from past mistakes, and custom workflows. Auto Memory forgets when the session closes.
clankbrain doesn't. Run both — they complement each other.
How is this different from other Claude memory repos?
Most memory tools remember. Clankbrain learns.
Every other tool — Auto Memory, MCP servers, single-file notes, SQLite stores — captures what happened. Clankbrain also improves how Claude works: skills score themselves on every use,
On session 5 every tool looks similar. By session 50, Clankbrain's skills have been refined by 50 real feedback loops. Nothing else compounds that way.
Every other tool — Auto Memory, MCP servers, single-file notes, SQLite stores — captures what happened. Clankbrain also improves how Claude works: skills score themselves on every use,
/evolve patches the steps that keep failing, and regret.md permanently blocks
approaches you've already rejected.On session 5 every tool looks similar. By session 50, Clankbrain's skills have been refined by 50 real feedback loops. Nothing else compounds that way.