cuba-memorys

MemoryIndustry

原名 cuba-memorys。同一守护进程、同一组 cuba_* MCP 工具，新产品名称。

面向 AI 编码 Agent 的长期记忆。 一个 MCP 服务，为你的 Agent 提供知识图谱，让它能够搜索、推理并接受纠正——这样它就不会在会话之间忘记你的代码库。

使用 Rust 编写。由 PostgreSQL + pgvector 提供支持。31 个 MCP 工具（设置 CUBA_DOCS=1 时为 32 个）、28 条 CLI 命令。以下所有数字均来自一个真正测量其声称指标的基准测试（自 v0.12 起）。（之前的基准测试并没有做到这一点。参见测量结果，以及那个说谎的基准测试。）

安装

pip install memory-industry        # or: npm install -g memory-industry
claude mcp add memory-industry -- memory-industry

# Previous names still install the same binary:
#   pip install cuba-memorys
#   npm install -g cuba-memorys

这就是全部的设置步骤。首次运行时，它会通过 Docker 部署 PostgreSQL 18 + pgvector 容器并初始化架构。Docker 必须处于运行状态。 cuba-memorys 命令仍是一个二进制别名。

{
  "mcpServers": {
    "memory-industry": {
      "command": "memory-industry"
    }
  }
}

{
  "mcpServers": {
    "memory-industry": {
      "command": "memory-industry",
      "env": { "DATABASE_URL": "postgresql://user:pass@localhost:5432/brain" }
    }
  }
}

cuba-memorys serve                      # 127.0.0.1:8787 by default
cuba-memorys serve 127.0.0.1:9000       # or pick the address

{
  "mcpServers": {
    "memory-industry": {
      "type": "http",
      "url": "http://127.0.0.1:8787/mcp",
      "headers": { "Mcp-Client-Id": "editor-window-1" }
    }
  }
}

cuba-memorys models all          # embeddings + NLI + reranker + runtime
cuba-memorys models embed        # just the embeddings model (~113 MB)
cuba-memorys models all --gpu    # GPU runtime, if you have one
cuba-memorys doctor              # confirms what loaded

memory-industry cache migrate            # the plan: touches nothing
memory-industry cache migrate --apply    # moves it

获取 GPU 运行时只是其中一半：二进制文件本身必须使用 --features cuda 构建，否则 gpu::configure() 不会注册任何提供程序，重排序器也会在 CPU 上运行。这并非假设——以下是在 6 核笔记本电脑上测得的 50 个候选项重排序开销，使用 cargo run --release --example rerank_bench 测量：

无论哪种方式，排序结果都相同——CPU 和 GPU 对每个候选项的判断一致，分数仅在小数点后第五位有所不同。在任意机器上运行 rerank_bench，即可查看重排序器是否能在该机器的预算内完成，还是在悄悄丢弃计算结果；cuba-memorys doctor 则会报告当前构建是否包含 GPU 提供程序。

**本节以前曾写道“每个模型都会悄悄在 CPU 上运行”，这让人以为使用 --features cuda 构建后，三个模型都会在 GPU 上运行。实际上只有重排序器会。**嵌入器以动态量化的 INT8 格式随附，这意味着它包含 96 个 DynamicQuantizeLinear，后接 144 个 MatMulInteger——CUDA 提供程序没有为这两种算子注册内核，因此无论如何构建，ONNX Runtime 都会将它们分配到 CPU 上。为该会话注册 CUDA 毫无益处，却占用了 VRAM 分配区，而模型从未在其中执行计算：**模型的全部 544 MB 权重都留在主机 RAM 中，却占用了 374 MiB。**NLI 交叉编码器则面临相反的问题——它采用 FP32，并因此受限于此，因为上游文档指出 mDeBERTa 不支持 FP16，而 INT8 构建会返回确信无疑的错误蕴含结果。

因此，现在会按模型而不是按进程决定放置位置，且只有重排序器会请求使用 GPU。在这次测量所用的 6 GB 显卡上，守护进程的 VRAM 占用从 5228 MiB 降至搜索时的 2950 MiB、空闲时的 0——采用下方 占用空间 中的两个可选步骤后，还可降至 1460 MiB。

各个环境变量（CUBA_DOCS、CUBA_RERANKER_PATH……）始终会覆盖预设值。

