mnemos（mnemos 命令行）

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:

Fatigue states and actions:

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. Post-Compaction Injection (PreToolUse, no matcher) detects the compaction marker on the first tool call after compaction and re-injects the full checkpoint into context
5. SessionStart hook loads last checkpoint on new session resume

Post-Compaction Recovery (Two-Layer Defense):

When Claude Code compacts the context (~83% full), Mnemos uses two layers:

• Layer 1: PreCompact outputs strong preservation instructions with inline checkpoint content for the summarizer
• Layer 2: After compaction, the first tool call triggers mnemos-post-compact-inject.sh which detects the .mnemos/just-compacted marker and re-injects the full checkpoint. This is the guaranteed path — it doesn't depend on the summarizer.

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

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