XERJ Second Brain 实战指南:把笔记文件夹变成带证据、可回放的双时态关系层

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

XERJ Second Brain 实战指南:把笔记文件夹变成带证据、可回放的双时态关系层

XERJ 的 second brain(第二大脑)是在既有文档之上的一层"关系层":节点就是普通文档,边也是普通文档,遍历是被限定在单次调用最多两跳的有界批量列式读取。本指南基于 docs/SECOND_BRAIN.md 展开,结合 SECOND_BRAIN_SPEC.md 契约与仓库源码,讲清楚它是如何从一次 xerj brain 命令把文件夹变成可查询、带证据、可回放的知识图谱,以及四个图 API 端点、召回耦合与权限边界的完整用法。读完你可以在本地用一条命令复现,并掌握通过 HTTP API 手工建边、读取邻域、检索受限召回的全部细节。

一、定位:关系层,不是图数据库

XERJ second brain 的设计出发点非常克制:它不是图数据库。没有查询语言、没有最短路径、没有 PageRank、没有无界遍历——这是刻意为之。边是普通的 XERJ 文档,遍历是一次有界、批量、列式的读取(单次调用最多两跳)。

这层关系的实现契约是 docs/design/SECOND_BRAIN_SPEC.md,源码是最终权威;针对仓库自身 docs/ 文件夹的端到端实测在 docs/usecases/second-brain/README.md。契约中有一段反复出现的规范性措辞,所有文档页和错误信息都必须包含:

"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)."

两个核心不变量贯穿始终:

  1. 边就是普通文档:没有存储格式改动,边走的是既有的 WAL → memtable → segment → doc-values 路径,因此回放、flush、merge、快照对边天然生效。
  2. 双时态、只软删:API 永不物理删除边,失效只是写入 invalid_at/expired_at,"上周二这个 brain 相信什么"永远可答。

二、brain 的构成:名字 + 两个保留索引

一个 brain 是一个名字,外加由该名字派生的两个保留索引:

角色 索引 源码
边(Edges) .xerj-memory-{brain}-edges authz::brain_edges_index(engine/crates/xerj-api/src/authz.rs)
节点(默认) .xerj-memory-{brain} authz::memory_namespace_index(engine/crates/xerj-api/src/authz.rs)

保留前缀是 .xerj-memory-(engine/crates/xerj-common/src/types.rs),与 agent-memory API 共用同一个命名空间,所以 brain 的默认节点索引就是同名 agent-memory 命名空间。

节点就是文档。图这一层从不解释节点内容,只把它们的 id 作为 src/dst 字符串存储。任何有文档 id 的东西都能当节点,包括 agent-memory 条目和 autoindex 的 section 文档。

边也是普通文档。它们位于边索引中,带一份显式 mapping,走普通写入路径。这份 mapping 由两个写入方各自一字不差地写出:HTTP 处理器 graph_api::edge_index_mapping(engine/crates/xerj-api/src/graph_api.rs)和 autoindex 探测器管线 detect::edge_index_mapping(engine/crates/xerj-autoindex/src/detect/mod.rs):

字段 类型
edge_id、src、dst、type、detector、src_file、src_format、dst_format keyword
weight、confidence float
valid_at、invalid_at、created_at、expired_at date,格式 epoch_millis
schema_version integer
evidence.quote text
evidence.source keyword
evidence.offset long

时间戳一律以 epoch 毫秒数字存储,绝不用 ISO 字符串——字符串会把 doc-values 列变成 KeywordColumn,毁掉 as-of 比较(这在契约里是"承重"级约束,见 SPEC §2.2)。

edge_id:派生而非随机

边文档的 _id 不是随机生成的:

edge_id = xxh3_128("xg1\0" src "\0" type "\0" dst "\0" decimal(valid_at_ms))

渲染为 32 位小写十六进制。两个写入方钉死同一个函数(graph_api.rs 与 detect/mod.rs),且各自用同一个固定测试向量钉住,防止漂移。其直接后果是:相同的 (src, type, dst, valid_at) 产生相同的文档 id,所以重复断言会覆盖而不是重复,对未变化的语料重跑探测器会收敛而不是增长;而在不同 valid_at 下重断言同一事实会生成一条不同的边——这是双时态设计,不是 bug。

