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.

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

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

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