项目定位与设计理念

Memex 是一个面向"agent fleet"（智能体舰队）的个人知识运行时与共享记忆平面，既托管用户个人的知识资产（阅读过的文章、随手捕捉的笔记、跨文档合成），也充当多个 AI 智能体协同工作的持久记忆层。Memex 明确声明自身是 plugin-agnostic（插件无关）的：任何 Claude Code 插件都可以将自己的 SQLite 存储注册到 Memex 中，让文档流经同一套索引流水线。资料来源：README.md:1-7

仓库内的多数代码与 Claude Code 协作完成（commit 通常为 Co-Authored-By: Claude Opus … 形式），v2.0 的设计与实现计划已通过 git 历史在 2026-05-26 之前保存，并被收录进 Memex 自身以供回溯。资料来源：README.md:9-13

按照 CLAUDE.md 的分层约定，Memex 仓库属于 Layer 2（Skill Atelier 产品），框架本体（Layer 1）位于 skill-atelier/ 仓库；两者的提交路径严格分离。资料来源：CLAUDE.md:43-50

三层架构详解

Memex 由"一层主插件 + 三个逻辑层"组成。所有文档写入必须经过 Layer 2 的网关路径（Mandatory write-path gateway），不得绕过。

flowchart TB
    User[用户 / 插件] -->|自然语言意图| Run[memex:run 单点入口]
    Run --> Brain[Memex Brain<br/>ingest/ask/capture/lint/synthesize]
    Brain -->|write-path 网关| Index[Memex Index<br/>5 个内部智能体]
    Index -->|联邦元数据 + FTS5 + 向量| IndexDB[(index.db)]
    Brain -->|业务存储| ArticleDB[(article.db)]
    Index -->|raw 归档| Raw[(~/.memex/raw/)]
    Index -->|委派 CRUD| Core[Memex Core<br/>scripts/stores.py]
    Core -->|任意 SQLite 存储| Stores[(消费者 store 1..N)]
    Brain -.派生.-> Graph[GraphRAG 知识层<br/>similarity graph + communities + reports]
    CodeGraph[Code Graph<br/>code_graph.db] -.外部提取.-> Stores

Memex Brain（个人二级大脑）

Brain 是面向用户的"有态度的"（opinionated）技能层，对应五个核心动作：

• ingest：摄入外部文章/博文/论文等原始内容，路由经过 Archivist（保留原文）、Librarian 子智能体（分类并分配 index_id、关系），最终由 Memex Core 落库。同一规范化内容基于哈希重新执行时静默跳过。资料来源：internal/brain/ingest/SKILL.md:5-32
• capture：比 ingest 更轻量——没有源 URL、不归档原始内容，仅用于随手记录想法/观察，但仍通过 Librarian 子智能体做分类与关联。资料来源：internal/brain/capture/SKILL.md:5-20
• synthesize：在多个已有来源上生成带引用的统一叙述，并保存为新的 synthesis 文档，写回 synthesizes 关系到源 index_id；这是 Brain 中唯一两步 LLM 子智能体调度流程（Synthesizer + Librarian）。资料来源：internal/brain/synthesize/SKILL.md:5-25
• lint / ask：分别在评测与问答路径上提供"质量巡检"和"基于已索引内容的检索式问答"。

Memex Index + 5 内部智能体（强制写入网关）

Index 层提供跨存储的联邦元数据、FTS5 全文检索、可选的向量嵌入与跨存储关系，是所有文档写入必经的网关角色：

• Librarian：分类子智能体，根据目标 store、调用者、载荷与已有索引片段，输出包含 index_id、key、domain、searchable、metadata、relations 的 JSON。关系只能断言到已有 index_id，不得编造。资料来源：prompts/librarian.md:6-44
• Reference Librarian：将用户的自然语言提问转换为 JSON 查询计划（fts_query / vector_query / filters / limit）；歧义时返回 clarify 字段而非猜测。资料来源：prompts/reference_librarian.md:5-26
• Archivist：负责 raw 载荷的规范化、SHA-256 计算与写入 ~/.memex/raw/<hash-prefix>/<stem>-<hash8>.<ext>，幂等。资料来源：internal/index/archive/SKILL.md:5-21
• Database Administrator / Data Steward：维护 schema、迁移、跨存储一致性。

Memex Core（CRUD 基底）