每个边索引还含有一份保留的 meta 文档,_id 为 __xerj-brain-meta(graph_api.rs)。它携带 meta_version、brain、nodes_index 和 created_at,没有 src/dst;所有计数与遍历都过滤 exists: src,因此 meta 文档永远不会作为边出现。

brain 命名校验

两个 crate 用相同的规则校验 brain 名(graph_api.rs、detect/mod.rs):非空、至多 200 字符、首字符为小写字母或数字、其余字符来自 a-z 0-9 _ - .、不得包含 ..,且名字不得以 -edges 结尾(该后缀保留给无此后缀的 brain 的边索引,否则 POST /_memory/kb-edges 会把记忆写进 brain kb 的边索引——契约中明确这是一次有意的破坏性变更)。

三、创建 brain:两条命令

从文件夹构建 brain 有两条命令,都接受 --brain <NAME>:

xerj autoindex <folder> --brain <NAME>
xerj brain <folder> [--brain <NAME>]

xerj autoindex 是发现与索引管线。其帮助文本(engine/crates/xerj-autoindex/src/cli.rs)对这两个旗标的说明是:

--brain <NAME>       second-brain name; relationship edges land in
                     .xerj-memory-<NAME>-edges (default: folder name slug)
--no-graph           skip relationship detection (wikilinks, local links,
                     section order, directory chains) — no edges are written

省略 --brain 时,名字从根文件夹的 basename 派生(xerj_autoindex::derive_brain_name,engine/crates/xerj-autoindex/src/lib.rs),basename 清洗为空时回退到 brain。名字在参数解析时就校验(cli.rs:211),坏名字在索引工作开始前就失败,而不是跑完才发现。

xerj brain <folder> 是单命令形态:启动或挂接服务器、以开启图检测的方式跑同一管线、并打开控制台(engine/crates/xerj-server/src/brain.rs,分派于 engine/crates/xerj-server/src/main.rs)。它自己的 --brain <NAME> 默认取文件夹名。

另外,你可以完全不用文件夹构建 brain——通过 HTTP API 断言边即可,边索引在第一次 link 调用时惰性创建。

真实运行样例

仓库对自身 docs/ 文件夹做过端到端实测(docs/usecases/second-brain/README.md):

$ xerj brain /home/claude/ai/xerj/docs
brain 'docs': 121 files (5 MB) under /home/claude/ai/xerj/docs
booted xerj server (pid 339338) — data: …/p5-brain/data
phase A: 7 datasets inferred, 14 junk/skipped files
phase B: indexing 106 files with 8 workers → http://localhost:9340
done in 0.5s — 7 datasets, 561 records live …
✓ your second brain is ready — 121 files, 364 links, 0.7s
  → http://localhost:9340/_xerj-console/#/second-brain?brain=docs
  agents: XERJ_URL=http://localhost:9340 xerj-mcp

该语料冷启动 0.7 秒,退出码 3("ready-with-junk":14 个图片/二进制/被误读的文件被跳过而非索引);重跑同一命令挂接到存活服务器,0.14 秒收敛、退出 0、零重复链接。完整可复现步骤见 docs/usecases/second-brain/REPRODUCE.md。

四、在控制台里阅读

