跳转至

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

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

记忆

一条记忆就是 agent 之后应当能再次找到的一个论断,例如“部署在周二进行”“支付团队负责账单服务”。Loom 把每个论断存为 loom.memory 中的一行,使用可读的键,并记录写入者、论断成立的时间、来源,以及是否有人为其背书。本页介绍这一行的结构、写入时如何与已存储的内容比对判定,以及行如何随时间变化。检索与排序介绍如何找到这些行。

ClickHouse 中的行

记忆、文档分块、对话轮次、实体边、代码符号、运行记录、审计条目和擦除请求,都是 ClickHouse 中的行,由服务器在启动时应用的编号迁移创建。在 Postgres 记忆权威模式下,Postgres 保存实时的记忆和知识状态,ClickHouse 则保存向量、搜索和历史记录。上传的文档原件也是 ClickHouse 中的行(loom.document_blobs),除非部署把它们的字节保存在兼容 S3 的存储桶中。除了 ClickHouse、Postgres 和该存储桶之外,Loom 还在共享卷上保存代码索引的 git 镜像(即 ClickHouse 所记录远程仓库的缓存)以及限流桶。

  • 身份元组位于排序键的最前面。 loom.memory 按 (org, namespace, agent, user_id, session_id, memory_key) 排序,因此把读取限定在某个命名空间内就是一次主键范围查询;只有在指定了 agent 的情况下,user 才能完全缩小范围;只有在指定了 agent 和 user 的情况下,session 才能完全缩小范围。身份与命名空间介绍了这个元组。
  • 单一引擎。 在默认的 ClickHouse 权威模式下,向量搜索、词法搜索、图遍历、过滤、审计和擦除都是针对同一批行的 SQL,无需再维护另一个需要保持同步的存储。代价是每次读取都是一次查询,而不是键值命中。在 Postgres 权威模式下,点读取(按键或 id 读取,且不在 as_of 回放中)由 Postgres 响应。
  • 写入即新版本。 记忆表使用 ReplacingMergeTree(version),并通过 FINAL 读取。修订、墓碑标记、固定或恢复操作都会插入一条新的版本行。

写入、派生、读取循环

flowchart LR
    W["Writer: memory.set,<br/>set_from_messages,<br/>knowledge.add"] --> G["Write checks:<br/>lock, pin, blacklist,<br/>precondition, conflict"]
    G --> T[("ClickHouse rows:<br/>memory, embeddings,<br/>chunks, audit_log")]
    T --> D["Workers derive:<br/>entities, deferred extraction,<br/>consolidation, calibration,<br/>usage folds"]
    D --> T
    R["Reader: memory.search,<br/>memory.ask, context.pack"] --> L["Retrieval legs:<br/>vector, lexical, graph,<br/>chunks, digests"]
    T --> L
    L --> K["Fuse and rank,<br/>gate or abstain"]
    K --> A["Answer with provenance"]
    A --> F["run.complete,<br/>memory.outcome"]
    F --> T
  1. 写入。 memory.set 会先执行各项检查(见下文),然后内联生成嵌入向量,并插入记忆行、对应的嵌入行、长值的原文分块(verbatim chunks)以及一条仅含哈希的审计行。如果内联嵌入失败,调用即失败,不会写入任何内容。memory.set_from_messages 由 LLM 从对话记录中挑选出需要长期保留的事实,并通过同样的批量路径写入。
  2. 派生。 Workers 负责处理对写入路径来说太慢的工作:实体标签(entity_extractor)、延迟提取(extraction_queue)、整合后的事实、门限重新校准,以及折算为排序信号的使用情况(usage_fold)。派生行带有 source_class=derived。
  3. 读取。 memory.search 会运行多条检索路径(向量、词法、实体图、原文分块、会话摘要),将结果融合并排序,然后返回命中结果或放弃回答。memory.ask 生成有依据的回答;context.pack 构建受预算限制的提示词块。
  4. 反馈。 如果一次运行指明了它所依赖的记忆(run.complete 的 memories_used,或 memory.outcome),这些记忆会获得加分;结果不佳则记录损害。这会形成一个有界且随时间衰减的排序项。它不会删除任何行,也不会把某一行排到其相关性应有的位置之下。

该循环是最终一致的。写入后立即读取,可以通过内联嵌入找到该事实;实体和提取出的事实会在 worker 下一轮处理之后出现。

loom.memory 行

一行是一条记忆的一个版本。

