memory-plugin

Hermes-style bounded, curated persistent memory for Claude Code.

Two files persist across sessions and are injected into context at session start:

How it maps to Claude Code

The model decides what to save via skills/memory/SKILL.md; the server enforces how.

Related MCP server: Mnemonic

Three learning loops

Modeled on the real pi-hermes-memory implementation (which splits learning into separate loops on purpose):

1. 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).

2. 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.

3. 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):

{
  "extraKnownMarketplaces": {
    "memory": { "source": { "source": "github", "repo": "alexanderop/claude-code-memory" } }
  },
  "enabledPlugins": { "memory@memory": true }
}

Local development

Point the marketplace at a local checkout instead of GitHub:

/plugin marketplace add ~/Projects/memory-plugin
/plugin install memory@memory

Background review (optional)

Off by default — it spawns a headless claude -p after each turn and costs tokens. Enable by exporting MEMORY_REVIEW_ENABLED=1 in the environment Claude Code runs in. It is recursion-guarded (MEMORY_REVIEW=1 on the child) and never blocks the turn.

Config (env vars)

Testing

Layered by cost, zero dev dependencies (plain Node — no Bun, no npm install):

npm test                 # unit + integration — zero token, ~1s, run on every edit
npm run test:unit        # manifests, skill frontmatter, and the store/security/correction/curator modules
npm run test:integration # version consistency, hook wiring, MCP path, markdown links, real MCP stdio round-trip
npm run test:e2e         # model-backed: loads the plugin via `claude --plugin-dir` (~$0.01, needs auth)

The unit suite exercises the real logic modules against temp dirs (never your ~/.claude); the integration suite spawns the actual MCP server and drives it over JSON-RPC. See docs/testing-strategy.md for the full layout and CI policy.

Not included (vs Hermes)

• Write-approval gating — add a PreToolUse hook matching mcp__memory__memory_* that returns {"permissionDecision":"ask"} (or stages to a pending file).

• Session search — Claude Code already ships a conversation-search skill over ~/.claude/projects/*/*.jsonl; no FTS5 server needed.