memory-engine

A memory system for Claude Code that stores project context, session notes, learned mistakes, and handoff information in Markdown files. Hooks are automatic actions triggered by events such as a session starting or ending.

In plain words
What is it for?
It is for loading project memory, saving work and decisions, detecting repeated pitfalls, reflecting on sessions, handing work to a later session, and checking memory-related status.
Why use it?
It reduces the need to repeat project context and records corrections or recurring problems for later sessions.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/helloruru/claude-memory-engine/skill
Any agent
npx skills add HelloRuru/claude-memory-engine --skill skill
Clone the repo
git clone --depth 1 https://github.com/HelloRuru/claude-memory-engine

Made for: Claude Code, Codex.

Per session 55 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 1,891 The whole file, excluding the scripts and references it only reads on demand.
Security scan B 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00055 $0.01891
Opus 5 $0.00028 $0.00945
Sonnet 5 $0.00011 $0.00378
Haiku 4.5 $0.00006 $0.00189

Measured 2d ago against content hash 60c81523347b, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade B, and why

memory-engine scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 2d ago.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Unrestricted tool accessmediumExcessive agency

A wildcard tool grant or "run any command" leaves no least-privilege boundary at all.

You don't need to remember to run any command before closing.
skill/SKILL.md · 172 lines

How it starts

The opening of the file, as written. The whole thing — 172 lines — stays where its author put it; the contents beside it link to each section on GitHub.

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.jsdetectPitfalls() + 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

Read the full file on GitHub · 172 lines

Files

What ships with it

2 files beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. 2d ago First seen · 172 lines · 55 tokens per session scan B 60c81523347b

Subscribe to this mod's changes

memory-engine is a skill published in the GitHub repository HelloRuru/claude-memory-engine (133 stars, last pushed 3mo ago), licensed MIT. It adds 55 tokens to every session and 1,891 once invoked, about $0.0003 per session on Opus 5. A static security scan graded it B with 1 finding (unrestricted tool access). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.