内置控制台为 brain 之上的文档提供三个界面(详见 docs/CONSOLE_READER.md):

  • Corpus(/_xerj-console/,落地路由)——autoindex-catalog 索引中每个数据集一张卡片;空引擎上会显示要运行的那一条命令。
  • Reader(#/reader?index=<index>&id=<id>&brain=<brain>)——任意记录按形状渲染(带附件的邮件、PDF 页面、笔记、代码符号),旁边是 brain 把它链接到什么的面板:一次 GET /_graph/{brain}/ego 调用,hops=1,按边类型分组。
  • Guest 模式——对持分享链接者只读地查看恰好被分享的那些索引,带可见的过期时间。

两个值得先知道的限制。其一,在启用认证的引擎(默认)上,Reader 的图面板会对已登录操作员被拒,因为控制台会话不是引擎 API key、控制台代理读不了保留命名空间(见下文"保留命名空间即租户边界");记录、搜索和附件仍可用,面板会明说"被拒"而不是假装没有链接。其二,Reader 展示的是提取出的文本:它不渲染 PDF 页面或邮件 HTML。

五、四个图端点

四个图路由全部挂载在 ES 兼容路由器上,与 agent-memory 路由并列(engine/crates/xerj-api/src/router.rs):

POST   /_memory/{namespace}                store
GET    /_memory/{namespace}                list
DELETE /_memory/{namespace}                drop the namespace
POST   /_memory/{namespace}/_recall        recall
DELETE /_memory/{namespace}/{id}           forget one

POST   /_graph/{brain}/link                assert an edge
DELETE /_graph/{brain}/link/{edge_id}      retire an edge
GET    /_graph/{brain}/ego                 bounded neighbourhood
GET    /_graph/{brain}/overview            brain-level stats

图错误统一用一种形状(graph_api.rs):

{"error": {"type": "graph_error", "reason": "<message>"}, "status": 400}

下面的示例假设服务器以 --insecure 启动——开放模式:单用户、无配置、无需凭据。在安全服务器上需追加 -H "Authorization: ApiKey <key>"(见授权一节)。

POST /_graph/{brain}/link —— 断言一条边

首次使用会创建边索引及其 meta 文档。派生的 id 是新的时候返回 201,相同 (src, type, dst, valid_at) 重断言返回 200。

curl -s -X POST 'http://localhost:9200/_graph/notes/link' \
  -H 'Content-Type: application/json' \
  -d '{
    "src": "note-fermentation",
    "dst": "note-sourdough",
    "type": "relates_to",
    "evidence": {"quote": "sourdough is a wild fermentation", "source": "notes/bread.md", "offset": 412}
  }'

请求体字段(LinkBody,graph_api.rs)。未知字段一律 400 拒绝,所以一个拼写错误不会静默丢掉断言的一部分:

字段 必填 默认 说明
src 是 非空;src == dst 返回 400
dst 是 非空
type 是 非空
weight 否 1.0 必须有限,钳制到 [0, 1]
confidence 否 1.0 必须有限,钳制到 [0, 1]
valid_at 否 服务器现在 epoch-ms 数字或 RFC3339 字符串
created_at 否 服务器现在 epoch-ms 数字或 RFC3339 字符串
detector 否 "manual@1" 自由字符串
evidence 否 省略 必须是对象;{quote, source, offset} 是读者期望的形状

当 evidence.source 是字符串时,它会镜像到顶层 src_file 字段(graph_api.rs)——这正是让"替换式失效"变成 doc-values 词项查询而非对象扫描的关键。

响应回显存储的文档:

{"brain": "notes", "edge_id": "<32 hex chars>", "created": true, "edge": { ... }}

DELETE /_graph/{brain}/link/{edge_id} —— 退役一条边

它从不删除文档。同一文档以同一 _id 重新索引,并补上 invalid_at 和 expired_at(graph_api.rs):

curl -s -X DELETE 'http://localhost:9200/_graph/notes/link/<edge_id>?invalid_at=2026-07-01T00:00:00Z'

invalid_at 接受 epoch-ms 数字或 RFC3339 字符串,默认服务器现在;expired_at 永远是服务器现在,不可由调用方设置。

退役一条已退役的边是无操作,但会如实报告现状:

{"brain": "notes", "edge_id": "...", "invalidated": false, "already_invalid_at": 1751328000000}

未知边 id 或未知 brain 返回 404,携带 "edge '<id>' does not exist in brain '<brain>'"。

GET /_graph/{brain}/ego —— 单节点或几个种子的有界邻域

curl -s 'http://localhost:9200/_graph/notes/ego?node=note-sourdough&hops=2&include_nodes=true'

查询参数(EgoParams,graph_api.rs):

参数 默认 说明
node 要展开的节点 id;与 nodes 互斥
nodes 逗号分隔的种子 id;去重、上限 64,截断计入 not_shown.frontier_clipped
hops 1 仅 1 或 2;其它值一律 400
direction both out、in 或 both
types 全部类型 逗号分隔的边类型白名单
limit 100 钳制到 1..=1000
as_of 现在 epoch-ms 数字或 RFC3339 字符串
include_expired false 同时返回已退役的边
include_nodes false 从节点索引水合节点摘要
nodes_index brain meta,否则 .xerj-memory-{brain} 单独授权,见下文
include_evidence true 在返回的边上水合 evidence、detector、confidence、created_at、expired_at

node 和 nodes 都省略或都给出都是 400;没有边索引的 brain 是 404。

