尚无译文的页面会以英语打开,并标注为英语。
本页由机器从英文原文翻译,内容以英文原文为准。 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(参见备份与恢复)。
- 对每个部分的前三次移动使用
dry_run=true运行,并读取返回的to_key、redirected和advisories。 - 然后按
created_at顺序分批移动,每批最多 50 条,这样各个修订会成为新键的多个版本。 - 传入审计样本或最新一次
memory.get得到的if_match_sha256。返回 409 表示该行已被他人修改:请暂停该部分,重新读取后再确认。 - 如果回复中没有
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,客户端可能回退到本地状态,两个存储随之出现不一致。重定向的存在正是为了防止这种情况。
相关内容
- 调查类 agent 记忆:目标布局
- Agent 集成
- 历史与来源追溯