memory + structured workflows for Claude Code · open source · MIT · built on official Claude Code APIs · memory files stored locally

Claude Code gives you memory,
hooks and skills.
Clankbrain wires them up.

Claude Code already has CLAUDE.md, auto memory, hooks and skills, but it ships the mechanism, not the finished setup. Clankbrain adds hooks that are already wired, organized memory files for lessons, decisions and rejected approaches, a Start/End Session routine, and 19 core workflows installed by default (36 in the repo). Built from 335 sessions on one production project.

Two commands: Start Session → work → End Session. That’s the daily routine.

Get started → Try the Wizard → View on GitHub
● Sessions compound, not reset ● 19 core workflow skills installed ● Refine skills with /learn and /evolve ● Live dashboard included ● No external dependencies
yf@clankbrain ~ sessions/active
# session active /
yf@clankbrain ~ $
see it in action

Two commands. Everything compounds.

Click through an illustrative session. GitHub sync is optional; memory stays local unless you configure it.

1 · Start Session
2 · Plan a change
3 · Approve
4 · End Session
claude-code · your-project
Click to begin the walkthrough
get started

Five minutes to a living environment

You need Claude Code, Python 3.7 or newer, and Node.js for the npx installer. Run from your project root. Codex can use the shared memory through AGENTS.md; Clankbrain’s automatic hooks remain specific to Claude Code.

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.
// UNDER AN HOUR. ANY CODEBASE.
Set up a production-grade AI coding memory system on any codebase in under an hour.
Scan your conventions. Map your endpoints. Seed your regret log.
Then ship faster than you thought possible.
→ scan-conventions reads your real code, writes coding-conventions.md
→ map-codebase maps all endpoints + methods + tables
→ Starter regret entries help flag familiar mistakes from day one
// 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
Open the project where you ran the installer. Type kit-health to check the installation.
// 03
Type: Start Session
Memory loads from disk, drift check runs, Claude resumes from the last saved project state. First run auto-scans your project and recommends which skills apply to your stack.
// 04
Type: End Session
/learn extracts lessons. Session changes doc written (SQL run, files changed, pending work). Memory saved. Next session starts smarter.
New machine? Run Install Memory — Claude scans the codebase and rebuilds all knowledge files from scratch.
BUILT-IN FEATURES
CLANKBRAIN
Skills provide reusable instructions
/learn records scores · /evolve patches weak steps when run
Memory can record project decisions
regret.md surfaces rejected approaches before planning
Auto memory stores notes across sessions
typed files: decisions · errors · lessons · regret
Instructions and rules can be shared through git
shared team memory · personal stays local
Hooks run scripts you configure
zero dependencies — stdlib Python only
Skills and plan mode provide building blocks
19 core workflows installed (36 in the repo): debug · review · refactor · design · security
Official hooks, rules and skills APIs
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
2+
red risks trigger a pause
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 — saved notes help you resume. Sync your memory first when switching machines.
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 — when you run it.
03 ─────
Knowledge Compounds
lessons.md and decisions.md grow every session and apply at every Start Session. Claude stops re-debating settled choices. Over many sessions it works more like a teammate who knows your project.
agentic core

The compound
learning loop

Hooks handle session bookkeeping. End Session runs /learn to extract lessons and score skills. Run /evolve every few sessions to revise weak steps using that feedback.

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 — records rejected approaches
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

19 core skills installed by default.
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 patternsExtract lessons from this session, score skills Y/N, update decisions.md and lessons.md
planplan [feature], I want to build X, design XStructured planning — options with build cost/friction/payoff ratings, decision logged live, full plan auto-displayed after every update
/evolve/evolve, evolve lessons into skillsRead skill_scores.md, patch weak steps, propose new skills from detected patterns
verification-loopverify, run verification loop, did that workAfter a code change — confirm it compiled, smoke test, self-check quality
search-firstsearch first, check if this existsEnforce research-before-coding: search codebase before implementing anything new
strategic-compactshould I compact, context getting longEvaluate whether to compact and guide through safe compaction that preserves all memory
fix-bugfix the bug, it's broken, not workingStructured root-cause flow: locate → read → diagnose → show fix → wait for confirmation → update memory. Auto-chains to guard after the fix.
modemode develop, mode review, mode safe, mode deployRestrict Claude's tool access to what a task actually needs — develop (full), review (read-only), safe (no writes), deploy (shell only)
debug-sessiondebug session, structured debug, debug this error7-step structured debugging: reproduce → isolate → hypothesize → fix → verify — then logs cause + fix to error-lookup.md so future sessions can consult the known fix. Auto-chains to verification-loop after the fix.
guardguard check, scan for issues, did I miss anythingScans 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 buildingFour 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.
scan-conventionsscan conventions, generate conventions, bootstrap conventionsReads 3–5 real methods from your codebase, extracts actual conventions (variable style, SQL patterns, error handling, naming, INSERT strategy), writes coding-conventions.md in ~10 min. Works on any stack. Run once on project start.
map-codebasemap codebase, generate code map, map my projectScans all endpoints, public methods, DB tables, HTML pages and JS functions. Writes code-map.md + java_function_index.md + js_function_index.md. Run once — never grep blindly for a method again.
// 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 — saves memory before compaction to help recover context
--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 → Or use the Wizard →
proof of concept

