mnemos — Claude Code skill: preserve memory across context compaction
mnemos — a skill that prevents data loss when the context window fills up and compacts. Structures working memory as a typed graph where goals and decisions persist, while less critical information compresses by policy.
MIT 134 installs ★ 713 updated 2026-10-13
npx skills add alinaqi/maggy --skill mnemos -a claude-codeWhat mnemos does
mnemos monitors four fatigue signals passively: context window fullness, directory scatter (when the agent bounces between folders), file re-reads (a sign of context loss), and error rate. As fatigue rises, the skill auto-triggers: it runs micro-consolidation to compress results, writes checkpoints to disk, and prepares emergency recovery before the context limit hits.
When Claude Code compacts the context, a three-layer defence kicks in. PreCompact hook writes preservation instructions and a marker to .mnemos/just-compacted. SessionStart hook—if it fires—immediately reloads the full checkpoint into the fresh context (the primary restore path). If SessionStart doesn't fire, the first tool call detects the marker and restores on its own.
Includes CLI commands for manual control: mnemos add goal, mnemos checkpoint --force, mnemos status. Can ingest Claude Code session transcripts and compute haziness for each session—a weighted score across five dimensions (correction density, edit redos, first-try error rate, orphan tool calls, git resets)—to show how tangled a coding session was.
What it helps with
- preserve goals and constraints when context window fills
- detect agent fatigue from token use, scope scatter, re-reads, and errors
- restore full checkpoint after context compaction fires
- measure how chaotic a coding session became
- checkpoint progress before handing off a task
Example prompts for the agent
- Create a GoalNode at the start:
mnemos add goal "Build a REST API for expense tracking" --task-id session-1 - Check fatigue before a long operation:
mnemos fatigue - After context compaction, checkpoint auto-restores with your goal and progress
How to install mnemos
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill mnemos -a claude-code2Manually: put the files in place
~/.claude/skills/mnemos/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/mnemos/
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill mnemos -a codex2Manually: put the files in place
.agents/skills/mnemos/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill mnemos -a cursor2Manually: put the files in place
.cursor/skills/mnemos/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install alinaqi/maggy skills/mnemos2Manually: put the files in place
.github/skills/mnemos/SKILL.md1Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill mnemos -a gemini-cli2Platform CLI
gemini skills install https://github.com/alinaqi/maggy --path skills/mnemosManually: put the files in place
.devin/skills/mnemos/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add alinaqi/maggy --skill mnemos -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about mnemos
How do I install mnemos in Claude Code?
Run npx skills add alinaqi/maggy --skill mnemos -a claude-code, then open ~/.claude/skills/mnemos/SKILL.md. For Cursor: npx skills add alinaqi/maggy --skill mnemos -a cursor; for GitHub Copilot: gh skill install alinaqi/maggy mnemos.
Why would I use mnemos?
When Claude Code compacts the context due to window overflow, the agent loses decisions and goals. mnemos stores them as typed nodes and restores them via the SessionStart hook after compaction, so the agent doesn't restart from scratch.
What is haziness and how do I see it?
Haziness scores how messy a coding session was across five dimensions: correction density, edit redos, first-try errors, orphan tool calls, and git resets. Run mnemos haze --recent 10 to see a table of recent sessions with scores ranging from clear to lost.
Source text
SKILL.md · MIT
--- name: mnemos description: Task-scoped memory lifecycle — typed MnemoGraph prevents lossy context compaction by treating facts/decisions/code-refs/handoffs as distinct node types with per-type eviction policies when-to-use: "When you need durable working memory across compactions — checkpoint decisions, preserve task handoffs, or audit what was remembered" user-invocable: false effort: high --- # Mnemos — Task-Scoped Memory Lifecycle ## What It Does Mnemos prevents lossy context compaction from destroying the structured knowledge you need most. It treats your working memory as a **typed graph** (MnemoGraph) where different types of knowledge have different eviction policies: - **GoalNodes** and **ConstraintNodes** are NEVER evicted — they survive all compaction - **ResultNodes** are compressed (summary kept) before eviction - **ContextNodes** are evictable when their activation weight drops - **CheckpointNodes** persist to disk for session resume ## Fatigue Model Mnemos monitors 4 dimensions of "agent fatigue" — all passively observed from hook data, no manual input needed: | Dimension | Weight | Signal Source | What It Measures | |-----------|--------|--------------|-----------------| | Token utilization | 0.40 | Statusline JSON | How full the context window is | | Scope scatter | 0.25 | PreToolUse file paths | How many directories the agent is bouncing between | | Re-read ratio | 0.20 | PreToolUse Read calls | How often the agent re-reads files it already read (context loss) | | Error density | 0.15 | PostToolUse outcomes | What fraction of tool calls are failing (agent struggling) | Fatigue states and actions: | State | Score | Action | |-------|-------|--------| | FLOW | 0.0–0.4 | Normal operation | | COMPRESS | 0.4–0.6 | Micro-consolidation runs (compress 3 ResultNodes, evict 1 cold ContextNode) | | PRE-SLEEP | 0.6–0.75 | Checkpoint written, consolidation runs | | REM | 0.75–0.9 | Emergency checkpoint, consider wrapping up | | EMERGENCY | 0.9+ | Checkpoint written, hand off immediately | ## How To Use ### Automatic (hooks handle everything): 1. **Statusline** writes `fatigue.json` on every API call 2. **PreToolUse** hook reads fatigue before every edit, auto-checkpoints at 0.60+ 3. **PreCompact** hook writes emergency checkpoint, compaction marker, and tells summarizer what to preserve 4. **SessionStart "compact"** fires immediately after compaction, re-injects full checkpoint (primary restore) 5. **SessionStart "startup|resume"** loads last checkpoint on new/resumed sessions 6. **PreToolUse fallback** (no matcher) detects compaction marker if SessionStart didn't fire 7. **Stop** hook writes final checkpoint for next session ### Post-Compaction Recovery (Three-Layer Defense): When Claude Code compacts the context (~83% full), Mnemos uses three layers: - **Layer 1 (PreCompact)**: Outputs strong preservation instructions with inline checkpoint content for the summarizer. Writes `.mnemos/just-compacted` marker. - **Layer 2 (SessionStart "compact")**: **PRIMARY re-injection.** Fires immediately when Claude resumes after compaction — before any agent action. Consumes the marker and injects the full checkpoint into the fresh context. This is the recommended approach per the RFC (Wake State Reconstruction). - **Layer 3 (PreToolUse fallback)**: If SessionStart doesn't fire (older versions, edge cases), the first tool call triggers `mnemos-post-compact-inject.sh` which detects the marker and injects. Safety net only. The result: after compaction, you'll see a "CONTEXT RESTORED AFTER COMPACTION" block with your goal, constraints, what you were working on, and progress. Resume from there. ### Manual CLI: ```bash mnemos init # Initialize .mnemos/ mnemos status # Show node counts + fatigue mnemos fatigue # Detailed fatigue breakdown mnemos checkpoint --force # Write checkpoint now mnemos resume # Output checkpoint for context mnemos consolidate # Run micro-consolidation mnemos nodes --type goal # List active GoalNodes mnemos add goal "Build auth" # Add a GoalNode mnemos bridge-icpg # Import iCPG ReasonNodes mnemos ingest-claude --all # Ingest Claude Code transcripts (see below) mnemos haze --recent 10 # Show per-session haziness scores ``` ## Claude Transcript Ingestion & Haziness Mnemos can ingest Claude Code session transcripts (the per-session JSONL under `~/.claude/projects/`) and score each session's **haziness** — a measure of how much the agent struggled. The `Stop` hook does this automatically on session exit; it is also available manually. **What's stored:** only structural fields (roles, tool names, file paths, error flags, timestamps) plus a **redacted, 200-char preview** of each turn. Full content is never persisted, and secrets (API keys, tokens, PEM blocks, JWTs, credentials) are redacted before anything touches disk. **Haziness** is a weighted score over five dimensions, each in `[0,1]`: | Dimension | Weight | What it measures | |-----------|--------|------------------| | correction_density | 0.30 | User corrections per eligible user turn | | redo_ratio | 0.25 | Edits re-touched after an error | | first_try_error_rate | 0.20 | Edits followed by errors within 3 turns | | orphan_tool_use_rate | 0.15 | Tool calls with no matching result | | backtrack_norm | 0.10 | `git revert`/`reset --hard`/`restore` calls | The composite maps to a band: `clear` < 0.25 ≤ `cloudy` < 0.50 ≤ `hazy` < 0.75 ≤ `lost`. ```bash mnemos ingest-claude --all # ingest every transcript + score mnemos ingest-claude --session <id> # one session by id mnemos ingest-claude --transcript <f> # a specific JSONL file mnemos haze --recent 10 # table of recent sessions mnemos haze --session <id> # per-dimension breakdown ``` Ingestion is idempotent (resumes via `last_line_offset`). **Opt out per project** with `touch .mnemos/claude-log.disabled`. ## Agent Instructions When working on a task: 1. **Create a GoalNode** at the start: `mnemos add goal "what you're trying to achieve" --task-id session-1` 2. **Add ConstraintNodes** for invariants: `mnemos add constraint "API backward compatibility" --scope src/api/` 3. **Check fatigue** before long operations: `mnemos fatigue` 4. **Checkpoint at sub-goal boundaries**: `mnemos checkpoint` 5. **On session resume**: the SessionStart hook automatically loads your checkpoint ## iCPG Integration Mnemos bridges with iCPG (Intent-Augmented Code Property Graph): - `mnemos bridge-icpg` imports active ReasonNodes as GoalNodes - Postconditions/invariants become ConstraintNodes - Checkpoint includes iCPG state (active intent, unresolved drift) ## Storage Everything lives in `.mnemos/` (gitignored): - `mnemo.db` — SQLite MnemoGraph - `fatigue.json` — Live token metrics (updated per API call by statusline) - `signals.jsonl` — Behavioral signal log (appended by PreToolUse + PostToolUse hooks) - `checkpoint-latest.json` — Most recent checkpoint - `checkpoints/` — Archived checkpoints
© alinaqi · MIT · alinaqi/maggy