它实际做什么

大多数记忆服务都是附加了嵌入的键值存储。这个服务对记忆分为四类，因为心理学文献指出，它们是四种不同的东西，且衰减方式各不相同：

程序记忆使用独立的数据表，而不是作为第九种观察类型，有一个具体原因：ACT-R 将陈述性记忆（通过访问强化）与程序记忆（通过成功强化）区分开来。如果把操作流程作为观察记录，那么一个因为总是失败而被频繁查阅的流程，其重要性反而会不断上升。它按 Wilson 下界排序，因此，1/1 次成功得分为 0.21，而 47/50 次成功得分为 0.84——侥幸成功一次不会胜过长期的成功记录。

检索

对三种信号进行混合 RRF 融合（k=60，Cormack 2009）——全文搜索、BM25（ts_rank_cd）和 pgvector HNSW——并通过熵路由加权，随着查询的 Shannon 熵升高，权重会从偏重关键词转向偏重语义。

默认以 compact 格式返回答案：键名缩写，内容截断至 1200 个字符。令牌数减少 30%，nDCG 还略有提升——在 221 个带 ID 评分的问题上进行测量，提升 +0.0090，配对 95% 区间为 [+0.0024，+0.0166]。格式实际上无法改变文档的排序；它改变的是，在评分之前，有多少文档能保留在响应令牌预算内。默认 5000 令牌预算下，verbose 格式占用 5286 个令牌，尾部内容会被截掉；compact 格式占用 3723 个令牌，可以完整保留。传入 "format": "verbose" 可查看每个分支的完整得分明细。

真正有效的验证

cuba_faro mode=verify 会根据存储的内容核验声明。过去，它通过与检索到的证据的余弦相似度为声明打分，但这行不通——相似度衡量的是文本在谈论什么，而不是它断言了什么。“cuba-memorys 是用 Rust 编写的”和“……用 Java 编写的”在向量空间中几乎相同。在实时语料库上的测量结果显示，错误声明得分为 0.61，正确声明为 0.59。

蕴含判断与相似度是不同的问题，需要某种能够阅读内容的机制。现在，本地交叉编码器会判定每条证据——supports / contradicts / unrelated——置信度则根据判定结果计算，并按对应证据的相似度加权。同一语料库，改进后：

主题相关不等于支持，unrelated 不计入任何一方。

判定器是本地运行于 ONNX 上的 mDeBERTa-v3-base-xnli：支持 100 种语言，每次判定约 50 ms，无需 API 密钥、无需联网、无需付费。这一点很重要——该语料库约 75% 为西班牙语，而大家首先会选用的仅支持英语的 NLI 模型，会在四条记忆中有三条上悄无声息地失效。运行 cuba-memorys models nli 安装；cuba-memorys doctor 会告诉你它是否已加载。

如果没有它，验证会回退到 LLM（通过采样使用 MCP 客户端自身的模型、本地 claude CLI，或 Anthropic API）；如果这些都不可用，则会如实返回 unknown，而不是捏造判定结果。

它不会做两件事。它不会依据薄弱证据确认声明：蕴含置信度必须超过 0.80，而矛盾判定只需达到 0.60，因为确认错误记忆与怀疑正确记忆的代价并不相同。而在无法判定时，它会明确说明，而不是返回数值最大的那个结果——对三分类头取 argmax，会轻易把明明错误的声明标为 supports，而它确实曾这样做过。

经过校准的弃答机制

分布外检测门会拒绝语料库无法回答的查询。阈值不是一个魔法常数：通过 Ledoit-Wolf 协方差收缩和保形分位数，使用 cuba-memorys calibrate --dataset <questions.jsonl> --apply 根据你自己的语料库进行校准并持久化（必须提供数据集——否则命令会拒绝执行）。（理论上的 χ² 阈值拒绝了 100% 可回答的查询。在这里，无分布假设校准并非可有可无。）

通过 git 在机器间同步

CUBA_MODE=red 可让两台机器共用一个数据库。cuba_sync 是另一种方式，适用于彼此永远无法连接的机器：图谱会写出为可提交的 JSON 文件，并可在另一端读回。