响应携带 brain、contract("xerj-second-brain/1")、seeds(恰有一个种子时还有 node)、as_of、hops、direction、edges、neighbors、not_shown,以及 include_nodes=true 时的 nodes。每条边携带 edge_id、src、dst、type、weight、hop、direction、valid_at 和 invalid_at(活跃边为 JSON null),外加 include_evidence 开启时的水合字段。

not_shown 每次响应都会填充,统计被扣下的内容:edges_clipped、frontier_clipped、expired_excluded、type_filtered、segments_without_columns、memtable_docs_scanned、dangling_nodes 和 dangling_ids(最多 50 个 id 原样列出)。节点 id 在节点索引中解析不到文档时报告为 dangling——边保留,缺失节点不臆造。

节点水合读取 title、text 或 body(前 160 字符作为 preview)以及 ax_path(作为 path)。没有 ax_path 的节点(如手写节点)path 为 null,不猜。

GET /_graph/{brain}/overview —— brain 级统计

由对边索引的三次搜索加对节点索引的一次计数构建:

curl -s 'http://localhost:9200/_graph/notes/overview?top=10&histogram_interval=day'

查询参数(OverviewParams,graph_api.rs):as_of(默认现在)、top(默认 10,钳制 1..=50)、histogram_interval(默认 day,接受 hour,其它值 400)。

响应携带 brain、contract、exists、as_of、nodes_index、nodes.total、embedder、edges(total/live/invalidated)、types、detectors、hubs.out、hubs.in、created_over_time,以及报告各聚合未列出尾部的 not_shown 对象(types_not_listed、detectors_not_listed、hubs_out_not_listed、hubs_in_not_listed)。

total 统计所有曾断言的边;live 统计 as_of 时刻可见的边;invalidated 是二者之差。created_over_time 是对全部已断言边按 created_at 做的 date_histogram,所以退役一条边不会把它从时间线抹掉。

embedder 报告节点存储配置的 embedder id,内置默认时报告 lexical-feature-hash(graph_api.rs)。内置 embedder 是词法特征哈希,不是神经模型。

不存在的 brain 返回 404 和简短响应体而非错误信封:

{"brain": "notes", "contract": "xerj-second-brain/1", "exists": false}

六、与召回耦合:restrict 与 blend

POST /_memory/{namespace}/_recall 接受一个可选的 graph 对象(GraphRecallOpts,engine/crates/xerj-api/src/memory_api.rs)。命名空间的 brain 就是命名空间本身:召回在 .xerj-memory-{namespace}-edges 上展开。graph 缺省时,召回行为与图出现之前完全一致。

curl -s -X POST 'http://localhost:9200/_memory/notes/_recall' \
  -H 'Content-Type: application/json' \
  -d '{"query": "fermentation", "k": 10,
       "graph": {"mode": "blend", "hops": 2, "weight": 0.3}}'
字段 必填 默认 说明
mode 是 restrict 或 blend;其它值一律 400
seeds 对 restrict 必填 对 blend,为前 5 个基础召回命中的 id restrict 且 seeds 缺失/为空是 400
hops 否 1 1 或 2
types 否 全部 边类型白名单
weight 否 0.3 blend 权重,钳制 [0, 1];对 restrict 忽略
as_of 否 现在 epoch-ms 数字或 RFC3339 字符串

restrict 把召回收窄到从种子可达的文档。blend 不动候选集,而是按 (1 - w) * normalized_score + w * proximity 重新排序,其中 proximity 对种子是 1.0,对在第 h 跳到达的节点是 0.5^hop * clamp(weight, 0, 1),取所有路径的最大值(memory_api.rs)。blend 命中的条目带 graph_proximity 字段。

响应新增一个 graph 对象,含 mode、seeds、hops、as_of、reachable(计数)和它自己的 not_shown。brain 没有边索引时,召回不带门禁继续执行,not_shown.no_edges_index 为 true,而不是让请求悄然失败(memory_api.rs)。折入 restrict 过滤器的可达集上限 10,000 个 id(memory_api.rs)。

注意 /_memory/{namespace}/_recall 要求 query 和 vector 恰好提供其一,未知字段一律 400。

七、边上的证据