分组 列 决定
身份 org, namespace, agent, user_id, session_id, run_id 谁可以读取它,以及谁写入了它
地址 memory_key, memory_id 调用方如何称呼它(key),以及 Loom 如何称呼一行(id)
内容 value, memory_type, tags, entities, files, confidence 它说了什么,以及如何分类
生命周期 status, pinned, conflict_with, duplicate_of, superseded_by, version 它是否被提供,以及被什么取代
时间 created_at, updated_at, valid_at, valid_to, invalid_at, expires_at 它何时写入,何时有效,何时停止服务
来源 actor, source_class, content_sha256, verified_by, verified_sha256 谁写入了它,Loom 如何得知它,是否有人证实过它
防护 lock_mode, lock_until, sensitivity, on_expire 它拒绝哪些写入,以及如何读取它

完整的列列表见schema 参考。可搜索的记忆在 loom.memory_embeddings 中也有一行:包含 value 和 key 的向量,用于词法匹配的摘录的小写、词干提取和词形还原副本,以及排序器读取的 source_class 和 verified 标志。

键

一个键以可读路径 <scope>/<kind>/<id> 命名某个主体的某一项属性:

sre/case/1234/evidence/dns-sidecar
project/loom/deploy-window
user/preferences/editor
  • 一个键只存一条事实。 冲突检查、取代和历史都按键进行。如果一个键里存放了多条互不相关的事实,就无法只修订其中一部分。
  • 修订时重写同一个键。 Loom 会保留每个版本,因此带编号的副本(…-v2)或由值的哈希生成的键只会掩盖修订。由哈希生成的键会在 namespace.audit 中作为 hash_keys 发现项列出。
  • 分面信息放在 tags 和 entities 中, 不要放进键里。

存储标识为 (org, namespace, agent, user_id, session_id, memory_key):同一个键由两个 agent 写入,或在两个会话中写入,就是两行记录。在命名空间策略 newest_wins 下,某个键的最新写入会使该命名空间中所有带该键的较旧有效行失效,无论是谁写入的。提取时,键由主体和属性生成,而不是由值生成,因此之后的会话如果陈述同一属性,就会落在同一个键上。在 auto_reinforce 和 manual_review 下,冲突解析器会判定同一用户的两个会话(不包括匿名用户 - 或发送为空的 user_id,它们的会话属于相互独立的任务)通过单点写入或批量写入而写下的同一个键的各行,判定方式与判定任何相近的记录对相同:对于它有把握判定为更新的情况,它会使较旧的行失效(manual_review 下除外),将矛盾标记为待审核,并让复用同一个键的两条不同事实保持有效。在 append_only 下不做任何判定。

记忆类型

memory_type 是自由字符串,默认值为 semantic。少数取值会改变该行的存储和检索方式(server/memory/domain/memory_types.py):

类型 是否嵌入 是否出现在未过滤的搜索中 用途
semantic(默认) 是 是 持久的事实。
preference 是 是 应在召回中排名靠前的偏好。
procedural 是 是 流程(procedure.*)。
reflection 是 否 从运行中得到的经验教训;使用 memory_type="reflection" 读取。
episodic 否 否 按时间先后重放的会话事件。
profile 否 否 按标签获取、始终加载的上下文(profile.*)。
其他任意值(decision) 是 是 领域类型默认可被搜索。
  • 反思不会出现在未过滤的搜索和 memory.ask 中:关于某个流程的经验教训,并不是对世界的陈述。
  • procedural 写入的值如果不是流程主体(非空的 situation 和至少两个 steps),则会以 semantic 存储,并标记 retyped_from:procedural,响应会在 retyped_from 中说明这一点。
  • 敏感度。 sensitivity="high" 的行不会被嵌入,因此任何搜索分支都找不到它。它只能通过 key 读取,且该读取会被审计。未设置 sensitivity 时,服务器会检测凭据格式、银行卡号、美国社会安全号码和明示的 PIN(high),以及电子邮件、电话和 IBAN 格式(medium)(LOOM_MEMORY_SENSITIVITY_AUTODETECT)。

状态

状态 含义 默认是否返回
active 当前有效的记忆。 是
conflicted 与另一条记忆相近但内容不同,通过 conflict_with 关联。 是
duplicate 与某条规范记录(duplicate_of)几乎完全相同,由该规范记录代为应答。 否(include_duplicates)
superseded 已被后来的记录取代(superseded_by,在 invalid_at 失效)。 否(include_superseded)
proposed 处于试用期的事实,通过 memory.proposal_decide 决定去留。 否(include_proposed)
rejected 被标记为错误(memory.reject,或被拒绝的提议)。 否
tombstoned 已被其写入者删除(memory.delete)。 否

默认返回的状态集合只在 server/memory/domain/temporal_sql.py(SERVED_STATUSES)中定义一次。conflicted 记录仍会被返回:如果隐藏矛盾的某一方,存储就会用一条自己有理由怀疑的事实自信地作答。

写入如何被判定

五个操作覆盖记忆的整个生命周期:

视角 操作 效果
扩展 memory.set 在某个 key 下记录一条事实。
修订 memory.update_by_id 按 id 修正一行(memory.update 按 key 做同样的事)。
收缩 memory.delete 为某个 key 打上墓碑标记。memory.restore 可在删除后 14 天内恢复。
强化 memory.pin 存储并固定:之后任何本身不固定的写入都不能替换它。
拒绝 blacklist.add 拒绝此后所有匹配某个子串或正则表达式的写入。

可搜索的 memory.set 按顺序执行以下检查:

  1. 锁与固定保护,作用于该 key 下的现有行。memory.lock(read_only 或 no_delete)返回 423 LOCKED。对已固定的 key 写入不同的值,返回 409 PINNED_CONFLICT。逐字节相同的重复陈述可通过所有保护。
  2. 黑名单。 值匹配已登记的模式时返回 422 BLACKLISTED;在批量写入中,该条目会被跳过。各副本缓存这些模式,并轮询一张只有一行的版本表(loom.blacklist_version),因此新模式会在数秒内到达每个副本。
  3. 前置条件。 if_match_sha256 使写入只在当前有效行的哈希仍然匹配时才生效;否则返回 409 PRECONDITION_FAILED。当前哈希(content_sha256)会包含在每个 memory.get、memory.get_by_id 和 memory.set 的响应中。
  4. 重复陈述。 与当前有效行逐字节相同的值,会写入一个新版本,并带上当前有效行的 reinforcement_count + 1。批量路径(memory.bulk_set,由 set_from_messages 使用)把 (org, namespace, agent, user_id) 内任何哈希相同的有效行视为同一条事实(LOOM_MEMORY_BULK_DEDUP_SCOPE=identity)。
  5. 近邻搜索与判定。 同一 memory_type 中、嵌入向量与新值接近的活跃行是近邻,按距离由近到远比较;指明了 user_id 的写入只从该用户的行中取近邻(写入如何被判定):
    • 规范形式相同(转为小写、去除标点、合并空白)→ merge:不写入任何内容,近邻被强化,merged_into_key 指明它;
    • 存在接近的已固定近邻 → rejected,409 PINNED_CONFLICT(在覆盖整个命名空间的令牌下,如果写入指明了用户,并重复陈述了其他用户的或共享的已固定值,则会被写入);
    • 在 newest_wins 下,如果某个近邻陈述了相同的主语和谓语但宾语不同 → refines:该近邻被停用,除非它的 valid_at 晚于新行的,此时返回 conflict;
    • 余弦相似度达到或超过重复阈值,且实词相同、没有不同的取值(数字、时间、金额或单位;如 "27:10" / "26:30")→ duplicate;
    • 余弦相似度达到或超过冲突阈值但内容不同 → conflict,两行均标为 conflicted;
    • 没有接近的近邻 → clear。
  6. 插入到 loom.memory 和 loom.memory_embeddings,并执行取代、实体投影,以及在 loom.audit_log 中写入一行仅含哈希的记录。

不可搜索的类型或 high 敏感度的行会跳过近邻搜索:它们没有可供比较的嵌入向量。dry_run=true 会运行所有检查但不写入任何内容,可在你确定 key 之前回答“这是新事实、重复陈述还是矛盾?”。响应包含 conflict_verdict、最多五个 peers 以及一个 next 提示。

  • 阈值。 开启 LOOM_ADAPTIVE_THRESHOLDS 并使用真实的嵌入器时,冲突阈值和重复阈值在启动时由该嵌入器自身的相似度分布得出(server/memory/app/embedder_calibration.py)。标量 LOOM_CONFLICT_THRESHOLD(0.85)和 LOOM_DUPLICATE_THRESHOLD(0.97)作为回退值。命名空间或记忆类型可以固定自己的阈值;calibration.get 会报告当前生效的是哪一个。
  • 冲突解析器。 余弦相似度只说明两条陈述讲的是同一件事,不说明它们是否一致。一个仅在 leader 上运行的 worker 会在写入落地后,对每条带有接近近邻的写入做判断,每行一次 LLM 调用:在默认的 auto_reinforce 和 newest_wins 下,对于它确信是更新的情况,会停用较旧的行(旧值仍可通过 include_superseded 和 as_of 读取),标记矛盾,并清除错误的标记(冲突)。对写入本身的判定不会调用 LLM。
  • 运行范围。 在某个 run_id 下的写入,如果其规范匹配项属于另一次运行,则按 duplicate 存储而不合并,因此限定运行范围的读取仍能找到它。
  • 命名空间策略。 default_conflict_policy 决定矛盾如何处理(auto_reinforce、manual_review、newest_wins、append_only)。

memory.update、memory.update_by_id 和 memory.bulk_set 运行相同的检查。判定细节、各项策略、Review 队列和 conflicts.resolve 见冲突与拒绝。

