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

Shared logic between

session-end.js

pre-compact.js

shared-utils.js

Commands (36 files, 18 pairs EN + ZH)

memory-backup.sh push

memory-backup.sh sync

memory-backup.sh pull

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