cuba-memorys sync export            # write the bundle under .memory-industry/ (or $CUBA_SYNC_DIR)
cuba-memorys sync import            # read one back in
cuba-memorys sync diff              # entities on disk vs entities in the database
cuba-memorys sync status            # which bundles this machine has already imported
cuba-memorys hook install           # export after every commit, import after every checkout, merge and rebase

同样的四种操作是 cuba_sync action=export|import|diff|status。一个捆绑包包含每个实体对应的一个 JSON 文件，文件中包含该实体的观察记录；此外还有 episodes/YYYY-MM/、errors/、decisions/、relations.json、projects.json、tombstones.json 和 manifest.json——内容包括当前活动项目以及所有未绑定到项目的内容，除非你传入 --scope all。除非你指定 --with-embeddings，否则不会包含嵌入向量：它们占用大部分字节，而且可以重新计算。一个捆绑包只会导入一次，清单哈希涵盖其中每个文件的内容——因此，未更改的捆绑包会被跳过，而手动编辑过的实体文件会被视为新捆绑包，而不是被悄悄忽略。导出时只会写入内容有变化的文件：如果上次导出后数据库没有任何写入，导出不会改动任何内容，包括 manifest.json；因此，它的 exported_at 表示捆绑包上次发生变化的时间。 **hook install 也会在合并和变基后导入。**它会写入四个钩子：post-commit 导出，post-checkout 导入，post-merge 导入，post-rewrite 在变基后导入。运行 git merge 时，git 不会运行前两个钩子；运行 git rebase（在含有自身提交的分支上执行 git pull --rebase 时会运行）时，则不会运行 post-merge。因此，如果没有最后两个钩子，合并或变基后的捆绑包就永远不会写入数据库，而下一次提交会将数据库导出并覆盖它，丢掉另一方的行。githooks(5) 指出，post-rewrite“由重写提交的命令调用（使用 --amend 调用的 git-commit，以及 git-rebase）”，其第一个参数为 amend 或 rebase；在 amend 后它不会执行任何操作，因为被 amend 的提交是这台机器自己的导出。git 在合并时停止后，不会运行 post-merge；结束合并的提交有第二个父提交，而在该提交上，post-commit 会先导入解决冲突后的结果，再进行导出。之前就安装了？请再次运行 hook install。

**hook install 会记录它解析出的目录。**每个钩子都会将 CUBA_SYNC_DIR 设为 install 解析出的目录——相对路径会相对于仓库根目录解析，而不是相对于你运行命令的目录——因为在 IDE、GUI 客户端或 cron 作业中进行的提交会使用其自身的环境；如果没有这个固定值，提交就会将内容导出到合并驱动程序未查找的位置。更改变量后，再次运行 hook install：它会替换自己的代码块，而不是保留第一次写入的代码块。.gitattributes 中的行只会以 git 能识别的方式写入：相对于工作树顶层，使用 /，且不带 . 或 ..（名称中含空格时会加引号）；它会替换先前安装留下的任何行。以前，./dir、绝对路径或 Windows 上的 data\sync 会按原样写入，无法匹配，却会被报告为 added。即使 CUBA_SYNC_DIR 位于仓库之外，钩子仍会安装——它们会从共享文件夹导入并向其中导出——但不会安装合并驱动程序，也不会写入任何行，因为 git 不会合并工作树之外的文件；install 会说明原因：.gitattributes: skipped — <path> is outside this repo; git never merges it。