Core 是最底层的"schema-agnostic CRUD 基底"：消费方提供 SQL 迁移文件，Memex 据此供应并托管任意 SQLite 存储。文档行写入推荐走 memex:index:write（经过 Librarian）；非文档表（lookup、配置、agents、roles）的插入走 memex:core:insert，最终落到 scripts/stores.py:insert(name, table, row)。资料来源：internal/core/insert/SKILL.md:5-10。同理，读取智能体档案走 scripts/agents/__init__.py:get_agent(db_path, agent_id)。资料来源：internal/core/get-agent/SKILL.md:5-10

派生子系统：Code Graph 与 GraphRAG

Code Graph（外部提取、纯 SQL 查询）

代码导航图存放在独立的 code_graph.db 中，由外部提取器（graphify）产出；Memex 自身不做任何 AST/源码解析（v2.10 起声明 EXTRACTOR-EXTERNAL）。Memex 负责入库（internal/codegraph/ingest、scripts/code_graph.py、db/code_graph.sql）并提供有界、确定性的查询 API：where_is、callers、dependencies、neighbors、module_map（位于 internal/codegraph/query），全部纯 SQL，零 LLM。资料来源：README.md:31-39

GraphRAG 社区摘要（派生知识层）

GraphRAG 是建立在已索引文档之上的派生层：

1. 相似度图：用规范化词集的 Jaccard 相似度构建无密钥（key-free）的词汇相似度图，无嵌入提供者也能运行。资料来源：internal/brain/graph-rebuild/SKILL.md:30-38
2. 社区检测：scripts/communities.py 做层次化社区检测。
3. 自底向上报告：由 Community Reporter 子智能体（prompts/community_reporter.md）按字符预算逐社区生成 {title, summary, rating, findings}，写入 index.db.community_reports，供 global-mode 问答使用。
4. 重建入口：通过 internal/brain/graph-rebuild（操作员手工触发）而非写入路径构建，保证 LLM 调用永远不在写路径上。资料来源：internal/brain/graph-rebuild/SKILL.md:5-22

单点入口、安装与可观测性

Memex 仅向 Claude Code 暴露一个技能 memex:run，它在 31 个内部过程之上做自然语言意图分发，使插件的技能描述占用严格保持在 Claude Code 的 1% 预算之内。资料来源：README.md:43-45

首次调用 memex:run 时，Step 0 检测缺失的 ~/.memex/，输出显式同意块（列出将要创建的内容）并提示 (y/n)；同意后会植入 5 个内部智能体种子、创建 article.db、写 registry.json。开发者也可以手动运行 python3 -m scripts.install。资料来源：README.md:54-77

可观测性方面，scripts/dashboard.py 以只读（mode=ro）方式汇总每个注册存储，并启动仅 loopback 的 stdlib HTTP 服务器提供单页 HTML 与 /api/summary JSON 端点——所有数据通过 textContent 渲染，绝不会因标题包含标记而执行脚本；非本地绑定需要显式 --allow-non-local。资料来源：scripts/dashboard.py:6-22

See Also

• 写入网关详解：prompts/librarian.md
• GraphRAG 重建与社区报告：internal/brain/graph-rebuild/SKILL.md
• 跨存储仪表盘：scripts/dashboard.py
• Layer 2 仓库约定与提交边界：CLAUDE.md

概述与分层定位

Memex 是一个面向 Claude Code 的"持久记忆层"插件，在 CLAUDE.md 中明确归类为 Layer 2（Skill Atelier 产品）：它不维护框架本身，所有运行时由 internal/.../SKILL.md 路由表与 scripts/agents/ 子代理派发器组成，并通过唯一的 Claude-Code 可见入口 memex:run 统一暴露能力，使技能描述占用严格控制在 1% 预算之内（README.md）。整体设计可归纳为三条原则：

1. 数据/指令分离：抓取、捕获、写入及 ask 返回的内容在 Librarian 写入路径上必须被结构化视为"数据而非指令"，以防御提示注入（CLAUDE.md）。
2. 写入优先、派生异步：文档写入永远走 Librarian；GraphRAG 相似图、社区、报告是派生维护层，绝不放在写路径上（internal/brain/graph-rebuild/SKILL.md）。
3. 可降级：派生层缺失时 global 模式返回 no_reports，local 返回空 seeds，错误被显式标注为"降级"而非失败（internal/brain/ask/SKILL.md）。

多库 SQLite 存储模式

Memex 的所有持久化集中在 ~/.memex/，由 scripts/paths.py 与 scripts/db.py 提供路径与连接工具，核心思路是"按职责拆分多库"——每个 store 拥有独立的 schema 与迁移账本：

