Agent skill

Memory Engine

by HelloRuru in HelloRuru/claude-memory-engine

Memory management system for Claude Code — Student Loop, Smart Context, Auto Learn, Session Handoff, Correction Cycle.

MITAuto-check passedAgent Workflows

Install Memory Engine

skills CLI
$ npx skills add HelloRuru/claude-memory-engine --skill memory-engine -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install HelloRuru/claude-memory-engine memory-engine --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/HelloRuru/claude-memory-engine.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skill .claude/skills/memory-engine && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
memory-engine
GitHub stars
134
Token cost
~1.9k tokens
SKILL.md length
804 words
Files
3 (incl. references)
Skills in repo
1
Repo updated
First seen
Licence
MIT

At a glance

Memory management system for Claude Code — Student Loop, Smart Context, Auto Learn, Session Handoff, Correction Cycle.

  • Works in 5 steps: Smart Context → Auto Learn (Pitfall Detection) → Student Loop (/reflect) → …
  • Tasks that involve Session handoff
  • SKILL.md covers Modules, Hooks, Commands (36 files, 18 pairs… and File Structure, plus 3 more sections
  • Calls git

What it does

Memory Engine is an agent skill from HelloRuru/claude-memory-engine. 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.

Its SKILL.md is about 1.9k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including reference files (for example `references/auto-learn.md` and `references/smart-context.md`).

It sits in Agent Workflows, covering Session handoff and Agent memory. The repository describes itself as: Claude Code 的記憶系統 | A memory system built with hooks + markdown. Zero dependencies. The licence is MIT.

When your agent uses it

  • Tasks that involve Session handoff
  • Tasks that involve Agent memory

Example prompts

  • “/memory-engine”

Workflow steps

5 steps, taken from the step headings in SKILL.md.

  1. Smart Context
  2. Auto Learn (Pitfall Detection)
  3. Student Loop (/reflect)
  4. Session Handoff (/handoff)
  5. Correction Cycle (/analyze)

What it can do on your machine

Read from SKILL.md and the folder at commit 04f085c. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Memory Engine loads about 1.9k tokens when it runs, and up to ~2.4k if it reads all its reference files. Until then it costs about 65 tokens; SKILL.md has 804 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~65
When it runs · the whole SKILL.md, loaded when a task matches
~1.9k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~2.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from HelloRuru/claude-memory-engine at commit 04f085c, republished under its MIT licence (© HelloRuru). 804 words, ~1,910 tokens.

Download SKILL.mdSave it as .claude/skills/memory-engine/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
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

HookFileWhat it does
SessionStartsession-start.jsLoad last summary + project memory + pending handoffs + pitfall review + /reflect reminder
SessionEndsession-end.jsSave summary + project index + backup (best-effort, may not fire)
PreCompactpre-compact.jsSnapshot + pitfall detection + backup — the real safety net
UserPromptSubmitmemory-sync.jsCross-session memory change detection + handoff detection
UserPromptSubmitmid-session-checkpoint.jsCheckpoint every 20 messages
PreToolUse(Write)write-guard.jsSensitive file write warning
PreToolUse(Bash)pre-push-check.jsSafety check before git push
—memory-backup.shBidirectional 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)

ENZHFunction
/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
Show full SKILL.md (256 more words)Show less

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

© HelloRuru, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (references) in skill of HelloRuru/claude-memory-engine.

  • SKILL.md
  • references/auto-learn.md
  • references/smart-context.md

Open the folder on GitHubat commit 04f085c

Compare with similar skills

Memory Engine next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Memory Engine compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Memory Engine this skillHelloRuru/claude-memory-engine134—~1.9kAutomated safety check: PassMIT
Beads Task Memorygastownhall/beads28k—~1.2kAutomated safety check: PassMIT
Session History Searchslopus/happy24k—~3.1kAutomated safety check: PassMIT
Memori Long-Term MemoryMemoriLabs/Memori17k—~2kAutomated safety check: NotesCustom licence
Coding Agent Session Findercode-yeongyu/oh-my-openagent70k—~2.8kAutomated safety check: PassCustom licence
Deja History Searchvshulcz/deja-vu1.1k1 repos~1.3kAutomated safety check: PassMIT