**合并驱动程序会合并它识别的内容，其余部分留给你处理。**实体、关系、项目、片段、错误和决策会根据它们在同步目录下的位置进行识别（如 entities/<file>、relations.json、episodes/<YYYY-MM>/<file>，等等），无论该目录叫什么，并按 id 合并。tombstones.json 会合并为一个以 (table_name, row_id) 为键的集合：保留双方的删除记录，各保留一次；如果双方都删除了同一行，则以较晚的删除记录为准。facts.json、procedures.json、artifacts.json 和 source_trust.json 会按导入冲突时使用的键合并——fact_id、id、(path, project_id)、source——如果双方都包含某行，则保留较新的那一行：已关闭的事实优先于未关闭的事实；过程采用较新的 updated_at（其成功和失败计数取两者中的较大值）；制品采用较新的 CRDT 时钟；来源的每项信任计数都取最高值。manifest.json 会在双方的 project_id、with_embeddings、embedding_dim、embedding_model 和 schema_version 一致时采用你的一方——导入会依据这些字段执行操作，但不会检查它们是否与文件匹配；其余内容都是派生数据，下次 sync export 时会重写。如果其中任一字段不同，就会产生冲突，提示信息会指出字段名称。embeddings.bin.zst、任何其他文件，以及双方任一侧无法完整解析或包含此版本不认识的字段的文件，都会导致程序以非零状态码退出，git 因而会保留冲突。以前，程序会在不写入文件的情况下以 0 状态码退出，git 会将其视为“已合并”：保留你的一方，丢弃另一方，且不留下任何标记。 删除现在会传播，并会在可能连带删除其他内容时停下。 删除一行会记录一个墓碑，接收端只删除其中列明的 ID。此前，删除并不是到达得慢——而是被撤销了：对端仍保留该行，将它导出，它便在下一轮往返中重新出现。实体墓碑最危险，因为删除一个实体会级联删除所有依附于它的内容。只有当这台机器上该实体下没有发送方未列明的观察或事件时，才会应用该墓碑；否则会暂缓应用，并在 tombstones_withheld 中报告。对端有 3 个子项的实体墓碑，不应在本端删除 300 个子项。

而且，数据包不能悄悄清空你的数据。 如果其中的墓碑会删除至少 25 行，并且超过本机观察总数的 10%，导入就会拒绝执行，并要求设置 confirm=true。远程清空和大量合理清理看起来一模一样，区别只在于这是否是你的本意。绝对数量下限和比例同样重要：对于只有一条观察的数据库，单看比例会要求用户确认删除这一条；而一个在日常整理时就会触发的保护机制，大家学会通过传入 confirm=true 来绕过它后，就形同虚设了。

conflict=merge 并不会合并内容，现在会明确说明这一点。 merge 和 skip 是同一种策略：本地缺少的行会被导入；对于已存在但内容不同的行，则保留先前已有的版本，并丢弃传入文本。变化在于不再默不作声——导入会统计这些行，并在 diverged 中报告，附上它们的 ID 和处理说明。conflict=overwrite 会采用传入版本，并将被替换的版本保留在 previous_versions 中（最多保留最新的 20 个）；如果内容发生变化，还会清除嵌入向量，让该行不再能凭借它已不再包含的含义被检索到。

无论采用哪种策略，计数器都会合并。 实体的 importance 和 access_count，以及关系的 strength，都不是由一端复制到另一端的值：每台机器都会根据自身的强化操作和遍历情况独立累积。两者取较高值，这样便具有幂等性——重复导入同一个数据包不会让数值膨胀。（求和更符合“双方都计数了”的直觉，但重复导入时会翻倍，因此不如不会破坏数值的规则可靠。）

识别哪台机器是哪台。 每个安装实例会在首次迁移时，在自己的数据库中生成一个 UUID——一行记录，重启后保持稳定，并且按设计唯一；清单会携带它，因此数据包可以注明由哪台机器生成。CUBA_NODE_NAME 的含义保持不变：它是存储在 origin_node 中、人类可读的标签。它不是身份标识，也不可能充当身份标识，因为两台机器都叫 pop-os 是最有可能发生的情况。

时钟为对端所需的变化而前进，本地杂动不会让它动。 观察的 version 只会在其内容、类型、可信度、证据等级或标签实际发生变化时递增，除此之外不会递增。衰减会改变 importance 和 last_accessed；reembed 会替换向量。如果这些操作也会让时钟前进，每次导出都会发送一张其实并未变化的图，两台机器就会不停地互相传递无关内容。用相同内容重写一行也不会让时钟前进，因此幂等的重新导入不会凭空制造本不存在的冲突。

旧数据包仍可导入。 格式为 SCHEMA_VERSION 2：现在会一并传递 version、updated_at、origin_node、previous_versions、evidence、verification 和 trust，因为比较时钟的冲突规则要求文件中包含时钟信息。此前写入的数据包仍可导入——所有新增字段都会使用默认值；而 v1 观察会被设为 asserted，这是对从未声称具有更高可信度的文件最诚实的解读。 任何看起来像凭据的传入包内容都会存为 quarantined，而非受信任内容——在你通过 cuba_eco 将其提升之前，不会提供给 cuba_faro 和 cuba_expediente——因为导入操作会从任何拥有推送权限的人都能写入的代码仓库中读取 JSON。

