memory-engine

name memory-engine description Memory management system for Claude Code — Student Loop, Smart Context, Auto Learn, Session Handoff, Correction Cycle. Triggered by memory commands (/save, /reflect, /handoff, /check) or memory-related questions. Not for general programming tasks. Memory Engine v1.6 A memory and learning system for Claude Code, built with hooks and markdown. Modules 1. Smart Context Auto-detects the current project from your working directory and loads its memory. Resolves per-project memory directory automatically — no hardcoded paths Implementation: ~/.claude/scripts/hooks/session-start.js Config: references/smart-context.md 2. Auto Learn (Pitfall Detection) Detects pitfall patterns before context compression — retries, errors followed by fixes, user corrections. Saves both the problem and the fix to ~/.claude/skills/learned/ Same mistake 3+ times across different days → suggests writing it into permanent rules Implementation: shared-utils.js → detectPitfalls() + savePitfalls() 3. Student Loop (/reflect) 8-step learning cycle. First 3 steps are automatic (every session). Last 5 via /reflect . Takes notes — records what was done, files changed, decisions made Links them — tags the project, connects to previous notes Spots patterns — scans for pitfall signals There is no real "end" to a Claude Code conversation. Memory Engine saves at three points: Every 20 messages ( mid-session-checkpoint ) — most reliable, self-counted Before context compression ( pre-compact ) — pitfall detection runs here, context is fullest When conversation ends ( session-end ) — best-effort, not guaranteed to fire You don't need to remember to run any command before closing. 4. Review — read past 7 days, mark useful vs outdated 5. Refine — 4-question decision tree (Keep? Condense? Already covered? Delete as last resort) 6. Re-study — re-analyze cleaned data for buried patterns 7. Slim down — list removable items, wait for user confirmation 8. Wrap up — produce a report 4. Session Handoff (/handoff) Pass context between Claude Code windows without losing progress. /handoff saves a handoff-*.md file with progress, decisions, unfinished tasks Next session auto-detects it on startup ( session-start.js ) Mid-conversation detection via memory-sync.js Each handoff is shown once, tracked by .handoff-read.json 5. Correction Cycle (/analyze) Learns from user corrections — mistakes that don't show up in error logs. Analyze ( /analyze ) — compare user's edits against rules, log missed rules, distill new ones Correct (auto, before tasks) — scan the error list as a reminder Reflect ( /reflect step 6) — same mistake 3+ times → upgrade to hard rule Hooks Hook File What it does SessionStart session-start.js Load last summary + project memory + pending handoffs + pitfall review + /reflect reminder SessionEnd session-end.js Save summary + project index + backup (best-effort, may not fire) PreCompact pre-compact.js Snapshot + pitfall detection + backup — the real safety net UserPromptSubmit memory-sync.js Cross-session memory change detection + handoff detection UserPromptSubmit mid-session-checkpoint.js Checkpoint every 20 messages PreToolUse(Write) write-guard.js Sensitive file write warning PreToolUse(Bash) pre-push-check.js Safety check before git push — memory-backup.sh Bidirectional sync script (push/pull/sync) — v1.6 Shared logic between session-end.js and pre-compact.js is extracted into shared-utils.js . Commands (36 files, 18 pairs EN + ZH) EN ZH Function /save /存記憶 Save memory — auto-dedup, route to correct file /reload /讀取 Load memory into current conversation /todo /待辦 Cross-project task tracking /backup /備份 Push local memory to GitHub ( memory-backup.sh push ) /sync /同步 Bidirectional sync ( memory-backup.sh sync ) — v1.6 pull+push /handoff /交接 Session handoff — pass progress to next window /diary /回顧 Generate reflection diary /reflect /反思 Analyze pitfalls, find patterns /learn /學習 Manually save a pitfall /analyze /分析 Record corrections into error notebook /correct /訂正 Review error notebook anytime /check /健檢 Quick health scan /full-check /大健檢 Full audit /memory-health /記憶健檢 Memory file stats + capacity warnings /memory-search /搜尋記憶 Keyword search across all memory files /recover /想起來 Restore memory from GitHub ( memory-backup.sh pull ) — v1.6 auto-distribute /compact-guide /壓縮建議 When to compact and when not to /overview /全覽 List all available commands File Structure ~/.claude/ scripts/hooks/ session-start.js # Load recall + smart-context + handoff session-end.js # Save summary + backup (best-effort) pre-compact.js # Pre-compression snapshot + pitfall detection + backup shared-utils.js # Shared functions (transcript, pitfall, backup) memory-sync.js # Cross-session sync + handoff detection mid-session-checkpoint.js write-guard.js pre-push-check.js memory-backup.sh # Bidirectional sync (push/pull/sync) — v1.6 sessions/ {date}-{id}-session.md # Session summaries {date}-{id}-compact.md # Pre-compact snapshots diary/ # Reflection diaries commands/ save.md / 存記憶.md # ...15 pairs handoff.md / 交接.md skills/learned/memory-engine/ SKILL.md # This file references/ smart-context.md # Project detection rules auto-learn.md # Pitfall detection rules Core Principles Test what you build After creating any hook or feature, always run a test to confirm it works "Written" does not mean "done" — see actual output before marking complete /reflect 4-question decision tree Does it serve the main purpose? → No → remove Can it be condensed? → Yes → replace with refined version Already covered by an existing rule? → Yes → don't duplicate Delete is the last resort → only if Q1-Q3 don't apply Troubleshooting MEMORY.md over 200 lines with no warning Cause: Didn't check line count before writing Fix: Run wc -l before every write. Over 170 lines → move old content to standalone files first Memory saved but next session doesn't know Cause: Content written directly into MEMORY.md instead of creating a pointer Fix: MEMORY.md holds pointers only. Details go in memory/*.md Backup push fails Cause: Conflicts in the memory repo or expired auth Fix: Run git pull first, resolve conflicts if any Memory from another device not showing up Cause: Backup was push-only. Device A pushes to GitHub, but Device B never pulls it back into its local projects/ directories Fix: v1.6 adds pull and sync modes to memory-backup.sh . The pull distributes global memory files from the backup repo into every local project directory that has a memory/ folder (newer file wins, won't overwrite local changes) Root cause: Each device has different working directories, so projects/ paths differ. Global memory must be actively distributed, not just stored in one place References references/smart-context.md — Project detection rules references/auto-learn.md — Pitfall detection rules + auto-learn flow