Similar skills

  • Beads Task Memory

    gastownhall/beads

    Tracks multi-session work with dependencies in the bd issue tracker so the agent can find ready tasks and recover its context after conversation compaction.

    28k GitHub stars~1.2k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Searches past Claude Code, Codex and Cursor sessions and summarizes what was worked on, tried or decided, using extraction scripts instead of reading raw logs.

    24k GitHub stars~3.1k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Memori Long-Term Memory

    MemoriLabs/Memori

    Connects Claude Code to Memori Cloud for long-term memory, recalling stored context before substantive replies and saving new context afterward.

    17k GitHub stars~2k tokensUpdated 4 days ago
    Agent WorkflowsAuto-check: notes
  • Coding Agent Session Finder

    code-yeongyu/oh-my-openagent

    Finds, reads and reconstructs past coding-agent sessions across Codex, Claude, OpenCode, Senpi and many other local agent logs.

    70k GitHub stars~2.8k tokensUpdated today
    Agent WorkflowsAuto-check passed
  • Deja History Search

    vshulcz/deja-vu

    Searches this machine's own history of past AI coding sessions across every tool used on it, before work is redone or something is denied.

    1.1k GitHub starsUsed in 1 repo~1.3k tokens
    Agent WorkflowsAuto-check passed
  • Memori MCP Memory Usage

    MemoriLabs/Memori

    Teaches an MCP-connected agent when and how to call Memori's recall, summary, compaction, augmentation, feedback and quota tools to keep context across sessions.

    17k GitHub stars~3.8k tokensUpdated 4 days ago
    Agent WorkflowsAuto-check passed

Categories

Questions about Memory Engine

What does Memory Engine do?

Memory management system for Claude Code — Student Loop, Smart Context, Auto Learn, Session Handoff, Correction Cycle. Memory Engine is an agent skill from HelloRuru/claude-memory-engine. Memory management system for Claude Code — Student Loop, Smart Context, Auto Learn, Session Handoff, Correction Cycle.

When should I use Memory Engine?

Memory Engine fits situations like: tasks that involve Session handoff; tasks that involve Agent memory.

How do I install Memory Engine in Claude Code?

Run `npx skills add HelloRuru/claude-memory-engine --skill memory-engine -a claude-code`. Or copy the skill folder (skill in HelloRuru/claude-memory-engine) into .claude/skills/memory-engine in your project. Claude Code loads it when a task matches its description.

How do I install Memory Engine in Codex?

Run `npx skills add HelloRuru/claude-memory-engine --skill memory-engine -a codex`. Or copy the skill folder (skill in HelloRuru/claude-memory-engine) into .agents/skills/memory-engine in your project. Codex loads it when a task matches its description.

Can I use Memory Engine in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add HelloRuru/claude-memory-engine --skill memory-engine -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/memory-engine, .gemini/skills/memory-engine, .github/skills/memory-engine and .opencode/skills/memory-engine in your project.

What does Memory Engine need to run?

Going by SKILL.md and its folder, Memory Engine needs the command-line tools its instructions call (git).

Does Memory Engine access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Memory Engine safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Memory Engine use?

Memory Engine is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Memory Engine use?

About 1.9k tokens (SKILL.md is roughly 7.6k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 503 tokens, read only when the agent opens those files.

What are the alternatives to Memory Engine?

Skills that share tags, products or a category with Memory Engine: Beads Task Memory (gastownhall/beads, 28k stars), Session History Search (slopus/happy, 24k stars), Memori Long-Term Memory (MemoriLabs/Memori, 17k stars) and Coding Agent Session Finder (code-yeongyu/oh-my-openagent, 70k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Memory Engine?

HelloRuru (a GitHub user) maintains it in HelloRuru/claude-memory-engine, which has 134 GitHub stars. The repository was last updated on May 11, 2026.

Source: HelloRuru/claude-memory-engine on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.