Mnemonics

Multi-agent memory coordination for Claude Code. Mnemonics connects Claude Code sessions to a Reminisce memory server via hooks and an MCP tool server — giving every session persistent memory, cross-session context, and automatic handoffs when context fills up.

What It Does

| Hook | When | What | |------|------|------| | UserPromptSubmit | Session start | Registers agent, injects pending handoffs + periodic memory refresh | | PostToolUse (heartbeat) | Every tool call | Keeps agent visible to peers | | PostToolUse (observe) | File edits | Extracts facts → stores memory traces | | PostToolUse (guard) | Bash errors | Detects recurring error patterns, warns Claude before retry #3 | | Stop | Session end | Posts session summary to Reminisce (Ollama-enriched if configured) | | statusLine | Continuous | Shows context % + agent status; triggers handoff at 70% fill |

MCP tools available to Claude:

| Tool | Purpose | |------|---------| | recall_agent_reflect | Surface relevant memories before starting a task | | recall_agent_coordinate | Claim work domains, observe project state, package handoffs | | recall_memorize | Explicitly store a key decision or fact mid-session |

Install

npm install -g mnemonics-mcp

Then run the setup wizard (no terminal required — uses Claude Code's native UI):

/mnemonics-setup

Or from the terminal binary:

node $(npm root -g)/mnemonics-mcp/bin/mnemonics-setup.js

Requires: Reminisce running somewhere accessible.

How It Works

Session Start

On the first prompt of every session, the register hook:

1. Calls Reminisce to register (or resume) the agent
2. Injects agent ID, spawn count, success rate, and model recommendation into Claude's context
3. Surfaces any pending handoffs from previous sessions (full task context, not truncated)
4. Checks for error pattern warnings queued by the guard hook
5. If ≥4 hours since last refresh, queries Reminisce for recent project memories and injects them

Context Handoff (Long Sessions)

When the context window crosses 70% (configurable via MNEMONICS_HANDOFF_THRESHOLD):

1. The statusline fires mnemonics-handoff.js as a detached one-shot background process
2. If Ollama is configured, generates a 3-5 sentence technical summary of the session
3. Stores a handoff memory in Reminisce tagged ["handoff", agent_type, project, tenant, "unconsumed"]
4. The next session picks this up on startup and injects the full summary — seamless continuity across compactions and restarts
5. Once surfaced, the handoff memory is deleted so it doesn't repeat

Error Guard

When the same error fingerprint appears 3+ times (Bash tool), the guard hook:

1. Stores an anti-pattern memory in Reminisce (importance 0.85)
2. Queues a warning that appears at the start of Claude's next turn
3. Prompt: "Recurring error (×3): <signature> — investigate root cause before retrying"

Conversation Capture

High-signal user messages (containing phrases like "remember", "root cause", "we decided", "the fix is", etc.) are automatically stored to Reminisce as semantic memories.

For explicit storage mid-session, Claude can call recall_memorize.

Configuration

All configuration is written to ~/.claude/settings.json (hooks + env) and ~/.claude.json (MCP server).

Environment Variables

| Variable | Default | Purpose | |----------|---------|---------| | REMINISCE_HOST | — | Required. Reminisce base URL, e.g. http://localhost:8300 | | REMINISCE_API_KEY | "" | API key if Reminisce requires auth | | MNEMONICS_AGENT_TYPE | executor | Agent role — see Agent Types below | | MNEMONICS_TENANT | default | Tenant namespace for isolating agent groups | | MNEMONICS_PROJECT | CWD basename | Project identifier | | MNEMONICS_REFRESH_INTERVAL_HOURS | 4 | Hours between periodic memory refreshes | | MNEMONICS_HANDOFF_THRESHOLD | 70 | Context % that triggers auto-handoff | | MNEMONICS_OLLAMA_HOST | — | Ollama base URL (enables AI-enriched summaries) | | MNEMONICS_OLLAMA_MODEL | qwen3:14b | Ollama model for summaries | | MNEMONICS_GUARD_THRESHOLD | 3 | Repeated errors before guard warning fires |

Agent Types

| Type | Purpose | |------|---------| | executor | Implements tasks — write code, run commands, fix bugs (default) | | conductor | Orchestrates other agents — plans, delegates, coordinates | | specialist | Domain expert — deep focus on a specific area | | ui_architect | Designs UI/UX architecture, component systems, and design patterns | | ui_engineer | Implements UI components, wires data, builds features | | stylist | CSS, Tailwind, theming, design token implementation | | ux_reviewer | Reviews UI/UX for usability, accessibility, and design compliance | | design_system | Maintains and evolves design system components and standards |

UI agent types (ui_architect, ui_engineer, stylist, ux_reviewer, design_system) automatically receive a shared design language standard in their system prompts — dark-first, data-dense, technically precise visual DNA applied consistently across all UI-focused sessions.

Skills

After setup, these slash commands are available in Claude Code:

| Skill | Purpose | |-------|---------| | /mnemonics-setup | Run or re-run the setup wizard | | /mnemonics-status | Show current agent registration and recent memories |

Architecture

Claude Code session
├── UserPromptSubmit hook  ─→  mnemonics-register.js
│     ├── Registers agent with Reminisce
│     ├── Injects handoffs + memory refresh
│     └── Captures high-signal prompts
│
├── PostToolUse hooks (async)
│     ├── mnemonics-heartbeat.js  ─→  keeps agent visible
│     ├── mnemonics-observe.js    ─→  file edits → memory traces
│     └── mnemonics-guard.js      ─→  error pattern detection
│
├── Stop hook
│     └── mnemonics-stop.js  ─→  session summary → Reminisce
│
├── statusLine
│     └── mnemonics-statusline.js
│           ├── Shows: context bar · model · cost · agent icon
│           └── At 70% context: spawns mnemonics-handoff.js (detached)
│
└── MCP server  (mnemonics-mcp.js)
      ├── recall_agent_reflect
      ├── recall_agent_coordinate
      └── recall_memorize

Temp files (per session, in OS tmpdir)

| File | Written by | Read by | |------|-----------|---------| | mnemonics-{sessionId}.json | register | heartbeat, statusline, stop, handoff | | mnemonics-activity-{sessionId}.json | observe | stop, handoff | | mnemonics-errors-{sessionId}.json | guard | guard | | mnemonics-pending-{sessionId}.json | guard | register | | mnemonics-handoff-triggered-{sessionId}.json | statusline | statusline (guard) |

All temp files are cleaned up by the Stop hook on session end.

Requirements

• Node.js ≥ 18
• Claude Code with hooks support
• Reminisce server (see System-Recall)
• Ollama (optional, for AI-enriched summaries)