固定保护用户说过的内容。 已固定的行不会被本身不固定的写入替换,无论是按 key 写入,还是在另一个 key 下写入接近的值。要修改它,请使用 memory.update(保留固定状态)或 memory.pin(重新固定)。memory.for_file 会把已固定的行排在最前;其他读取都不按固定状态排序。

整合会保留谱系。 memory.consolidate(以及命名空间选择启用时的整合 worker)把关于同一主题的片段合并为 source_class='derived' 的规范行,并为每个来源写入一行 loom.memory_belief_sources(support_type='derived_from')。删除某个来源时,如果整合行的所有来源都不再存在,则该行被停用;如果仍有部分来源存在,则降级为 conflicted(memory.delete 响应中的 dependents_tombstoned、dependents_downgraded)。

记忆的生命周期

stateDiagram-v2
    [*] --> active: memory.set (clear, refines)
    [*] --> conflicted: memory.set (conflict)
    [*] --> duplicate: memory.set (duplicate)
    [*] --> proposed: memory.set(proposed=true)
    active --> conflicted: a later close write
    conflicted --> active: conflicts.resolve (revise, allow)
    conflicted --> tombstoned: conflicts.resolve (contract, or peer revised)
    proposed --> active: memory.proposal_decide (accept)
    proposed --> conflicted: memory.proposal_decide (accept, contradicted on trial)
    proposed --> rejected: memory.proposal_decide (reject)
    active --> rejected: memory.reject
    active --> superseded: newer write (newest_wins, refines, conflict resolver)
    superseded --> active: memory.restore
    active --> tombstoned: memory.delete, blacklist sweep, expiry
    tombstoned --> active: memory.restore (within 14 days)

每个箭头都是一个新版本;旧版本保留在 loom.memory_versions 中。

标签、实体与文件

  • tags 是自由标签(case:1234、kind:evidence)。搜索可以按标签过滤(tags)、用标签加权(tags_soft),或让带有这些标签的结果下沉(demote_tags)。命名空间的 tag_registry 可以为标签附加保留、去重和冲突策略。标签保持写入时的大小写:memory.list 和 knowledge.list 匹配标签时不区分大小写,其他所有标签过滤(包括 memory.search 和 memory.apply)都按原样精确匹配。
  • entities 是值中提到的命名事物,以搜索读取时使用的规范形式存储(小写;去掉冠词、所有格和标点;中心名词用单数),因此 Billing Services 和 billing service 是同一个实体。写入方可以传入实体;否则由 entity_extractor worker 填充。实体用于实体加权和实体图。
  • files 是该记忆所涉及的仓库路径;memory.for_file 会在编辑这些文件之前提供相关记忆。

memory.for_file 每条记忆渲染一行。决策(decision)或约束(constraint)会完整输出,上限见下文,并且不计入请求的 token_budget(默认 300 个 token);其他行受该预算限制,并被截断为 220 个字符的一行。放不下的行会被整行省略,而其后的行仍有机会输出;末尾的 - … <n> more 行同样计入预算,说明有多少行被省略以及如何列出它们。标题和移除页脚始终会输出,只要有行被省略,… more 行也会输出,因此小于这些内容的预算可能被超出。

决策和约束共用一个上限 memory_for_file_whole_tokens(1,500 个 token,约 6,000 个字符),因此受数十条决策和约束管辖的文件不会撑爆提示。它们按块中的顺序输出;会超过上限的一条被省略,其后仍能放下的则照常输出。末尾一行统计被省略的数量,并列出前五个键,每个键可用 memory.get 读取(团队行则在其所指的命名空间中读取),或用 loom_search 找到。若某行连同取代它的较新行一起被省略,则计入 … more 行,绝不会作为需要读取的行被点名。默认值使整个块保持在 coding-agent 宿主从钩子传给模型的 10,000 个字符以内,无需任何改动。

