memory + structured workflows for Claude Code · open source · MIT · built on official Claude Code APIs · data stays on your machine

# Every session, your coding agent
wakes up a stranger.
Clankbrain fixes that.

You re-explain your codebase every session. Your agent forgets your decisions, your mistakes, your patterns. Clankbrain gives it a living memory — decisions, lessons, patterns that grow with your project — plus 20+ built-in workflows for debugging, code review, refactoring, design, security, and more.

Two commands: `Start Session` → work → `End Session`. That's the whole interface.

Get started → View on GitHub
● Sessions compound, not reset ● 20+ workflow skills built in ● Skills self-improve from failure ● Live dashboard included ● No external dependencies
yf@clankbrain ~ sessions/active
# session active /
yf@clankbrain ~ $
see it in action

## Two commands. Everything compounds.

Click through a real session — the same workflow that runs on production codebases.

1 · Start Session
2 · Plan a change
3 · Approve
4 · End Session
claude-code · your-project
Click to begin the walkthrough
That's the whole workflow. Two commands. Every session compounds.
Install 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 — stdlib Python only
no structured development workflows
20+ built-in workflows: debug · review · refactor · design · security
unofficial / proprietary internals
official Anthropic hooks + skills APIs
product studio

## Don't build the wrong thing.
Validate first.

`/product-risk` runs the Four Big Risks — Value, Usability, Feasibility, Viability — before you write a line of code.

EVALUATE ─────
Score what exists
Point it at any product — yours or someone else's. Targeted questions for each risk. Red/Yellow/Green scorecard. Biggest risk identified. One concrete next action.
CREATE ─────
Validate + build
Describe your idea. Pass the four-risk gate. Generates working HTML/CSS/JS prototypes with real data, real interactions, responsive layouts — plus a full plan file, decisions logged, and project scaffolding.
Kill gate If 2+ risks score red, the skill refuses to build. Tells you what to validate first. The job is to prevent building things nobody wants.
4
risk dimensions
6
phases in create mode
~30m
idea to working prototype
0
bad ideas get built
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
End Session
save memory
→ STATUS.md
→ memory/
/evolve
every 3-5 sessions
patches weak skills
proposes new ones
Start Session
applies all lessons
Claude arrives
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 `## 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
agentic toolkit

## 21 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
fix-bug | fix the bug, it's broken, not working | Structured root-cause flow: locate → read → diagnose → show fix → wait for confirmation → update memory. Auto-chains to guard after the fix.
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.
guard | guard check, scan for issues, did I miss anything | Scans recently changed files against a library of known error patterns, flags violations before they ship. After any bug fix, extracts the root cause as a new permanent rule.
product-risk | /product-risk, validate this idea, is this worth building | Four Big Risks (Value, Usability, Feasibility, Viability). Evaluate mode scores existing products Red/Yellow/Green. Create mode validates an idea, then generates working HTML/CSS/JS prototypes + full project scaffolding. Kill gate: refuses to build if 2+ risks are red.

// 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
Set it up in 5 minutes →
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.

yf@clankbrain ~ $
cat stats.md
────────────────────────────────────────
sessions logged 160
skills in active use 23+
sessions, zero data lost 160
memory files tracked 20+
decisions preserved 15+
rejected approaches logged 12
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
// REQUIRES YOU
Running `End Session` — skipping it means lessons don't get extracted
Running `/learn` — skill scores only exist if you log them
Running `/evolve` every few sessions — skills don't self-patch without it
Keeping memory honest — garbage in, garbage out
The compound learning loop only compounds if you close it. A developer who runs `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:
· `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 names
The 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: `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. When you do want universal behavioral guardrails, ship them as a dedicated rule file — like the included `karpathy-principles.md`, which encodes Andrej Karpathy's 4 LLM coding principles (think before coding, simplicity first, surgical changes, goal-driven execution) as an always-load rule.
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.
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. The core kit uses only the standard library — no pip install needed. Semantic search (`/recall`) optionally uses `sentence-transformers` for meaning-based matching; without it, recall falls back to keyword grep. 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, `/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.