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.

1. Review — read past 7 days, mark useful vs outdated
2. Refine — 4-question decision tree (Keep? Condense? Already covered? Delete as last resort)
3. Re-study — re-analyze cleaned data for buried patterns
4. Slim down — list removable items, wait for user confirmation
5. 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

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