Mnemos
- 96 installs
- 706 repo stars
- Updated July 14, 2026
- alinaqi/claude-bootstrap
mnemos is a Claude skill that gives agents a typed working-memory graph so goals, constraints, and decisions survive context compaction.
About
mnemos is a task-scoped memory lifecycle that prevents lossy context compaction from destroying the knowledge an agent needs. It stores working memory as a typed graph where goals and constraints are never evicted, results are compressed before eviction, and checkpoints persist to disk for session resume. It monitors agent fatigue and auto-checkpoints before compaction, then re-injects the checkpoint afterward. A developer uses it to preserve decisions and task handoffs across compactions.
- Prevents lossy context compaction with a typed MnemoGraph memory model
- Keeps goals and constraints while compressing or evicting other node types
- Monitors agent fatigue and auto-checkpoints before compaction
Mnemos by the numbers
- 96 all-time installs (skills.sh)
- Ranked #4,561 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
mnemos capabilities & compatibility
- Capabilities
- memory · token optimization
- Use cases
- memory · token optimization
- Pricing
- Free
What mnemos says it does
Mnemos prevents lossy context compaction from destroying the structured knowledge you need most.
**GoalNodes** and **ConstraintNodes** are NEVER evicted — they survive all compaction
**PreToolUse** hook reads fatigue before every edit, auto-checkpoints at 0.60+
npx skills add https://github.com/alinaqi/claude-bootstrap --skill mnemosAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 96 |
|---|---|
| repo stars | ★ 706 |
| Last updated | July 14, 2026 |
| Repository | alinaqi/claude-bootstrap ↗ |
What it does
Checkpoint an agent's goals, constraints, and decisions so they survive context compaction and session resume.
Who is it for?
Preserving durable agent working memory, checkpoints, and handoffs across context compaction
Skip if: Long-term project knowledge bases, since it is task-scoped memory tied to a session lifecycle
When should I use this skill?
You need durable working memory across compactions, to checkpoint decisions or preserve handoffs
What you get
A restored context block after compaction with the goal, constraints, and progress preserved
- persisted checkpoints
- a restored context block after compaction
By the numbers
- Fatigue model over 4 dimensions
- Haziness score over 5 dimensions
- Five node types with distinct eviction policies
Files
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-compactedmarker. - 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.shwhich 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:
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 scoresClaude 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.
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 breakdownIngestion 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-icpgimports 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 MnemoGraphfatigue.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 checkpointcheckpoints/— Archived checkpoints
Related skills
Setup Matt Pocock SkillsScaffold the per-repo configuration that Matt Pocock’s engineering agent skills rely on so they understand the issue tracker, triage labels, and domain documentation la495k196k
Lark AppsConnect Claude, Cursor or custom agents directly to Lark (Feishu) for messaging, document automation, approval workflows and enterprise data access.402k
CavemanSlash token usage by roughly 75% while keeping every technical detail intact when working with Claude Code, Cursor or similar agents.391k94.7k
Lark Skill MakerQuickly turn any Lark/Feishu OpenAPI call or multi-step workflow into a reusable agent skill with its own SKILL.md.386k16k
Running Claude Code Via Litellm CopilotRun Claude Code at a fraction of the cost by routing requests through LiteLLM to the GitHub Copilot Chat API.270k72
Codex PetGenerate a complete Codex Pet spritesheet and metadata from one reference image without needing an OpenAI key or Codex Pro.246k10FAQ
What survives compaction?
GoalNodes and ConstraintNodes are never evicted, ResultNodes are compressed before eviction, and CheckpointNodes persist to disk for resume.
Is checkpointing automatic?
Yes. Hooks monitor agent fatigue and auto-checkpoint at a 0.60+ score, then re-inject the checkpoint after compaction.