claude-memory-engine

---

WHAT — Every new conversation, Claude starts from zero

• That bug you spent 30 minutes on last session — it hits the same wall again
• Your preferences, your project rules — gone the moment a new session starts
• Switch from Project A to Project B — it can't tell which is which
• Long conversations get fuzzy — important decisions vanish after compression
• Memory files pile up — no one organizes them, they just keep growing
• Your computer dies — local memory gone, no backup

Memory tools can help it "remember." But remembering is not the same as learning.

---

WHY — Because it learns

Memory Engine doesn't just help Claude remember — it teaches Claude to learn like a student:

• Mistakes don't repeat — it saves both the problem and the fix
• Switching projects doesn't mean starting over — it knows what you're working on
• It gets better over time — each cycle, it understands you a little more
• You can see how it learns — everything is markdown and JS, no black box

---

HOW — Through the Student Loop

• Student Loop — 8-step learning cycle, like cramming for finals but it keeps getting better
• Smart Context — auto-loads the right project's memory based on your working directory
• Auto Learn — saves both the problem and the fix when it hits a wall, won't repeat the same mistake

:brain: The Student Loop

Think of it like exam prep. I'm trying to make Claude Code act like a student cramming for finals — take notes after every class, organize them, review for patterns, build an error notebook, and do a big end-of-term review. Each cycle, it gets a little better.

In class (automatic, runs every session)

There is no real "end" to a Claude Code conversation — it might close, idle out, or get compressed. So Memory Engine doesn't rely on any single moment. Instead, it saves at three different points:

1. Every 20 messages (mid-session-checkpoint) — saves a checkpoint + mini analysis. The most reliable save point, because it counts messages itself
2. Before context compression (pre-compact) — fires right before context is compressed. Saves a snapshot, detects pitfalls, runs backup. This is when context is fullest, so pitfall detection is most accurate here
3. When the conversation ends (session-end) — saves a final summary + backup. Nice to have, but not guaranteed to fire (window might just close)

You don't need to remember to run any command before closing — your important stuff is already saved before you close.

On top of that, Claude also:

• Takes notes — records what was done, which files changed, key decisions made
• Links them — tags the project, connects to previous notes
• Spots patterns — scans for pitfall signals (retrying 5+ times, errors followed by fixes, user corrections)

Final exam review (manual, run /reflect)

After a few days of notes, run /reflect and Claude will:

4. Review — read the past 7 days of notes and pitfall records, mark what's still useful and what's outdated
5. Refine — apply four decision questions: Keep it? -> Condense it? -> Already covered by a rule? -> Delete only as last resort
6. Re-study — re-analyze the cleaned-up data to find patterns that were buried in noise
7. Slim down — list items that can be removed, wait for your confirmation before deleting anything
8. Wrap up — produce a report: what was learned, what changed, what to watch for next cycle

This isn't a one-time thing. Each cycle makes the notes sharper, the patterns clearer, the mistakes fewer. It's a loop that keeps improving.

:pencil2: Correction Cycle

Some mistakes don't show up in error logs. You correct its output, and only then does it realize — "oh, that was wrong." These mistakes don't get remembered automatically. Unless someone builds it an error notebook.

Record (/analyze, manual — run right after you correct something)

• You fix its work, type /analyze
• It compares both versions against existing rules
• Known rules it missed → logged, counted
• Patterns not in the rules yet → distilled into new ones
• The sooner you run it, the fresher the context

Review (automatic: before each task / manual: type /correct anytime)

• Before starting work, it scans the error notebook automatically
• Not re-learning — just a reminder: "I got this wrong last time, don't repeat it"
• Want to review on your own? Type /correct — no need to wait for a task or a cycle

Clean up (/reflect step 6, manual)

• Periodically scan the full notebook
• Same mistake 3+ times → upgrade to a hard rule
• Already internalized → mark cleared, free up space

But you know that from here on, your AI has grown a little more.

Can I just type /correct directly? Yes. /correct works anytime — no need to wait for a task or a cycle. It simply opens the error notebook and shows you what's active.

How often should I run /reflect? There's no fixed schedule. A good rhythm is once a week, or whenever the notebook feels cluttered. Step 6 of /reflect handles cleanup — upgrading repeat offenders to hard rules and clearing ones you've already internalized.

Do I have to run /analyze first before /correct works? No. /analyze records new mistakes; /correct reviews existing ones. They're independent. Even if you never run /analyze, /correct still shows whatever is already in the notebook.