派生层（相似图、社区、报告）虽驻留 index.db，但只通过显式重建触发：scripts.graph_build.build_graph() 用归一化 token 集合的 Jaccard 相似度绘制 similar_to 边，因此无需任何嵌入提供方即可工作（internal/brain/graph-rebuild/SKILL.md）。这种"key-free lexical graph"使 Memex 在没有外部 API key 的环境下依然能跑全局检索。

写入与查询数据流

写入路径的入口包括 memex:brain:ingest、memex:brain:capture、memex:brain:synthesize 三种意图，全部经 Librarian 子代理完成分类与去重（scripts/brain.py、internal/brain/capture/SKILL.md、internal/brain/synthesize/SKILL.md）。其中 synthesize 是唯一拥有两次 LLM 派发的脑流：Synthesizer 产出正文，Librarian 再将其分类为新文档并自动追加 synthesizes 关系。Community reporter 则按"自底向上、按预算滚动"的策略生成每个社区的结构化报告，写入 index.db.community_reports（internal/brain/community-report/SKILL.md）。

查询路径由 memex:brain:ask 承担，三种模式对应不同检索策略（internal/brain/ask/SKILL.md）：

• direct — Reference Librarian 子代理输出 JSON 查询计划（FTS5 + 向量 + 过滤器），Python 执行（scripts/agents/reference_librarian.py）。
• global — 对 community_reports 做 map-reduce：每个报告交给 haiku 子代理打分（0–100），零分丢弃，按分数降序装入预算。
• local — 以向量余弦选种子文档，沿 relations 扩展邻域，挂上种子所在社区的报告再作答。

整体流程可概括为：用户意图 → memex:run 路由 → Librarian 写入 stores →（异步）派生图与社区报告 → 三种 ask 模式汇总输出。

仪表盘、迁移与 v1 升级

memex:steward:dashboard 提供只读本地 Web 仪表盘，递归枚举 ~/.memex/ 下所有 store 并以 JSON 汇总；/api/search 在三类表面（Documents/Agents/Code）上做关键字搜索，结果按类型分组（internal/steward/dashboard/SKILL.md）。Overlay 渲染 Markdown 时使用依赖自由的 DOM 构造器——createElement + textContent，绝不把文档文本塞入 innerHTML——使对抗性输入只能渲染为静态文本。

模式演化由 scripts/stores.py 的迁移运行器负责；v2.12.2 修复了"账本落后于实际 schema"导致的 duplicate column name 崩溃，使运行器具备自愈能力。从 v1 升级则走 scripts/upgrade_from_v1.py：探测 v1 安装、把 .ai/ 复制到 legacy/v1-wiki/（保留 symlink、对悬挂 symlink 容错）、写入 legacy/upgrade-log.md，全流程绝不覆盖现有数据。

常见失败模式

• 派生层陈旧：global/local ask 主题看似过时，应运行 internal/brain/graph-rebuild 重建（internal/brain/ask/SKILL.md）。
• 迁移账本与 schema 不同步：v2.12.2 之前表现为 duplicate column name；之后运行器自愈，但若新 store 出现该错误仍应检查 migrations 表（scripts/stores.py）。
• 嵌入提供方不可用：相似图基于词汇 Jaccard，问答可继续运行（精度下降）；向量查询则被跳过（internal/brain/graph-rebuild/SKILL.md）。
• 提示注入：抓取到的目标仓库 CLAUDE.md 永远是被研究的数据，绝不会被解释为覆盖 memex 的 M-规则（CLAUDE.md）。

See Also

• Brain 文档
• Core 文档
• Index 文档
• Packaging 文档

概述

Memex 是一个面向 Claude Code 的"持久记忆"插件，其核心由一组内部代理（internal agents）和一个联邦索引（federated index）共同构成。31 个内部过程统一通过单条 Claude Code 可见的 memex:run 技能调度，但写入、检索、归档、健康检查等职责由五个常驻子代理承担 资料来源：[README.md] 资料来源：[CLAUDE.md]。所有代理都遵守 *extractor-external* 原则——不解析源码、不抓取网页，只消费已经结构化的载荷（payload），再写入或读取同一个 SQLite 数据库 ~/.memex/index.db 资料来源：[CLAUDE.md] 资料来源：[scripts/agents/reference_librarian.py]。

五个内部代理的职责划分

scripts/agents/ 目录下注册了五个核心子代理；它们由 scripts/_internal_agents_seed.py 写入联邦索引的"代理档案表"，自 v2.17.0 起仪表盘关键词搜索会把它们与文档、代码图谱一起呈现（Documents / Agents / Code 三组聚合）资料来源：[社区讨论 v2.17.0]。