探测器发出的每条边都携带教出它的文本。组装文档时为每条被检出的边设置 evidence.quote、evidence.source 和 evidence.offset(detect/mod.rs),其中 source 是文件相对仓库根的路径,offset 是 section 文本内的字节偏移。quote 是包含该偏移的完整去除首尾空白行,截断到 240 字符(detect::line_at,detect/mod.rs)。同一路径镜像到顶层 src_file 字段。

八个探测器中有三个没有作者可引用的句子可引,因为它们依据的是文件布局或统计而非某人写下的句子。它们在同一字段记录生成的 rationale,offset 为 0:

  • samedir 写 "<a> and <b> share directory <dir>"(detect/samedir.rs)
  • sequence 写 "<label> precedes <label> of <file>",首个 section 写 "<label> opens <file>"(detect/sequence.rs)
  • sharedterm 写 "<a> and <b> share N distinctive terms: …",点名产生链接的词,最罕见的在前(detect/sharedterm.rs)

控制台读回这一区别并差异化渲染:quote 用引号展示,结构性 rationale 加 WHY — 前缀且绝不戴引号,完全无证据的边显示 no evidence recorded — asserted, not detected(xerj-ux/src/ux/ego-ledger.js、xerj-ux/src/ux/brain-map.js)。

最后一种情况对手工断言最重要。POST /_graph/{brain}/link 只在调用方提供时才存 evidence。当你或 agent 手工断言链接而没有 quote 时,存储的文档就没有 evidence 字段,读者会照实说。没有任何东西被臆造来填这个洞。

诚实的表述是"每条链接都展示它的证据",而非"每条链接都有一条 quote"。

八、八个探测器,以及它们不做的事

仓库随附八个探测器(SPEC 中的注册表在 engine/crates/xerj-autoindex/src/detect/mod.rs default_detectors):

探测器 边 type detector 标签 权重 置信度 触发条件
wikilink wikilink wikilink@2 1.0 0.95 [[Target]] 或 [[Target|alias]] 解析到语料文件
mdlink mdlink mdlink@2 0.9 0.9 text 解析到语料文件
href href href@2 0.7 0.85 <a href="..."> 指向语料文件,仅限 html 嗅探文件
pathcite pathcite pathcite@1 0.6 0.7 正文中裸文件路径解析到语料文件
cratecite cratecite cratecite@1 0.5 0.6 正文中的 crate 目录名,链接到该目录的 Cargo.toml
sequence sequence sequence@2 0.8 0.99 文件卡片,然后文件内每个 section 接续下一个
samedir same_dir samedir@2 0.3 0.4 共享目录的文件,按路径顺序成链,绝非团簇
sharedterm shared_term sharedterm@1 0.45 0.5 两个文档使用相同的独特词,每文档上限 5 条链接

标签上的 @N 是探测器版本号,任何行为变化都会 bump,旧边因此始终可归因到产生它们的规则。各探测器的 TAG/EDGE_TYPE 常量与 1:1 类型→标签映射见 detect/ 目录(如 wikilink.rs、mdlink.rs、samedir.rs 等)。顺带一提,从源码注册表看(detect/mod.rs),当前实现还多注册了一个 emailthread 探测器(email-thread@1,对应 replies_to/attachment_of 两种边类型)——文档正文以八个结构性探测器为准,这是实现上的增量。

探测器确定且带版本,这条路径上没有 LLM。同一语料在文件 mtime 不变的情况下,每次运行产出字节级相同的边集合,因为边身份是 (src, type, dst, valid_at) 的哈希,而 valid_at 取源文件 mtime 而非墙钟(detect/mod.rs)。

八个里有七个是结构性的:它们寻找显式引用和文件布局。 sharedterm 是唯一会读文档内容的,而且它把内容当词读,不当含义读。当两个文档都用相同独特词时它把它们连起来,边携带这些词以便核对。酸面包连到泡菜,前提是两页都真的说 "ferments" 和 "lactobacillus";一页说 "cultured"、另一页说 "fermented" 就不连——而且注意没有词干化,"ferment"、"ferments"、"fermentation" 对这个探测器是三个无关的词。这条路径上没有任何东西是模型:XERJ 内置 embedder 是词法特征哈希,sharedterm 连那个都不用,它把词当字符串比。请把它描述为共享词汇,永远不要说成语义理解。