:detective: Smart Context + Auto Learn

Smart Context (automatic, no config needed)

• Whatever folder you're working in, it loads that project's memory
• Switch projects and it switches automatically

Auto Learn (automatic, on session end)

• Hit a wall and figured it out? It saves both the problem and the fix
• Reminds itself next time a new conversation starts
• Same kind of mistake 3+ times across different days → suggests writing it into permanent rules

:link: Day-to-day tools

Memory and learning are the core, but day-to-day work needs more:

Feature	Description
Health	/check daily scan + /full-check weekly audit to keep the memory system healthy
Tasks	/todo tracks pending items across all projects
Backup	/backup /sync connect to GitHub — bidirectional sync, safe even if your machine dies
Cross-device	Set up a GitHub memory repo, and your memory works across machines. New device? Run /recover and it's all there
Recovery	/recover restores lost memory from GitHub backup
Search	/memory-search keyword search across all memory files
Bilingual	Every command has an English + Traditional Chinese version (36 files)

Not sure what commands are available? Type /overview (/全覽) to see them all.

Daily Operations

EN	ZH	Function
/save	/存記憶	Save memory across sessions — auto-dedup and route to the right file
/reload	/讀取	Load memory into the current conversation
/todo	/待辦	Cross-project task tracking
/backup	/備份	Push local memory to GitHub
/sync	/同步	Bidirectional sync — push local, pull remote

Reflection & Learning

EN	ZH	Function
/diary	/回顧	Generate a reflection diary
/reflect	/反思	Analyze pitfall records and find recurring patterns
/learn	/學習	Manually save a pitfall experience

Health Checks

EN	ZH	Function
/check	/健檢	Quick scan — capacity, broken links, orphan files
/full-check	/大健檢	Full audit — commands, git repos, environment config
/memory-health	/記憶健檢	Memory file line counts, update dates, capacity warnings

Search & Maintenance

EN	ZH	Function
/memory-search	/搜尋記憶	Keyword search across all memory files
/recover	/想起來	Restore memory from GitHub backup
/compact-guide	/壓縮建議	Guide for when to compress and when not to
/overview	/全覽	List all available commands

Collaboration

You have three Claude Code windows open. One's fixing a bug, one's writing docs, one's cleaning up code. You switch over — and that window has zero clue what you were just doing.

/save is for things you want to remember long-term. /backup pushes everything to GitHub. /handoff is for right now — what you were working on, what's done, what's not.

EN	ZH	Function
/handoff	/交接	Generate a handoff file so another session can pick up where you left off

How it works: Run /handoff in window A. It saves a handoff file with your progress, decisions, and unfinished tasks. Window B picks it up automatically — no command needed on the receiving end. If B is already mid-conversation, it detects the new handoff in real time. If B starts a new conversation, it loads the handoff on startup. Either way, B sees it once and moves on.

Engine maintenance (new in v2.0)

EN	ZH	Function
/bb-pause	/暫停同步	Pause SessionEnd auto-commit while refactoring engine internals

When you're editing memory-backup.sh, hooks/*.js, or CLAUDE.md, the SessionEnd hook might auto-commit a half-finished version. /bb-pause on creates a .bb-pause lock file that makes the script exit early. Run /bb-pause off when you're done.

Hook	Trigger	What it does
session-start	New conversation	Load last summary + project memory + pending handoffs
session-end	Conversation ends	Save summary + backup (best-effort, may not fire)
pre-compact	Context compression (auto or manual)	Save snapshot + pitfall detection + backup — the real safety net
memory-sync	Every message sent	Detect cross-session memory changes + new handoffs
write-guard	Before file writes	Sensitive file interception
pre-push-check	Before git push	Safety check
mid-session-checkpoint	Every 20 messages	Save checkpoint + mini analysis

---

:arrows_counterclockwise: Cross-device Sync (rewritten in v2.0)

Memory Engine supports cross-device sync through a GitHub repo. Set it up once, and your memory works on every machine.

How it works:

1. /backup pushes local memory to your private GitHub repo (memory-backup.sh push)
2. /sync does bidirectional sync — pull remote updates, then push local changes (memory-backup.sh sync)
3. /recover on a new device pulls everything back and distributes to all local projects (memory-backup.sh pull)

What this means: Switch laptops, reinstall your OS, set up a new workstation — run /recover and Claude picks up right where you left off. No re-explaining your preferences, no lost context.