Back to search
claude-memory-engine
SkillWorks with Claude CodeGitHub
Claude Code 的記憶系統 | A memory system built with hooks + markdown. Zero dependencies.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/helloruru--claude-memory-engine)HTML
<a href="/listings/helloruru--claude-memory-engine"><img src="/api/listings/helloruru--claude-memory-engine/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 578 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <h1 align="center">Claude Memory Engine</h1>
- <p align="center">
- <strong>Not just memory — it learns.</strong><br>
- Learn from mistakes. Learn to improve.<br>
- AI can be a student too, growing through every cycle.
- </p>
- <p align="center">
- Built with hooks and markdown. No database. No external API.<br>
- Just scripts and files. Nothing hiding.
- </p>
- <p align="center">
- <img src="https://img.shields.io/badge/license-MIT-D4A5A5?style=flat-square" alt="MIT License">
- <img src="https://img.shields.io/badge/node-18%2B-B8A9C9?style=flat-square" alt="Node 18+">
- <img src="https://img.shields.io/badge/dependencies-zero-A8B5A0?style=flat-square" alt="Zero Dependencies">
- <img src="https://img.shields.io/badge/claude_code-hooks-E8B4B8?style=flat-square" alt="Claude Code Hooks">
- <img src="https://img.shields.io/badge/version-2.0-C4B7D7?style=flat-square" alt="v2.0">
- </p>
- <p align="center">
- <b>English</b> | <a href="README.zh-TW.md">繁體中文</a> | <a href="README.ja.md">日本語</a>
- </p>
- ---
- ## WHAT — Every new conversation, Claude starts from zero
- - That bug you spent 30 minutes on last session — it hits the same wall again
- - Your preferences, your project rules — gone the moment a new session starts
- - Switch from Project A to Project B — it can't tell which is which
- - Long conversations get fuzzy — important decisions vanish after compression
- - Memory files pile up — no one organizes them, they just keep growing
- - Your computer dies — local memory gone, no backup
- Memory tools can help it "remember." But remembering is not the same as learning.
- ---
- ## WHY — Because it learns
- Memory Engine doesn't just help Claude remember — it teaches Claude to learn like a student:
- - Mistakes don't repeat — it saves both the problem and the fix
- - Switching projects doesn't mean starting over — it knows what you're working on
- - It gets better over time — each cycle, it understands you a little more
- - You can see how it learns — everything is markdown and JS, no black box
- ---
- ## HOW — Through the Student Loop
- - **Student Loop** — 8-step learning cycle, like cramming for finals but it keeps getting better
- - **Smart Context** — auto-loads the right project's memory based on your working directory
- - **Auto Learn** — saves both the problem and the fix when it hits a wall, won't repeat the same mistake
- ### :brain: The Student Loop
- > Think of it like exam prep. I'm trying to make Claude Code act like a student cramming for finals — take notes after every class, organize them, review for patterns, build an error notebook, and do a big end-of-term review. Each cycle, it gets a little better.
- **In class (automatic, runs every session)**
- There is no real "end" to a Claude Code conversation — it might close, idle out, or get compressed. So Memory Engine doesn't rely on any single moment. Instead, it saves at three different points:
- 1. **Every 20 messages** (`mid-session-checkpoint`) — saves a checkpoint + mini analysis. The most reliable save point, because it counts messages itself
- 2. **Before context compression** (`pre-compact`) — fires right before context is compressed. Saves a snapshot, detects pitfalls, runs backup. This is when context is fullest, so pitfall detection is most accurate here
- 3. **When the conversation ends** (`session-end`) — saves a final summary + backup. Nice to have, but not guaranteed to fire (window might just close)
- You don't need to remember to run any command before closing — your important stuff is already saved before you close.
- On top of that, Claude also:
- - **Takes notes** — records what was done, which files changed, key decisions made
- - **Links them** — tags the project, connects to previous notes
- - **Spots patterns** — scans for pitfall signals (retrying 5+ times, errors followed by fixes, user corrections)
- **Final exam review (manual, run `/reflect`)**
- After a few days of notes, run `/reflect` and Claude will:
- 4. **Review** — read the past 7 days of notes and pitfall records, mark what's still useful and what's outdated
- 5. **Refine** — apply four decision questions: Keep it? -> Condense it? -> Already covered by a rule? -> Delete only as last resort
- 6. **Re-study** — re-analyze the cleaned-up data to find patterns that were buried in noise
- 7. **Slim down** — list items that can be removed, wait for your confirmation before deleting anything
- 8. **Wrap up** — produce a report: what was learned, what changed, what to watch for next cycle
- > This isn't a one-time thing. Each cycle makes the notes sharper, the patterns clearer, the mistakes fewer. It's a loop that keeps improving.
- ### :pencil2: Correction Cycle
- Some mistakes don't show up in error logs. You correct its output, and only then does it realize — "oh, that was wrong." These mistakes don't get remembered automatically. Unless someone builds it an error notebook.
- **Record** (`/analyze`, manual — run right after you correct something)
- - You fix its work, type `/analyze`
- - It compares both versions against existing rules
- - Known rules it missed → logged, counted
- - Patterns not in the rules yet → distilled into new ones
- - The sooner you run it, the fresher the context
- **Review** (automatic: before each task / manual: type `/correct` anytime)
- - Before starting work, it scans the error notebook automatically
- - Not re-learning — just a reminder: "I got this wrong last time, don't repeat it"
- - Want to review on your own? Type `/correct` — no need to wait for a task or a cycle
- **Clean up** (`/reflect` step 6, manual)
- - Periodically scan the full notebook
- - Same mistake 3+ times → upgrade to a hard rule
- - Already internalized → mark cleared, free up space
- But you know that from here on, your AI has grown a little more.
- <details>
- <summary><strong>FAQ</strong></summary>
- **Can I just type `/correct` directly?**
- Yes. `/correct` works anytime — no need to wait for a task or a cycle. It simply opens the error notebook and shows you what's active.
- **How often should I run `/reflect`?**
- There's no fixed schedule. A good rhythm is once a week, or whenever the notebook feels cluttered. Step 6 of `/reflect` handles cleanup — upgrading repeat offenders to hard rules and clearing ones you've already internalized.
- **Do I have to run `/analyze` first before `/correct` works?**
- No. `/analyze` records new mistakes; `/correct` reviews existing ones. They're independent. Even if you never run `/analyze`, `/correct` still shows whatever is already in the notebook.
- </details>
- ### :detective: Smart Context + Auto Learn
- **Smart Context** (automatic, no config needed)
- - Whatever folder you're working in, it loads that project's memory
- - Switch projects and it switches automatically
- **Auto Learn** (automatic, on session end)
- - Hit a wall and figured it out? It saves both the problem and the fix
- - Reminds itself next time a new conversation starts
- - Same kind of mistake 3+ times across different days → suggests writing it into permanent rules
- ### :link: Day-to-day tools
- Memory and learning are the core, but day-to-day work needs more:
- | Feature | Description |
- | :--- | :--- |
- | Health | `/check` daily scan + `/full-check` weekly audit to keep the memory system healthy |
- | Tasks | `/todo` tracks pending items across all projects |
- | Backup | `/backup` `/sync` connect to GitHub — bidirectional sync, safe even if your machine dies |
- | Cross-device | Set up a GitHub memory repo, and your memory works across machines. New device? Run `/recover` and it's all there |
- | Recovery | `/recover` restores lost memory from GitHub backup |
- | Search | `/memory-search` keyword search across all memory files |
- | Bilingual | Every command has an English + Traditional Chinese version (36 files) |
- <details>
- <summary><strong>Full command list</strong></summary>
- > **Not sure what commands are available?** Type `/overview` (`/全覽`) to see them all.
- **Daily Operations**
- | EN | ZH | Function |
- | :--- | :- | :--- |
- | `/save` | `/存記憶` | Save memory across sessions — auto-dedup and route to the right file |
- | `/reload` | `/讀取` | Load memory into the current conversation |
- | `/todo` | `/待辦` | Cross-project task tracking |
- | `/backup` | `/備份` | Push local memory to GitHub |
- | `/sync` | `/同步` | Bidirectional sync — push local, pull remote |
- **Reflection & Learning**
- | EN | ZH | Function |
- | :--- | :- | :--- |
- | `/diary` | `/回顧` | Generate a reflection diary |
- | `/reflect` | `/反思` | Analyze pitfall records and find recurring patterns |
- | `/learn` | `/學習` | Manually save a pitfall experience |
- **Health Checks**
- | EN | ZH | Function |
- | :--- | :- | :--- |
- | `/check` | `/健檢` | Quick scan — capacity, broken links, orphan files |
- | `/full-check` | `/大健檢` | Full audit — commands, git repos, environment config |
- | `/memory-health` | `/記憶健檢` | Memory file line counts, update dates, capacity warnings |
- **Search & Maintenance**
- | EN | ZH | Function |
- | :--- | :- | :--- |
- | `/memory-search` | `/搜尋記憶` | Keyword search across all memory files |
- | `/recover` | `/想起來` | Restore memory from GitHub backup |
- | `/compact-guide` | `/壓縮建議` | Guide for when to compress and when not to |
- | `/overview` | `/全覽` | List all available commands |
- **Collaboration**
- You have three Claude Code windows open. One's fixing a bug, one's writing docs, one's cleaning up code. You switch over — and that window has zero clue what you were just doing.
- `/save` is for things you want to remember long-term. `/backup` pushes everything to GitHub. `/handoff` is for right now — what you were working on, what's done, what's not.
- | EN | ZH | Function |
- | :--- | :- | :--- |
- | `/handoff` | `/交接` | Generate a handoff file so another session can pick up where you left off |
- **How it works:** Run `/handoff` in window A. It saves a handoff file with your progress, decisions, and unfinished tasks. Window B picks it up automatically — no command needed on the receiving end. If B is already mid-conversation, it detects the new handoff in real time. If B starts a new conversation, it loads the handoff on startup. Either way, B sees it once and moves on.
- **Engine maintenance (new in v2.0)**
- | EN | ZH | Function |
- | :--- | :- | :--- |
- | `/bb-pause` | `/暫停同步` | Pause SessionEnd auto-commit while refactoring engine internals |
- When you're editing `memory-backup.sh`, `hooks/*.js`, or `CLAUDE.md`, the SessionEnd hook might auto-commit a half-finished version. `/bb-pause on` creates a `.bb-pause` lock file that makes the script exit early. Run `/bb-pause off` when you're done.
- </details>
- <details>
- <summary><strong>8 Hooks (all automatic)</strong></summary>
- | Hook | Trigger | What it does |
- | :--- | :------ | :----------- |
- | `session-start` | New conversation | Load last summary + project memory + pending handoffs |
- | `session-end` | Conversation ends | Save summary + backup (best-effort, may not fire) |
- | `pre-compact` | Context compression (auto or manual) | Save snapshot + pitfall detection + backup — the real safety net |
- | `memory-sync` | Every message sent | Detect cross-session memory changes + new handoffs |
- | `write-guard` | Before file writes | Sensitive file interception |
- | `pre-push-check` | Before git push | Safety check |
- | `mid-session-checkpoint` | Every 20 messages | Save checkpoint + mini analysis |
- </details>
- ---
- ## :arrows_counterclockwise: Cross-device Sync (rewritten in v2.0)
- Memory Engine supports cross-device sync through a GitHub repo. Set it up once, and your memory works on every machine.
- **How it works:**
- 1. `/backup` pushes local memory to your private GitHub repo (`memory-backup.sh push`)
- 2. `/sync` does bidirectional sync — pull remote updates, then push local changes (`memory-backup.sh sync`)
- 3. `/recover` on a new device pulls everything back and distributes to all local projects (`memory-backup.sh pull`)
- **What this means:** Switch laptops, reinstall your OS, set up a new workstation — run `/recover` and Claude picks up right where you left off. No re-explaining your preferences, no lost context.
- > The GitHub repo is private by default. Your memory never touches any external service beyond your own GitHub account.
- ### v2.0 — Full Environment Engine
- v1.6 only synced memory files, which meant your second machine forever ran an older `CLAUDE.md`, missing slash commands, and stale hooks. v2.0 rewrites the sync as a **full environment engine** — the entire `~/.claude/` working environment travels with you:
- | Synced Artifact | v1.6 | v2.0 |
- | :--- | :---: | :---: |
- | MEMORY.md + per-project memory | ✅ | ✅ |
- | CLAUDE.md (top-level rules) | ❌ | ✅ |
- | commands/ (slash commands) | ❌ | ✅ |
- | hooks/ (the engine itself) | push only | ✅ bidirectional |
- | settings.json (hook registry) | ❌ | ✅ (auto-backup before overwrite) |
- | skills/ and skills/learned/ | partial | ✅ |
- **Core architecture: SYNC_TABLE**
- A single source-of-truth table inside `memory-backup.sh`. Both push and pull read the **same table**, fixing the asymmetric bug where push synced X but pull silently skipped X. Adding a new sync target is one line:
- ```bash
- SYNC_TABLE=(
- "$CLAUDE_DIR/CLAUDE.md|$REPO_DIR/CLAUDE.md|file|CLAUDE.md (top-level rules)"
- "$CLAUDE_DIR/commands|$REPO_DIR/commands|dir-md|slash commands"
- # ... add a line, push/pull both pick it up
- )
- ```
- ### v2.0 Features
- | Feature | Usage | Purpose |
- | :--- | :--- | :--- |
- | **Dry-run** | `bash memory-backup.sh push --dry-run` | Preview what would change before doing it. No real copies. |
- | **Status** | `bash memory-backup.sh status` | Show local-vs-repo diff + git commits behind/ahead |
- | **Machine-id** | `echo "laptop" > ~/.claude/machine-id` | Tags commits with machine name for multi-device attribution |
- | **`.bb-pause` lock** | `/bb-pause on` / `off` | Pause SessionEnd auto-commit while refactoring engine itself |
- | **`.bak.*` filter** | automatic | settings backup files stay out of the repo |
- ---
- ## :package: Installation
- **Step 1** — Create a GitHub repo for memory backup (cross-device sync):
- > Without a backup repo, `/backup`, `/sync`, and `/recover` won't work. Memory only lives locally — if your machine dies, it's all gone. With a repo, your memory works across devices.
- ```bash
- gh repo create claude-memory --private
- git clone https://github.com/YOUR_USERNAME/claude-memory.git ~/.claude/claude-memory
- ```
- **Step 2** — Copy files:
- ```bash
- cp hooks/*.js ~/.claude/scripts/hooks/
- cp hooks/*.sh ~/.claude/scripts/hooks/
- cp commands/*.md ~/.claude/commands/
- cp -r skill/ ~/.claude/skills/learned/memory-engine/
- ```
- **Step 3** — Create directories:
- ```bash
- mkdir -p ~/.claude/sessions/diary
- mkdir -p ~/.claude/scripts/hooks
- ```
- **Step 4** — Add hooks config to `~/.claude/settings.json`:
- <details>
- <summary><strong>Click to expand full config</strong></summary>
- ```json
- {
- "hooks": {
- "SessionStart": [
- {
- "matcher": "*",
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/session-start.js"
- }
- ]
- }
- ],
- "SessionEnd": [
- {
- "matcher": "*",
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/session-end.js"
- }
- ]
- }
- ],
- "UserPromptSubmit": [
- {
- "matcher": "*",
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/memory-sync.js"
- },
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/mid-session-checkpoint.js"
- }
- ]
- }
- ],
- "PreCompact": [
- {
- "matcher": "*",
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/pre-compact.js"
- }
- ]
- }
- ],
- "PreToolUse": [
- {
- "matcher": "Bash",
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/pre-push-check.js"
- }
- ]
- },
- {
- "matcher": "Write",
- "hooks": [
- {
- "type": "command",
- "command": "node ~/.claude/scripts/hooks/write-guard.js"
- }
- ]
- }
- ]
- }
- }
- ```
- </details>
- **Step 5** — Restart Claude Code. Done!
- ---
- ## :rocket: Quick Start
- Done installing? Here's what to do next.
- 1. **Just start working** — open Claude Code and go. `session-start` loads your last session's context automatically
- 2. **Just close when done** — `session-end` saves a summary if it fires; `mid-session-checkpoint` and `pre-compact` already have your back
- 3. **Want to remember something?** — `/save` stores it in long-term memory
- 4. **Switching windows?** — `/handoff` passes your progress to the next window
- 5. **After a few days** — `/reflect` reviews your notes, finds patterns, cleans up
- That's it. Everything else runs in the background.
- ---
- ## :zap: Token Impact
- Memory Engine adds almost no token overhead to your daily usage.
- | Hook | When it runs | Token cost |
- | :--- | :----------- | :--------- |
- | `session-start` | Once per conversation | ~200–500 tokens (loads last summary + project memory) |
- | `memory-sync` | Every message | **0** unless another session changed memory files |
- | `mid-session-checkpoint` | Every message | **0** unless it's the 20th message |
- | `write-guard` | Before file writes | **0** unless writing a sensitive file |
- | `pre-push-check` | Before git push | **0** unless pushing |
- | `session-end` / `pre-compact` | End of conversation / compression | Output not injected into context |
- **SKILL.md** (136 lines) is a learned skill — Claude Code only loads it when relevant, not every conversation.
- **Bottom line:** ~200–500 extra tokens at the start of each conversation. Everything else is zero unless triggered.
- ---
- ## :wrench: Customization
- | What | Where |
- | :--- | :---- |
- | Context map | Smart Context auto-resolves per-project memory directory (no config needed). Override in `session-start.js` |
- | Keywords | `correctionKeywords` in `shared-utils.js` |
- | Sensitive files | `PROTECTED_PATTERNS` in `write-guard.js` |
- | Retention | `MAX_SESSIONS` in `session-end.js` (default: 30) |
- ---
- ## :bulb: Design Philosophy
- **Why not a database?**
- - Markdown — you can open it, read it, edit it, git commit it
- - Claude Code already reads `.md` natively — why add complexity?
- **Why not a Plugin?**
- - Plugins are black boxes
- - Hooks + Commands are transparent — every `.js` file is right there to inspect
- - Don't like something? Change it. Think it's unnecessary? Delete it
- - Tools should be something you control, not something that controls you
- ---
- ## :pray: Credits
- > **All code was written from scratch. No code was copied, forked, or adapted from any source project.**
- | Project | What it inspired |
- | :--- | :--- |
- | [contextstream/claude-code](https://github.com/contextstream/claude-code) | Smart Context, auto-learning from mistakes |
- | [memvid/claude-brain](https://github.com/memvid/claude-brain) | Memory statistics, lightweight design |
- | [rlancemartin/claude-diary](https://github.com/rlancemartin/claude-diary) | Reflection diary, pattern analysis |
- ---
- <details>
- <summary><strong>Changelog</strong></summary>
- **v1.6 — Cross-Device Sync**
- - Added `memory-backup.sh` — bidirectional sync script with `push`, `pull`, and `sync` modes
- - `pull` mode distributes global memory files from the backup repo into every local project directory (newer file wins, won't overwrite local changes)
- - `push` mode auto-detects all project directories instead of hardcoding paths
- - `/sync` command updated: now runs pull + push in one step
- - `/recover` command updated: uses `memory-backup.sh pull` for automatic distribution
- - New troubleshooting entry: "Memory from another device not showing up"
- **v1.5.2 — Save System Rewrite**
- - Pitfall detection moved from `session-end` to `pre-compact` (runs before compression, catches more context)
- - Save system documented with three save points ranked by reliability
- - `reflect.md`, `反思.md`, `交接.md` generalized for public use
- - Correction Cycle FAQ added (EN + ZH, 3 questions each)
- - Design Philosophy converted to bullet-point format
- **v1.5.1 — Quick Reference**
- - Added `/overview` (`/全覽`) to command tables and SKILL.md
- - 36 bilingual command files (18 pairs EN + ZH)
- **v1.5 — Session Handoff + Shared Core**
- - Session Handoff — switch between Claude Code windows without losing context. `/handoff` saves a handoff file, the next session picks it up automatically
- - Correction Cycle — `/analyze` compares your edits against rules, logs mistakes, builds an error notebook that auto-reviews before each task
- - `shared-utils.js` — extracted shared functions from `session-end.js` and `pre-compact.js`, eliminating ~80% duplicated code
- - Smart Context now resolves the correct memory directory per-project automatically — no hardcoded paths
- - Backup scope expanded: hooks, engine skill, and all project memories included in `/backup` and `/sync`
- - 36 bilingual command files (EN + ZH), up from 28
- **v1.4 — The Real Safety Net**
- - PreCompact hook — saves snapshot before context compression (auto or manual)
- - Cross-device sync — GitHub memory repo works across machines, `/recover` on new device pulls everything back
- - Fires one step before compression — always has a save point, no matter how the conversation ends
- **v1.3 — The Student Loop**
- - 8-step learning cycle (first 3 automatic, last 5 via `/reflect`)
- - Mid-session checkpoints (every 20 messages)
- - `/reflect` 4-question decision tree
- - SessionEnd fixes (transcript parsing, IDE noise filtering, pitfall threshold raised to 5)
- **v1.2 — Full Command Suite**
- - 14 bilingual commands (daily ops / reflection / health checks / search & recovery)
- - Two-tier health checks (`/check` + `/full-check`)
- - Cross-project tasks, backup sync, disaster recovery, compression guide
- **v1.1 — Smart Context Auto-detect**
- - No manual config needed — auto-scans project memory directories
- - Chinese correction detection (13 Chinese keywords)
- - Pitfall records include solutions, session summaries revamped, weekly auto-digest
- </details>
- <details>
- <summary><strong>File structure</strong></summary>
- ```
- claude-memory-engine/
- hooks/
- session-start.js # New session -> load recall + smart-context + handoff
- session-end.js # Session end -> save summary + backup (best-effort)
- pre-compact.js # Context compression -> snapshot + pitfall detection + backup
- shared-utils.js # Shared functions (transcript, pitfall, backup)
- memory-sync.js # Every message -> cross-session memory sync + handoff
- write-guard.js # Before file write -> sensitive file warning
- pre-push-check.js # Before git push -> safety check
- mid-session-checkpoint.js # Every 20 messages -> checkpoint
- memory-backup.sh # Bidirectional sync (push/pull/sync) — v1.6
- commands/
- save.md / 存記憶.md # Save memory across sessions
- reload.md / 讀取.md # Load memory
- todo.md / 待辦.md # Cross-project tasks
- backup.md / 備份.md # Push to GitHub
- sync.md / 同步.md # Bidirectional sync
- diary.md / 回顧.md # Reflection diary
- reflect.md / 反思.md # Pattern analysis
- learn.md / 學習.md # Pitfall learning
- check.md / 健檢.md # Quick health check
- full-check.md / 大健檢.md # Full audit
- memory-health.md / 記憶健檢.md
- memory-search.md / 搜尋記憶.md
- recover.md / 想起來.md
- compact-guide.md / 壓縮建議.md
- handoff.md / 交接.md # Session handoff
- skill/
- SKILL.md
- references/
- smart-context.md
- auto-learn.md
- ```
- </details>
- ---
- ## Requirements
- - Claude Code (with hooks support)
- - Node.js 18+
- - Zero dependencies
- ## License
- MIT — see [LICENSE](LICENSE) for details.
- ---
- <p align="center">
- Made by <a href="https://ohruru.com">HelloRuru</a>
- </p>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.