memory-engine

# 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`. 1. Takes notes — records what was done, files changed, decisions made 2. Links them — tags the project, connects to previous notes 3. 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 ```text ~/.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 1. Does it serve the main purpose? → No → remove 2. Can it be condensed? → Yes → replace with refined version 3. Already covered by an existing rule? → Yes → don't duplicate 4. 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