335 sessions.
One living environment.

Built and validated on a production project — Java backend, vanilla JS, SQL Server. These are author-reported figures from the environment this kit grew out of, rather than a controlled comparison. The 37 skills include project-specific workflows; the public kit contains 36.

yf@clankbrain ~ $
cat stats.md
────────────────────────────────────────
sessions logged 335
skills in active use 37
sessions, zero data lost335
memory files tracked 40+
decisions preserved 75
rejected approaches logged38
dependencies zero
context recovery saved notes persist
setup time ~5 minutes
────────────────────────────────────────
// author’s production-project experience,
// not a controlled benchmark or a recovery guarantee
// persistent memory + a skill feedback loop, in plain text files
sync & team

Works on any machine — when you want it to

Memory files are stored locally by default. Optional sync sends them to a repository you choose. The kit also sends anonymous usage telemetry; set CLANKBRAIN_NO_TELEMETRY=1 to disable it. Your coding agent’s own data handling still applies. 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.

Fewer manual merges for append-only notes. Add *.md merge=union to .gitattributes once. The union driver keeps additions from both sides, but may leave duplicate or contradictory entries. Review merged memory, especially decisions and current status.

team mode — opt-in

One person debugs it. The team keeps the fix.

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 A shared fix gives teammates a starting point
decisions.md Records settled choices and their rationale
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
Team sync excludes these personal files (separate backup or sync settings may still copy them): 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 can build a useful record of project-specific decisions, fixes, and workflow improvements. The benefit depends on the quality of those notes and how consistently they are used.

The habit is the product. The kit is what makes the habit stick.
questions

FAQ

Can I use Clankbrain with Codex?
Yes. The installer writes AGENTS.md, so Codex can read the shared project memory. Ask it to read and update those files at session boundaries. Clankbrain’s Claude Code hooks and skill installation do not automatically run in Codex; shared memory support does not mean full automation parity.
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 — hook events include SessionStart, UserPromptSubmit, PostToolUse, PreCompact and Stop; availability of additional events depends on your Claude Code version

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?
A longer CLAUDE.md uses more context, and extra detail does not always improve results. Clankbrain keeps it short and puts the detail in separate memory files.

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. Keep the always-loaded instructions focused and retrieve details when needed.

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?
Use a Claude Code account or API setup supported by Anthropic. The kit itself has no plan requirements — it's plain markdown files and Python scripts that run locally. Plan usage limits still apply. The PreCompact hook and Start Session routine help preserve saved context; Clankbrain does not increase model context windows or plan allowances.
What happens if Claude Code crashes mid-session?
Memory files live on disk, with git history if you have committed them. A crash generally leaves saved files intact; unsaved work may still be lost. Open a new session, type Start Session, and Claude resumes from the last saved project state. 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. Database-backed memory can offer useful querying, but plain Markdown makes notes easy to inspect, diff, and version with your code. 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, and they overlap. Auto memory is notes Claude writes itself from your corrections and loads in every session. Clankbrain adds ready-wired hooks and separate files you can read and edit, for lessons, decisions and rejected approaches, plus a Start/End Session routine and scored skills. You can run both. If auto memory is enough for you, you may not need Clankbrain.
How is this different from other Claude memory repos?
Most memory tools store notes. Clankbrain also tracks how its workflows perform.

Skills are scored after use, /evolve rewrites the steps that keep failing when you run it, and regret.md keeps approaches you have already rejected where Claude can check them before planning.

In the first few sessions the difference is small. Over many sessions, each skill gets adjusted by your own feedback, if you keep running End Session and /evolve.