memory-plugin
Hermes-style bounded, curated persistent memory for Claude Code.
Two files persist across sessions and are injected into context at session start:
File (~/.claude/memory-plugin/) | Purpose | Limit |
|---|
MEMORY.md | Agent notes — environment, conventions, completed work | 2,200 chars |
USER.md | User profile — preferences, style, habits | 1,375 chars |
How it maps to Claude Code
| Hermes feature | Here |
|---|
| Inject memory at session start (frozen snapshot) | SessionStart hook → additionalContext (scripts/inject-memory.mjs) |
memory tool: add / replace / remove | MCP server mcp/memory-server.mjs → memory_add / memory_replace / memory_remove (+ memory_list) |
| Char limits + "memory full" error | Enforced in the MCP server |
| Substring matching for replace/remove | matchOne() — short unique substring, errors if ambiguous |
| Duplicate prevention | Exact-match no-op on add |
| Security scanning | lib/security.mjs — injection/exfil/backdoor patterns + invisible Unicode |
| Background self-improvement review (memory only) | Stop hook → detached claude -p review (scripts/review.mjs, opt-in) |
| Correction detector | UserPromptSubmit hook → regex (lib/correction.mjs, scripts/detect-correction.mjs) |
| Skill capture (procedural memory) | Always-on policy injected at session start — agent writes SKILL.md inline |
The model decides what to save via skills/memory/SKILL.md; the server enforces how.
Three learning loops
Modeled on the real pi-hermes-memory
implementation (which splits learning into separate loops on purpose):
- Background review (memory) —
Stop hook fires a detached claude -p that mines
the finished turn for durable facts/preferences/corrections and saves them via the
memory tools. It is explicitly forbidden from writing skills — a stale subprocess
with only a transcript snapshot would author bad procedures. Opt-in (token cost).
- Correction detector —
UserPromptSubmit hook runs a free, two-pass regex over each
prompt (strong patterns always fire; weak patterns need a following directive word;
negative patterns suppress). On a hit it nudges the agent to persist the lesson before
answering. Detection is pure regex — no LLM call.
- Skill capture (procedural) — done inline by the main agent, never in a subprocess.
The session-start policy tells it to write a structured
SKILL.md
(## When to Use / ## Procedure / ## Pitfalls / ## Verification) to ~/.claude/skills/
(portable) or .claude/skills/ (repo-specific) the moment it finishes a complex,
reusable workflow — while it still has full context. Claude Code's native skill
discovery then handles progressive disclosure.
The Curator (skill lifecycle)
Ports Hermes' active → stale (30d) → archived (90d) aging so captured skills don't
pile up forever.
- Use signal — a
PostToolUse hook on the Skill tool records real invocations
into a .last-used sidecar (scripts/track-skill-use.mjs). "Last used" is
max(.last-used, SKILL.md mtime, dir mtime), so a skill that's invoked but never
edited isn't falsely aged out, and a fresh skill is never stale.
- Weekly sweep — a
SessionStart hook (scripts/curate.mjs) throttled to once per
7 days via a sentinel. Approximates Hermes' "every 7 days after idle" without a daemon.
- Safety — notify-only by default: it reports stale/archivable skills in the
session context and only moves files when
MEMORY_CURATOR_ARCHIVE=1. pinned: true
in frontmatter is never touched. Archiving moves (never deletes) into
~/.claude/skills/.archive/ and is fully reversible.
Install (as a Claude Code plugin)
This repo is also a single-plugin marketplace (.claude-plugin/marketplace.json),
so installation is two slash commands inside Claude Code. There is no build or
npm install step — the MCP server is zero-dependency.
/plugin marketplace add alexanderop/claude-code-memory
/plugin install memory@memory
marketplace add <owner>/<repo> registers this GitHub repo as a marketplace.install <plugin>@<marketplace> — both are named memory here (plugin name
memory, marketplace name memory).
Claude Code copies the plugin into ~/.claude/plugins/cache and resolves
${CLAUDE_PLUGIN_ROOT} automatically, so the bundled MCP server and hooks just
work. They activate on the next turn — run /reload-plugins to pick them up
without restarting. Verify with /plugin (shows memory enabled) and /mcp
(shows the memory server with its memory_* tools).
Non-interactive / team install
Declare it in .claude/settings.json (project) or ~/.claude/settings.json (global):