由它如何判定"独特"得出两条界限:

  • 出现在语料 10% 以上文档中的词是该语料自身的词汇,被忽略——这意味着十份文档或更少的文件夹不会产生任何 shared_term 边,因为十份里两份就占 20%。小文件夹仍由 same_dir 和 sequence 连接。
  • 一条链接至少需要两个共享词族。只有一个词相同是巧合;没有词干化时 "trajectory" 和 "trajectories" 是两个词项但同一个词,所以按一个计。
  • 每篇文档至多取 5 条 shared_term 链接,所以"万物相似"的文件夹不会变成毛线团。被上限拒绝的候选链接由索引运行记为 edges_capped 报告,而不是消失。

在 24 个主题文件夹中的 240 篇 arXiv PDF 上实测:七个结构性探测器产出 11,854 条边,其中 11,642 条连接单篇文档的 section、212 条连接目录邻居——没有一条跨文件夹,因为该语料里没有任何东西引用任何东西。sharedterm 增加 462 条边,377 条跨文件夹。对照语料自身的归档,这些文档的随机一对共享顶层主题的概率是 17.0%,shared_term 链接共享的则是 35.9%:约为随机水平的二倍。请把这读作信号的诚实强度——有用,但替代不了去读边上的证据。

这从文档层面回应了 issue #164「second brain 只能靠显式引用、不能靠主题连接文档」——对共享措辞的文档成立。共享主题却不共享词的文档仍然不连接,这个缺口是真实的。

九、跳数上限与引擎边界

hops 只能是 1 或 2,其它值一律 400,响应体携带这句精确措辞(GRAPH_HOPS_CAP_REASON,engine/crates/xerj-engine/src/graph.rs):

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.

hops=0 被同一检查拒绝;直接在引擎上而非经 HTTP 调用时,hops=0 会得到 hops must be at least 1. 前缀加上同一句(graph.rs)。同一字符串被 /_graph/{brain}/ego(graph_api.rs)和 /_memory/{namespace}/_recall 的 graph 块共用,措辞不因表面而异。

两跳以上的深度在客户端组合:取上一响应的 id 再展开。ego 每次调用通过 nodes= 最多接受 64 个种子,正是为此。

引擎内其它边界,全部如实报告而非沉默(graph.rs):

边界 值 报告为
跳数 2 带上述句子的 400
每跳 frontier id 4096 not_shown.frontier_clipped
每请求结果边 100,000 not_shown.edges_clipped
ego 每调用种子 64 not_shown.frontier_clipped
ego 返回边 limit,钳制到 1000 not_shown.edges_clipped
restrict 可达 id 10,000 graph.not_shown.reachable_clipped

缺少跳跃所需 doc-values 列的 segment 会被跳过并计入 segments_without_columns。跳跃路径永不回退到读 _source,所以被跳过的 segment 总是被报告。

从引擎实现看(graph.rs),整个展开是"每 segment 每跳一次列扫描覆盖整个 frontier"(both 方向两次:一次扫 src、一次扫 dst),每行 O(1) 哈希集合成员判断,成本与 frontier 大小无关——这正是"有界、批量、列式"承诺的来源。

十、双时态行为

链接是退役,不是删除。DELETE /_graph/{brain}/link/{edge_id} 以同一 _id 重新索引同一文档,加两个时间戳:

  • invalid_at 是事实不再为真的时刻,调用方可设,默认服务器现在。
  • expired_at 是系统记录那一刻的时刻,永远是服务器现在。

这是两个时钟。valid_at 和 created_at 是断言侧的对应物:valid_at 是事实变为真的时刻,created_at 是系统记录它的时刻。

某时刻的可见性由 bitemporal_visible 决定(graph.rs):

visible(as_of) = valid_at <= as_of AND (invalid_at is absent OR invalid_at > as_of)

include_expired=true 只关闭后半部分。在 as_of 之后断言的边无论怎样都不可见,因为它在被询问的世界里还不存在。被此规则排除的边计入 not_shown.expired_excluded。

因此给 ego 或 overview 传 as_of 回答的是"这个 brain 在那个时刻相信什么",包括此后被退役的边。由于不同的 valid_at 产生不同的派生 edge_id,在新的 valid_at 重断言一个事实会创建一条独立边而不是改动旧边——这就是历史得以完整保留的机制。

一个值得注意的后果:因为退役是同一文档的重索引而非删除,边索引永远不会通过图 API 变小。回收空间意味着通过普通索引 API 删除文档,而那会丢弃历史。

