open source · MIT license

You re-explain your codebase to Claude
every single session.

Claude Code Memory Kit gives Claude a permanent memory for your project. Functions, decisions, bugs, and context — loaded automatically every session. Never lost to a crash, a context limit, or a new machine.

bash — your-project/
$ Start Session Python 3.11 found check_memory.py — no drift STATUS.md — Session 88 5 lessons loaded 4 decisions loaded 3 known errors loaded Session 88 ready. Last change: drift fixes + SETUP.md update What are we working on? $
88
real production sessions — not a demo project
100+
functions tracked across 5 JS files on the test codebase
21
undocumented functions caught by drift detection — first run
7
production bugs permanently captured in errors.md — never hit twice
Real-world test

Tested on a production codebase — not a todo app

88 sessions. Legacy Java backend. Multiple crashes. This is what actually happened.

The stack
Java on Resin 2.1.17 (legacy server with non-standard compiler constraints), 5 JS files, 3 CSS files, 100+ functions, multi-page frontend with dashboard, admin panel, scheduler, email system, and encrypted URL handling. Not a clean greenfield project.
💥
Sessions crashed. Context was never lost.
API timeouts, context overflow, mid-task interruptions — all happened. Every time: open a new session, type Start Session, and Claude picks up exactly where it left off. Lessons loaded. Known bugs loaded. No re-explanation. This was tested repeatedly and held up every time.
🔍
Drift detection caught 50+ undocumented functions
When a large new feed feature was built across multiple sessions (~50 functions, ~100 CSS classes), drift detection flagged every undocumented entry automatically. On the very first run at project start, it caught 21 functions that had never been documented. Without the detector, all of that would have been invisible to Claude.
🐛
Critical bugs became permanent knowledge
A Resin 2.1.17 compiler limitation — it silently fails to generate $1.class for anonymous generic inner classes — was discovered the hard way. Logged to errors.md and lessons.md. Now it loads every session. Same with a SQL apostrophe injection bug in email subjects. Neither will ever cost a debugging session again.

"Without this kit, day 3 would have started re-explaining the Java patterns to Claude. By day 6 the context would have been too bloated to continue cleanly."

— from an actual session recap, day 6 of 7 building the platform
Get started

One line, then you're in Claude Code

Run this in your project root. It downloads setup.py and runs it. Claude handles the rest from inside the chat.

terminal
$ python -c "import urllib.request; exec(urllib.request.urlopen('https://raw.githubusercontent.com/YehudaFrankel/Claude-Code-memory-starter-kit/main/install.py').read().decode())"
Daily workflow

Two commands. Everything else is automatic.

The drift checker runs silently after every file edit. Memory updates after every code change. You don't manage any of it — you just work.

STEP 01
Open project
cd your-project
STEP 02
Load memory
Start Session
STEP 03
Work normally
auto-saves
STEP 04
Close out
End Session
NEXT TIME
Full context
instantly
What's included

Each feature came from hitting a real problem.

Nothing here is decoration. If it's in the kit, it's because a session went wrong without it.

🧠 Persistent memory
JS functions, API endpoints, CSS classes, architectural decisions — all documented in .claude/memory/. Claude reads compact summaries instead of re-scanning your entire codebase every session. On a 100+ function project, this is the difference between a 10-second startup and a 10-minute one.
🔍 Drift detection — the key differentiator
check_memory.py runs silently after every file edit via a PostToolUse hook. Add a function, rename a CSS class, delete an endpoint — Claude's memory updates within seconds, not next session. On the test codebase, it caught 21 undocumented functions on first run and ~50 more when a new feature was added across sessions. Without it, that logic would have been invisible to Claude indefinitely.
📋 Task continuity
Four files that travel with your repo: todo.md for plans, lessons.md so mistakes don't repeat, decisions.md so architecture doesn't get re-debated, errors.md so you never debug the same bug twice.
Auto-invoked skills
Say "review this file" and Claude runs the full code-review skill automatically. Generate Skills builds a starter set of 7 skills tailored to your stack: code-review, security-check, fix-bug, new-feature, environment-check, run-verification, and refactor. Each skill includes supporting reference docs (like ANTI-PATTERNS.md, ENVIRONMENT-MATRIX.md) that Claude reads when it runs. Add custom skills with a single chat message.
🚀 Headless mode
For large refactors, scaffolding, or multi-file changes: run claude --headless "your task" and Claude works fully in the background. You return to finished code. Best for well-defined jobs where you don't need to watch every step.
🔄 Safe updater
Type Update Kit. The updater shows you exactly what will change and asks before touching anything. Your memory files, task files, and everything below the kit block in CLAUDE.md — never touched.
🤝 Team-ready
Memory files commit to git. Merge strategy: they're append-only tables, conflicts are rare and obvious. Handoff generates a snapshot for whoever picks up the project next — no Slack thread required.
Reference

13 commands, all in plain English

Type any of these in Claude Code chat. Skills fire automatically — no commands needed.

