# https://github.com/nousergon/mnemon 项目说明书 生成时间：2026-07-18 21:13:57 UTC ## 目录 - [项目概览与系统架构](#page-1) - [MCP 工具、记忆模型与捕获管线](#page-2) - [部署、仪表板与同步工作流](#page-3) - [运维检查、已知限制与社区待办](#page-4) ## 项目概览与系统架构 ### 相关页面 相关主题：[MCP 工具、记忆模型与捕获管线](#page-2), [部署、仪表板与同步工作流](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/nousergon/mnemon/blob/main/README.md) - [ARCHITECTURE.md](https://github.com/nousergon/mnemon/blob/main/ARCHITECTURE.md) - [pyproject.toml](https://github.com/nousergon/mnemon/blob/main/pyproject.toml) - [src/mnemon/__init__.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/__init__.py) - [src/mnemon/__main__.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/__main__.py) - [src/mnemon/cli.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/cli.py) - [src/mnemon/mcp_server.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/mcp_server.py) - [src/mnemon/storage.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/storage.py) - [.github/workflows/ci.yml](https://github.com/nousergon/mnemon/blob/main/.github/workflows/ci.yml)
# 项目概览与系统架构 ## 1. 项目定位与核心职责 `mnemon` 是以 PyPI 包名 `mnemon-memory` 发布的 AI Agent **长期记忆中间件**，面向 Claude Code、`claude.ai` 等 Agent 工作流提供"跨会话持久化 + 语义检索 + 置信度衰减"三件套。当前稳定线为 0.7.x，最新发行版 v0.7.7 引入 `memory_save` 的 prose supersession 自动检测，0.7.6 则完成了 Fly suspend 场景下的会话卫生与衰减扫描补偿 资料来源：[README.md:1-40]() 资料来源：[CHANGELOG/release notes v0.7.7](#)。 仓库内代码采用 `src/` 布局：`src/mnemon/__init__.py` 暴露公共 API，`__main__.py` 支持 `python -m mnemon` 启动 CLI 资料来源：[src/mnemon/__init__.py:1-30]() 资料来源：[src/mnemon/__main__.py:1-20]()。包元信息与依赖集中在 `pyproject.toml`，从中可读到 `mnemon` 作为 console_scripts 入口点 资料来源：[pyproject.toml:1-80]()。 ## 2. 系统架构总览 整体遵循"**入口层 → 服务层 → 存储层**"三层划分，并通过环境变量与 feature flag 控制可观测行为 资料来源：[ARCHITECTURE.md:1-120]()。 ```mermaid graph LR subgraph 入口层 Entry CLI[mnemon CLI] Hook[claude-code-hook] MCP[MCP Server
modelcontextprotocol] Mirror[mnemon-mirror] end subgraph 服务层 Service Save[memory_save
supersession auto-detect] Query[memory_search / list] Decay[confidence decay sweep] Tier[salience tier
Phase 2/3] Cap[capture-attention
Phase A/B/C] end subgraph 存储层 Storage DB[(documents 表
id, content, source_client,
confidence, relations)] end CLI --> Save Hook --> Save MCP --> Save Mirror --> DB Save --> DB Query --> DB Decay --> DB Tier --> DB Cap --> DB ``` 入口层负责协议适配：CLI 面向运维和手动录入 资料来源：[src/mnemon/cli.py:1-60]()，Claude Code 通过 hook 注入 `source_client=claude-code-hook`，MCP 端则按 `clientInfo` 协商工具调用 资料来源：[src/mnemon/mcp_server.py:1-80]()。服务层封装 `memory_save`、`memory_search`、衰减扫描、显著性分级与捕获注意力等算子；存储层以 `documents` 表为核心 Schema，写入路径要求调用方显式传 `source_client`，否则会出现 NULL provenance（详见 issue #274） 资料来源：[src/mnemon/storage.py:1-90]()。 ## 3. 关键模块与数据契约 **存储契约**：`documents` 主键为 `id`，必填列含 `content`、`source_client`、`confidence` 与 `relations`（JSON）。`source_client` 由调用方填入，常见取值包括 `claude-code-hook`、`mnemon-mirror`、`mnemon-cli`；`relations` 支持 `supersedes` / `correction_of` 等边类型 资料来源：[src/mnemon/storage.py:30-90]()。v0.7.7 起，当 `correction_of` 缺省但正文出现 `supersedes id N` / `#N` 形态时，写入路径会自动追加 `supersedes` 关系并打印 WARN，不会静默改写 资料来源：[release notes v0.7.7](#)。 **服务算子**：`memory_save` 串联去重、显著性分级、捕获注意力与 supersession 检测；`decay sweep` 自 v0.7.6 起改为 wall-clock 触发，规避 Fly 实例 suspend-resume 期间静默漏跑 资料来源：[release notes v0.7.6](#)；显著性分级（Phase 2/3）与捕获注意力（Phase A/B/C）默认全部 **gated default-off**，需通过 `MNEMON_STANDING_TIER_ENABLED`、`MNEMON_CAPTURE_ATTENTION_ENABLED` 等 env 显式开启 资料来源：[release notes v0.7.0rc6](#) 资料来源：[release notes v0.7.0rc4]()。 **CLI 命令**：`mnemon install` / `uninstall` 注册并清理 hook 子命令，`mnemon save` 调用服务层写入，`uninstall` 当前在未注册场景打印 "no mnemon registration found (or CLI errored silently)"，社区已提出文案整改（issue #244） 资料来源：[src/mnemon/cli.py:60-200]()。 ## 4. 部署形态与可配置特性 CI 矩阵覆盖 Python 3.10 / 3.12 / 3.13 与多 OS 维度，自托管 AL2023 runner 上线前需校验预缓存完整性（issue #272、PR #271） 资料来源：[.github/workflows/ci.yml:1-80]()。Fly 自托管是当前主要部署形态，冷启动 / suspend-resume 预算约 1s，v0.7.6 的 `stop`→`suspend` 切换已压缩该窗口，README 待补文档（issue #246）。 运维侧的可调旋钮包括： - `MNEMON_STANDING_TIER_ENABLED`：开启显著性 standing tier； - `MNEMON_CAPTURE_ATTENTION_ENABLED`：开启 Phase A 自动捕获； - `MNEMON_*` 系列 env 用于在 `flyctl secrets set` 后无需重新部署即可热生效 资料来源：[release notes v0.7.0rc4]()。 生态集成方面，仓库当前**未**接入 fleet groomer 的 `BACKLOG_REPOS` 列表（issue #276），保持交互式 only；claude.ai chat 表面的自动保存策略也尚未确定（issue #273），这两项构成近期需要决策的开放问题。 --- ## MCP 工具、记忆模型与捕获管线 ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [部署、仪表板与同步工作流](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/mnemon/server.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/server.py) - [src/mnemon/server_remote.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/server_remote.py) - [src/mnemon/store.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/store.py) - [src/mnemon/search.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/search.py) - [src/mnemon/embedder.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/embedder.py) - [src/mnemon/vecstore.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/vecstore.py) - [src/mnemon/capture.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/capture.py)
# MCP 工具、记忆模型与捕获管线 ## 1. MCP 服务器与暴露的工具 mnemon 通过 Model Context Protocol（MCP）把记忆能力以工具的形式暴露给宿主 AI（Claude Code、Claude.ai 等）。本地入口由 `src/mnemon/server.py` 实现，基于 FastMCP 注册工具；远程/托管入口由 `src/mnemon/server_remote.py` 提供，便于在 Fly.io 等云端以服务的形式挂载。 主要工具包括： - `memory_save`：写入一条记忆，自动处理去重、关系（`supersedes` / `correction_of`）与置信度初始化。`资料来源：[src/mnemon/server.py:80-140]()` - `memory_search`：混合关键词 + 向量检索，返回 Top-K 记忆。`资料来源：[src/mnemon/server.py:140-200]()` - `memory_get` / `memory_delete`：按 id 取回或撤销记忆。`资料来源：[src/mnemon/server.py:200-260]()` `server_remote.py` 复用了同一套工具注册器，但额外支持 `MNEMON_*` 环境变量驱动的部署形态（绑定、鉴权、日志级别）。`资料来源：[src/mnemon/server_remote.py:1-60]()` ## 2. 记忆模型与存储 记忆的核心数据模型由 `src/mnemon/store.py` 定义并落库到 SQLite。文档（document）字段至少包含：`id`、`content`、`source_client`、`confidence`、`salience_tier`、`created_at`、`last_seen_at` 以及关系数组。`资料来源：[src/mnemon/store.py:40-120]()` 关键模型特性： - **关系**：文档之间可以是 `supersedes`（取代）或 `correction_of`（订正），用于在写入时形成有向图。`资料来源：[src/mnemon/store.py:120-180]()` - **置信度衰减**：v0.7.6 起使用基于墙钟的衰减扫描，跨 Fly suspend 周期仍可正确累计。`资料来源：[src/mnemon/store.py:180-240]()` - **显著性分层（salience tier）**：0.7.0rc6 引入 Phase 2/3，将记忆划分为不同保活级别。`资料来源：[src/mnemon/store.py:240-300]()` 向量侧由 `src/mnemon/vecstore.py` 持有独立索引，文档主键与 SQLite 行一一对应，搜索时通过余弦相似度召回候选，再由 `store.py` 做关系展开。`资料来源：[src/mnemon/vecstore.py:1-80]()` ## 3. 捕获管线（Capture Pipeline） 捕获管线是 mnemon 把"对话上下文"变成"持久记忆"的核心子系统。它以"阶段"为单位推进，默认全部为 off / 显式触发： | 阶段 | 触发形式 | 默认状态 | 关键开关 | |---|---|---|---| | Phase A — 激活基础设施 | hooks / 工具调用 | 默认 off | `MNEMON_CAPTURE_ATTENTION_ENABLED` | | Phase B — 自动评分 | 写入后回调 | 默认 off | `MNEMON_CAPTURE_PHASE_B` | | Phase C — 跨会话接力 | 进程间事件 | 默认 off | `MNEMON_CAPTURE_PHASE_C` | 实现位于 `src/mnemon/capture.py`，提供 `should_capture(...)`、`score_candidate(...)`、`emit_handoff(...)` 三个钩子；Claude Code 侧 hooks 通过 `source_client="claude-code-hook"` 注入。`资料来源：[src/mnemon/capture.py:1-120]()` 社区中正在讨论两个相关议题： - **#273**：claude.ai 聊天面目前从不写入 mnemon，需要在"自动保存"与"显式保存"之间明确语义。`资料来源：[issue #273]()` - **#274**：MCP 通道写入时 `source_client` 为 NULL，需要从 MCP `clientInfo` 在服务端补戳，否则钩子保存与 MCP 保存无法区分。`资料来源：[issue #274]()` ## 4. 嵌入与检索 `src/mnemon/embedder.py` 抽象文本嵌入，优先使用本地 `sentence-transformers`，回退到 OpenAI 兼容接口；嵌入维度在初始化时落盘到 `vecstore` 元表，确保后续切换模型不会与历史向量错配。`资料来源：[src/mnemon/embedder.py:1-90]()` `src/mnemon/search.py` 把"关键词 + 向量 + 关系"三路召回合并：向量路返回 Top-N 候选，关键词路用 SQLite FTS5 兜底，关系路沿 `supersedes` / `correction_of` 边做一次扩展；最终按加权得分重排。`资料来源：[src/mnemon/search.py:60-160]()` v0.7.7 起，`memory_save` 在用户没有显式传 `correction_of`、但正文包含 `supersedes id N` / `#N` 这类触发式表述时，会自动建立 `supersedes` 关系，并以 WARN 日志告知——这是加法式变更，不会静默改写既有关系。`资料来源：[src/mnemon/server.py:100-140]()` --- ## 部署、仪表板与同步工作流 ### 相关页面 相关主题：[项目概览与系统架构](#page-1), [运维检查、已知限制与社区待办](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/mnemon/setup.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/setup.py) - [src/mnemon/upgrade.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/upgrade.py) - [src/mnemon/downgrade.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/downgrade.py) - [src/mnemon/uninstall.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/uninstall.py) - [src/mnemon/sync.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/sync.py) - [src/mnemon/mirror.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/mirror.py)
# 部署、仪表板与同步工作流 ## 概述 mnemon 的"部署、仪表板与同步"子系统由六个核心模块组成，承担三方面职责： 1. **生命周期管理**：`setup.py` / `upgrade.py` / `downgrade.py` / `uninstall.py` 处理本地 CLI 与钩子的安装、版本切换、清理 2. **运行期可视化**：仪表板（dashboard）子命令为记忆图谱、置信度衰减、显著度分层提供入口 3. **跨端收敛**：`sync.py` 与 `mirror.py` 实现多设备 / 多端状态同步 该子系统统一以 `documents.source_client` 字段标识写入来源：`claude-code-hook`（钩子）、`mnemon-mirror`（镜像）、CLI 直调三类，因此部署与同步路径的选择会直接影响落库条目的可追溯性。 ## 本地生命周期管理 ### 安装（setup.py） `setup.py` 是部署入口，负责： - 注册钩子到 Claude Code 等客户端，写入 `claude-code-hook` 作为 `source_client` - 初始化 SQLite `documents` 表与配置目录 - 校验依赖与 Python 版本 社区实践（issue #276）中讨论是否将本仓库接入 fleet groomer 的 `BACKLOG_REPOS`，以便自动接收 backlog 清理；当前仍为交互式管理。 ### 升级与降级（upgrade.py / downgrade.py） 版本切换通过 `pip install mnemon-memory==` 配合迁移脚本完成。0.7.6 的"挂起鲁棒会话卫生"（#218）即通过升级链路部署——`stop` → `suspend` 改造将冷启动预算降至约 1 秒，相关 README 文档待办见 #246。0.7.0rc4 引入的 `MNEMON_CAPTURE_ATTENTION_ENABLED` 环境变量允许通过 `flyctl secrets set` 在线翻转 Phase A 激活位，无需重部署。 ### 卸载（uninstall.py） `uninstall.py` 清理注册信息与会话绑定。issue #244 指出当前提示文案"no mnemon registration found (or CLI errored silently)"易引发误判，需重写以精确反映未注册或已清理状态。 ## 仪表板（Dashboard） 仪表板由若干 CLI 子命令驱动，提供以下视图： - **记忆图谱视图**：渲染 `documents` 表中的节点与 `correction_of` / `'supersedes'` 关系 - **衰减扫掠状态**：0.7.6（#217）后扫掠以**挂钟时间**触发，能在 Fly 机器挂起 / 唤醒后正确恢复，不再静默失效 - **显著度分层**：0.7.0rc6 引入的 Salience Tier 在仪表板以分层视图呈现 Phase 2 / Phase 3 - **捕获注意力面板**：默认关闭（default-off），对应 #273 关于"自动保存姿态"的待决——claude.ai chat surface 等隐式会话默认不入库 ## 同步与镜像工作流 `sync.py` 负责拉取增量并合并本地写入；`mirror.py` 推送 `source_client = mnemon-mirror` 的记录到对端。两者构成对称的双向同步通道。 当前痛点（issue #274）：当调用方未显式传入 `source_client` 时（例如 MCP 显式保存），落库条目为 NULL provenance，与钩子路径无法区分。社区正在讨论**由 MCP `clientInfo` 在服务端侧强制打戳**的方案，使三条写入路径在落库后仍可追溯。 ```mermaid flowchart LR A[setup.py 安装] --> B[本地 CLI + 钩子] B --> C{运行期} C -->|save| D[(SQLite documents)] C -->|sync| E[sync.py 拉取] C -->|mirror| F[mirror.py 推送] E --> D F --> D D --> G[仪表板] C -->|版本切换| H[upgrade/downgrade.py] H --> D B -->|清理| I[uninstall.py] ``` ## 已知问题与运维待办 - **#276**：决定是否接入 fleet groomer 的 `BACKLOG_REPOS` - **#274**：服务端打戳 `source_client` 以保留 MCP 来源可追溯性 - **#273**：明确 claude.ai chat surface 的自动保存姿态（Profile snippet vs. 显式 only） - **#272**：在自托管 AL2023 runner 上验证多版本 Python（3.10/3.12/3.13）+ `matrix.os` - **#263**：CI 漏报的 ruff 66 个 lint 错误需集中修复 资料来源：[src/mnemon/setup.py:1-120]()、[src/mnemon/upgrade.py:1-80]()、[src/mnemon/downgrade.py:1-60]()、[src/mnemon/uninstall.py:1-40]()、[src/mnemon/sync.py:1-150]()、[src/mnemon/mirror.py:1-150]() --- ## 运维检查、已知限制与社区待办 ### 相关页面 相关主题：[MCP 工具、记忆模型与捕获管线](#page-2), [部署、仪表板与同步工作流](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [src/mnemon/doctor.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/doctor.py) - [src/mnemon/uninstall.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/uninstall.py) - [src/mnemon/upgrade.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/upgrade.py) - [src/mnemon/auth.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/auth.py) - [src/mnemon/persistent_sessions.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/persistent_sessions.py) - [src/mnemon/safety.py](https://github.com/nousergon/mnemon/blob/main/src/mnemon/safety.py) - [tests/test_uninstall.py](https://github.com/nousergon/mnemon/blob/main/tests/test_uninstall.py) - [.github/workflows/ci.yml](https://github.com/nousergon/mnemon/blob/main/.github/workflows/ci.yml) - [README.md](https://github.com/nousergon/mnemon/blob/main/README.md)
# 运维检查、已知限制与社区待办 本页面向运维人员、集成方与首次接触 mnemon 的开发者，梳理"上线前可执行的体检"、"当前已知的设计与基础设施限制"，以及"社区已记录但未关闭的待办议题"。所有结论均来自仓库源码与公开 issue 跟踪，不引入外部假设。 ## 1. 内置运维检查工具 ### 1.1 `mnemon doctor` `doctor` 是面向部署后环境与运行时状态的体检入口，扫描本地凭证、会话存储、Fly/Fly-style 部署握手等关键环节是否一致。`src/mnemon/doctor.py` 中按"失败先于警告"的顺序收集检查项，并在结尾给出可粘贴的诊断摘要。 资料来源：[src/mnemon/doctor.py:1-60]() ### 1.2 `mnemon uninstall` `uninstall` 在交互模式下逐项移除钩子注册、`.mnemon` 配置目录与会话存档，CI/非交互模式下则走最小路径。卸载结果判定不依赖返回码字符串，而是基于会话存档目录的实际状态。 资料来源：[src/mnemon/uninstall.py:42-110]() 需要注意的是，当未检测到任何注册时，CLI 仍会输出提示信息以避免静默失败，但当前文案与"完全卸载"语义不一致——这是社区记录中的 #244 议题，目标是将提示改写为更贴近实情的措辞。 资料来源：[tests/test_uninstall.py:18-44]() 与社区 issue #244 ### 1.3 `mnemon upgrade` `upgrade` 通过比对本地 `__version__` 与 PyPI 元数据决定升级路径；长驻守护进程在重启前会显式写出旧/新版本以便回滚。`upgrade` 不直接对数据库进行模式变更，结构迁移走独立的 migration hook。 资料来源：[src/mnemon/upgrade.py:30-95]() ## 2. 已知限制 ### 2.1 `documents.source_client` 在显式 MCP 写入时不可区分 `source_client` 字段只在调用方主动传入时填充：钩子写入 `claude-code-hook`，镜像写入 `mnemon-mirror`，CLI 写入对应的子命令标记。但当 MCP server 接收来自客户端的 `memory_save` 时，凭证来源不可观测，于是数据库中留下 `NULL` / "explicit" 的占位值。 结果：事后追溯无法在"claude.ai Profile snippet"、"第三方 MCP 客户端"与"显式 CLI 调用"之间做可靠区分，这是当前必须人工判读的最大盲点之一。 资料来源：[src/mnemon/auth.py:120-180]() 与社区 issue #274 ### 2.2 `claude.ai` 聊天表面不会写入 mnemon 经过多轮有决策轨迹的 claude.ai 对话验证，`claude.ai` 聊天表面仍未触发任何 mnemon 写入。运维上这意味着：要么为该表面配置自动保存（"Profile snippet" 路径），要么在文档中明确标注其为"仅显式"，将决策留给用户。 资料来源：社区 issue #273 ### 2.3 Fly 部署冷启动预算 Fly 自托管机器在 `stop` → `suspend` 迁移后，冷启动预算约 1 秒。`persistent_sessions.py` 在恢复阶段必须等待会话索引重新加载才能响应查询，运维脚本应容忍这一基线延迟。README 尚未显式记录该数字。 资料来源：[src/mnemon/persistent_sessions.py:55-95]() 与社区 issue #246 ### 2.4 CI 与基础设施债 切换至 AL2023 自托管 runner 后，`ci.yml` 的矩阵任务尚未校验多 Python 版本（3.10 / 3.12 / 3.13）与多 OS 同时可用的实际可行性；预缓存脚本仅固定 Python 3.12，存在与早高峰 morning-signal 相似的 `actions/setup-python` 兼容性陷阱。 资料来源：[.github/workflows/ci.yml:25-70]() 与社区 issue #272 代码层面，`ruff check src/ tests/` 在 `main` 上仍报 66 条错误（46 条 `--fix`、14 条 `--unsafe-fixes` 可修），主要集中在测试文件的未使用导入；CI 流水线上未启用 ruff 检查，故未拦截。这是上线前必须清理的"良性债务"。 资料来源：[tests/test_validate_cross_device.py:1-30]() 与社区 issue #263 ## 3. 待办与小修议题汇总 | 议题 | 标签 | 影响面 | 备注 | |------|------|--------|------| | #276 fleet groomer `BACKLOG_REPOS` 接入决策 | ops | 跨仓一致性 | 当前维持交互式手动模式 | | #274 服务端补 `source_client` 戳记 | schema | MCP 可观测性 | 修改 `auth.py` 读取 `clientInfo` | | #273 claude.ai 是否走自动保存 | policy | 文档/产品 | 需运营拍板 | | #272 多版本 Python 矩阵验证 | ci | 流水线稳定性 | 跟随 PR #271 | | #263 ruff 旧债 | quality | 维护性 | 现 66 条错误未被 CI 拦截 | | #244 uninstall 文案改写 | docs | 用户体验 | 标签 `good first issue` | | #246 README 冷启动说明 | docs | 自托管用户 | 复用 #213 的 `stop→suspend` 改进 | | #236 calibration fixture 缺回退 | packaging | CI 新克隆失败 | 期望 `.json` → `.example.json` | 资料来源：[README.md:1-40]() 与上述对应 issue ## 4. 推荐运维流程 1. **部署后**：立即执行 `mnemon doctor` 并归档摘要。 2. **升级前**：确认 `mnemon upgrade` 输出的 from/to 版本与发布说明一致；运行结构迁移钩子。 3. **卸载前**：人工核对 `~/.mnemon/sessions/` 与钩子注册目录；非交互场景记录返回码。 4. **变更审查**：升级 ruff 闸门、补 MCP `clientInfo` 穿透后再发布新版本，以闭合当前已知债。 通过上述体检与限制清单，运维方可在 v0.7.7（散文 supersession 自动检测）之上获得一张可控的前进地图，而无需把每个待办都升级为正式 RFC。 --- --- ## Doramagic 踩坑日志 项目：nousergon/mnemon 摘要：发现 30 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: 0.7.0rc6。 ## 1. 安装坑 · 失败模式：installation: 0.7.0rc6 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: 0.7.0rc6 - 对用户的影响：Upgrade or migration may change expected behavior: 0.7.0rc6 - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc6 | 0.7.0rc6 ## 2. 安装坑 · 失败模式：installation: Pre-existing ruff lint debt (66 errors) not caught by CI - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Pre-existing ruff lint debt (66 errors) not caught by CI - 对用户的影响：Developers may fail before the first successful local run: Pre-existing ruff lint debt (66 errors) not caught by CI - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/263 | Pre-existing ruff lint debt (66 errors) not caught by CI ## 3. 安装坑 · 失败模式：installation: Uninstall message reword - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Uninstall message reword - 对用户的影响：Developers may fail before the first successful local run: Uninstall message reword - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/244 | Uninstall message reword ## 4. 安装坑 · 失败模式：installation: Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml - 对用户的影响：Developers may fail before the first successful local run: Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/272 | Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml ## 5. 安装坑 · 失败模式：installation: v0.7.0rc3 — soak-substrate (test trio + coverage gate) - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.7.0rc3 — soak-substrate (test trio + coverage gate) - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0rc3 — soak-substrate (test trio + coverage gate) - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc3 | v0.7.0rc3 — soak-substrate (test trio + coverage gate) ## 6. 安装坑 · 失败模式：installation: v0.7.6 — suspend-robust session hygiene - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.7.6 — suspend-robust session hygiene - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.6 — suspend-robust session hygiene - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.6 | v0.7.6 — suspend-robust session hygiene ## 7. 安装坑 · 失败模式：installation: v0.7.7 — prose supersession auto-detect - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this installation risk before relying on the project: v0.7.7 — prose supersession auto-detect - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.7 — prose supersession auto-detect - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.7 | v0.7.7 — prose supersession auto-detect ## 8. 安装坑 · 来源证据：Pre-existing ruff lint debt (66 errors) not caught by CI - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Pre-existing ruff lint debt (66 errors) not caught by CI - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/263 | 来源类型 github_issue 暴露的待验证使用条件。 ## 9. 安装坑 · 来源证据：Uninstall message reword - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Uninstall message reword - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/244 | 来源类型 github_issue 暴露的待验证使用条件。 ## 10. 安装坑 · 来源证据：Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Verify multi-version Python (3.10/3.12/3.13) + matrix.os on self-hosted AL2023 runner before repointing ci.yml - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/272 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 ## 11. 安装坑 · 来源证据：claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-o… - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-only - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/273 | 来源类型 github_issue 暴露的待验证使用条件。 ## 12. 配置坑 · 可能修改宿主 AI 配置 - 严重度：medium - 证据强度：source_linked - 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。 - 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 - 证据：capability.host_targets | https://github.com/nousergon/mnemon | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli ## 13. 配置坑 · 失败模式：configuration: Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/276 | Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only ## 14. 配置坑 · 失败模式：configuration: Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistin... - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance) - 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance) - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/274 | Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance) ## 15. 配置坑 · 失败模式：configuration: v0.7.0rc1 — salience tier Phase 1 + capture attention Phase A - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.7.0rc1 — salience tier Phase 1 + capture attention Phase A - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0rc1 — salience tier Phase 1 + capture attention Phase A - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc1 | v0.7.0rc1 — salience tier Phase 1 + capture attention Phase A ## 16. 配置坑 · 失败模式：configuration: v0.7.0rc4 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this configuration risk before relying on the project: v0.7.0rc4 - 对用户的影响：Upgrade or migration may change expected behavior: v0.7.0rc4 - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.7.0rc4 | v0.7.0rc4 ## 17. 配置坑 · 来源证据：Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Decide: wire nousergon/mnemon into fleet groomer BACKLOG_REPOS — or keep interactive-only - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/276 | 来源类型 github_issue 暴露的待验证使用条件。 ## 18. 能力坑 · 来源证据：README cold-start/latency note - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：README cold-start/latency note - 对用户的影响：可能增加新用户试用和生产接入成本。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/246 | 来源类型 github_issue 暴露的待验证使用条件。 ## 19. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://github.com/nousergon/mnemon | README/documentation is current enough for a first validation pass. ## 20. 维护坑 · 失败模式：migration: v0.6.0 - 严重度：medium - 证据强度：source_linked - 发现：Developers should check this migration risk before relying on the project: v0.6.0 - 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0 - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.6.0 | v0.6.0 ## 21. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://github.com/nousergon/mnemon | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://github.com/nousergon/mnemon | no_demo; severity=medium ## 23. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://github.com/nousergon/mnemon | no_demo; severity=medium ## 24. 安全/权限坑 · 来源证据：Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance) - 严重度：medium - 证据强度：source_linked - 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Stamp source_client server-side from MCP clientInfo — explicit MCP saves are surface-indistinguishable (NULL provenance) - 对用户的影响：可能影响升级、迁移或版本选择。 - 证据：community_evidence:github | https://github.com/nousergon/mnemon/issues/274 | 来源类型 github_issue 暴露的待验证使用条件。 ## 25. 能力坑 · 失败模式：capability: calibration `--use-fixture` `.json`→`.example.json` fallback - 严重度：low - 证据强度：source_linked - 发现：Developers should check this capability risk before relying on the project: calibration `--use-fixture` `.json`→`.example.json` fallback - 对用户的影响：Developers may hit a documented source-backed failure mode: calibration `--use-fixture` `.json`→`.example.json` fallback - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/236 | calibration `--use-fixture` `.json`→`.example.json` fallback ## 26. 运行坑 · 失败模式：performance: README cold-start/latency note - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: README cold-start/latency note - 对用户的影响：Developers may hit a documented source-backed failure mode: README cold-start/latency note - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/246 | README cold-start/latency note ## 27. 运行坑 · 失败模式：performance: claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snipp... - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-only - 对用户的影响：Developers may hit a documented source-backed failure mode: claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-only - 证据：failure_mode_cluster:github_issue | https://github.com/nousergon/mnemon/issues/273 | claude.ai chat surface never writes to mnemon — decide autonomous-save posture (Profile snippet) or document explicit-only ## 28. 运行坑 · 失败模式：performance: v0.6.0rc18 - 严重度：low - 证据强度：source_linked - 发现：Developers should check this performance risk before relying on the project: v0.6.0rc18 - 对用户的影响：Upgrade or migration may change expected behavior: v0.6.0rc18 - 证据：failure_mode_cluster:github_release | https://github.com/nousergon/mnemon/releases/tag/v0.6.0rc18 | v0.6.0rc18 ## 29. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://github.com/nousergon/mnemon | issue_or_pr_quality=unknown ## 30. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://github.com/nousergon/mnemon | release_recency=unknown