十一、保留命名空间即租户边界

.xerj-memory-* 命名空间容纳每个 agent-memory 命名空间和每个 second brain,是保留的。触及其中索引需要主体持有该具体索引上的匹配特权(engine/crates/xerj-api/src/authz.rs 模块文档)。

brain 授权所对的资源是它的边索引 .xerj-memory-{brain}-edges。谁能读一个 brain:

主体 可达范围
开放模式(--insecure,或未配置 admin key) 每个 brain;单用户、无配置
配置的 admin key 每个 brain
用 role_descriptors 点名边索引铸造的 key 该 brain,按授予的特权
未带 role_descriptors 铸造的 key 任何 brain 都不可达
分享链接访客(xerj share … --brain,见下文) 该 brain,仅 read:ego 和 overview,绝无 link/unlink
无凭据或凭据无效 什么都不可达

ego 和 overview 需要 read;link 和 unlink 需要 write。惰性创建边索引算作写入 brain,不是独立的 manage 步骤。

把 brain alice 授给一个 key,铸造时点名它的两个索引。第二个名字是节点索引,ego 的节点水合和 overview 的笔记计数都需要它。与上面示例不同,这个需要安全服务器。只有超级用户能铸造受限 key,所以出示 XERJ 写入 <data_dir>/admin.key 的 admin key:

curl -s -X POST 'http://localhost:9200/_security/api_key' \
  -H "Authorization: ApiKey $(cat ./data/admin.key)" \
  -H 'Content-Type: application/json' \
  -d '{"name": "alice-agent",
       "role_descriptors": {"alice": {"indices": [
         {"names": [".xerj-memory-alice-edges", ".xerj-memory-alice"],
          "privileges": ["read", "write"]}]}}}'

对 --insecure 服务器铸造确实会返回 key,但该 key 授予的不比"一切"更窄:开放模式在任何凭据被检查前就把每个调用者解析为超级用户,所以上面的授权从不被consult。brain 隔离只存在于启用 auth.enabled 并配置了 admin key 的服务器上。

拒绝是一个 ES 形状的 403,error.type 为 security_exception(authz.rs),点名资源、动作和能修复它的授权。

三个刻意为之的性质值得点出:

  • 授权先于存在性检查。 每个图处理器在查看 brain 是否存在之前先授权调用者,因此"不是你的 brain"和"不存在的 brain"返回同样的 403,状态码无法用来枚举 brain。
  • ego?nodes_index= 单独授权。 节点索引可被调用者重定向,而 brain 的 meta 文档(任何对 brain 有 write 者都可写)可以把它指向任何地方,所以水合按解析出的索引独立授权。否则对一个 brain 的 write 会变成对节点上每个索引的读原语。
  • 多数据集 nodes_index 逐名授权。 xerj brain 把一个文件夹产出的每个数据集索引记为一个逗号拼接的字符串("ax-mail,ax-pdfs")。其中每个名字各自授权(graph_api.rs 的 authorize_nodes_index),一个未授权名字就拒绝请求。在 2026-09-18 之前,整个字符串被当作单个索引名与 key 的授权比较,于是每个受限 key 都被拒绝任何跨多数据集 brain 的 overview 和节点水合,且 overview 对这类 brain 报 0 笔记——因为它找的是一个叫 "ax-mail,ax-pdfs" 的索引。

强制不止这四条路由。brain 的边住在一个名字恰好以点开头的普通索引里,因此可以通过通用 ES 兼容与原生索引路由命名它。这些门在两层被关闭,任何处理器都绕不过:授权中间件(从请求路径和请求体解析目标:_bulk、_msearch、_mget、_aliases、_reindex、索引模板等)和引擎的索引守卫(位于通往索引数据的唯一漏斗内)。第二层回答"不存在"而非"被禁",这正是让 POST /_search 和 _cat/indices 这类扇出动词过滤而非失败的原因。

源码里两句大白话界限:

  • 这使保留命名空间成为真实边界,把受限 key 关在它的授权内。但它不把 XERJ 变成通用多租户授权系统。未带 role_descriptors 铸造的 key 保留其历史可达范围:普通非保留索引。
  • 显式授权不被二次猜疑。用 names: ["*"] 铸造的受限 key 可以触及保留命名空间,因为 * 匹配每个索引,而那正是操作员要的。只有超级用户能铸造它。想要 brain 隔离的操作员必须授予具体名字,或授予排除 .xerj-memory- 的前缀。