只读的对等节点。 CUBA_PEER_TOKEN 只能使用另外五个动词，除此之外什么也不能做。pull 会将数据包放在响应中返回，而不是写入任何位置，并按文件分页（limit、offset），每页最多 3 MB——如果分页期间 manifest_hash 发生变化，就中止操作，因为这意味着此节点在传输过程中被写入，分页内容描述的是两个不同的状态。notify 是对等节点令牌唯一可以执行的写入操作：用一段简短的 summary（最多 2000 个字符）说明另一台机器有了新发现，并标记 node_id/node_name；它会显示在下一次 cuba_jornada start 和 status 中，并在导入带有其 manifest_hash 的数据包时自动关闭——它本身永远不会进入图谱。conflicts 会列出两台机器意见不一致的行及其两种文本，resolve id=… keep=ours|theirs|both 则会关闭其中一项：keep=both（默认值）会保留本机文本为当前文本，并将另一方的文本存入 previous_versions，不丢弃任何内容；而 theirs 还会清除嵌入向量，因为它描述的是当前已不存在的文本。fetch 是另一半，在本机上运行：它会通过 HTTP 分页获取对等节点的 pull 数据，保存文件，并使用与任何数据包相同的验证流程导入；同时记录对等节点的清单哈希，因此如果内容没有变化，下一次 fetch 会在开启事务前停止。默认情况下，导出时不包含嵌入向量，而 pull 默认包含嵌入向量——收到无向量文本的对等节点在重新生成嵌入向量之前无法搜索刚收到的内容；而在没有 GPU 的机器上，重新生成会很慢且只能顺序进行——如果数据包的模型或维度与本机不匹配，就会拒绝该数据包，而不会悄悄将其他向量空间中的向量填入索引。

出现故障时，它会告诉你

$ cuba-memorys doctor
[  ok  ] migrations           49 aplicadas, ninguna dirty
[  ok  ] embedding_dim        runtime 1024-d == columna vector(1024)
[  ok  ] runtime_role         'cuba_app' sin superuser — RLS y audit efectivos
[ warn ] binary_freshness     4 proceso(s) MCP corren un binario más viejo que el de disco

之所以需要这个功能，是因为混合搜索引擎的故障模式不是崩溃，而是向量分支停止工作、搜索悄悄退化为词法搜索，却没有任何症状。现在，如果嵌入维度不匹配，服务器会拒绝启动；如果某个分支发生故障，搜索响应中会设置 degraded: true。

CLI：无需 LLM 介入的记忆

共有 23 个命令。运行 memory-industry --help 可查看所有命令。

dedupe — 因为不同的字符串就是不同的实体

cuba_alma create 使用 ON CONFLICT (name) 插入。因此，一个项目会被拆分成 Mapupita-Web、Mapupitta-Web（拼写错误）、Mapupita Web、mapupita……搜索其中一个时，找不到其他名称。在一个包含 266 个实体的真实图谱中，158 个实体（59%）没有任何关系——对于 PageRank 和多跳检索来说，它们根本不存在。

决定是否合并的不是嵌入向量质心。这看似是显而易见的办法，但实际上行不通：M-Codes Reference Guide 和 G-Codes Reference Guide 的质心余弦相似度为 0.811。在一个围绕单一领域的语料库中，质心相似度衡量的是领域，而不是实体——阈值设为 0.80 会把两本不同的 CNC 指南合并，且无法撤销。

因此，--apply 只合并有确凿依据的对象（统一大小写和分隔符后完全相同）。拼写错误和近似匹配会显示出来，逐个通过 --judge 判断。旧名称会写入 brain_entity_aliases，因此不会丢失：查询旧名称仍会解析到对应实体。

31 个工具

工具以古巴文化命名。cuba-memorys 会公开所有工具，也可以设置 CUBA_TOOL_PROFILE=lean，只公开 13 个日常核心工具，以及 cuba_tools + cuba_call——31 个工具中有 15 个，目录缩小 49%，且没有丢失任何功能，其余工具可按需调用。

