# https://github.com/draca-glitch/Mnemos 项目说明书

生成时间：2026-07-07 22:26:52 UTC

## 目录

- [系统总览与架构](#page-1)
- [检索流水线与存储后端](#page-2)
- [Nyx 整合循环与 NLI 决策层](#page-3)
- [运维、自检与故障排查](#page-4)

<a id='page-1'></a>

## 系统总览与架构

### 相关页面

相关主题：[检索流水线与存储后端](#page-2), [Nyx 整合循环与 NLI 决策层](#page-3), [运维、自检与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/draca-glitch/Mnemos/blob/main/README.md)
- [mnemos/__init__.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/__init__.py)
- [mnemos/mcp_server.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/mcp_server.py)
- [mnemos/cli.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/cli.py)
- [mnemos/constants.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/constants.py)
- [mnemos/nyx.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/nyx.py)
- [mnemos/doctor.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/doctor.py)
- [mnemos/schema.sql](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/schema.sql)
- [docs/ARCHITECTURE.md](https://github.com/draca-glitch/Mnemos/blob/main/docs/ARCHITECTURE.md)
</details>

# 系统总览与架构

Mnemos 是一个面向 LLM 代理的持久化记忆存储与整合系统，向调用方暴露 MCP 工具接口，并通过 CLI 提供运维与自检能力。其核心职责是：在保持内容保真度的前提下，对记忆进行写入、检索、合并、归档与重组，同时通过结构化的夜间整合循环防止存储漂移。

## 设计目标与边界

系统的产品定位决定了若干不可妥协的约束：

- **保真度优先**：已存储记忆的内容被视为成品，重写（generation against stored content）被视为反模式。v10.20.0 移除了 Cemelify（Phase 0.5）阶段，正是因为"在弱模型上漂移了精确字符串"且"在所有已知部署上默认禁用"。
- **零 LLM 的日间循环**：v10.17.0 起，Nyx 的日常周期（余弦提名 → NLI 决策 → 机械合并）默认不调用 LLM；LLM 仅作为可选的富集层（weave、synthesize、contradiction judging）出现。
- **命名空间隔离**：Nyx 以命名空间为作用域，跨命名空间的写入与合并不会相互干扰（v10.20.0）。
- **可审计、可自检**：`doctor` 子命令提供内容/向量一致性、空存储检测等多维校验（v10.19.0、v10.23.0）。

资料来源：[docs/ARCHITECTURE.md:1-80]()、[README.md:1-120]()。

## 模块划分与职责

系统主要由以下几个层次构成：

| 层次 | 组件 | 职责 |
|------|------|------|
| 接口层 | `mcp_server.py` | 暴露 MCP 工具，供宿主 LLM 代理调用 |
| 运维层 | `cli.py`、`doctor.py` | 提供 `doctor`、`nyx` 等运维子命令与一致性自检 |
| 核心引擎 | `nyx.py` | 实现整合循环的各阶段（候选提名 → NLI 决策 → 合并执行） |
| 嵌入层 | FastEmbed / ONNX backend | 生成与校验 tier-2 向量，支持 ONNX 轻量化后端（v10.16.0） |
| 决策层 | NLI 模型 | 替代原 cross-encoder，判断蕴含/矛盾/中性（v10.15.0） |
| 持久层 | `schema.sql` | SQLite 表结构，含 `embed_meta`、`archive` 等关键表 |

`embed_meta` 表自 v10.6 起记录 `text_hash`，以便后续检测内容与向量是否同步；v10.24.0 修复了该表在 UTC 默认值上的历史问题以及归档侧的孤儿行。

资料来源：[mnemos/mcp_server.py:1-60]()、[mnemos/nyx.py:1-200]()、[mnemos/schema.sql:1-150]()、[mnemos/doctor.py:1-100]()。

## 核心数据流

下图展示了一次写入与一次夜间整合的主要路径：

```mermaid
flowchart LR
  A[LLM 代理] -->|MCP 调用| B[mcp_server.py]
  B --> C[prep_memory_text]
  C --> D[embedder: FastEmbed/ONNX]
  D --> E[(memories + embed_meta)]
  E --> F[Nyx 夜间循环]
  F --> G[cosine 候选提名]
  G --> H[NLI 决策]
  H --> I[机械合并/归档]
  I --> E
  J[doctor] -->|一致性校验| E
```

关键节点说明：

- `prep_memory_text` 在 v10.22.0 后会排除 Nyx 的簿记标签（如 `consolidated`、`nyx-split`、`merged-into-*` 等），避免它们污染用于一致性哈希的规范化文本。
- NLI 决策层在 v10.21.0 起增加 `UNRELATED` 判决，以处理"主题相似但断言无关"的候选对。
- `nli_scan_cache`（v10.18.0）以内容哈希为键缓存判定结果，未变更的成对记录在后续扫描中零成本。

资料来源：[mnemos/__init__.py:1-40]()、[mnemos/constants.py:1-200]()、[mnemos/nyx.py:200-400]()。

## 关键运行时约束

系统的若干运行时行为直接源自社区中暴露的问题：

- **空存储必须报错**：若解析到的命名空间下活跃记忆为 0，`doctor` 须报告异常而非判定为健康，避免对错误 `MNEMOS_DB` 路径或 `MNEMOS_NAMESPACE` 的"空过式健康"（v10.23.0）。
- **归档必须携带 tier-2 向量**：整合日不应产生"已归档但无向量"的孤立行；v10.24.0 修复了 51 条此类历史记录。
- **预算可控**：夜间扫描受 `MNEMOS_NLI_FINDER_MAX_PAIRS` 等常量约束，防止 NLI 调用失控扩散（v10.18.0）。

资料来源：[mnemos/cli.py:1-200]()、[mnemos/constants.py:50-250]()。

## 小结

Mnemos 的架构围绕"内容保真 + 零 LLM 整合 + 可自检"三条主线展开：MCP 接口层接收写入，嵌入层固化语义表示，Nyx 引擎以机械方式在夜间维护存储一致性，`doctor` 持续守护数据与向量之间的不变量。后续页面将分别深入 Nyx 阶段机、NLI 决策层、`doctor` 校验矩阵与命名空间隔离机制。

---

<a id='page-2'></a>

## 检索流水线与存储后端

### 相关页面

相关主题：[系统总览与架构](#page-1), [Nyx 整合循环与 NLI 决策层](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mnemos/core.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/core.py)
- [mnemos/query.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/query.py)
- [mnemos/embed.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/embed.py)
- [mnemos/rerank.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/rerank.py)
- [mnemos/cemelify.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/cemelify.py)
- [mnemos/splitter.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/splitter.py)
</details>

# 检索流水线与存储后端

## 概述与设计目标

Mnemos 的检索流水线与存储后端共同构成"写入即嵌入、查询即余弦召回 + NLI 决策"的双层结构。存储层以 SQLite 为主、向量表（tier-2）为辅，承担原文、标签与向量三者的解耦落盘；检索层在余弦召回后由 NLI 决策层完成去重与矛盾判别，二者通过 `embed_meta.text_hash` 在 `doctor` 检查中互相校验，确保内容与向量的长期一致性。

资料来源：[mnemos/core.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/core.py)、[mnemos/embed.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/embed.py)、[mnemos/query.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/query.py)

## 嵌入流水线：原文到 tier-2 向量

`embed.py` 负责把内存原文转成可检索的稠密向量。`prep_memory_text` 构造的 canonical embed-text 自 v10.22.0 起排除 Nyx 的账务类标签（`consolidated`、`nyx-split`、`merged-into-*`、`split-from-*`、`split-part-*`），否则一致性哈希会因为每晚的重写而失配。文本经过 FastEmbed（或 ONNX 后端，参见 v10.16.0）编码后写入 `embed_meta` 表并记录 `text_hash`，以便后续比对。

写入路径的另一要点是 v10.24.0 修正的归档侧嵌入生命周期：归档记忆必须保留对应的 tier-2 向量，硬删除时不得遗留孤儿 `arch` 行，且 `embedded_at` 使用本地时区 DDL，避免同步嵌入看起来比实际早数小时。

资料来源：[mnemos/embed.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/embed.py)、[mnemos/splitter.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/splitter.py)、[mnemos/cemelify.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/cemelify.py)

## 存储后端：内容、标签与向量的分层

存储后端采用"主表存原文与标签 + embed_meta 表存向量元信息"的分层模型。`core.py` 暴露的写入/查询 API 是主表的唯一入口，向量层只通过 `embed_meta.text_hash` 与主表建立软引用。Nyx 阶段四（v10.18.0 起引入的 `nli_scan_cache`）以两个内容的哈希为键做记忆化，使同一对的 NLI 行级分数在后续扫描中免费复用。

归档是分层模型的关键约束：v10.24.0 的取证审计发现 51 条归档记忆缺失 tier-2 向量、3 条孤儿 `arch` 行幸存于硬删除之后，因此写入路径必须保证归档即嵌入、删除即清理两端的原子性。

资料来源：[mnemos/core.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/core.py)、[mnemos/embed.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/embed.py)、[mnemos/query.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/query.py)

## 检索流水线：余弦召回 + NLI 决策

`query.py` 负责把用户查询嵌入后从 `embed_meta` 拉取 top-k 余弦候选，再交给 NLI 决策层做去重确认与矛盾检测。NLI 模型（v10.15.0 起）判定"相同主张 / 相反主张"，比 cross-encoder 重排序更贴合"是否重复 / 是否矛盾"的决策语义；v10.21.0 新增的 `UNRELATED` 裁决配合 `CONTRADICT_MIN_SIM` 余弦下界，避免把无关候选错判为冲突。

| 阶段 | 输入 | 输出 | 关键阈值 |
|---|---|---|---|
| 余弦召回 | 查询向量 | top-k 候选 | `CONTRADICT_MIN_SIM`（候选须达到相似度下界才进入矛盾判定）|
| NLI 决策 | (memory_a, memory_b) | SUPERSEDED / EVOLVED / CONTRADICTS / COMPATIBLE / UNRELATED | 行级分数缓存键为 `text_hash_a ⊕ text_hash_b`|
| 一致性校验 | 当前内容 | `embed_meta.text_hash` | v10.19.0 `doctor` 强制比对 |

`rerank.py` 在 NLI 不可用时退化为 cross-encoder 重排，`splitter.py` 负责长记忆切行以适配 NLI 行级打分。资料来源：[mnemos/query.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/query.py)、[mnemos/rerank.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/rerank.py)、[mnemos/splitter.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/splitter.py)

## 一致性诊断：`doctor` 与空库守卫

`doctor` 子命令是检索/存储两端的看门人。v10.19.0 起它对每条 active 记忆重新派生 embed-text 哈希并与 `embed_meta.text_hash` 比对，捕获绕过 API 的直接 SQL 写入；v10.23.0 又加入空库检测：当 `MNEMOS_DB` 路径错配或 `MNEMOS_NAMESPACE` 不匹配导致 0 条 active 记忆时，`doctor` 不再空判"healthy"，而是提示配置错误。这一闭环让存储后端的任何不一致都会在检索前被暴露。

资料来源：[mnemos/core.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/core.py)、[mnemos/embed.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/embed.py)、[mnemos/query.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/query.py)、[mnemos/rerank.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/rerank.py)、[mnemos/cemelify.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/cemelify.py)、[mnemos/splitter.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/splitter.py)

---

<a id='page-3'></a>

## Nyx 整合循环与 NLI 决策层

### 相关页面

相关主题：[系统总览与架构](#page-1), [检索流水线与存储后端](#page-2), [运维、自检与故障排查](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mnemos/consolidation/__init__.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/consolidation/__init__.py)
- [mnemos/consolidation/orchestrator.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/consolidation/orchestrator.py)
- [mnemos/consolidation/mechanical.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/consolidation/mechanical.py)
- [mnemos/consolidation/llm.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/consolidation/llm.py)
- [mnemos/consolidation/phases.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/consolidation/phases.py)
- [mnemos/consolidation/prompts.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/consolidation/prompts.py)
</details>

# Nyx 整合循环与 NLI 决策层

## 概述与设计目标

Nyx 是 Mnemos 的夜间整合引擎，负责对记忆存储做"去重—合并—矛盾裁决—重嵌入"的全流程治理。其设计哲学建立在两个相互独立的层级之上：

- **检索层（retrieval）**：负责"是不是同一主题"，由 cross-encoder reranker 承担。
- **决策层（decision）**：负责"是不是同一论断 / 是不是相反论断"，由 NLI（natural language inference）模型承担。

v10.15.0 引入 NLI 决策层之后，Nyx 的每日整合循环在 v10.17.0 演化为"零 LLM 调用"的纯机械流水线：cosine 提名候选对 → NLI 决策（去重确认 + 矛盾探测 + phase-4 扫描） → 机械 UNION 执行合并。LLM 相关的工作（weave、synthesize、矛盾裁决的精排）成为可选的 enrichment tier，由显式 phase 列表门控。`资料来源：[mnemos/consolidation/orchestrator.py:1-80]()`

整个 Nyx 循环是 namespace-scoped 的，跨命名空间不会相互污染（v10.20.0 之后取消了原来无差别重写所有已存记忆的 Cemelify 阶段，避免对低质量模型产生内容漂移）。

## Nyx 阶段编排（phases）

`mnemos/consolidation/phases.py` 定义了阶段注册表与执行顺序。每日整合周期被切分为若干独立的 phase，每个 phase 都是幂等且可单独禁用的：

| 阶段 | 触发条件 | 职责 |
|------|---------|------|
| phase-0 | 周期开始 | 候选对提名（cosine rank） |
| phase-1 | 周期内 | 去重确认（NLI admission gate） |
| phase-2 | 周期内 | 行级去重（line-level dedup via NLI） |
| phase-3 | 周期内 | 机械 UNION 合并（selection, never generation） |
| phase-4 | 周期内 | 矛盾扫描（cross-store NLI finder） |
| enrichment phases | 显式开启 | weave / synthesize / 矛盾精排（需 LLM） |

`资料来源：[mnemos/consolidation/phases.py:1-120]()`

LLM 阶段被显式列出且需要主动启用；零 LLM 的核心循环（phase-0 → phase-4）不依赖任何外部生成调用，因此即便 MNEMOS_LLM_* 环境变量缺失或模型不可用，每晚的去重与矛盾探测也能正常推进。`资料来源：[mnemos/consolidation/orchestrator.py:80-160]()`

## NLI 决策层

NLI 决策层是 Nyx 在 v10.15.0 之后的"裁判"。它的输入是两个记忆的 canonical embed-text，输出是三种极性之一：

- **entailment**：B 是 A 的语义子集或等价重述 → 触发去重 / 行级合并。
- **contradiction**：B 与 A 互斥 → 进入 phase-4 矛盾候选集。
- **neutral**：既不蕴含也不矛盾 → 视作 UNRELATED，不做任何修改。

v10.21.0 显式为 phase-4 矛盾裁判增加了 UNRELATED 裁决，原因是原 prompt 预设"两条记忆主题相似"导致候选穷举失真。`资料来源：[mnemos/consolidation/prompts.py:1-200]()`

NLI 评分对内容是纯函数，因此 v10.18.0 引入了 `nli_scan_cache`：以两个内容的 hash 作为键，未变化的对在跨夜扫描中免于重算；变化的对则精准失效自身。预算由 `MNEMOS_NLI_FINDER_MAX_PAIRS` 控制，确保大规模存储也不会让单次扫描失控。`资料来源：[mnemos/consolidation/orchestrator.py:160-240]()`

后端方面，v10.16.0 引入了 ONNX 运行时优先策略：当本地存在 ONNX export 时，`mnemos[nli]` extra 从多 GB 的 torch 依赖降级为 `onnxruntime + transformers tokenizer`，避免在小型部署中拖入整条 PyTorch 链路。温度采样方面实现了 self-healing rejection：当 NLI head 的 softmax 温度异常（熵过低，模型近乎退化随机猜）时，自动拒绝该裁决并降级为保守决定。`资料来源：[mnemos/consolidation/llm.py:1-160]()`

## 机械执行与归档一致性

合并的最终执行由 `mechanical.py` 完成。它做的是 selection，从两个输入中选择保留哪一个，或者在相位上做行级 UNION，绝不调用 LLM 重新生成内容。这种"机械而非生成"的执行模型保证：

1. 已存内容的 fidelity 在合并前后字节级一致（除非显式 overwrite）。
2. 嵌入向量在归档侧的 lifecycle 由 v10.24.0 修复：归档记忆的 tier-2 向量必须随归档同时存在，避免"归档但无向量"的孤儿行。
3. embed-text 的构造从 v10.22.0 起排除 Nyx 自身的 bookkeeping tags（`consolidated`、`nyx-split`、`merged-into-*`、`split-from-*`、`split-part-*`），避免因为每晚的 tag 重写导致 `embed_meta.text_hash` 与内容漂移，进而破坏 doctor 的 coherence 校验。

`资料来源：[mnemos/consolidation/mechanical.py:1-120]()`

`资料来源：[mnemos/consolidation/__init__.py:1-40]()`

## 失败模式与可观测性

`doctor` 子命令（v10.19.0 起）会对每个 active memory 重新派生 embed-text hash 并与 `embed_meta.text_hash` 比对，专门捕获"内容被改但未重嵌"的情形——典型场景包括绕过 API 的直接 SQL 写入、手动迁移脚本或第三方插件。v10.23.0 进一步：当解析后的命名空间下活跃记忆为 0 时，doctor 不再返回"healthy"，而是报告"empty store"并附带 namespace / db path 配置提示，从而避免在错误的 `MNEMOS_DB` 路径或错配的 `MNEMOS_NAMESPACE` 下误判为空载。

---

<a id='page-4'></a>

## 运维、自检与故障排查

### 相关页面

相关主题：[系统总览与架构](#page-1), [检索流水线与存储后端](#page-2), [Nyx 整合循环与 NLI 决策层](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [mnemos/cli.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/cli.py)
- [mnemos/mcp_server.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/mcp_server.py)
- [mnemos/core.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/core.py)
- [mnemos/storage/sqlite_store.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/storage/sqlite_store.py)
- [mnemos/constants.py](https://github.com/draca-glitch/Mnemos/blob/main/mnemos/constants.py)
- [scripts/mnemos-session-hook.sh](https://github.com/draca-glitch/Mnemos/blob/main/scripts/mnemos-session-hook.sh)
</details>

# 运维、自检与故障排查

本页说明 Mnemos 在日常运维中的自检入口、健康检查覆盖范围、常见故障模式以及对应的排查路径。读者应是负责部署、看护 Nyx 周期、并在出现归档/向量不一致时定位根因的运维或集成方开发者。

## 1. 运维对象与边界

Mnemos 的运行时由三个平面组成：CLI 平面（`mnemos` 命令及其子命令）、MCP 平面（`mnemos/mcp_server.py` 暴露给代理的接口）以及存储平面（SQLite + 嵌入元数据表，由 `mnemos/storage/sqlite_store.py` 持有）。运维动作通常发生在 CLI 与存储平面之间；MCP 平面承载代理调用，但它复用了 CLI 与 core 层相同的状态机，所以排查入口仍以 `mnemos doctor` 为主。

命名空间（namespace）是所有诊断和自检的隐式前缀。`MNEMOS_DB` 决定数据库文件路径，`MNEMOS_NAMESPACE` 决定命名空间；如果两者配置不一致，历史上会出现"每个检查都空过"的假阳性 [资料来源：[mnemos/cli.py:1-1]()] [资料来源：[mnemos/constants.py:1-1]()]。

## 2. `doctor`：自检入口

`mnemos doctor` 是面向运维人员的健康检查命令，输出当前 namespace 下 store 的多项诊断结论，并给出配置建议。它的语义从 v10.19.0 起被显著强化——不仅检查可达性，还逐条比对每条活跃记忆的 embed-text 哈希与 `embed_meta.text_hash`：

| 检查项 | 触发条件 | 提示信息关键词 |
|---|---|---|
| 空 store 检测 | 当前 namespace 下活跃记忆为 0 | "no active memories" + 配置提示（v10.23.0 起视为问题） |
| 内容/向量一致性 | 重新计算的 embed-text 哈希 ≠ `embed_meta.text_hash` | 标记为需要重新嵌入 |
| 归档残留 | 归档记忆缺少 tier-2 向量或存在孤儿归档行 | "tier-2 leak" / "orphan arch row"（v10.24.0 修复） |
| 嵌入元数据时间戳 | `embed_meta.embedded_at` 与写入时区不一致 | 提示 DDL 时区漂移 |

需要强调的是，空 store 不再被判定为"healthy"——这避免了 `MNEMOS_DB` 路径错配或命名空间错配时检查项全部空过的隐患 [资料来源：[mnemos/cli.py:1-1]()] [资料来源：[mnemos/storage/sqlite_store.py:1-1]()]。

## 3. 嵌入生命周期与一致性

自 v10.6 起，Mnemos 在写入时记录 `embed_meta.text_hash`；自 v10.19.0 起，`doctor` 用这个哈希对内容漂移做反向审计。任何绕过 API 直接修改 `memories.content` 的写入，都会让下一次 `doctor` 暴露该记忆 [资料来源：[mnemos/core.py:1-1]()]。

归档侧的嵌入生命周期是 v10.24.0 的关键修复点。归档操作必须同步迁移 tier-2 向量，否则会出现"51 条归档记忆无 tier-2 向量、且全部集中在合并日"的典型泄露形态；另外还存在 3 条悬空归档行（指向已被硬删除的记忆）以及 `embedded_at` 默认值在 UTC/localtime 之间漂移的历史问题 [资料来源：[mnemos/storage/sqlite_store.py:1-1]()]。

`prep_memory_text` 的规范化在 v10.22.0 收紧：Nyx 的内部记账标签（`consolidated`、`nyx-split`、`merged-into-*`、`split-from-*`、`split-part-*`）不再进入 embed-text，因而也不会让哈希翻转——这是保证 `doctor` 一致性长期稳定的前提 [资料来源：[mnemos/core.py:1-1]()] [资料来源：[mnemos/constants.py:1-1]()]。

## 4. 常见故障与排查路径

**症状 A：`doctor` 报告 "tier-2 leak"。** 这表示归档行缺少嵌入向量。排查顺序：(1) 确认运行版本 ≥ v10.24.0；(2) 重跑一次合并周期，让归档侧的迁移逻辑执行；(3) 若仍有残留，使用存储平面直接清理孤儿归档行 [资料来源：[mnemos/storage/sqlite_store.py:1-1]()]。

**症状 B：`doctor` 报告大量"内容/向量不一致"。** 通常来源于外部 SQL 直写、备份恢复、或在 embedding 服务降级期间写入。修复方式是对受影响记忆触发重新嵌入；不要直接修改 `embed_meta`，让 API 路径负责重写 [资料来源：[mnemos/core.py:1-1]()]。

**症状 C：Nyx 周期异常慢或产出空结果。** 自 v10.17.0 起，零 LLM 的日级合并是默认形态；如果在 v10.20.0 之前曾启用过 phase 0.5（Cemelify），需要确认当前配置未再引用该阶段——它已被移除，因为重写已存内容会破坏 fidelity [资料来源：[mnemos/constants.py:1-1]()] [资料来源：[mnemos/core.py:1-1]()]。

**症状 D：`nli_scan_cache` 命中率异常。** NLI 扫描以内容哈希为键；只要两侧内容未变，就不应重复计算。可通过 `MNEMOS_NLI_FINDER_MAX_PAIRS` 观察每夜消耗 [资料来源：[mnemos/constants.py:1-1]()]。

## 5. 会话钩子与持续看护

`scripts/mnemos-session-hook.sh` 在会话启动/退出时被调用，用于刷新运行时环境（路径、命名空间、Nyx 调度提示）。在多 namespace 部署中，钩子与 `doctor` 组合使用可形成"启动 → 自检 → 周期 → 自检"的最小闭环 [资料来源：[scripts/mnemos-session-hook.sh:1-1]()] [资料来源：[mnemos/mcp_server.py:1-1]()]。

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：draca-glitch/Mnemos

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx pha...。

## 1. 安装坑 · 失败模式：installation: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx pha...

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder
- 对用户的影响：Upgrade or migration may change expected behavior: v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.15.0 | v10.15.0 NLI decision layer: entailment-based dedup confirm, contradiction detection, Nyx phase-4 finder

## 2. 安装坑 · 失败模式：installation: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection
- 对用户的影响：Upgrade or migration may change expected behavior: v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.16.0 | v10.16.0 ONNX backend for the NLI layer; self-healing temperature rejection

## 3. 安装坑 · 失败模式：installation: v10.23.0 doctor flags an empty store instead of blessing it

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this installation risk before relying on the project: v10.23.0 doctor flags an empty store instead of blessing it
- 对用户的影响：Upgrade or migration may change expected behavior: v10.23.0 doctor flags an empty store instead of blessing it
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.23.0 | v10.23.0 doctor flags an empty store instead of blessing it

## 4. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/draca-glitch/Mnemos | host_targets=mcp_host, claude_code, claude, cursor, chatgpt

## 5. 配置坑 · 失败模式：configuration: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this configuration risk before relying on the project: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped
- 对用户的影响：Upgrade or migration may change expected behavior: v10.20.0 phase 0.5 removed; Nyx is namespace-scoped
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.20.0 | v10.20.0 phase 0.5 removed; Nyx is namespace-scoped

## 6. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/draca-glitch/Mnemos | README/documentation is current enough for a first validation pass.

## 7. 维护坑 · 失败模式：migration: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks

- 严重度：medium
- 证据强度：source_linked
- 发现：Developers should check this migration risk before relying on the project: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks
- 对用户的影响：Upgrade or migration may change expected behavior: v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.24.0 | v10.24.0 archive-side embedding lifecycle: no more tier-2 leaks

## 8. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/draca-glitch/Mnemos | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/draca-glitch/Mnemos | no_demo; severity=medium

## 10. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/draca-glitch/Mnemos | no_demo; severity=medium

## 11. 运行坑 · 失败模式：performance: v10.17.0 zero-LLM daily consolidation cycle

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v10.17.0 zero-LLM daily consolidation cycle
- 对用户的影响：Upgrade or migration may change expected behavior: v10.17.0 zero-LLM daily consolidation cycle
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.17.0 | v10.17.0 zero-LLM daily consolidation cycle

## 12. 运行坑 · 失败模式：performance: v10.19.0 doctor verifies content/vector coherence

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v10.19.0 doctor verifies content/vector coherence
- 对用户的影响：Upgrade or migration may change expected behavior: v10.19.0 doctor verifies content/vector coherence
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.19.0 | v10.19.0 doctor verifies content/vector coherence

## 13. 运行坑 · 失败模式：performance: v10.21.0 contradiction judge gains an UNRELATED verdict

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v10.21.0 contradiction judge gains an UNRELATED verdict
- 对用户的影响：Upgrade or migration may change expected behavior: v10.21.0 contradiction judge gains an UNRELATED verdict
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.21.0 | v10.21.0 contradiction judge gains an UNRELATED verdict

## 14. 运行坑 · 失败模式：performance: v10.22.0 embed-text excludes Nyx bookkeeping tags; coherence stays green

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this performance risk before relying on the project: v10.22.0 embed-text excludes Nyx bookkeeping tags; coherence stays green
- 对用户的影响：Upgrade or migration may change expected behavior: v10.22.0 embed-text excludes Nyx bookkeeping tags; coherence stays green
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.22.0 | v10.22.0 embed-text excludes Nyx bookkeeping tags; coherence stays green

## 15. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/draca-glitch/Mnemos | issue_or_pr_quality=unknown

## 16. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/draca-glitch/Mnemos | release_recency=unknown

## 17. 维护坑 · 失败模式：maintenance: v10.18.0 memoized NLI finder: the nightly sweep stops re-proving old negatives

- 严重度：low
- 证据强度：source_linked
- 发现：Developers should check this maintenance risk before relying on the project: v10.18.0 memoized NLI finder: the nightly sweep stops re-proving old negatives
- 对用户的影响：Upgrade or migration may change expected behavior: v10.18.0 memoized NLI finder: the nightly sweep stops re-proving old negatives
- 证据：failure_mode_cluster:github_release | https://github.com/draca-glitch/Mnemos/releases/tag/v10.18.0 | v10.18.0 memoized NLI finder: the nightly sweep stops re-proving old negatives

<!-- canonical_name: draca-glitch/Mnemos; human_manual_source: deepwiki_human_wiki -->