XERJ Second Brain 完整复现指南:`xerj brain` 一键把你的笔记变成可检索、可回放的知识图谱
XERJ Second Brain 完整复现指南:xerj brain 一键把你的笔记变成可检索、可回放的知识图谱
本篇指南基于 XERJ 仓库 docs/usecases/second-brain/REPRODUCE.md 展开。它以仓库自身的 docs/ 目录为语料,从零复现"第二大脑"(second brain)完整流程:构建、启动、链接检测、证据校验、退役重放、仪表盘验证、MCP Agent 接口与测试套件。读完本文,你将掌握 xerj brain 的完整命令行操作、退出码语义、四个图 API 端点的调用方式,以及如何用自动化脚本验证"每条链接都有证据、任何时刻都可回放"这两条核心承诺。
前置概念:什么是 XERJ 的 second brain
XERJ 对 second brain 的定位非常克制:它不理解你的笔记,只把你已经写下的结构变成可查询、带时间戳、带证据的关系层。xerj brain <folder> 是一个命令把笔记文件夹变成可查询的知识图谱——单一静态二进制、无需图数据库、无 LLM、无 embedding 服务、零配置,控制台仪表盘展示"你的笔记相信什么",MCP 接口给 Agent 同样的四个动词。
这份定位写进了 API 模块的模块文档(engine/crates/xerj-api/src/graph_api.rs):
This is not a graph database. There is no query language, no shortest-path, no PageRank, and no unbounded traversal — by design. Edges are ordinary documents; expansion is a bounded, batched read (≤2 hops per call).
也就是:边(edge)是普通文档,遍历是有上限、批量、列式(columnar)的读取,不是图查询语言。这个边界是整个功能的设计骨架,复现时你会在 hops > 2 得到 400 报错处再次看到它。
0. 构建(限定 crate,绝不 workspace 全量)
xerj brain 依赖六个 crate。按 REPRODUCE.md 原文,构建必须限定范围:
cd $REPO/engine
cargo build --release -j 32 -p xerj-engine -p xerj-api -p xerj-autoindex \
-p xerj-console-api -p xerj-server -p xerj-mcp
其中 $REPO 是仓库根目录,$DATA 是用于存放脑服务器数据的新建空目录。构建约束"scoped — never workspace-wide"与实现契约 SECOND_BRAIN_SPEC.md 第 0 节中的流所有权(stream ownership)规则一致:每个流只允许触碰自己名下的文件,构建同样限定 crate。
1. 运行 brain:一条命令到就绪
DATA=$(mktemp -d)
$REPO/engine/target/release/xerj brain $REPO/docs \
--url http://localhost:9340 --data-dir "$DATA" --no-open
预期输出形态(数值随当前 docs/ 状态变化,不变量是幂等、证据、回放):
brain 'docs': 121 files (5 MB) under …/docs
booted xerj server (pid …) — data: …/data
phase A: 7 datasets inferred, 14 junk/skipped files
phase B: indexing 106 files with 8 workers → http://localhost:9340
✓ your second brain is ready — 121 files, 364 links, 0.7s
→ http://localhost:9340/_xerj-console/#/second-brain?brain=docs
退出码语义
0ready(就绪);3ready-with-junk(不可读文件被记录但绝不致命——该语料包含图片和二进制,预期会出现);1无内容可索引 / 服务器失败;2用法错误。
退出码的实现在 engine/crates/xerj-server/src/brain.rs 的帮助文本中同样被声明为契约。而"ready-with-junk"的场景在 README.md 的真实运行记录里就是实测值:121 个文件中有 14 个(图片、二进制、一个被嗅探器误判的 YAML-frontmatter markdown)被跳过而非索引,退出码为 3。
幂等性检查
再次运行完全相同的命令:必须附加(attach)到已在运行的服务器、快速收敛(该语料实测 0.14 s)、退出 0、链接数不增长。这条承诺的底层机制在 SECOND_BRAIN_SPEC.md 第 6.4 节:检测器边的 valid_at 取自源文件 mtime,未变化文件重跑会重放出完全相同的 edge_id,bulk index 覆盖而非重复——因此重跑收敛、kill -9 也安全。端到端测试 engine/crates/xerj-server/tests/brain_cli.rs 正是断言"run 2 附加到运行中的服务器、边集合与 run 1 字节一致"。
认证:admin.key
启动的服务器在 $DATA/admin.key 维护自己的 admin key,下面所有直接 HTTP 调用都需要它:
AUTH="Authorization: ApiKey $(cat "$DATA/admin.key")"
认证模型在 graph_api.rs 中有完整说明:brain 即边界(issue #79),ego/overview 需要 read,link/unlink 需要 write;open 模式与 admin key 拿到所有 brain,未在 role_descriptors 中命名该边索引的 key 拿不到任何 brain。
xerj brain 的 CLI 选项
从 brain.rs 的帮助文本可看到完整选项表:
| 选项 | 含义 | 默认值 |
|---|---|---|
--brain <NAME> |
brain 名(成为 URL 一部分) | 文件夹名派生(derive_brain_name),非法时需显式指定 |
--url <U> |
要使用的服务器 | http://localhost:9200;只有本地 localhost URL 且无监听时才启动新服务器 |
--data-dir <PATH> |
新启动服务器的数据与日志目录 | ~/.xerj/brain |
--api-key <K> |
已运行安全服务器的 API key(或环境变量 XERJ_API_KEY) |
本命令启动的服务器无需传入,key 从 <data-dir>/admin.key 读取 |
--fresh |
忽略 resume journal,原地重建计划、重走全部文件(id 幂等,不会删除已移除笔记的文档) | 关 |
--no-open |
只打印链接,不打开浏览器 | 关 |
--help, -h |
帮助 | — |
--fresh 与 resume journal 的纠葛是真实存在的坑(见"已知缺陷"一节):当数据目录被清空而 journal 还在时,xerj brain 不再擅自猜测,而是报告 journal 与服务器的不一致并给出可执行的恢复命令。
2. 核心主张 1:每条链接都有证据
从一个 hub 节点开始,查询它的邻域:
curl -s -H "$AUTH" 'http://localhost:9340/_graph/docs/overview' | python3 -m json.tool
# take an id from .hubs.in[0].id (call it $NODE)
curl -s -H "$AUTH" \
"http://localhost:9340/_graph/docs/ego?node=$NODE&include_nodes=true" \
| python3 -m json.tool
然后针对源文件校验一条引用原文(这正是整个功能的意义所在):
# 对 authored 边(detector mdlink@1 / wikilink@1 / href@1):
# evidence.quote 必须是 evidence.source 中的逐字原文
grep -F "<paste evidence.quote here>" $REPO/docs/<evidence.source>
你会看到什么
evidence.offset是链接所在 section 内部的字节偏移,不是整个文件的偏移(契约 SECOND_BRAIN_SPEC.md 第 6.5 节)。- 结构边(
samedir@1、sequence@1)携带生成的 rationale(如 "a.md 和 b.md 共享目录 …"),offset 为 0——不是提取的文本。
README.md 里有一条实测的 mdlink 边完整 JSON,其中 evidence.quote 是 "Consistent with the <a href="https://link.gitcode.com/i/a15c0c6a10e457744852f7ced715a762" target="_blank">earlier run</a>, and now with a",evidence.source 是 research/wordpress-authz-agentic-audit.md,offset 为 1568——并注明该引用已逐字节对照磁盘文件验证。
需要精确陈述的边界是:主张是"每条链接都展示它的证据",而非"每条链接都有引用文本"。手动断言(manual link)可能不带 evidence,UI 此时显示"no evidence recorded — asserted, not detected";结构检测器给出的是 rationale 而非笔记原文。契约 SECOND_BRAIN_SPEC.md 第 4.1 节确认 evidence 字段本身就是可选的。
检测器全景
XERJ 的链接检测是确定性的、带版本号的、无 LLM 的。从契约第 6.2 节的模块布局与 engine/crates/xerj-autoindex/src/detect/ 目录可以看到全部检测器:
| 检测器 | 匹配对象 | 权重 | 置信度 | UI 名称 |
|---|---|---|---|---|
wikilink@2 |
[[target]] / [[target|alias]] |
1.0 | 0.95 | — |
mdlink@2 |
text |
0.9 | 0.9 | — |
href@2 |
<a href="relative-or-corpus-url"> |
0.7 | 0.85 | — |
pathcite@1 |
正文中的裸路径 token | 0.6 | 0.7 | "cites file" |
cratecite@1 |
正文中 crate 目录名 | 0.5 | 0.6 | "cites crate" |
sequence@2 |
卡片 → s0,s_i → s_{i+1} | 0.8 | 0.99 | — |
samedir@2 |
每目录内排序文件链 | 0.3 | 0.4 | — |
sharedterm@1 |
两个文档共有的显著词 | 0.45 | 0.5 | "shared wording" |
注意 samedir@2 生成的是链(chain)而非团(clique)——团是 O(n²) 且会淹没真实信号;链让目录凝聚力在 2-hop 上限内可达。而 sharedterm@1 是第一个"读文档说了什么"而非"引用了什么"的检测器,但它比较的是字符串,不是模型——"shared wording"绝不等于"shared meaning"。
3. 核心主张 2:退役,然后回放
# capture a moment before the retirement
T_BEFORE=$(date +%s%3N)
# assert a manual link (src/dst are node ids from step 2)
curl -s -H "$AUTH" -H 'content-type: application/json' \
-X POST http://localhost:9340/_graph/docs/link \
-d '{"src":"<id1>","dst":"<id2>","type":"manual"}'
# → 201 {"edge_id":"…", …}
# retire it
curl -s -H "$AUTH" -X DELETE http://localhost:9340/_graph/docs/link/<edge_id>
# → {"invalidated":true,"invalid_at":<ms>}
# now: the link is gone, and the response SAYS one link was excluded
curl -s -H "$AUTH" "http://localhost:9340/_graph/docs/ego?node=<id1>&types=manual"
# → 0 edges, "not_shown":{"expired_excluded":1,…}
# replay the moment before the retirement: the link comes back,
# with its later invalid_at visible
curl -s -H "$AUTH" \
"http://localhost:9340/_graph/docs/ego?node=<id1>&types=manual&as_of=$T_BEFORE"
# or ask now with tombstones included
curl -s -H "$AUTH" \
"http://localhost:9340/_graph/docs/ego?node=<id1>&types=manual&include_expired=true"
双时态语义
POST /_graph/{brain}/link断言一条边;201 表示新建,200 表示更新。edge_id由xxh3_128("xg1\0" src "\0" type "\0" dst "\0" decimal(valid_at_ms))派生(契约第 2.3 节),因此同一 (src, type, dst, valid_at) 重放即覆盖,幂等;在不同valid_at重新断言同一事实会得到一条新边——这是双时态设计,不是 bug。DELETE /_graph/{brain}/link/{edge_id}绝不物理删除,只做软失效:把同一_id的文档重新索引,附加invalid_at(事实停止为真的时刻,可调用方指定)与expired_at(系统记录该失效的时刻,总是服务器当前时间)。- 读取端点全部支持
as_of(epoch 毫秒或 RFC3339);include_expired=true时 tombstone 会原样返回。 - 诚实记账:被排除的链接不会被静默隐藏——
not_shown对象逐项计数expired_excluded、edges_clipped、frontier_clipped等。契约第 0 节把"诚实带内(honesty in-band)"列为硬不变量,not_shown出现在每个读端点的每个响应里,且是可 grep 的合并门禁(第 9 节验证门 6)。
2-hop 上限:诚实拒绝
curl -s -H "$AUTH" "http://localhost:9340/_graph/docs/ego?node=<id1>&hops=3"
# → 400, "…not a graph database…"
hops > 2 返回 400,其标准措辞(契约第 4.6 节,规范字符串)为:
"hops is capped at 2: XERJ's second brain is a relationship layer over documents, not a graph database (no Cypher, no shortest-path, no variable-depth traversal). Iterate: expand again from this response's 'reachable' ids."
引擎侧实现(SECOND_BRAIN_SPEC.md 第 3.2 节)还有两个配套上限:GRAPH_MAX_FRONTIER = 4096(每跳 frontier id 上限)与 GRAPH_MAX_RESULT_EDGES = 100_000(请求结果边上限),超出部分计数到 stats 而不是静默丢弃。
4. 仪表盘与自动化验证
浏览器打开 http://localhost:9340/_xerj-console/#/second-brain?brain=docs(控制台用同一套 bootstrap 凭据处理自己的登录)。值得关注的是:
- ego 台账(ego ledger):链接按"什么教会了它们"(what taught them)分组;
- 证据悬停/点击:悬停链接浮出证据,点击钉住完整纸质轨迹(paper trail);
- 信念时间擦除器(belief-time scrubber):叙述 appeared/retired 计数;
- AUTHORED vs STRUCTURAL 分裂:诚实展示有多少链接来自写下的引用、多少来自目录结构。
一个重要的 UI 语言规则(契约第 7.1 节,对控制台所有界面具约束力):人类可见界面只说 link / believed since / retired / what taught this,schema 词汇(edge、src、dst、valid_at、as_of、edge_id)只允许出现在钉住的纸质轨迹(面向 Agent 的复制面)与 API 文档里。前端数据层 xerj-ux/src/data/second-brain-api.js 与渲染器 xerj-ux/src/ux/ego-ledger.js 就是这套规则与真实数据层的实现。
自动化等价物:contract-check.mjs
REPRODUCE.md 强调:仪表盘的渲染逻辑与数据契约已由真实数据层 + 真实渲染器在 Node 中对活服务器跑过(47/47 检查,需要 Node ≥ 20):
XERJ_URL=http://localhost:9340 XERJ_BRAIN=docs \
XERJ_ADMIN_KEY_FILE="$DATA/admin.key" \
node $REPO/docs/usecases/second-brain/contract-check.mjs
该脚本位于 docs/usecases/second-brain/contract-check.mjs,做的事情包括:动态导入 second-brain-api.js 的 liveSecondBrain 与 ego-ledger.js 的 renderPanelBody;断言 overview/ego 的每个字段形状;渲染全部九个面板(edgesLive、edgesTotal、invalidated、detectors、typeDist、edgeTimeline、ego、hubs、notShown);对真实链接执行"退役 → 时间旅行 → 重断言收敛"循环;最后检查语言规则——剥离 HTML 与 data 属性后,valid_at、as_of、edge_id 不得出现在可见文本中。
注意其边界说明:这证明的是渲染逻辑和数据契约,不是真实浏览器的像素与交互行为(拖拽、悬停卡)——后者没有被机器验证。
5. Agent 表面(MCP)
XERJ_URL=http://localhost:9340 \
XERJ_AUTH="ApiKey $(cat "$DATA/admin.key")" \
$REPO/engine/target/release/xerj-mcp
然后通过 stdio:
tools/list必须包含xerj_brain_ego、xerj_brain_link、xerj_brain_unlink、xerj_brain_overview;- 以
{"brain":"docs"}调用xerj_brain_overview必须往返返回"contract": "xerj-second-brain/1",且边计数与第 2 步一致。
这四个工具与 HTTP 端点的一一映射写在 engine/crates/xerj-mcp/src/lib.rs 的模块文档里:
| MCP 工具 | 后端 HTTP | 语义 |
|---|---|---|
xerj_brain_ego |
GET /_graph/{brain}/ego |
单节点的带证据、双时态链接邻域 |
xerj_brain_link |
POST /_graph/{brain}/link |
断言链接(幂等,确定性 edge_id) |
xerj_brain_unlink |
DELETE /_graph/{brain}/link/{id} |
退役链接(软失效;永不删除) |
xerj_brain_overview |
GET /_graph/{brain}/overview |
全脑概览:计数、hubs、detectors、时间线 |
因为整条流水线是确定性的——同一文件夹进,字节一致的脑出——Agent 可以引用它。注意 MCP 提示行(xerj brain 成功横幅中打印的 agents: 行)会携带本次运行解析到的凭据,避免出现"横幅建议的命令对着刚启动的服务器 401"的坑(brain.rs 专门为此做了处理,并有对应单测)。
6. 测试套件
cd $REPO/engine
cargo test --release -p xerj-engine --test graph_expand # 5
cargo test --release -p xerj-server --test brain_cli # 3
cargo test --release -p xerj-autoindex # 109
cargo test --release -p xerj-console-api # 76
cargo test --release -p xerj-mcp # 25
cargo test --release -p xerj-engine --lib # 241
cargo test --release -p xerj-api --lib # 84 pass, 1 fail
各套件覆盖什么:
graph_expand(5):契约第 3.6 节的固定样例测试——flush 前(memtable 路径)与 flush 后(列式路径)的字节一致展开、软失效后的as_of时间旅行、hop-2 与上限裁剪。引擎侧实现是Index::graph_expand(SECOND_BRAIN_SPEC.md 第 3.2 节):每请求一次 snapshot,每 segment 做一次"整 frontier 的列扫描",无_source访问。brain_cli(3):engine/crates/xerj-server/tests/brain_cli.rs 端到端驱动真实二进制跑契约第 8.1 节五笔记固定样例——run 1 启动分离服务器、索引、转发一次性 passkey 设置链接且--no-open绝不打开浏览器;run 2 附加并收敛到字节一致的边集合;run 3 不带--no-open时把控制台 URL 交给平台 opener(通过XERJ_BROWSER覆盖观察)。还断言了 wikilink 证据的精确字节偏移(alpha→beta @35 等)与"空文件夹在触碰服务器之前就拒绝"(退出 1、不建数据目录)。xerj-autoindex(109):含全部检测器的单测与集成测试(同一文件夹索引两次、边集合字节一致、(src, dst, type, detector)元组匹配契约第 8.3a 节:4 wikilink + 4 samedir + 5 sequence = 13 条边)。xerj-console-api(76)/xerj-mcp(25)/xerj-engine --lib(241):控制台图读取、MCP 工具构建与引擎库的常规覆盖。
唯一一个 xerj-api 失败(reindex_pages_past_10k_via_keyset)在 main 上就是既有失败(其 commit 是 main 的祖先),与图功能无关,列出它只是免得你惊讶。
7. 清理
kill <server pid printed at boot> # or: pkill -f 'xerj.*9340'
rm -rf "$DATA"
xerj brain 启动的服务器是分离进程(自己的进程组),日志追加到 <data-dir>/server.log,pid 写在 <data-dir>/server.pid(brain.rs),所以 kill $(cat $DATA/server.pid) 也是可行的清理方式。
已发布数值的运行环境
Linux x86-64、release 构建、121 文件 / 5.7 MB 语料、全新数据目录、端口 9340。README 的实测表值得一并引用:
| 项目 | 实测值 |
|---|---|
| 语料 | 121 文件,5.7 MB(52 markdown + 69 代码/图片/配置) |
| 检测出的链接 | 364 |
| 冷启动 | 0.7 s |
| 收敛重跑 | 0.14 s,退出 0,零重复 |
| 数据目录 | 12 MB(约源文件 2.1×,含完整文档存储 + 图索引) |
未测量项必须诚实陈述:Agent 的 token 经济、大规模语料(超过本 5.7 MB 语料与早期 autoindex 工作中的 518 MB 语料——后者未走图路径)行为、以及与其他笔记工具的对比。REPRODUCE.md 原话:"Token economics and large-corpus scaling were not measured; treat any extrapolation as yours, not ours." 任何外推都是你自己的,不是 XERJ 的。
已知缺陷(真实、已观察到、不阻塞)
复现时你可能会遇到,全部来自 README.md 的 "Known warts" 一节:
- CLI 进度计数器 off-by-one:该语料下 phase-B 进度行打印 "365 edges (mdlink 84)",而服务器真相(以及最终汇总)是 364(mdlink 83)。疑似原因是一个字节相同的重复路径别名导致一条链接被检测两次——是假设,未根因定位。
- YAML-frontmatter markdown 可能被嗅探为 YAML:一个带 frontmatter 的
SKILL.md落进了 junk/skipped 而非被索引。 - 过期 resume journal 会在数据目录被清空后污染链接:
xerj brain不再猜测——它报告 journal 与服务器的不一致而非自行重置。若数据目录确实被清空,用--fresh重跑原地重建计划并重发每篇笔记;若没有,指向 journal 写入时针对的数据目录,或在新的 state 目录/prefix/brain 下重建并在切换读取方之前验证。 - 本语料未覆盖 wikilink 检测(真实文档用 markdown 链接);它由 demo-corpus 运行(30 条 wikilink)与 autoindex 测试套件覆盖。
- 树中有一个既有红测(
reindex_pages_past_10k_via_keyset,继承自main),与本功能无关、真实、不在本范围。
延伸阅读
- 本 use case 的定位与三条核心主张:docs/usecases/second-brain/README.md
- 规范契约(FROZEN,字段名/路由/JSON 形状/固定样例均以此为准):docs/design/SECOND_BRAIN_SPEC.md
xerj brainCLI 实现(启动/附加服务器、admin.key 解析、成功横幅):engine/crates/xerj-server/src/brain.rs- 图 API 实现与 brain 安全边界:engine/crates/xerj-api/src/graph_api.rs
- MCP 四个 brain 工具:engine/crates/xerj-mcp/src/lib.rs
- 仪表盘真实数据层与交互控制器:xerj-ux/src/data/second-brain-api.js
- 实时契约检查脚本:docs/usecases/second-brain/contract-check.mjs