XERJ Second Brain 完整复现指南:`xerj brain` 一键把你的笔记变成可检索、可回放的知识图谱

原创2026-10-17 18:17:052,210 阅读
文章标签:搜索引擎全文检索向量数据库数据库后端MCP 服务Agent 记忆人工智能日志分析dsh-plugin

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

退出码语义

  • 0 ready(就绪);
  • 3 ready-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),与本功能无关、真实、不在本范围。

延伸阅读

登录后查看全文
xerj