Librarian 的契约细节定义在 prompts/librarian.md：子代理必须输出 searchable 文本供 FTS5 索引，且 relations 只能引用 existing_index_snippet 中真实存在的 index_id——禁止编造 资料来源：[prompts/librarian.md]。当 payload["body"] 超过 char_budget 时，librarian._bound_payload_body 会做有界截断并写入 body_truncated=True / body_full_chars 标记，让下游 LLM 知道正文被截断 资料来源：[scripts/agents/librarian.py]。

Reference Librarian 把 ask 流程拆成两阶段：阶段一 ask_prepare 用 reference_librarian.md 模板生成子代理提示词；阶段二 ask_execute 执行返回的 JSON 查询计划（fts_query / vector_query / filters / limit），返回排序后的命中 资料来源：[scripts/agents/reference_librarian.py] 资料来源：[prompts/reference_librarian.md]。在 v2.17.0 之前，这一表面只能搜文档；现在五个代理档案本身也可被同样的关键词检索 资料来源：[社区讨论 v2.17.0]。

Synthesizer 与 Community Reporter 不属于常驻五代理，但同样消费联邦索引：前者从多个 index_id 合成主题文章（2–6 段散文 资料来源：[prompts/synthesizer.md]），后者按 GraphRAG 社区产出 title / summary / rating / findings JSON，自底向上滚动生成报告 资料来源：[prompts/community_reporter.md] 资料来源：[internal/brain/community-report/SKILL.md]。

联邦索引的结构

~/.memex/index.db 是 Memex 的唯一事实源，由若干逻辑表拼接而成 资料来源：[internal/brain/graph-rebuild/SKILL.md] 资料来源：[scripts/agents/community_reporter.py]：

• 文档表（articles / captures / syntheses 等）——每行带 searchable 字段，FTS5 虚表以 MATCH 提供全文检索。
• 关系表 relations——开放动词集合，其中 similar_to 边由 graph_build.build_graph 用 Jaccard 词面相似度批量生成，无需嵌入、无需 API 密钥 资料来源：[internal/brain/graph-rebuild/SKILL.md]。
• 社区表 communities / community_members / community_reports——report_prepare 给出 community_id 的预算上下文，subagent 输出 title / summary / rating / findings，Python 持久化并写一份 summary 嵌入（embedding 不可用时容错）资料来源：[scripts/agents/community_reporter.py]。
• 代理档案表——由 _internal_agents_seed.py 初始化，记录五个代理的 name / profile / default caller_agent_id；仪表盘搜索的 *Agents* 表面就来自这张表 资料来源：[scripts/_internal_agents_seed.py] 资料来源：[社区讨论 v2.17.0]。

派生层（关系边、社区、社区报告）不在写路径上——它们由 memex:brain:graph-rebuild 按需重建，以避免每次写入都触发 LLM 调用 资料来源：[internal/brain/graph-rebuild/SKILL.md]。

代理与索引的协同工作流

下面以 memex:run ask "..." 为例，展示五个代理与联邦索引的端到端交互：

sequenceDiagram
    participant U as 用户
    participant R as memex:run 路由
    participant RL as Reference Librarian
    participant DB as index.db (FTS5 + vector)
    participant LR as Librarian
    participant CR as Community Reporter
    U->>R: "我在哪里写过 GraphRAG？"
    R->>RL: ask_prepare(query)
    RL-->>R: subagent_prompt (JSON 查询计划)
    RL->>DB: ask_execute (FTS5 + cosine)
    DB-->>RL: 排序后的命中
    alt global 模式
        RL->>CR: parse_map_response / community_reports
        CR-->>RL: map-reduce score 0-100
    end
    RL-->>U: 合成答案 + 引用
    Note over LR,DB: 写路径只走 Librarian；<br/>graph / community_reports 由 graph-rebuild 派生

资料来源：internal/brain/ask/SKILL.md] scripts/agents/reference_librarian.py] internal/brain/community-report/SKILL.md]

global 模式遍历 community_reports（按 rating DESC 排序 资料来源：[scripts/brain.py]）；local 模式以余弦种子文档向外扩展 relations 邻域，并附带种子所属社区的摘要 资料来源：[internal/brain/ask/SKILL.md]。

常见失败模式