每一行:

  • 来自额外命名空间(仓库的代码命名空间)的记忆,标题为 Team rule (by <author>, <age>);若是决策(memory_type 为 decision 或带有标签 decision),则为 Decision (by <author>, <age>)。
  • 一行把它的 constraint、gotcha 和 decision 类别列在同一对方括号中([constraint, decision];标题为 Decision 的行会省略 decision)。
  • (pinned) 标记已固定的行。固定是该行自身的标志:代码命名空间的成员可以对自己在那里写入的行设置它,因此团队行上的 (pinned) 只表示有人冻结了它,并不表示是维护者所为。
  • 没有人固定的决策,例如由 loom decisions extract 写入的决策,不带固定标记:按原样提供。
  • (outcome: failed) 标记任何已记录结果为失败的决策,无论是否固定。
  • 带有 source-changed 标签的决策(其来源文档不再这样表述;见提取决策)显示为 (source changed),无论是否固定。
  • 备注会说明其关联的代码何时发生了变更或已被移除。
  • 字符串值按文本输出,而不是按其存储的 JSON 形式输出;决策或约束之外的行,如果被读取或该行截断,则以 … 结尾;被截断的对象或列表按存储形式输出。
  • 带来源的决策会在其值之后完整附上 — source: <source_resource_id>,因此 knowledge: 引用会保留其 #section,并可通过 knowledge.get 解析。
  • 冲突检查将较新的行与其同类型的较旧行关联后,较新行会置于较旧行之上,团队行会说明它取代了哪一行(较旧行带有标签 decision 时为 supersedes decision)。冲突检查关联的两条带类型的决策各自保持其在块中的位置,不加此类说明,因为每个决策键本身就是独立的决策。当预算或上限使任何命名空间中取代其他行的某一行被省略时,它所取代的每一行也会一并省略,因此较旧的行绝不会被当作当前有效的行。

与代码关联的记忆

这能为编码 agent 带来什么,以及从哪里开始: 与代码关联的记忆。

关于代码的记忆会与它所提到的定义和文件建立关联,并且这些关联会随代码一起变化。memory_code_links worker 会把每条带有 repo:<id> 标签的记忆(编码插件会给各自的会话打上该标签),或写在某个仓库代码命名空间中的记忆,与该仓库的 trunk 建立关联:

  • 每个带反引号的名称、A::b 和 a.b() 调用,只要恰好解析到一个定义;记忆的 files 用于在同名定义之间做选择,而被定义多次的名称不会被关联;
  • 正文中单独出现的 camelCase 或 snake_case 单词,只关联到记忆的 files 中的定义;
  • 记忆提到的、且不包含上述任何定义的每个文件。

trunk 中尚未定义的限定名称会等待 memory_code_links_pending_days(14),因此关于未合并代码的记忆会在代码合并后建立关联。

