Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add alinaqi/maggy --skill mnemos -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/mnemos/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/mnemos/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set61

The whole set →
shopify-apps shopify-apps guides Shopify app work with Remix, the Admin GraphQL API, and checkout extensions. Use it when building an app or extension for a Shopify store. CX Codex +1 273installs azure-cosmosdb Skill for Azure Cosmos DB work: partition key selection, consistency levels, change feed, and SDK patterns with TypeScript examples. Adds CRUD templates, hierarchical keys, and cross-partition query patterns to your IDE. CX Codex +1 269installs workspace Discovers workspace topology across multi-repo and monorepo setups, tracking API contracts and shared types for coding agents. CX Codex +1 198installs cpg-analysis cpg-analysis uses Joern CPG and CodeQL to inspect control flow, data flow, and taint paths. Built for deep refactoring work and security audits. CX Codex +1 175installs icpg icpg — a skill that tracks WHY code exists via a reason graph (ReasonNodes) backed by Design by Contract. Helps agents avoid duplicate work, understand code constraints, and detect when symbols drift from their original purpose. CX Codex +1 156installs maggy maggy is a Claude Code skill that brings GitHub Issues and Asana tickets into one inbox, starts a TDD run from a ticket, and prepares a daily competitor briefing. CX Codex +1 131installs cross-agent-delegation cross-agent-delegation routes coding tasks across Claude, Kimi, and Codex using iCPG graph complexity metrics and Mnemos checkpoints. CX Codex +1 122installs polyphony polyphony gives every AI agent a separate Docker container and git branch, so parallel agents never step on each other's files. CX Codex +1 116installs

Project sponsors

Companies that keep this analytics open