Setup MemoryFirst time only. Runs setup.py from inside Claude Code — no terminal needed.
Start SessionLoads memory, reads all four task files, reports session number and last change. Full context in seconds.
End SessionUpdates STATUS.md, syncs memory, runs drift check. Confirms everything is clean before you close.
Check DriftCompares live code against memory. Reports what's missing and what's stale. Fixes it if you confirm.
Analyze CodebaseScans all JS/CSS/backend files. Updates memory with everything found. Adds missing entries only — never overwrites.
Install MemoryNew machine. Scans project, copies memory files to system path, fills gaps. One command to rebuild context.
Generate SkillsReads your stack and creates auto-invoked skills tailored to your actual file names and conventions.
Update KitPulls latest kit from GitHub. Previews changes. Applies only the kit-managed block — nothing else moves.
Estimate: [task]Before starting anything. Complexity rating, files that will change, risks flagged, one clarifying question if needed.
Debug SessionReproduce → isolate → hypothesize → test → fix → verify → log. Structured, no jumping straight to a fix.
Code HealthFinds console.logs, hardcoded values, missing error handling, dead code, files over 500 lines. Pre-ship scan.
HandoffGenerates HANDOFF.md from your task files and memory. Current state, next tasks, decisions made, gotchas.
Create a skill called…Describe what you want in plain English. Claude creates the SKILL.md and tells you the trigger phrase.
How it works

7 files. Each one does one thing.

No framework. No cloud. Just markdown files and a Python script.

01
CLAUDE.md — the instruction file
Claude reads this automatically when you open a project. You fill in your stack, file names, and conventions once. It also contains all the commands. This is the only file you actually edit.
02
.claude/memory/ — the knowledge base
Five markdown files: js_functions.md, backend_reference.md, html_css_reference.md, project_status.md, user_preferences.md. Claude reads these instead of re-scanning your whole codebase every session.
03
tasks/ — session continuity
todo.md is Claude's plan. lessons.md is its mistake log. decisions.md is its architecture record. errors.md is its bug history. All four are read at the start of every session. All four commit to your repo.
04
check_memory.py — the drift guard
Scans your JS and CSS files, finds every function and class, checks whether they're in the memory files. If something's missing or stale, it reports it. Runs automatically after every edit via a PostToolUse hook in settings.json.
05
settings.json — the automation layer
Tells Claude Code to run check_memory.py --silent after every Edit or Write tool call. You never trigger it manually. It just runs in the background and alerts you if drift appears.
06
.claude/skills/ — reusable playbooks
Each skill is a folder with a SKILL.md (trigger + instructions) and optional supporting docs Claude reads when it runs — like ANTI-PATTERNS.md for the refactor skill, or ENVIRONMENT-MATRIX.md for the environment-check skill. Generate Skills creates 7 skills tuned to your stack. You can add custom ones with a single chat message: "Create a skill called [name] that [does X]."
07
update.py — the safe updater
Finds the kit-managed commands block in CLAUDE.md (looks for ## Session Commands or older heading variants). Replaces only that block. Everything else — your project config, memory files, task files — is untouched. Shows a diff before applying.
What gets created

The full file layout

Everything commits to your repo. Pull on a new machine, type Install Memory, and you're back.

your-project/
your-project/ ├── CLAUDE.md ← edit the bottom half for your project ├── STATUS.md ← session log, auto-updated ├── update.py ← safe updater ├── tasks/ ← commit this │ ├── todo.md ← plan before code │ ├── lessons.md ← mistake log │ ├── decisions.md ← architecture record │ └── errors.md ← bug history ├── tools/ │ └── check_memory.py ← drift detector, auto-runs └── .claude/ ├── settings.json ← hooks + permissions ├── memory/ │ ├── MEMORY.md │ ├── js_functions.md │ ├── backend_reference.md │ ├── html_css_reference.md │ ├── project_status.md │ └── user_preferences.md └── skills/ ← auto-invoked by Claude ├── code-review/ ├── security-check/ ├── fix-bug/ ├── new-feature/ ├── environment-check/ ← fill in ENVIRONMENT-MATRIX.md ├── run-verification/ ← fill in TEST-STRATEGY.md └── refactor/ ← fill in ANTI-PATTERNS.md

Built from frustration, not theory

This started as a CLAUDE.md I copy-pasted between projects. After session 20 I got annoyed and built the drift detector. Skills were added after noticing the same prompts typed every single day. The updater came after manually patching CLAUDE.md across three separate repos. The tasks/ files came after debugging a bug that had already been fixed two weeks earlier. Everything here has a story.

88
sessions on a real production Java platform — the codebase that stress-tested every part of this kit
1 wk
to ship a full course platform: scheduler, emails, admin panel, dashboard, feed — with Claude holding the context
50+
undocumented functions caught by drift detection across a single large feature addition
7
production bugs permanently captured in errors.md — never hit twice

"By session 10 Claude knew the codebase better than I did — because it had been reading the same lessons.md, errors.md, and decisions.md at the start of every single session."

— from an actual session recap, session 42

Stop re-explaining. Start where you left off.

One line installs it. Claude handles the rest. You'll be running Start Session in under 2 minutes.

Install now ★ Star on GitHub