关联会记录定义的指纹:它的所有重载以及选择这些重载的条件,均按 token 计算,因此空白、注释(Go 的 //go: 指令和 Python 的 # type: 注释除外)以及格式化工具所做的大部分改动(行尾逗号和其他可选分隔符、JavaScript 的 ;、引号风格及其所需的转义、数字字面量的大小写、Python 文档字符串的缩进、Python、JavaScript 和 TypeScript 中的括号)都不会改变指纹。合并相邻的字符串字面量以及任何其他编辑则会改变指纹。 文件中定义了什么,是从仓库裸 git 镜像中已索引的 head 处读取该文件得到的。对每个已索引的提交,worker 都会跟踪该提交中的重命名和编辑:

关联状态 条件
fresh 定义仍在原处,文本与撰写记忆时一致。
moved 它所在的文件被移动,或仅被重命名而无其他改动,或被移到了另一个文件。
changed 它的文本在记忆撰写之后发生了变化(changed_since 给出对应的提交),无论是否重命名。
unresolved 它的名称已不存在,原处可能有一个新定义就是它,但无法确定。会照常提供,并附带复查信号。
missing 代码已消失:没有新的内容取而代之。关联会保留其位置,因此回滚后可以再次找到它。

控制台中的记忆详情:其关联的代码,一个定义是当前的,另一个自某次提交以来已变化

控制台中的记忆详情会列出这些关联及其状态 (视频片段)。

关联会跟随其定义经历文件移动、重命名(伴随编辑时,只要新名称与旧名称相关),以及其所在类在文件内的重命名。位于另一个类或命名空间中的同名定义绝不会继承关联,而 missing 关联只有在其自身的名称重新出现时才会恢复。若某个名称已从其文件中消失,会在自上次检查以来变化的文件中查找它,这些文件取自镜像中保存的状态,与索引并列;因此,如果某次提交没有被索引完整接收(超过 code_ingest_max_files_per_commit),被该提交移动的定义会在重新检查关联时被跟踪到。当提到它的这类文件达到 memory_code_links_mirror_naming_files 个或更多,或在条目前缀下变化的文件超过 memory_code_links_mirror_changed_files 个,或无法读取 diff,或路径数量超过 git 一条命令所能接受或在其时限内所能搜索的范围时,镜像不会补充任何内容,由索引来决定。当 git 无法运行搜索,或找到的定义无法计算指纹时,索引中的同名定义无法确定的有效关联会变为 unresolved。ingest 不会索引的文件(位于条目的 path_prefixes 之外、被其拒绝列表拒绝、超过字节上限、二进制文件)不会增加定义;而生成的文件(ingest 会将其声明为生成文件,但不会搜索其文本)则会增加。解析失败的文件会保持其关联不变,直到它能够被解析。当指纹规则变化时,每个关联都会基于其哈希当初所取自的提交重新计算哈希。当其旧文本已不在 git 中时,与旧文本匹配的关联会采用下次检查发现的文本,而已变化的关联仍为 changed;旧文本已无法解析的关联会保留其最后的状态,worker 会对此作出报告。

Loom 从不改写记忆。命名空间的 code_change_policy(namespace.register)决定读取时如何处理变更:

策略 被移除的代码 被修改的代码
retire_removed(默认) 当一条记忆的所有关联都是 missing 时(待定或 unresolved 的关联不计入),搜索(以及 memory.ask、context.pack)会在挑选结果之前将其排除;memory.get 仍会显示它。代码恢复后它也随之恢复。 标记。
flag 标记。 标记。
revise 与 retire_removed 相同。 由 LLM 对照新旧代码重新检查该论断:仍成立的会被重新锚定,被推翻的会得到一个修正后的论断,作为该关联的 suggestion。

在每种策略下,当一条仍被搜索提供的记忆,其最差的关联为 changed、unresolved 或 missing 时,它的排名会降低:它会移到按分数排名的后续 memory_search_code_changed_places(3)行之下(同样在下移或已经下移的行不计入),但绝不会被移出结果,也不会排到仅作为填充提供的行之后(低于相似度下限,或因低于弃答阈值而被标记),这发生在置信度与弃答检查按相关性顺序读取这些行之后;score_components.code_changed_places 说明它在其所属搜索的各行中下移了多远(loom_search 会按相似度,在其搜索未降级的行中安排其合并后的仓库决策)。以下情形绝不会被下移:

  • 由人持有的记忆;
  • 仅有的此类关联指向调用方无权读取的代码,或指向没有任何机制使其保持最新的关联(memory_code_links_enabled 关闭)的记忆;
  • 由标识符匹配或 anchor_first、recent_first 层级安排位置的行,下移也不会把它们算作一个位置;
  • 搜索针对答案为日期顺序的查询所提供的每一行(loom_search 按相似度安排的合并后仓库决策仍会下移);
  • 后续页(page=<handle>)的行,按其暂存的顺序提供;
  • 分块、记录或摘要命中,它们不带 code_state。

当提问中带有时间词(when、after、since、latest 等)时,阅读器块(render="reader",即 loom_search 的块)会按日期列出其行,因此下移在其中不会体现;results 则保留下移。

当 memory_ask_recency_weight 大于 0(默认 0.2)时,memory.ask 会按相似度和时效性对搜索的行重新排序,其标识符查找会安排各自的行;没有查询的 context.pack 启动读取不进行搜索。下移在以上这些情形中都不会体现。

revise 对每次编辑只判断一次已变化的关联,并受每轮预算(memory_code_links_revise_per_pass)的限制。敏感度标为 high 的记忆绝不会发送给模型。由人固定、锁定(直到锁到期)或验证过的记忆,以及提到的代码多于关联上限的记忆,只会被标记。为记忆的较早取值(其文本、文件、仓库或用户)所建立的关联,在重新关联之前会被所有读取忽略。

关联是针对 trunk 保存的。在其他分支上,lesson 会将该分支自身的定义(取关联最近 16 个名称中的任意一个)与撰写记忆时的文本进行比较:仍保留旧文本的发布分支,在 trunk 已修改之后仍读作 fresh,而拥有 trunk 已移除的代码的分支仍会得到它的 lesson。在无法读取分支文件的情况下(设置了 LOOM_GIT_HISTORY=none 的主机没有 git 镜像),lesson 沿用 trunk 的最后状态。

关联会在代码所在之处被读取:

  • code.symbol 将关联的记忆作为 lessons 附上,每条都带有其 code_state。它们来自仓库的团队命名空间以及调用中指定的 lesson_namespaces(通过 MCP 调用且未指定时,取调用方的记忆主目录),绝不会来自调用方可读的所有命名空间。
  • code.search、code.callers、code.callees、code.impact、code.outline 以及任务的 code.context_pack 会为答案中靠前的文件(code_result_lessons_paths)附上 lessons:来自相同的命名空间,去除任何其他仓库的代码命名空间,包含与每个文件中的代码关联的记忆,或以其路径或路径尾部(裸文件名,search/handler.py;绝对路径会被认为指向以它结尾的根目录之下的某个文件)提到该文件的记忆,每条都带有其 code_state,总量在 code_result_lessons_tokens 之内。每一行带有 path、memory_key、namespace、excerpt、code_state、changed_since(使其代码进入已变化、unresolved 或 missing 状态的提交,已知时提供),以及在其取代较旧行时的 supersedes_key;被答案所读取的另一行所取代的行不会提供。lessons_left_out 统计被上限、截断或该规则排除的行数。决策或约束要么完整提供,要么被排除。该读取在答案之后运行,从不进入搜索 memo,并且在 include_lessons: false、code_result_lessons 关闭,或令牌被限定在其自身用户或会话时跳过。
  • memory.for_file 会提供与该文件中的代码关联的记忆,以及其 files 提到该文件的记忆。代码发生变化、再也找不到或已消失的行会如此说明,并给出它首次被读作该状态的已索引提交;context.pack 的决策行带有同样的备注,其记忆行则带有 code_state=<state>@<commit> 标签。
  • memory.get 以 code 的形式返回关联(包含任何 suggestion);memory.search 中读取自记忆自身行的命中,会以 code_state 带上其最差的关联(分块、记录或摘要命中不带此项,也绝不会被排除);memory.ask 会注明其代码已移动、变化或消失的记忆。
  • namespace.validate 会列出调用方有权读取的仓库中,代码已变化、再也找不到或已消失的记忆。

时间

列 时间轴 含义
valid_at 现实 事实成立的时间,由写入方给出。NULL 表示未知。
valid_to 现实 事实不再成立的时间。读取时会丢弃已超过其 valid_to 的行。
temporal_anchor 现实 事实所涉及的日期(事件日期),由提取过程设置。
created_at 记录 Loom 写入该行的时间。
invalid_at 记录 Loom 淘汰该行的时间(被取代)。
tombstoned_at 记录 写入方删除该行的时间。
expires_at 记录 该行退出服务集合的时间,前提是其写入方或命名空间所有者设置了过期时间。

as_of 读取会回放其中一条时间轴。as_of_basis="valid_time"(默认值)查询的是在时间 T 什么为真:即最佳现实日期(valid_at,否则 temporal_anchor,再否则 created_at)不晚于 T 的行。as_of_basis="knowledge_time" 查询的是到时间 T 为止 Loom 已经获知了什么:即在 T 之前写入,且到 T 时尚未被淘汰、删除或失效的行。

在 newest_wins 下,模板化替换只有在对端行的 valid_at 不晚于新行的对应时间时才会淘汰对端行,因此回填旧事实不会淘汰当前事实。这是有效时间加淘汰标记,而不是双时态模型:决定两行中哪一行为当前行的是取代关系,而不是按日期排除。完整的区间模型需要每个写入方说明各个事实何时结束,而 agent 通常并不知道这一点。

版本与历史

每一次变更(值编辑、墓碑标记、恢复、锁定、状态切换)都会写入一行新记录,其纳秒级 version 更高,其余各列沿用原值。合并会丢弃旧版本,因此 loom.memory 保存的是当前状态,而不是历史。

历史记录保存在 loom.memory_versions 中,这是一个只追加的镜像表,由物化视图在每次插入时填充。memory.history 读取某个键的所有版本;namespace.rollback 将命名空间中的每个最新版本恢复到某个时间点的版本;memory.redact 清除某个历史值,同时保留其审计条目。每个版本上的 content_sha256 就是 if_match_sha256 所比较的值,也是证明(attestation)所绑定的对象。

来源追溯

服务器会在每次写入时为两个列盖章,且从不从请求体中读取它们:

  • actor:human:<subject> 或 process:<subject>(服务账号),取自令牌。
  • source_class:Loom 如何获得这些内容,由操作和令牌决定。
source_class 含义
asserted 调用方直接给出(memory.set)。
extracted 提取流水线从对话记录中推断得出。
observed Loom 根据所见的活动记录得到。
derived 由其他记忆计算得出(整合输出、会话摘要)。
imported 由导入器从其他系统加载。
external 写入方声明其为外部内容:工具结果、网页、文档。

请求只能声明降级(derived、external 或 imported);其他任何值都会返回 422。agent 从其环境中复制的文本正是攻击者可以控制的内容,因此 memory.ask 会将未经证明的 external 行排除在综合结果之外(LOOM_MEMORY_ASK_EXCLUDE_UNVERIFIED_EXTERNAL,默认开启),而 LOOM_MEMORY_SEARCH_TRUST_WEIGHT 可以在排序中提升 asserted 行和已证明行的权重。

  • 谱系。 整合会写入 loom.memory_belief_sources 行;会话摘要会在 session_summaries.derived_from 中列出它所概括的键。memory.provenance 说明一行数据的来源,memory.evidence 返回提取出的事实所取自的对话轮次,memory.lineage 则追溯共享记忆是如何被提升的。
  • 证明。 memory.verify 记录是谁为内容担保,并与其哈希绑定。读取时会报告 verification:内容未变时为 human 或 process,内容变更后为 stale,从未证明过则为 none。编辑会保留证明并读作 stale,它绝不会把信任转移到新内容上。

内容该放在哪里

内容 层面 为什么不放进记忆
下周仍然成立、且其他会话需要的事实 持久记忆,memory.set 它本身就是记忆。
用户希望被记住的一段对话记录 memory.set_from_messages(提取) 一整行大内容只能作为整体被检索到;提取会为每个键写入一条简短的事实。
当前计划、租约、游标、“我做到哪了” 工作记忆,working_memory.* 协调状态每一步都会变化;对其排序会污染召回结果。
可能需要重新读取的大型工具结果 context.offload / context.fetch 它是按键获取的数据块,而不是需要排序的论断。
某一条工作线的可恢复状态 会话简报,session.brief_* 简报由用户选择恢复,绝不会被排入其他任务的答案中。
文档、规范或运维手册;任何超过几 KB 的内容 知识库,knowledge.add / knowledge.upsert 文档按标题分块;记忆则是根据最多 1,200 个字符的摘录生成嵌入。
聊天轮次日志 对话,conversation.* 轮次是证据,而非信念;memory.recall 会读取某次提取所用到的轮次。
具有身份标识和精确字段的数据(PR、工单) 记录,memory.record.* 记录按字段逐一合并,并支持精确过滤。
始终加载的人设或偏好 配置档案,profile.* 每次都按标签获取;将其与问题一起排序会白白浪费名额。

对于文档:把文档存入知识库,再以一个可读的键写入一条简短的记忆,说明它是什么并指向该文档。context.pack 会把工作记忆加载在持久部分之前,因此 agent 会先看到自己的状态。

保留策略

Loom 只删除写入方要求删除的内容。任何记忆表都没有默认 TTL,也没有按时间清理行的扫描任务。一行记忆会在以下情况下不再出现在服务集合中:写入方删除或取代它,写入方为它设置了过期时间(ttl_seconds、valid_to),或者命名空间所有者或运维人员配置了保留窗口。memory.restore 可以在 14 天内恢复一条墓碑记录。保留与擦除介绍了相关设置和擦除 saga。

一个事实随时间的变化

3 月,用户说“我住在 Delhi”;6 月,又说“我搬到了 Berlin”。

  • 6 月的写入。 提取过程根据主体和属性生成键,因此两条陈述落在同一个键上。6 月的行不会覆盖 3 月的行:Delhi 版本仍保留在 loom.memory_versions 中,可通过 memory.history 读取。
  • 归错键的事实。 如果 Berlin 落在另一个键下,近邻搜索会发现 Delhi 这一行相近但内容不同,并把两者都标记为 conflicted,通过 conflict_with 相互关联。之后如何处理由命名空间策略决定(参见一次写入如何被判定)。
  • “4 月时他们住在哪里?” 使用 as_of 读取即可回答,可以按事实成立的时间查询,也可以按 Loom 在该日期所知的内容查询(时间)。
  • “这是谁说的?” actor 和 source_class 记录写入者以及该事实的来源方式;memory.evidence 返回提取出该事实的对话轮次。
  • 错误的导入。 namespace.rollback 会把命名空间中的每个头版本恢复到某个时间点的版本,除非另行指定,否则以试运行方式执行。

示例

写入一条事实,在写入变更之前先探测,然后针对你读取到的哈希值进行更新:

import asyncio
import os
from datetime import datetime, timezone

from loom import Datapack


async def main() -> None:
    dp = Datapack(
        org="acme",
        namespace="eng-tooling",
        base_url=os.environ["LOOM_BASE_URL"],
        api_key=os.environ["LOOM_API_KEY"],
    )
    agent = dp.agent("release-bot")
    key = "project/billing/deploy-window"

    out = await agent.memory.set(
        memory_key=key,
        value="Billing deploys only on Tuesdays and Thursdays, never on Fridays.",
        tags=["kind:constraint", "service:billing"],
        entities=["billing"],
        valid_at=datetime.now(timezone.utc),
    )
    print(out["conflict_verdict"], out["content_sha256"])

    probe = await agent.memory.set(
        memory_key="project/billing/deploy-days",
        value="Billing deploys only on Thursdays.",
        dry_run=True,
    )
    if probe["conflict_verdict"] == "conflict":
        peer = probe["peers"][0]  # closest peer, with its key
        current = await agent.memory.get(memory_key=peer["memory_key"])
        await agent.memory.update(
            memory_key=peer["memory_key"],
            value="Billing deploys only on Thursdays.",
            if_match_sha256=current["content_sha256"],
        )


asyncio.run(main())

如果更新返回 409 PRECONDITION_FAILED,说明在你读取之后有另一个写入方修改了该行:请重新读取,并重新做出判断。通过 HTTP 写入使用 POST /v1/memory.set;通过 MCP 则使用 loom_memory_set 工具。

相关内容