跳转至

尚无译文的页面会以英语打开,并标注为英语。

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

根据审计结果优化命名空间

如果写入方把 memory.set 当作对象存储来用(以哈希键保存 JSON blob,把租约存成记忆,把文档存成 claim),每张表都会保持一致,但召回却毫无用处。本流程把这样的命名空间重新整理为 investigation agent 指南中描述的布局。每一次迁移都会留下重定向,因此仍在运行的写入方继续读取旧键时,依然能得到答案。

Claude Code 和 Codex 插件中的 loom-optimize skill 会执行相同的步骤。

两个操作

namespace.audit(POST /v1/namespace.audit,MCP loom_namespace_audit,CLI loom audit-namespace)。只读。

输入 默认值
org, namespace 必填
window_seconds 604800(7 天)
sample_limit 5

它返回 summary(live_rows、live_bytes、excerpt_bytes、version_rows、version_bytes、unembedded_rows、gets、searches、sets、get_search_ratio,以及 inspector_calls:控制台和助手工具集发起的 get 与 search,不计入上述计数;从控制台发起的写入会计入 sets)、findings[](code、severity、count、share、bytes、samples[]、detail、remedy)、skipped(无法运行的规则:检查、摘要读取、证据读取;其余规则仍会返回结果)、coverage、healthy(“没有严重问题”),以及 criticals / warnings / infos 的计数。样本包含键、行 id、标识列和计数,从不包含值。每条 finding 还带有证据字段;计划会读取 kind(使用情况的启发式判断不能证明存在误用)、samples_complete 和 evidence[],即每个样本行当前的 version 和 content_sha256。

memory.move(POST /v1/memory.move,MCP loom_memory_move)。

输入 默认值
org, namespace, agent, from_key, to_key 必填
value, memory_type, tags, entities, valid_at, source_resource_id 沿用源行的值
keep_redirect true
if_match_sha256 无
dry_run false

它返回 {from_key, to_key, redirected, memory_id, version, content_sha256, advisories, dry_run};试运行(dry run)还会返回 memory_type 和 value_preview。移动之后:

  • memory.get(from_key) 仍返回旧值,并附带 canonical_key;
  • memory.get(from_key, follow=true) 返回新行;
  • memory.search 和 memory.list 只显示新行。

1. 审计

loom audit-namespace --org <org> --namespace <ns> --window-days 7 --samples 5

该 CLI 在服务器上运行(直接读取 ClickHouse)。它会输出一张表(code、severity、kind、count、share、first sample),使用 --json 时则输出 output model,并在命名空间不健康时以退出码 1 退出。在其他任何地方,请通过 HTTP 或 MCP 调用 namespace.audit。

先看 summary:

  • get_search_ratio 达到数百,说明该命名空间被当作键值存储使用(对 procedure 的读取是有意按键读回的,因此不计入其中);
  • unembedded_rows 大于零,说明存在搜索永远找不到的行。

然后再看各项发现。当 healthy 为 true 且没有 warning 或 critical 时即可停止:info 级别的发现是写入方需要留意的提示,不需要返工。system_state 类发现(索引积压、缺少遥测数据)与部署有关,与写入方无关;当 telemetry_unavailable 为 warning 时,exact_key_store 和 intentional_exact_key_reads 会被列入 skipped,而不是视为通过,coordination_as_memory 则只运行其 key 段分支(samples_complete: false)。

控制台的命名空间审计面板显示的是同一份审计结果。当命名空间不健康时(出现一项 critical 发现,或在 exact_key_store、double_encoded_values、unembedded_rows 和 coordination_as_memory 中出现两项 warning),context.pack 会携带 namespace_health 块,因此 agent 在会话开始时就能看到它。

2. 方案

每个发现项写一个小节。只有审计返回的代码才有对应的小节。