memory_api.rs 顶部的模块文档仍描述 #79 之前 /_memory/* 无每命名空间授权的模型。处理器确实调用 authz::authorize_memory_namespace;注释过时了,代码没有。

十二、分享一个 brain

xerj share <folder> 通过链接和口令,把 xerj brain 索引过的文件夹的只读搜索权交给另一个人。xerj brain 在收尾摘要里打印确切的命令,每个参数在需要时加引号(名为 case files 的文件夹会作为一个参数粘贴):

  share it: xerj share /home/you/casefiles   (read-only link + passcode for one person; the documents stay on this machine)

文件夹参数按 xerj brain 命名的方式解析:brain 是 derive_brain_name(<folder>)(或 --brain),索引是该 brain meta 文档里的 nodes_index 列表(engine/crates/xerj-server/src/share.rs 的 resolve_target)。从未在本节点索引过的文件夹会报出说明性错误,绝不猜测——错 key 或非 admin key 报为 key 问题,而不是"从未索引的文件夹"。

访客的 key 获得这些索引和 brain 边索引上的 read,以及保留命名空间里的别无其它——不是 .xerj-memory-{brain} 记忆命名空间、不是任何其它 brain、不是 /_memory/*。一个后果:纯 HTTP API 建的 brain 把笔记留在 .xerj-memory-{brain},分享永不授予它,所以这种 brain 的访客能用 ego 走链接,但 overview 和节点水合会被拒(403)。xerj brain 建的 brain 把笔记放在分享点名的数据集索引里,两者都可用。在图 API 上这意味着 GET /_graph/{brain}/ego 和 GET /_graph/{brain}/overview;link 和 unlink 在到达特权检查前就被访客路由白名单拒绝。ego?nodes_index= 不能把水合重定向到分享未点名的索引,单独或作为列表中的一个名字都不行。

该命令拒绝在开放模式下运行的节点,理由同上:brain 隔离只存在于开启认证的服务器上。整个特性——命令、访客能/不能到达什么、威胁模型、--tunnel——都在 docs/SHARING.md。

十三、验证与测试

这一特性由多层测试钉住。契约 SPEC §9 列出的验证门包括:cargo test -p xerj-engine graph_(§3.6 套件在 flush 前后均绿)、cargo test -p xerj-api graph_api 加 memory_api 召回图测试(restrict/blend/无边索引)、cargo test -p xerj-autoindex detect 加双跑收敛测试。实测的套件计数见 docs/usecases/second-brain/REPRODUCE.md:graph_expand 5/5、brain_cli 3/3、autoindex 109/109、console-api 76/76、mcp 25/25、engine lib 241/241,同一服务器上图特性开启时 ES 兼容一致性门 1360 过/0 败/3 跳过。

针对夹具的断言很具体(SPEC §8):edge_id("note-alpha", "wikilink", "note-beta", 1753600000000) == "bef814a75bd3d914c3e561f610154304" 这一钉死向量被两个 crate 各自的单元测试钉住(graph_api.rs);五个笔记(alpha.md…epsilon.md)的 8 条边、ego 的规范响应、以及"先退役再回放"的时间旅行断言都字节级规范。控制台仪表盘的数据契约由 docs/usecases/second-brain/contract-check.mjs 对着真实数据层与真实渲染函数执行(47/47 通过),未验证的是真实浏览器像素与交互行为。

十四、本文未覆盖的边界

  • 控制台的 corpus 主页、reader 和 guest 模式见 docs/CONSOLE_READER.md;控制台的 Second Brain 仪表盘(THE MAP、ego ledger)和 MCP 界面存在但不在本文范围内。
  • 边字段 src_format/dst_format 由探测器写入并在 mapping 中,但上面没有端点把它们作为独立的成形响应字段返回;通过普通搜索 API 读边 _source 时它们作为一部分出现。
  • 本仓库没有发表图展开的性能数据,所以这里一条都不引用。可以复现的只有 docs/usecases/second-brain/README.md 中 121 文件 0.7 秒这个单一语料实测,token 经济学与大规模行为同样未测量、未宣称。
登录后查看全文
xerj