知识图谱 — cuba_alma（实体）· cuba_cronica（观察、事件、时间线）· cuba_puente（类型化关系、遍历、链接预测）· cuba_ingesta（批量导入）

搜索 — cuba_faro（混合 RRF、验证、MMR 多样化、OOD 弃答）

错误记忆 — cuba_alarma（报告）· cuba_remedio（解决）· cuba_expediente（搜索过往错误；如果某种方法此前失败过，会发出警告）

会话与决策 — cuba_jornada（会话生命周期、差异）· cuba_decreto（架构决策）· cuba_proyecto（按项目隔离）· cuba_pre_compact（在 /compact 后保留状态）

程序性 — cuba_receta（按 Wilson 下置信界排序的配方）

认知 — cuba_reflexion（差距检测）· cuba_hipotesis（溯因推理）· cuba_contradiccion（语义冲突）· cuba_juez（大模型裁判）· cuba_centinela（前瞻性触发器）· cuba_calibrar（贝叶斯校准、来源可信度）

维护 — cuba_zafra（衰减、剪枝、合并、PageRank、Leiden 社区）· cuba_eco（RLHF 反馈）· cuba_vigia（健康状况、漂移、中心性）· cuba_forget（GDPR 擦除）· cuba_archivo（CFR-21 哈希链审计日志）· cuba_pizarra（工作记忆）· cuba_sync（通过 git 在机器间进行便于版本控制的导出/导入，支持传播删除操作并防止远程擦除）

元工具 — cuba_tools（发现）· cuba_call（调用）

配置

占用情况

记忆服务属于基础设施：即使你不使用它，它也会运行。在测试所用的 6 GB 笔记本 GPU 上，它过去从启动起就会占用 5228 MiB 显存——占显卡显存的 93%——导致其他 GPU 程序无法启动。NVIDIA 驱动在创建通道时会返回 NV_ERR_NO_MEMORY，这也是游戏或 GPU 加速终端无法运行时遇到的问题。

下面的四项数据中，两项是随附的默认值；另外两项需要添加配置行。此表将它们区分开来，而不是把最佳数据说成是默认就有的。

默认值列中的所有内容都是随附代码的一部分。CUBA_RERANK_CHUNK=4 是一个环境变量。最后一列还需要使用下文所述的重新构建的重排序器。这些改动没有移除任何功能。

四项改动让它达到了现在的状态：

按模型而非按进程分配。 只有重排序器使用 GPU 加速——INT8 嵌入器无法使用 GPU，而 FP32 NLI 偶尔才会运行，并且可以容忍 150-400 ms 的延迟，不值得为它占用 1 GB 显存。arena 上限按会话计算，因此在 6 GB 显卡上，三个会话都请求 CUDA 就意味着超额分配 3 倍，迟早会失败。

不再不断翻倍的 CUDA arena。 ArenaExtendStrategy::NextPowerOfTwo 是 ONNX Runtime 的默认值，它会按 2 的幂次预留，而不是按会话所需的大小预留。

重排序器在收到首个批次时才加载。 使用套接字激活时，守护进程的启动次数远多于执行重排序的次数，而且很多次启动只会响应 save。

无人请求时不运行守护进程。 CUBA_IDLE_SHUTDOWN_SECS 加上 systemd .socket 单元：套接字占用端口，守护进程在收到首个实际连接时启动，并在空闲时间结束后退出。它会通过常规路径关闭——serve 返回，后台 drain 刷新正在进行的嵌入写入，sqlx 关闭连接池——因为直接退出进程会悄无声息地丢失这些写入。

# ~/.config/systemd/user/memory-industry.socket
[Socket]
ListenStream=127.0.0.1:8787
Accept=no

[Install]
WantedBy=default.target

# ~/.config/systemd/user/memory-industry.service (abridged)
[Service]
Type=exec
ExecStart=%h/.local/bin/memory-industry serve 127.0.0.1:8787
# Every knob — CUBA_IDLE_SHUTDOWN_SECS, the per-model devices — lives in the env file, never here.
EnvironmentFile=%h/.config/memory-industry/memory-industry.env
# An idle shutdown exits 0 — Restart=always would bounce it straight back up.
Restart=on-failure