发现项 变更内容 做法
double_encoded_values, json_prefix_excerpts, hash_keys 该行迁移到可读的键,值以结论句开头 解码一次;先写结论句,再写来源行,其余内容写成简短的行;使用带 value、tags、entities、valid_at、if_match_sha256 的 memory.move
oversized_values, episodic_blobs 正文变成文档或 blob;保留键的行只留一段话 先用 knowledge.upsert(Markdown,source_uri=loom://<org>/<ns>/<key>)或 context.offload,再用 memory.move 迁移旧键,并以这段话作为 value
unembedded_rows 值被拆分或缩短,以便生成嵌入 同 oversized_values;namespace.validate 会在其 unembedded 行中列出这些记录
coordination_as_memory 该块内容转入工作记忆;旧键仍可继续应答 先 working_memory.set,再用 memory.move 并设置 keep_redirect=true
hand_rolled_index_rows 这些行保持可读并增加 tags;写入方不再产生它们 只加标签(memory.update_by_id);不迁移
exact_key_store, version_churn 写入方需要修改 把这些键列给负责人
telemetry_unavailable, index_backlog, intentional_exact_key_reads 无需改动:这是部署的状态,或是一种工作流 不做整改;对于 telemetry_unavailable,待账本覆盖该时间窗口后重新运行;对于停滞的 index_backlog,检查嵌入 worker

mentor(mentor.brief)还会指出另外三种属于数据变更的形态。它们按同样的规则整改,以提示中的 evidence 作为计数:

Mentor 提示 变更内容 做法
documents_as_memories 同 oversized_values 先 knowledge.upsert,再用 memory.move,以这段话作为 value
checkpoints_as_memory 运行转储变成 context.offload blob;由一条以运行 id 为键的简短 episodic 行取而代之 context.offload,再用 memory.move,value 为一行账本记录,memory_type=episodic
records_for_identities 以 <prefix>-<id> 为键且带标量字段的行,变成一个 schema 加每行一条 record 先 memory_schema.register 一次,每行 memory.record.write,再用 memory.move 迁移到指针行

每个小节需说明:数量和字节数,三个“之前 → 之后”的示例键(取自该发现项的 samples),带参数的完整调用,以及它不会做的事:

  • 不使用 memory.delete;
  • 不原地修改值:重写后的值只会写入新键;
  • 不处理最近一小时内写入的行:写入方可能正在写入过程中。

把方案作为知识文档存放在 loom://<org>/<ns>/_optimize/plan-<YYYYMMDD>(用 knowledge.upsert 并指定该 source_uri),这样负责人的批准以及整改前后的数字就集中在一处。

3. 获得批准

命名空间所有者需以书面形式批准。展示计划不等于计划已获批准。部分批准仅适用于所指明的章节。如果所有者的写入方正在运行(审计中该时间窗口内的 sets 会显示这一点),请告知对方;无论如何,最近一小时的行都不在范围内。

4. 应用

如果该命名空间很重要,请先备份:将 memory.list … fields=["value"] 的结果导出到 JSONL 文件;使用 namespace.snapshot(可通过 HTTP 或 SDK 调用,MCP 不提供此操作);或者在服务器上使用 CREATE TABLE … AS loom.memory 加 INSERT SELECT(参见备份与恢复)。

  1. 对每个部分的前三次移动使用 dry_run=true 运行,并读取返回的 to_key、redirected 和 advisories。
  2. 然后按 created_at 顺序分批移动,每批最多 50 条,这样各个修订会成为新键的多个版本。
  3. 传入审计样本或最新一次 memory.get 得到的 if_match_sha256。返回 409 表示该行已被他人修改:请暂停该部分,重新读取后再确认。
  4. 如果回复中没有 memory_id、version 和 content_sha256,说明这次移动没有发生,不要计入。
curl -s "$LOOM_BASE_URL/v1/memory.move" -H "Authorization: Bearer $LOOM_API_KEY" \
  -H 'Content-Type: application/json' -d '{
    "org": "acme", "namespace": "agent-sre", "agent": "sre-bot",
    "from_key": "3f9a0c1e5b7d2a4c6e8f0a1b3c5d7e9f",
    "to_key": "sre/case/c-42/evidence/e-7",
    "value": "Disk on ingest-3 filled at 02:10 UTC.\nSource: alert A-981.",
    "tags": ["case:c-42", "kind:evidence"],
    "dry_run": true}'

5. 度量

在相同的时间窗口内再次运行审计,并将前后对比表追加到计划文档中(对同一个 source_uri 执行 knowledge.upsert)。请将写入规则提供给负责人。

6. 不要退役任何内容

只要所有者愿意,旧键就可以一直通过重定向读取。一旦写入方改用新键,所有者可以用 memory.delete 将旧键标记为墓碑(软删除:memory.history 仍会保留它们)。此流程从不执行该操作。

警告: 如果退役仍有活跃写入方在读取的键,会使其视图分裂:它的 memory.get 会返回 found: false,客户端可能回退到本地状态,两个存储随之出现不一致。重定向的存在正是为了防止这种情况。

相关内容