1. 关系越界——Librarian 引用了不存在的 index_id；修复方式是确保 existing_index_snippet 至少给出 20 条相关上下文供 LLM 选择 资料来源：[prompts/librarian.md]。
2. 上下文爆栈——长 body 让分类子代理超时；librarian._bound_payload_body 会显式截断并打 body_truncated 标记 资料来源：[scripts/agents/librarian.py]。
3. 派生层陈旧——global / local 模式返回 no_reports 或空种子时，应先 memex:brain:graph-rebuild 再问，而非把它放回写路径 资料来源：[internal/brain/ask/SKILL.md] 资料来源：[internal/brain/graph-rebuild/SKILL.md]。
4. 模型层错配——scripts/agents/community_reporter.py 强制使用 claude-haiku-4-5（社区报告是机械抽取），Librarian 强制 claude-sonnet-4-6；tests/test_model_tier_dispatch.py 防止悄悄回退到 Opus 主模型 资料来源：[internal/brain/community-report/SKILL.md] 资料来源：[internal/brain/capture/SKILL.md]。

See Also

• Memex 仪表盘、3D 知识图谱与三组搜索面（v2.13–v2.17）
• GraphRAG 相似图、社区检测与社区报告
• Librarian 写路径与 ingestion / capture / synthesize 流程
• Memex 升级与 v1 → v2 迁移

概述

Memex 在 v2.13 至 v2.17 五个版本中新增了三类紧密耦合的可视化与查询子系统：本地只读 Dashboard、3D 知识图谱视图、以及外部抽取、Memex 内只读托管的代码图 (Code Graph)。三者共享同一组只读 SQLite store，并由同一个 loopback HTTP 服务器对外提供页面与 JSON 接口；Dashboard 不修改任何 store，因此不构成 Librarian 写路径的旁路。资料来源：internal/steward/dashboard/SKILL.md:1-30 README.md:1-30

Memex Dashboard (`memex:steward:dashboard`)

Dashboard 由 memex:steward:dashboard 技能触发，背后实现是 scripts/dashboard.py。设计上有四条硬性约束：仅使用 Python 标准库 (http.server + sqlite3 + json，不引入 Flask/FastAPI/jinja)；以 mode=ro 打开所有已注册 store，因此对 M3（Librarian 写路径）不可见；默认绑定 127.0.0.1，只有显式传入 --allow-non-local 才允许非本地监听；HTML 模板是静态资源、所有数据通过 textContent 渲染，文档标题里的标记不会成为脚本。资料来源：scripts/dashboard.py:1-30 internal/steward/dashboard/SKILL.md:1-20

汇总页面聚合以下维度：每个已注册 store 的行数、联邦索引按 domain/store/author 分布、关系图、嵌入覆盖率、摄取时间线、知识社区、Brain captures、代码导航图以及 agent 注册表；/api/summary 暴露 JSON 摘要供前端拉取。任一 store 缺失时聚合层防御性跳过而非抛出。HTTP 端口默认 8765，被占用则 +1 自动递增，最多 +20 次尝试。资料来源：internal/steward/dashboard/SKILL.md:1-30 scripts/dashboard.py:1-30

3D 知识图谱视图

/graph 路由暴露一个 Obsidian 风格的 3D 知识图谱：文档为节点、关系为边、按 GraphRAG community 上色。鼠标拖拽旋转、滚轮或捏合缩放、悬停展示元信息，点击节点弹出 Markdown 渲染后的内容（v2.16 起）。资料来源：README.md:1-30 internal/steward/dashboard/SKILL.md:1-30

图本体由 internal/brain/graph-rebuild 维护，核心算法在 scripts.graph_build.build_graph()：对每个文档的 searchable 字段做归一化 token 集合的 Jaccard 相似度，无需 embedding provider 与 API key，再用 scripts.communities.detect_communities 做层次化社区检测，最后由 internal/brain/community-report 自底向上生成社区报告写入 index.db.community_reports。GraphRAG 是派生层——不放在每次写入路径上，批写入之后通过维护入口按需重算。资料来源：internal/brain/graph-rebuild/SKILL.md:1-40

社区报告由 Community Reporter 子代理（参见 prompts/community_reporter.md）在字符预算内汇总成员文档与子社区 rolled-up 摘要，输出 {title, summary, rating, findings}，所有结论必须严格基于提供的素材。资料来源：prompts/community_reporter.md:1-30

关键词搜索与点击阅读

