# https://github.com/nitekeeper/memex 项目说明书

生成时间：2026-06-27 01:47:45 UTC

## 目录

- [Memex 概览与三层架构](#page-overview)
- [系统架构、数据库模式与数据流程](#page-architecture)
- [五个内部代理与联邦索引](#page-agents)
- [Memex Dashboard、3D 知识图谱与代码图](#page-dashboard)

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

## Memex 概览与三层架构

### 相关页面

相关主题：[系统架构、数据库模式与数据流程](#page-architecture)

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

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

- [README.md](https://github.com/nitekeeper/memex/blob/main/README.md)
- [CLAUDE.md](https://github.com/nitekeeper/memex/blob/main/CLAUDE.md)
- [skills/README.md](https://github.com/nitekeeper/memex/blob/main/skills/README.md)
- [internal/brain/ingest/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/ingest/SKILL.md)
- [internal/brain/capture/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/capture/SKILL.md)
- [internal/brain/synthesize/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/synthesize/SKILL.md)
- [internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/graph-rebuild/SKILL.md)
- [internal/brain/community-report/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/community-report/SKILL.md)
- [internal/core/insert/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/core/insert/SKILL.md)
- [internal/core/get-agent/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/core/get-agent/SKILL.md)
- [internal/index/archive/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/index/archive/SKILL.md)
- [prompts/librarian.md](https://github.com/nitekeeper/memex/blob/main/prompts/librarian.md)
- [prompts/reference_librarian.md](https://github.com/nitekeeper/memex/blob/main/prompts/reference_librarian.md)
- [prompts/community_reporter.md](https://github.com/nitekeeper/memex/blob/main/prompts/community_reporter.md)
- [prompts/synthesizer.md](https://github.com/nitekeeper/memex/blob/main/prompts/synthesizer.md)
- [scripts/dashboard.py](https://github.com/nitekeeper/memex/blob/main/scripts/dashboard.py)
</details>

# Memex 概览与三层架构

## 项目定位与设计理念

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），不得绕过。

| 层级 | 名称 | 主要职责 | 关键存储 | 关键技能 / 脚本 |
|---|---|---|---|---|
| Layer 2 | **Memex Brain** | 二级大脑（second-brain）技能层：ingest、ask、capture、lint、synthesize | `~/.memex/article.db` | `internal/brain/*`（如 [ingest/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/ingest/SKILL.md)） |
| Layer 2 | **Memex Index + 5 内部智能体** | 联邦元数据、FTS5 全文检索、向量嵌入、跨存储关系 | `~/.memex/index.db` | Librarian、Reference Librarian、Archivist、DBA、Data Steward；提示词在 [prompts/](https://github.com/nitekeeper/memex/blob/main/prompts/librarian.md) |
| Layer 2 | **Memex Core** | CRUD 基底：从消费方提供的 SQL 迁移文件供应并托管任意 SQLite 存储；schema 无关 | 任意注册的 SQLite 存储 | `scripts/stores.py`；行插入走 [internal/core/insert/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/core/insert/SKILL.md) |

```mermaid
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](https://github.com/nitekeeper/memex/blob/main/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](https://github.com/nitekeeper/memex/blob/main/prompts/librarian.md)
- GraphRAG 重建与社区报告：[internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/graph-rebuild/SKILL.md)
- 跨存储仪表盘：[scripts/dashboard.py](https://github.com/nitekeeper/memex/blob/main/scripts/dashboard.py)
- Layer 2 仓库约定与提交边界：[CLAUDE.md](https://github.com/nitekeeper/memex/blob/main/CLAUDE.md)

---

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

## 系统架构、数据库模式与数据流程

### 相关页面

相关主题：[五个内部代理与联邦索引](#page-agents)

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

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

- [scripts/db.py](https://github.com/nitekeeper/memex/blob/main/scripts/db.py)
- [scripts/stores.py](https://github.com/nitekeeper/memex/blob/main/scripts/stores.py)
- [scripts/paths.py](https://github.com/nitekeeper/memex/blob/main/scripts/paths.py)
- [scripts/brain.py](https://github.com/nitekeeper/memex/blob/main/scripts/brain.py)
- [scripts/upgrade_from_v1.py](https://github.com/nitekeeper/memex/blob/main/scripts/upgrade_from_v1.py)
- [scripts/agents/reference_librarian.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/reference_librarian.py)
- [db/agents.sql](https://github.com/nitekeeper/memex/blob/main/db/agents.sql)
- [db/index.sql](https://github.com/nitekeeper/memex/blob/main/db/index.sql)
- [db/code_graph.sql](https://github.com/nitekeeper/memex/blob/main/db/code_graph.sql)
- [README.md](https://github.com/nitekeeper/memex/blob/main/README.md)
- [CLAUDE.md](https://github.com/nitekeeper/memex/blob/main/CLAUDE.md)
- [internal/brain/ask/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/ask/SKILL.md)
- [internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/graph-rebuild/SKILL.md)
- [internal/brain/capture/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/capture/SKILL.md)
- [internal/brain/synthesize/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/synthesize/SKILL.md)
- [internal/brain/community-report/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/community-report/SKILL.md)
- [internal/steward/dashboard/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/steward/dashboard/SKILL.md)
</details>

# 系统架构、数据库模式与数据流程

## 概述与分层定位

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

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

## 多库 SQLite 存储模式

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

| 库文件 | 主要职责 | 关键表（部分） |
|---|---|---|
| `index.db` | Brain 全局联合索引（主入口） | `articles`、`relations`（含 `similar_to`）、`communities`、`community_members`、`community_reports`、`code_graph`（v2.10.0 新增 docstring 信号列） |
| `article.db` | 抓取/合成的文章正文与元数据 | `articles`、`syntheses` |
| `captures.db` | 用户自由笔记 | `captures` |
| `agents.db` | 代理/角色注册表 | `agents`、`roles`（[db/agents.sql](https://github.com/nitekeeper/memex/blob/main/db/agents.sql)） |
| 各 store 的 `migrations` | Schema 版本账本 | 跟踪模式演化 |

派生层（相似图、社区、报告）虽驻留 `index.db`，但**只通过显式重建触发**：`scripts.graph_build.build_graph()` 用归一化 token 集合的 Jaccard 相似度绘制 `similar_to` 边，因此无需任何嵌入提供方即可工作（[internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/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](https://github.com/nitekeeper/memex/blob/main/scripts/brain.py)、[internal/brain/capture/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/capture/SKILL.md)、[internal/brain/synthesize/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/synthesize/SKILL.md)）。其中 `synthesize` 是唯一拥有**两次** LLM 派发的脑流：Synthesizer 产出正文，Librarian 再将其分类为新文档并自动追加 `synthesizes` 关系。Community reporter 则按"自底向上、按预算滚动"的策略生成每个社区的结构化报告，写入 `index.db.community_reports`（[internal/brain/community-report/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/community-report/SKILL.md)）。

查询路径由 `memex:brain:ask` 承担，三种模式对应不同检索策略（[internal/brain/ask/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/ask/SKILL.md)）：

- **`direct`** — Reference Librarian 子代理输出 JSON 查询计划（FTS5 + 向量 + 过滤器），Python 执行（[scripts/agents/reference_librarian.py](https://github.com/nitekeeper/memex/blob/main/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](https://github.com/nitekeeper/memex/blob/main/internal/steward/dashboard/SKILL.md)）。Overlay 渲染 Markdown 时使用依赖自由的 DOM 构造器——`createElement` + `textContent`，绝不把文档文本塞入 `innerHTML`——使对抗性输入只能渲染为静态文本。

模式演化由 [scripts/stores.py](https://github.com/nitekeeper/memex/blob/main/scripts/stores.py) 的迁移运行器负责；v2.12.2 修复了"账本落后于实际 schema"导致的 `duplicate column name` 崩溃，使运行器具备自愈能力。从 v1 升级则走 [scripts/upgrade_from_v1.py](https://github.com/nitekeeper/memex/blob/main/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](https://github.com/nitekeeper/memex/blob/main/internal/brain/ask/SKILL.md)）。
- **迁移账本与 schema 不同步**：v2.12.2 之前表现为 `duplicate column name`；之后运行器自愈，但若新 store 出现该错误仍应检查 `migrations` 表（[scripts/stores.py](https://github.com/nitekeeper/memex/blob/main/scripts/stores.py)）。
- **嵌入提供方不可用**：相似图基于词汇 Jaccard，问答可继续运行（精度下降）；向量查询则被跳过（[internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/graph-rebuild/SKILL.md)）。
- **提示注入**：抓取到的目标仓库 `CLAUDE.md` 永远是被研究的数据，绝不会被解释为覆盖 memex 的 M-规则（[CLAUDE.md](https://github.com/nitekeeper/memex/blob/main/CLAUDE.md)）。

## See Also

- [Brain 文档](https://github.com/nitekeeper/memex/blob/main/docs/BRAIN.md)
- [Core 文档](https://github.com/nitekeeper/memex/blob/main/docs/CORE.md)
- [Index 文档](https://github.com/nitekeeper/memex/blob/main/docs/INDEX.md)
- [Packaging 文档](https://github.com/nitekeeper/memex/blob/main/docs/PACKAGING.md)

---

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

## 五个内部代理与联邦索引

### 相关页面

相关主题：[Memex Dashboard、3D 知识图谱与代码图](#page-dashboard)

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

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

- [scripts/_internal_agents_seed.py](https://github.com/nitekeeper/memex/blob/main/scripts/_internal_agents_seed.py)
- [scripts/agents/librarian.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/librarian.py)
- [scripts/agents/reference_librarian.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/reference_librarian.py)
- [scripts/agents/archivist.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/archivist.py)
- [scripts/agents/dba.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/dba.py)
- [scripts/agents/data_steward.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/data_steward.py)
- [scripts/agents/community_reporter.py](https://github.com/nitekeeper/memex/blob/main/scripts/agents/community_reporter.py)
- [internal/brain/ask/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/ask/SKILL.md)
- [internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/graph-rebuild/SKILL.md)
- [internal/brain/community-report/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/community-report/SKILL.md)
- [prompts/librarian.md](https://github.com/nitekeeper/memex/blob/main/prompts/librarian.md)
- [prompts/reference_librarian.md](https://github.com/nitekeeper/memex/blob/main/prompts/reference_librarian.md)
- [prompts/community_reporter.md](https://github.com/nitekeeper/memex/blob/main/prompts/community_reporter.md)
- [prompts/synthesizer.md](https://github.com/nitekeeper/memex/blob/main/prompts/synthesizer.md)
- [README.md](https://github.com/nitekeeper/memex/blob/main/README.md)
- [CLAUDE.md](https://github.com/nitekeeper/memex/blob/main/CLAUDE.md)
</details>

# 五个内部代理与联邦索引

## 概述

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 | `scripts/agents/librarian.py` | 把外部载荷分类为 `index_id / key / domain / searchable / metadata / relations`，是**写路径**的契约 | `memex:brain:ingest` / `capture` / `synthesize` |
| Reference Librarian | `scripts/agents/reference_librarian.py` | 把自然语言问句翻译成 FTS5 + 向量查询计划，并分 `ask_prepare` / `ask_execute` 两阶段执行 | `memex:brain:ask`（local / global） |
| Archivist | `scripts/agents/archivist.py` | 归档、迁移与 v1 升级路径兼容 | 升级与归档类 `memex:run` 意图 |
| DBA | `scripts/agents/dba.py` | 管理多 store SQLite schema、迁移 runner 自愈 | `scripts/stores.py`、安装与升级流程 |
| Data Steward | `scripts/agents/data_steward.py` | 联邦索引的一致性、去重与质量监控 | 仪表盘后台、stale 检测 |

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 "..."` 为例，展示五个代理与联邦索引的端到端交互：

```mermaid
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 迁移](#)

---

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

## Memex Dashboard、3D 知识图谱与代码图

### 相关页面

相关主题：[系统架构、数据库模式与数据流程](#page-architecture)

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

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

- [scripts/dashboard.py](https://github.com/nitekeeper/memex/blob/main/scripts/dashboard.py)
- [internal/steward/dashboard/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/steward/dashboard/SKILL.md)
- [internal/brain/graph-rebuild/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/graph-rebuild/SKILL.md)
- [README.md](https://github.com/nitekeeper/memex/blob/main/README.md)
- [internal/codegraph/ingest/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/codegraph/ingest/SKILL.md)
- [db/code_graph.sql](https://github.com/nitekeeper/memex/blob/main/db/code_graph.sql)
- [prompts/community_reporter.md](https://github.com/nitekeeper/memex/blob/main/prompts/community_reporter.md)
</details>

# Memex Dashboard、3D 知识图谱与代码图

## 概述

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]()

| 版本 | 新增能力 |
| --- | --- |
| v2.13.0 | 启动 Dashboard：`memex:steward:dashboard` + `scripts/dashboard.py` |
| v2.14.0 | `/graph` 3D 知识图谱视图（Obsidian 风格） |
| v2.15.0 | 关键词搜索框 + 点击阅读 overlay |
| v2.16.0 | overlay Markdown 渲染、点击外部关闭 |
| v2.17.0 | 搜索跨 Documents / Agents / Code 三类分组 |

## 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](https://github.com/nitekeeper/memex/blob/main/USER_GUIDE.md) — 安装与日常使用
- [internal/brain/community-report/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/brain/community-report/SKILL.md) — 社区报告子流程
- [internal/core/insert/SKILL.md](https://github.com/nitekeeper/memex/blob/main/internal/core/insert/SKILL.md) — 非文档表的写入路径
- [README.md](https://github.com/nitekeeper/memex/blob/main/README.md) — Memex 三层架构与代码图总览

---

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

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: nitekeeper/memex; human_manual_source: deepwiki_human_wiki -->