VRAM 只是其中一半。模型权重也驻留在主机内存中，而过去无论机器配置如何，这部分内存需求都是固定的。使用 cargo run --release --features cuda --example mem_bench 测量，守护进程已停止，测试设备为配备 6 GB 笔记本 GPU 的机器：

常驻内存最终稳定在约 1941 MiB；峰值达到 2677 MiB，是因为加载 1,1 GB 的 ONNX 文件时，除了留下的模型权重之外，还会产生瞬时内存开销。必须满足的是峰值，而不是稳定状态。

在进行测量的这台机器上，这没问题。但在 4 GB 笔记本上就不行了；在受 MemoryHigh=4500M 限制的 systemd 单元下，曾观察到 2,56 GiB 被换出到 swap——MemoryHigh 不会终止进程，而是回收内存；回收内存意味着换页。

重新运行测试时，有两个需要了解的注意事项。mem_bench 通过 nvidia-smi --query-compute-apps 统计自身 PID 占用的 VRAM，因为读取 memory.used 会把显卡上其他所有进程的占用也算进去——第一次尝试显示进程启动时占用了 3590 MiB，其实是游戏和桌面 shell 占用的。还要使用守护进程自己的环境运行：如果未设置 CUBA_RERANKER_PATH，它会悄悄加载未融合的产物，在 CPU 上的预热时间会从 3,7 s 增至 131 s。

因此，守护进程现在会在启动时读取机器信息并选择一个级别。这不是凭空新增的机制：这三种降级方式原本就已存在，也都有测试覆盖。

级别的选择方式。 预算为 min(cgroup 限制，系统可用内存) − 768 MiB 的余量，并且必须以 cgroup 限制为准。在这台机器上，/proc/meminfo 报告可用内存为 7,16 GB，而守护进程的 cgroup 将其限制在 4,39 GiB——如果相信 /proc，就会在内核已经开始换页的限制下加载 2,6 GiB 的模型权重。读取器会从 cgroup 根目录一路遍历到叶节点，并采用找到的最严格的 memory.max 或 memory.high，因为限制通常设在某个祖先节点上。

随后按实测价值依次加载模型：先加载嵌入模型，再加载重排器（nDCG 提升 +93%，因此优先级高于判别器），最后加载 NLI。

该方案只能减少配置。 每个参数的上限都设为守护进程原本使用的值，因此在资源充足的机器上，级别为 full，一切保持不变。降级只会向下进行。

你始终拥有优先权。 手动设置的以下任一项都会保持原样——调节器只会补齐缺失项，不会覆盖已有决定：

CUBA_EMBED_INTRA_THREADS   CUBA_RERANK_INTRA_THREADS   CUBA_NLI_INTRA_THREADS
CUBA_RERANK_CHUNK          CUBA_GPU_MEM_LIMIT_MB       CUBA_OOD_FIT_LIMIT
CUBA_DB_MAX_CONNECTIONS

无论预算如何，都可以通过将模型指向一个不存在的路径来强制关闭它——CUBA_RERANKER_PATH=/nonexistent 或 CUBA_NLI_PATH=/nonexistent。调节器自身也使用同样的机制。

要查看它的决定，运行 cuba-memorys doctor：它会报告检测结果和由此生成的方案，并在级别降至 minimal 时发出警告。启动时也会记录该方案，并附上完整的机器检测信息。

重排模型产物

发布的 bge-reranker-v2-m3 ONNX 在任何图融合之前就已转换为 FP16，因此其中穿插着 785 个 Cast 节点。ONNX Runtime 在加载时会挽回一部分（节点数从 2023 降到 897，包含 49 个 SkipLayerNormalization），但它无法融合 Gelu，而且每次冷启动都会重复这项工作。从 FP32 导出版本重新构建并先进行融合：

python -m onnxruntime.transformers.optimizer \
  --input model.onnx --output model.onnx \
  --model_type bert --num_heads 16 --hidden_size 1024 \
  --opt_level 1 --use_gpu --float16

在真实搜索中，前 10 个结果的顺序完全相同，fused_score 的差异最多为 0,0029；在真实批次形状的合成 logits 上，Pearson ≥ 0,9997，且每个批次的排名都相同。

