mnemos

Mnemos — 任务级记忆生命周期

功能介绍

Mnemos 可防止有损上下文压缩破坏你最需要的结构化知识。它将工作记忆视为一个类型化图谱（MnemoGraph），不同类型的知识有不同的淘汰策略：

• GoalNodes 和 ConstraintNodes 永不淘汰——它们在所有压缩过程中都会保留
• ResultNodes 会在淘汰前进行压缩（保留摘要）
• ContextNodes 会在其激活权重下降时被淘汰
• CheckpointNodes 会持久化到磁盘，以便恢复会话

疲劳模型

Mnemos 会监控“Agent 疲劳”的 4 个维度——全部通过钩子数据被动观察，无需手动输入：

维度	权重	信号来源	衡量内容
Token 利用率	0.40	状态栏 JSON	上下文窗口的占用程度
范围分散度	0.25	PreToolUse 文件路径	Agent 在多少个目录之间来回切换
重读比率	0.20	PreToolUse Read 调用	Agent 重读已读文件的频率（上下文丢失）
错误密度	0.15	PostToolUse 结果	工具调用失败的比例（Agent 遇到困难的程度）

疲劳状态和操作：

状态	分数	操作
FLOW	0.0–0.4	正常运行
COMPRESS	0.4–0.6	执行微型整合（压缩 3 个 ResultNodes，淘汰 1 个低活跃度 ContextNode）
PRE-SLEEP	0.6–0.75	写入检查点，执行整合
REM	0.75–0.9	紧急写入检查点，考虑结束工作
EMERGENCY	0.9+	写入检查点，立即移交

使用方法

自动模式（钩子处理所有操作）：

1. Statusline 在每次 API 调用时写入 fatigue.json
2. PreToolUse 钩子在每次编辑前读取疲劳状态，并在达到 0.60+ 时自动写入检查点
3. PreCompact 钩子写入紧急检查点和压缩标记，并告知摘要器需要保留的内容
4. SessionStart "compact" 在压缩后立即触发，重新注入完整检查点（主要恢复方式）
5. SessionStart "startup|resume" 在新会话或恢复的会话中加载最近的检查点
6. PreToolUse fallback（无匹配器）在 SessionStart 未触发时检测压缩标记
7. Stop 钩子为下一个会话写入最终检查点

压缩后恢复（三层防护）：

当 Claude Code 压缩上下文（占用约 83%）时，Mnemos 会使用三层机制：

• 第 1 层（PreCompact）：向摘要器输出强制保留指令，并附上内联检查点内容。写入 .mnemos/just-compacted 标记。
• 第 2 层（SessionStart "compact"）：主要重新注入方式。 Claude 在压缩后恢复时立即触发——早于任何 Agent 操作。使用该标记，并将完整检查点注入新的上下文。这是 RFC（唤醒状态重建）推荐的方式。
• 第 3 层（PreToolUse fallback）：如果 SessionStart 未触发（旧版本、边缘情况），第一次工具调用会触发 mnemos-post-compact-inject.sh，检测标记并注入。仅作为安全网。

结果：压缩后，你会看到一个“压缩后恢复的上下文”区块，其中包含你的目标、约束、正在处理的内容和进度。可从那里继续。

手动 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 scores

Claude 对话记录摄取与模糊度

Mnemos 可以摄取 Claude Code 会话对话记录（位于 ~/.claude/projects/ 下的每个会话 JSONL 文件），并评估每个会话的模糊度——衡量 Agent 遇到多少困难。会话退出时，Stop hook 会自动执行此操作；也可手动执行。

存储内容：仅包含结构字段（角色、工具名称、文件路径、错误标记、时间戳），以及每轮对话的脱敏 200 字符预览。绝不会持久化完整内容；在任何内容写入磁盘之前，都会先对机密信息（API 密钥、令牌、PEM 块、JWT、凭据）进行脱敏。

模糊度是由五个维度加权得出的分数，每个维度的取值范围为 [0,1]：

维度	权重	衡量内容
correction_density	0.30	每个符合条件的用户轮次中的用户纠正次数
redo_ratio	0.25	出错后再次修改的比例
first_try_error_rate	0.20	修改后 3 轮内出现错误的比例
orphan_tool_use_rate	0.15	没有匹配结果的工具调用比例
backtrack_norm	0.10	git revert/reset --hard/restore 调用

综合分数对应一个等级：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 breakdown

摄取操作具有幂等性（通过 last_line_offset 恢复）。如需按项目选择退出，请执行 touch .mnemos/claude-log.disabled。

Agent 指令

处理任务时：

1. 开始时创建一个 GoalNode：mnemos add goal "what you're trying to achieve" --task-id session-1
2. 为不变量添加 ConstraintNodes：mnemos add constraint "API backward compatibility" --scope src/api/
3. 长时间操作前检查疲劳度：mnemos fatigue
4. 在子目标边界处创建检查点：mnemos checkpoint
5. 恢复会话时：SessionStart hook 会自动加载你的检查点

iCPG 集成

Mnemos 可与 iCPG（意图增强型代码属性图）对接：

• mnemos bridge-icpg 会将活跃的 ReasonNodes 导入为 GoalNodes
• 后置条件/不变量会成为 ConstraintNodes
• 检查点包含 iCPG 状态（活跃意图、未解决的偏移）

存储

所有内容都保存在 .mnemos/ 中（已加入 gitignore）：

• mnemo.db — SQLite MnemoGraph
• fatigue.json — 实时令牌指标（由状态行按每次 API 调用更新）
• signals.jsonl — 行为信号日志（由 PreToolUse 和 PostToolUse hooks 追加）
• checkpoint-latest.json — 最近的检查点
• checkpoints/ — 已归档的检查点