v2.15 在 Dashboard 顶部引入搜索框：对联邦索引优先做 FTS5 排序，失败回退到 LIKE 模糊匹配并高亮片段。点击结果或点击 3D 图节点会打开内容 overlay，v2.16 之后 overlay 把文档内容渲染为 Markdown（标题、粗体/斜体、行内与围栏代码、列表、引用、分割线、链接以及 GFM 表格），点击 overlay 外部即可关闭。资料来源：internal/steward/dashboard/SKILL.md:1-30

v2.17 进一步把搜索面扩展到三类，按组展示结果：documents（联邦索引 FTS5 + LIKE）、agents（agent 注册表）、code（code_graph.db 中的节点/边）。新增的 code 类来源于外部抽取器 graphify 产出、再由 internal/codegraph/ingest 导入的代码图。资料来源：internal/steward/dashboard/SKILL.md:1-30 internal/codegraph/ingest/SKILL.md:1-30

代码图 (Code Graph)

代码图是一个独立 store (code_graph.db)，schema 在 db/code_graph.sql。Memex 坚持 EXTRACTOR-EXTERNAL 原则：不进行任何源码/AST 解析，由消费者插件 (kaizen、atelier) 通过 graphify 抽取，Memex 仅负责导入与查询；查询接口 (scripts/code_graph.py) 是纯 SQL、无 LLM：提供 where_is、callers、dependencies、neighbors、module_map 等确定性、有界结果集的查询。资料来源：README.md:1-30 db/code_graph.sql:1-30

v2.10 起 schema 增加 docstring-presence 字段，仅作为前向兼容存储——Memex 不会自己计算该信号，因此严格遵守 EXTRACTOR-EXTERNAL 约束；Dashboard 把它当作只读信号透出给用户。资料来源：README.md:1-30

常见失效模式

• 端口占用：默认 8765 被占用时自动 +1 递增（最多 +20），仍失败则启动失败；非本地访问必须显式 --allow-non-local。资料来源：internal/steward/dashboard/SKILL.md:1-30
• store 缺失：聚合层防御性跳过缺失 store，UI 显示空分区而非崩溃。资料来源：scripts/dashboard.py:1-30
• GraphRAG 陈旧：global/local 模式 ask 返回的主题若过时，需要在批写入后运行 memex:brain:graph-rebuild 重算图/社区/报告。资料来源：internal/brain/graph-rebuild/SKILL.md:1-40
• 代码图抽取漂移：Memex 不解析源码——任何 docstring-presence 等信号必须由上游 graphify 计算并随图一起导入，否则 schema 字段保持为空。

See Also

• USER_GUIDE.md — 安装与日常使用
• internal/brain/community-report/SKILL.md — 社区报告子流程
• internal/core/insert/SKILL.md — 非文档表的写入路径
• README.md — Memex 三层架构与代码图总览

Pitfall Log / 踩坑日志

项目：nitekeeper/memex

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 失败模式：installation: v2.10.0。

1. 安装坑 · 失败模式：installation: v2.10.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.10.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.10.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.10.0 | v2.10.0

2. 安装坑 · 失败模式：installation: v2.11.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.11.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.11.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.11.0 | v2.11.0

3. 安装坑 · 失败模式：installation: v2.12.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.12.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.12.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.12.0 | v2.12.0

4. 安装坑 · 失败模式：installation: v2.16.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: v2.16.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.16.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.16.0 | v2.16.0

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

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

6. 配置坑 · 失败模式：configuration: v2.13.0

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: v2.13.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.13.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.13.0 | v2.13.0

7. 能力坑 · 能力判断依赖假设

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

8. 维护坑 · 失败模式：migration: v2.12.2

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: v2.12.2
• 对用户的影响：Upgrade or migration may change expected behavior: v2.12.2
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.12.2 | v2.12.2

9. 维护坑 · 维护活跃度未知

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/nitekeeper/memex | no_demo; severity=medium

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

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

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

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

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

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

14. 维护坑 · 失败模式：maintenance: v2.12.1

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.12.1
• 对用户的影响：Upgrade or migration may change expected behavior: v2.12.1
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.12.1 | v2.12.1

15. 维护坑 · 失败模式：maintenance: v2.14.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.14.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.14.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.14.0 | v2.14.0

16. 维护坑 · 失败模式：maintenance: v2.15.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.15.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.15.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.15.0 | v2.15.0

17. 维护坑 · 失败模式：maintenance: v2.17.0

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.17.0
• 对用户的影响：Upgrade or migration may change expected behavior: v2.17.0
• 证据：failure_mode_cluster:github_release | https://github.com/nitekeeper/memex/releases/tag/v2.17.0 | v2.17.0