Attention 不会融合，而且在这里无法解决。 在 FP16 产物和干净的 FP32 产物上，opt_level 为 0、1、2 和 99 时，结果均为 is_fully_optimized: Attention (or MultiHeadAttention) not fused。该导出版本通过动态形状子图（Shape → Gather → Unsqueeze → Concat → Reshape）构建 Q/K/V reshape，而 AttentionFusion 需要一个形状为常量的 Reshape，才能从中读取 num_heads 和 head_size。因此，如果不使用静态形状重新导出，flash/efficient attention 就无法使用——在有人为此花上一下午之前，值得先了解这一点。

测量结果——以及那个撒谎的基准测试

直到 v0.12，本节还保留着这样一句话：“这里的每个数字都是实测值，而非假设值”；但其中的每个数字都是错的。基准测试有三个方面的问题，发现这些问题后，我们撤回了两个已发布的结论。

只有 10 个查询。 95% 置信区间约为 ±0.12；它能检测出的最小效应约为 0.25 nDCG。任何关于更小差异的说法，都只是带着小数点的噪声。

相关性通过子串匹配判断。 只要结果文本包含一个标记词，就算正确——因此，任何提到“postgres”的观察都被算作对任何 postgres 相关问题的正确答案，无论它实际上有没有回答问题。这衡量的是关键词是否出现，而非检索效果，而且会让整个基准测试偏向词法分支、不利于向量分支。

nDCG 是根据检索到的内容，而非实际存在的内容进行归一化。 如果语料库中有 5 篇相关文档，但只找到 2 篇，那么这 2 篇就被当作“理想”排序——这样一来，漏掉 60% 答案的系统也能得到完美的 1.0。（而且，这个文件发布时的 R@10 = 3.125。召回率是一个比例。）

真实数字不是 0.894。在 221 个带有 ID 的查询上，结果是 nDCG@10 = 0.50 [95% CI 0.44–0.56]。系统并没有变差，它从来就不是 0.894。

这造成的影响

• “交叉编码器重排器毫无收益”——它从来没有运行过。 三个错误接连出现：faro 用 if let Ok(..) 包裹调用并丢弃了错误；它向一个不包含 token_type_ids 的 XLM-RoBERTa 模型传入了 token_type_ids；它把 f16 logits 当成 f32 读取。输出与未进行重排时“逐位完全相同”，不是因为重排没有改变结果，而是因为它根本没有运行。现已修复；正在进行正确的测量。

• 关联检索确实会变差——但旧证据（n=10 时为 −0.03）根本无法证明这一点。在新数据集上使用配对自举法（正确的检验方法：两组使用相同的查询）后，置信区间为 [−0.051, −0.018]，从未触及零。它没有改善任何查询，却损害了 23 个查询。决策是对的，理由却不对。关键不在于增加更多数据，而在于使用正确的检验方法。

重新诚实评估后仍然成立的结论

基础理论

开发

git clone https://github.com/LeandroPG19/Memorys.git
cd Memorys/rust && cargo build --release

# On an NVIDIA machine, build this way instead — without it the reranker spends
# its whole budget for a ranking that gets discarded. It accelerates the
# reranker only; see Footprint for why the other two models stay on the CPU.
cargo build --release --features docs,cuda

./scripts/demo.sh                  # runs on a throwaway Postgres it removes on exit
./scripts/merge-gate.sh            # local CI 100% — sole merge judge (see docs/gate.md)
./scripts/como-el-ci.sh todo       # same SIL
./scripts/quality-gate.sh          # second judge: CRAP + mutants of rust/src in the diff
cargo run --release --example rerank_bench   # does the reranker fit its budget here?

发布由标签驱动：在 LeandroPG19/Memorys 上创建 v* 标签，即会触发 GitHub Release 二进制文件（5 个平台）、PyPI wheel（memory-industry 和 cuba-memorys 别名）、npm（memory-industry 和 cuba-memorys 别名）以及 MCP Registry（io.github.LeandroPG19/memory-industry）的发布。测试会固定 Cargo.toml、package.json、pyproject.toml 和 server.json 中的版本，确保它们不会出现偏差。

许可证

Apache-2.0 — 可使用、修改、发布、销售，也可将其嵌入闭源产品。无需承担著佐权义务。该许可证还明确授予专利权，这正是法务部门关心的部分。

作者

Leandro Perez G. — @LeandroPG19