内存与上下文槽位
仅允许同时存在一个活动实现的注册器,以及位于其上的内存适配器契约。属于 插件 SDK 概览 的一部分。
独占槽位¶
| 方法 | 注册内容 |
|---|---|
api.registerContextEngine(id, factory) |
上下文引擎(同一时间仅一个活动)。使用 info.acceptedHostParams 限制可接受的主机添加的生命周期字段,包括可选的 maintain() 取消;未声明的引擎将接收当前所有主机字段。 |
api.registerMemoryCapability(capability) |
统一内存能力 |
要参与持久化已接纳回合,上下文引擎必须在 info.transcriptSemantics 下声明 currentTurnFence: "before-current-turn-entry-v1" 和 turnAdvancementIdempotency: "atomic-idempotent-v1",然后将 commitTurn(...) 实现为以 advancementKey 为键的原子、幂等写入。OpenClaw 仅提供包含式的已接纳回合,从已接纳的用户条目到其终结条目;使用 readSessionTranscriptVisibleMessageDelta(...) 游标 API 来引导或重建更早的历史。如果没有完整契约,OpenClaw 会对整个逻辑回合及其重试使用旧版上下文路径,保持已配置引擎不变,并在下一个逻辑回合再次尝试该引擎。
内存嵌入适配器¶
registerMemoryCapability是独占的内存插件 API。- 选定的内存插件可以省略
capability.runtime,包括通过其自身钩子处理内存的情况。内存设置页面会中性地报告缺少主机搜索支持;这不会评估其他内存集成。插件加载和搜索运行时失败仍然是错误。 registerMemoryCapability还可以公开publicArtifacts.listArtifacts(...)用于主机管理的导出。枚举这些已声明工件的伴随插件,在存在专门的公共消费者 API 之前,仍使用保留的openclaw/plugin-sdk/memory-host-core外观中的listActiveMemoryPublicArtifacts(...);它们不得访问其他插件的私有布局。- 能够返回会话转录命中的内存运行时应实现
runtime.authorizeSearchHits(...)。主机在原始搜索命中到达调用者可见表面之前调用此钩子,并提供请求代理、会话键和沙箱状态。只返回请求者可以观察的命中。对于没有会话的主机或操作员调用者,主机会设置trustedAgentScope;只返回该代理自己的会话命中,不返回其他代理的命中。当会话调用者携带主机授予的会话回忆通行证时,主机会将其作为conversationRecall转发;只接纳通行证允许的命中。如果缺少该钩子,OpenClaw 会采用失败关闭策略,扣留会话来源命中,同时保留普通内存命中。将转录身份和可见性策略保留在所属内存插件中;调用者不得从路径推断授权,也不得复制插件特定规则。 - 嵌入提供商使用
api.registerEmbeddingProvider(...)和contracts.embeddingProviders;没有单独的仅限内存注册表。
压缩前内存刷新¶
在 MemoryPluginCapability 上注册一个刷新解析器,以提供在压缩前保存持久化上下文的静默回合。OpenClaw 首先从 agents.defaults.compaction.memoryFlush 和活动上下文窗口解析刷新时机。当 enabled 为 false 时,主机不会调用该解析器。返回 null 可因提供商特定原因跳过刷新。
有两个解析器字段:
flushPlanResolver返回完整的MemoryFlushPlan或null。其契约与早期版本相比没有变化。Memory Core 使用它。providerFlushPlanResolver返回由主机补全的计划:MemoryFlushFilePlanDraft(完整的MemoryFlushPlan就是其中一种草稿)或MemoryFlushToolsPlan。当插件同时注册两者时,主机使用providerFlushPlanResolver。
每个计划都有 prompt、systemPrompt 和一个持久化分支。在来自 providerFlushPlanResolver 的计划中,softThresholdTokens、forceFlushTranscriptBytes、reserveTokensFloor 和 model 字段是有意为之的提供商覆盖。主机会用其解析出的时机填充省略的时机字段,并且仅为工具分支从 memoryFlush.model 填充省略的 model;没有 model 的文件计划会保留会话的模型。model 覆盖会将回合固定到精确的 provider/model 引用,例如 ollama/qwen3:8b,而不继承活动回退链。
恰好选择一个持久化分支:
| 分支 | 计划字段 | 刷新工具和存储 |
|---|---|---|
| 文件 | relativePath: string |
仅限目标文件的 read 和仅追加 write。主机会创建目标并要求可写工作区访问权限。Memory Core 使用此分支。 |
| 分支 | 计划字段 | 刷新工具与存储 |
|---|---|---|
| 工具 | persistenceToolNames: readonly string[](非空),可选 lookupToolNames: readonly string[](只读) |
read 以及所选内存插件拥有的已声明持久化和查找工具。宿主不创建目标文件,也不要求可写工作区访问权限。查找工具不能持久化内存。 |
只有所选内存槽位的所有者可以通过
providerFlushPlanResolver 提供工具分支计划。宿主会跟踪哪个插件提供了有效
解析器,包括在合并 sidecar 能力字段时;所有者的
任一类型解析器都优先于 sidecar 的解析器。来自非所有者的工具分支计划会被跳过,并记录一条
指明该插件名称的警告。
对于工具分支,所有权来自已注册的工具元数据。来自其他插件的 同名工具会被排除。在此投影之后,常规消息、模型、沙箱、允许列表、 和授权策略仍然适用。持久化和 查找工具的名称不得重叠;宿主会跳过重叠的计划,并记录一条 包含插件名称的警告。如果没有任何已声明的持久化工具保留下来,宿主会 跳过推理,并记录一条指明缺失工具的警告。如果策略 移除了任何查找工具,刷新仍会使用其保留下来的持久化 工具运行,并记录一条指明不可用查找工具的警告。跳过的刷新之后,压缩可以 继续。
受众与刷新标识¶
刷新运行在一个分离的内部会话中,因此其维护转录不会
进入后续用户轮次。对于工具分支轮次,宿主会从源
轮次的可信会话条目、会话密钥、会话 ID、
以及源轮次的发送者所有权中解析源轮次的 memoryAudience,包括在轮次完成后调度的刷新。它会将该受众委托给分离的会话密钥,
同时保留源血缘和撤销检查。持久化和查找工具
会接收此委托受众以及源沙箱状态。如果源没有
有效受众,宿主会跳过工具分支刷新并记录调试日志。维护
副本仍然具有 senderIsOwner: false;提供者通过提供的受众
及其当前权限检查来授权内存访问。
只有工具分支刷新上下文会在
OpenClawPluginToolContext 上包含 memoryFlush: { flushId: string }。宿主会从源
会话实例(其 sessionId 和生命周期修订版本)及其
压缩前 compactionCount(不存在时为零)确定性地派生 flushId。计数在完成的压缩之后递增,因此同一周期内的模型回退尝试和后续重试共享同一个 ID;后续周期或新的会话实例(包括保留会话 ID 的重置)会获得不同的 ID。提供者可以将此 ID 与其
变更的身份组合起来,以对重试去重。该 ID 不授予权限。
完成证据¶
工具分支刷新只有在至少一个已声明的持久化工具
无错误完成,或助手的最终输出是静默令牌
NO_REPLY 时才成功。成功的查找调用不是持久化证据。如果没有任一
有效完成信号,宿主会记录一次失败的刷新,原因为 no
persistence tool call succeeded。运行错误仍会使刷新失败。文件分支
保留其文件写入和完成行为。
提供者中立内存运行时¶
提供者中立运行时允许基于记录的提供者拥有内存槽位,
而无需冒充工作区文件。遗留的文件形态
MemoryPluginRuntime 契约保持完整。成功意味着:
- 现有遗留提供者继续无需更改地工作;
- 仅记录的提供者可以服务所有其声明需求所支持的读取者;
- 不支持的操作作为能力声明,而不是通过调用提供者并处理失败来发现。
集成包含三个层次:
- 宿主选择一个提供者,提供可信调用者权限,拥有与调用者 绑定的生命周期,并路由请求。
providerRuntime通过提供者作用域引用和声明的能力提供中立的搜索、检索和健康状态。- 提供者拥有的工具、技能和 UI 保留诸如变更、 组织和维护等丰富工作流。中立运行时不会取代它们。
外部插件从已公开的
MemoryPluginCapability 派生提供者类型;memory-host-search 仍然是捆绑消费者的私有本地外观。
import type { MemoryPluginCapability } from "openclaw/plugin-sdk/memory-host-core";
type MemoryProviderRuntime = NonNullable<MemoryPluginCapability["providerRuntime"]>;
type MemoryProviderOpenResult = Awaited<ReturnType<MemoryProviderRuntime["open"]>>;
type MemoryProviderHandle = NonNullable<MemoryProviderOpenResult["provider"]>;
const providerRuntime: MemoryProviderRuntime = {
async open({ agentId, context }) {
// Reuse the plugin's service. Routing facts and record IDs do not grant access.
const provider: MemoryProviderHandle = await service.openMemoryReader({ agentId, context });
return { provider };
},
};
api.registerMemoryCapability({ providerRuntime });
service.openMemoryReader 是提供者拥有的代码。它返回一个与调用者绑定的
MemoryProviderHandle,其成员如下:
| 成员 | 契约 |
| 成员 | 契约 |
|---|---|
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
capabilities |
必需声明所支持的源、分页、候选类型和项目过滤。 |
search(request) |
返回命中结果以及可选的分页、覆盖率和警告字段。每个命中结果都有一个提供方作用域的 reference 和一个 excerpt;分数和引用是可选的。每个提供方都必须遵守 minScore。lexicalOnly 是提供方可以忽略的提示。 |
get(request) |
解析带有可选修订版本和读取边界的提供方作用域引用。返回显式的 ok 或 not_found;拒绝和失败不得表现为空的成功。 |
health() |
返回 ready、degraded 或 unavailable,而不泄露分区内容。它必须对所有经过身份验证的调用方有效,包括以目的 status 打开的宿主权限;search 和 get 仍可以拒绝该调用方。 |
close() |
释放此调用方的租约,而不会关闭另一个调用方的共享服务。 |
candidates(request) |
仅当 capabilities.candidates 非空时存在。符合条件的结果包括提供方拥有的项目或触发器元数据;仅支持 search 并不会启用自动注入。 |
refresh() |
可选的提供方拥有的刷新。这不是通用的做梦、修复或删除 API。 |
能力在提供方代码运行之前强制执行:
| 能力 | 声明 | 被拒绝的请求 |
|---|---|---|
| 搜索源 | 包含 "memory" 和/或 "sessions" 的非空 sources 数组 |
sources 包含未声明的语料库 |
| 分页 | pagination: boolean |
分页为 false 时存在 cursor |
| 自动回忆 | 包含 "trigger" 和/或 "project" 的 candidates 数组 |
candidates({ kind }) 指定了未声明的类型 |
| 项目过滤 | projectFilter: boolean |
项目过滤为 false 时提供了非空的 activeProjectKeys |
所选 memory 槽位所有者也可以声明 recallToolNames。这些是
Active Memory 用于深度回忆的具体代理工具。有效的显式
Active Memory toolsAllow 列表优先,其次是所选
提供方的 recallToolNames,然后是内置回退。未选中的 sidecar
不能提供此字段。对于原生提供方,recallToolNames 还
控制提供方直接触发回忆:Active Memory 仅在
声明非空且当前轮次的工具策略允许所有已声明工具时
才运行它。
否则它会跳过提供方查找,并且不注入任何内容。
宿主消费者¶
| 宿主消费者 | 提供方运行时用途 | 原生提供方声明 |
|---|---|---|
Gateway memory.search v2 |
search() |
请求的 sources;游标使用 pagination: true |
Gateway memory.get / memory.status |
get() / health() |
必需的处理方法 |
| Doctor 和 CLI 状态 | health() 使用操作员或 host/status 权限 |
Health 必须接受 status 调用方 |
| 压缩后刷新 | 可选的 refresh() |
无能力标志;省略或拒绝会被记录 |
| 主机消费者 | 提供方运行时用途 | 原生提供方声明 |
|---|---|---|
| 项目回忆 | candidates({ kind: "project" }) |
当提供项目密钥时,candidates: ["project"] 和 projectFilter: true |
| Active Memory 触发回忆 | 词法 search() 加上触发候选项 |
sources: ["memory"]、candidates: ["trigger"]、非空 recallToolNames(该轮工具策略允许完整使用),以及当提供项目密钥时 projectFilter: true |
| Active Memory 深度回忆 | 代理工具 | 所选所有者声明并注册 recallToolNames |
| 语音快速上下文 | search() |
每个已配置来源 |
| Memory Wiki | search() |
请求的来源;受保护的转录回忆需要 "sessions" |
必需的 MemoryCallerContext 携带一个 assertCurrent() 回调、一个可选中止信号,以及 MemoryCallerAuthority:
operator:已认证的操作员作用域和可选连接身份;session:实际的会话密钥、可选会话 ID、沙箱状态,以及可选的主机解析记忆受众。conversationRecall携带主机授予该会话工具上下文的有界回忆通行证,例如一次 Active Memory 回忆运行;只能从该可信上下文中复制它,绝不能从模型输入中复制;host:一个具名的主机操作,而不是操作员或私有会话授权。
主机在异步操作前后重新检查调用方和插件生命周期。提供方根据提供的授权应用可见性策略,并在释放数据前重新验证。没有受众的会话授权不具有私有或会话授权。主机授权也不授予私有或会话访问权限。
记忆受众¶
OpenClaw 从可信轮次事实和持久会话谱系中一次性解析记忆受众。提供方和插件工具消费由此产生的主机铸造值:
type MemoryAudience =
| { kind: "owner-private"; agentId: string }
| { kind: "conversation"; agentId: string; sessionKey: string; sessionId: string };
- 来自可信代理所有者的直接轮次具有
owner-private受众。 - 来自其他发送者的直接轮次,或群组、频道或线程轮次,具有针对持久根会话的
conversation受众。 - 派生的子运行只有在主机验证每个已记录的父密钥、会话 ID 和生命周期修订版本后,才继承其根受众。
- 缺失、格式错误、跨代理、循环或过期的谱系不会产生受众。未知或缺失的持久聊天类型也不会产生受众。
受众独立于沙箱策略。即使调用方具有有效受众,提供方也可以拒绝沙箱化调用方。操作员授权也是独立且显式的;它不会成为 owner-private 会话授权。
提供方不得从会话查找、会话密钥模式、记录 ID 或缓存指纹中重建受众。它们还必须拒绝针对另一个代理的受众。主机将每个受众绑定到其调用会话,并在为另一个会话出示时拒绝它。由主机中介的子运行会收到一个新的受众,该受众绑定到子会话的当前会话 ID 和生命周期修订版本(对于分离的子运行,则绑定到其密钥无对应行的缺失状态),并共享父代的谱系和撤销状态;子运行重置或重新分配也会使其被拒绝。主机拒绝其未铸造的受众对象,并在其谱系中的任何会话更改实例或生命周期,或拥有该受众的运行结束时,使已捕获的受众失效。主机在打开提供方前后以及每次提供方调用周围检查受众时效性。传递给 open() 的 context.assertCurrent() 包含受众时效性,因此提供方如果在 I/O 前立即调用它(包括在其自身等待的工作之后),会被拒绝,而不是在过期授权下操作。保持会话 ID 和生命周期修订版本的会话写入(例如轮次自身的活动和用量记账)在发布期间不会中断这些检查;待处理的重置、替换或删除在结算前仍报告时效性不可用,然后撤销受众。受众撤销不会中止 context.signal;在每个副作用前调用 assertCurrent()。
兼容性与主机集成¶
- 消费者优先使用
providerRuntime。只有其缺失时才选择主机拥有的旧版适配器。失败、拒绝或无效的提供方运行时绝不会针对旧版存储重试。 - 现有插件注册、
MemoryPluginRuntime、管理器类型和getActiveMemorySearchManager仍然可用。现有插件无需迁移源代码或存储。 - 旧版适配器声明记忆和会话搜索、无分页、无项目过滤和无自动回忆候选项。它保留管理器接收器、虚拟路径、读取边界、可见性过滤和清理。其健康详情省略主机路径,例如数据库和工作区位置。
- 提供方引用包含
providerId;另一个已选提供方的引用会被拒绝。提供方拥有修订行为,并且不得用无关内容替换过期引用。 - Gateway 暴露中性搜索,使用
memory.search和version: 2,检索使用memory.get,健康使用memory.status。任何具有operator.read的已认证操作员连接都可以调用它们,与无版本memory.search的调用方相同,包括令牌认证的 CLI 连接。进程内代理工具和代理运行时调用方改用其已准入运行的操作员授权。请求中止、连接关闭和已撤销的客户端授权会在每次提供方调用前后重新检查。省略搜索版本或发送version: 1会为旧版提供方保留旧的文件形状响应。原生提供方会返回一个指明所选插件的错误,并指导客户端使用version: 2重试。 - 语音快速上下文、项目回忆、Active Memory 触发回忆和 Memory Wiki 在所选插槽所有者注册
providerRuntime并声明其所需能力时使用中性接口。使用旧版运行时,它们保留其管理器调用、结果和引用标签。 - 仅记录提供方保留其自身的工具、技能和 UI;选择不会创建虚假的文件浏览器。旧版主机忽略
providerRuntime,因此需要它的插件必须声明兼容的主机版本。
这是共享读取运行时。Memory Core 工具和 CLI、文件索引诊断、 启动工作区文件、压缩前保存、重置捕获以及维护保留其现有所有权。原生提供商工作流将继续与其并行运行。
Dreaming 保持独立¶
Dreaming 不是提供商运行时功能。选择另一个内存插件仍可在现有加载器策略下, 将 Memory Core 激活为 Dreaming 边车。显式禁用 Memory Core 可阻止该边车。Dreams UI 和基于文件的维护方法并不意味着所选提供商实现了 Dreaming。
捆绑的 Memory Core 工作器¶
Memory Core 使用共享的 process-runtime 工作器池进行词法检索、
余弦回退和不可变块准备。检索会保留搜索代际,直到其读取器关闭;发布、源哈希验证和遗忘操作仍由其现有数据库所有者负责。
捆绑工作器使用私有的 memory-core-host-engine-knn 外观进行只读数据库访问、
共享 SQLite 空闲生命周期和向量原语,并使用 memory-core-host-engine-indexing 进行纯分块、注释、哈希和嵌入输入限制。这些外观避免将提供商注册表或可写存储初始化加载到工作器线程中。它们是捆绑的运行时契约,而非第三方类型化 SDK 入口点。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw