memory Power

单用户、User/Agent Profile 与长期知识

City 管理唯一使用者 local 的基础资料;MemoryPower 管理持续约定和知识。所有本地 Agent 共享这个 User,切换 Federation 账号不改变身份和记忆。需要提炼、归并或复杂更正的工作由专用 Memory Session 处理,Memory Coordinator 管理请求、重试和提交。不会逐轮复制聊天或自动采集每轮消息。后台整理属于 Memory Power 内部流程,按明确范围启用,默认关闭。

归属与模式

targetprofileknowledge
user跨 Agent 的用户约定用户目标、事实、历史知识
agent当前 Agent 专属约定Agent 私有经验
current_workspace不支持当前项目事实、决策与流程

首次组装或 syncshot 时加载两级 Profile,并与 Instruction 一起冻结,再由 Agent 按需查询知识。Identity 与 Instruction 合并为 Agent system,Agent Profile 独立紧随其后;User Profile 单独位于 Session 信息之前,纳入完整 system 快照,不进入 User 原文。历史约定不定义本轮任务,当前请求与权限优先。

remember

{"target":"user","mode":"profile","content":"主回答前提醒我使用英语,我写英语时简要纠正表达。"}
参数行为
content必填,非空正文
targetuser、agent、current_workspace
modeprofile 或 knowledge,默认 knowledge
topicknowledge 主题,默认 inbox
memory_typefact、preference、decision、episode、procedure、document;默认 fact
sourceknowledge 可选来源说明

明确的新信息通过确定性提交保存,Profile 返回 profile_id,知识返回 memory_id。User 写入不要求登录或 resolve_user。需要语义归并或判断的请求交给 Memory Session。只有实际提交完成后才能确认已保存,受理或运行中的请求仍需查看处理结果。

保存结果与生效方式

持续行为约定应明确指定 mode=profile,省略 mode 仍默认为按需检索的 knowledge。返回的 status 表示保存或处理状态,mode 表示使用方式。异步处理以返回的 Job ID 关联结果;已受理、排队或运行中不表示保存成功。

Profile 保存后,新 Session 和 syncshot 读取完整当前正文;已有 Session 通过本轮有界参考更正感知核心版本变化。知识在按需检索时生效。User / Agent 知识管理和状态查看无需 Workspace,只有项目写入需要项目。

异步处理与状态

digest、revise 和 optimize 返回持久化处理记录,由专用 Memory Session 在后台处理。digest 从明确指定的会话范围提炼长期信息,revise 按修订要求处理指定记忆,optimize 整理 User 或 Agent Profile。接收请求后不能立即宣称已保存或已修订。

Memory Power 创建 work 分类、memory 类型的处理会话,并绑定专用指令和受限工具。工具只接受当前处理请求绑定的真实 Session,模型提出的变更经宿主校验后提交。会话类型名称本身不授予记忆处理权限。

从 Session 调用时,会为原调用 Session 与 Turn 订阅最终的 succeeded、skipped 或 failed 结果。对 digest 而言,接收方是调用 Session,可以与被读取的来源 Session 不同。完成摘要包含状态与结果记忆 ID,不携带来源正文。反馈通过独立 outbox 持久化并幂等处理。原轮次可接收时注入反馈;原轮次已结束则保留处理记录供查询,不自动新开轮次。记录的 delivery_status 为 delivered 时表示已注入,为 saved 时表示仅保留结果;两者都结束投递,saved 不再触发注入重试。投递失败会退避重试,不改变记忆提交状态。管理页请求没有聊天接收方。需要时通过处理记录查询结果,避免反复轮询,也不要重复确认同一 Job 已经反馈过的保存结果。

action输入结果
memory.jobslimit?、offset?当前 Agent 与 Workspace 下的 {items, total},条目为 MemoryJobView,不含来源正文
memory.job_statusjob_id单条 MemoryJobView,包含类型、范围、关联 Memory Session、结果或错误,不含来源正文
memory.job_detailjob_id{job: MemoryJobView, changes: MemoryJobChangeDetail[]},包含固定差异与来源摘录
memory.retryjob_id显式请求的失败记录重新进入处理后的实际状态;自动批次从后台整理页重试

状态包括 queued、running、committing、retry_wait、succeeded、skipped、failed。只有 succeeded 表示变更已提交;skipped 表示无需保存,failed 保留失败原因。重试沿用原请求范围和来源,不代表重试成功。Memory Job 属于记忆内部处理,不会创建用户 Task。

job_detail 是独立的读取端点,按当前 Job 的 Agent/Workspace 范围校验,与 job_status 使用相同的范围检查。它返回该请求持久化的授权来源摘录;列表和状态不含来源正文。每条差异包含操作、主题、可选记忆 ID、已有正文的 expected_version、固定的 before/after 快照、captured_at 与原始 sources 摘录。变更前正文绑定本次实际读取的版本;新增记录的 before 为 null,失效操作保留正文并标记为 invalidated。Profile 快照仅展示精确编辑区域,版本对应本次读取的完整 Profile。

来源摘录取自该 Job 已授权的输入,保留角色和可用的 Session、消息标识,并说明是否只展示部分原文。当前记忆后来发生变化,也不会改写这些快照。待处理或失败的差异仅为暂存计划,不能视为已经生效。未保存快照的记录返回 changes: [],不会用当前正文推造历史内容。

Memory 管理页的「处理记录」提供分页列表、状态详情、关联 Memory Session ID、提交结果和失败重试。选中记录后,通过 job_detail 加载差异与依据;逐条展示变更,长正文分段并高亮差异,来源分页展示。存在活跃记录时列表会刷新状态。宿主 actions 使用界面选定的 Agent 与 Workspace,执行相同的权限检查。

后台整理

在 Memory 的「后台整理」页选择 Agent、Workspace 和知识归属,再启用此范围。默认关闭;开关只控制该 Agent、项目上下文和目标的组合。自动处理仅提交 Agent 私有知识或获准共享的 Workspace 知识,不修改 User/Agent Profile,也不写入 User 知识。显式 remember、digest、revise、optimize 继续按各自请求执行。

可信材料来自两处:用户在后台整理页直接填写的明确纠错,以及官方 Power 组合接入的 Task accept 命令事实、带明确反馈的 Task revise 事实。Task 执行成功、普通 Turn 结束和打开结果都不表示验收。Task 事实与对应工作状态一起原子保存,并固定当时交付物的有界原文、角色、指纹和读取区间。删除 Task 前会归档这些事实;删除 Task 或遗忘知识不清除所有来源副本。Task 材料默认进入原 Agent 私有范围,不能因为有 Workspace 就自动共享。共享纠错需点击「提交项目共享纠错」,明确允许该项目使用原文。

维护检查每五分钟重放已发布事实、核对既有 Job,并在允许时安排一个后台批次。关闭时仍可可靠接收事实和核对已有提交回执,但不启动新的自动计算。已经进入执行的有界工作可以完成。没有新增材料不调用模型;不会自动扫描私人 Session 历史。Memory 自身的 Session、变更与完成反馈不是新的原始来源。

每批固定一个 Agent、一个目标和一种 knowledge 用途,最多 4 个事实、16 个来源、32,000 字符。每个范围按 UTC 日期最多预留 2 次自动计算,重试也占额度,两次之间至少间隔 10 分钟。常规计算沿用每次 120 秒和每 Job 最多 3 次尝试的上限。这些是计算次数与执行边界,不是货币成本结算。显式请求在每个 Job 边界优先;正在执行的计算和原子提交不被抢占。

管理页显示开关、积压、接收序号、连续处理水位、预算/冷却延期、来源边界、批次和对应 Job 状态。只有核对已发布提交回执的 succeeded,或明确无需修改的 skipped,才把输入标记为 processed。失败、来源错误与预算延期保留输入;前方未完成的事实会阻止连续水位推进。失败批次从此页重试,仍受范围开关、冷却、每日额度和尝试上限约束。自动批次没有聊天接收方,「已提交」不表示完成摘要已投递。

多个本地 City 使用同一平台数据根时,共享范围账本在文件锁内去重事件和批次。批次绑定原 City 的 Job;另一 City 可看到该归属,但不会接管或重新计算自己无法读取的 Job。恢复应保留原 City 的处理数据。自动流程沿用删除抑制,不具备显式重新记住的 allow_recreation 授权;精确正文抑制仍不能保证识别全部语义改写。

宿主管理入口

以下入口只供可信宿主和管理页使用,不注册为普通模型工具。

入口输入结果
memory.dream.statusagent_id、workspace_id?、target=agent/current_workspace当前范围账本、积压和本 City 的 Job 状态
memory.dream.configure同一范围 + enabled持久化开关后的状态
memory.dream.correction同一范围 + 客户端 UUID event_id、ISO occurred_at、content、workspace_share_allowed已接收,尚未处理或提交;相同事件重试须保留原参数
memory.dream.retry同一范围 + batch_id原批次受预算约束的重试状态

官方 Power 组合已连接可靠 Task 事实源。独立构造 MemoryPower 时,可通过 dreaming.read_signals 注入返回 MemorySignalInput[] 的可信可重放事实读取函数;不配置时仍可使用管理页纠错入口。来源端口不授予自动启用或扩大写入范围的权限。

文档维护

User 和 Agent 复用确定性的 MemoryProfile 服务。追加、编辑和删除均携带基础版本与可信来源;相同来源请求重试保持幂等,同一请求键不能用于不同内容。精确编辑要求唯一匹配、互不重叠、版本一致并保留来源标记,正文变更前保留备份。

显式调用 memory.optimize,输入 {"target":"user"} 或 {"target":"agent"},提交核心记忆整理 Job。Agent 目标绑定当前调用 Agent。Coordinator 安排专用 Memory Session、限制处理预算并检查提交版本。使用 jobs/job_status 查询状态,job_detail 查看差异与依据,retry 重试失败请求。同一请求范围内,对同一 Profile 版本重复整理使用稳定来源标识并复用 Job。Digest 按固定来源快照与提炼策略去重,无关知识变化不会产生重复请求。

Profile 文件服务提供正文、版本与长度读取,所有读写入口都持有本地跨进程范围锁,并在读取正文或回执前恢复 pending 操作。追加、编辑和删除的回执固定于对应提交版本。文件服务不运行自动定时优化,不根据长度自动创建 Job。整理以保留有效约定为准,不要求压缩到固定篇幅。

已有 Session 的持久 system 不随文件写入改写。核心版本变化时,本轮参考更正会停用该范围的旧快照,并提供当前有界正文;若发生截断,未展示部分不能继续沿用旧约定。完整刷新使用 syncshot。SOUL.md 是独立的 Agent 静态指令。

用户中心与管理 API

  • memory.user_read:返回唯一使用者资料。
  • memory.user_update:更新 display_name,不更换 user_id。
  • memory.profile_read/status:target=user,或 target=agent 并提供 agent_id。
  • memory.profile_edit:相同范围 + version + edits(old_text/new_text)。
  • memory.profile_delete:相同范围 + version,备份后删除整份 Profile。

版本由 read 返回;冲突时需重新读取。宿主为管理编辑和删除生成可重放的来源定位。profile_id 不可传给知识 read/revise/forget。删除整份 Profile 会停止使用当前正文;备份、来源账本、原始 Session 和 Job 中的来源正文副本仍保留,不代表所有历史副本已清除。

知识存储、导入与遗忘边界

知识的当前有效记录、版本、提交回执和抑制项以各范围已发布的 manifest 为准,read/search/list 从该 manifest 读取。逻辑 memory_id 中的 wiki/evidence 是标识命名空间,不代表正文来自同名目录。

运行时不会自动扫描、迁移或回退读取旧 wiki/evidence 文件。已有数据需要由调用方明确选择记录,并通过 SDK 级 create_memory_import_changeset helper 构造变更集,再调用 Provider 提交;这不是自动迁移或面向聊天的 import action。导入前须确认来源、目标范围和备份。缺失的原始证据只标记为导入来源,不推断不存在的证据。

Profile 继续使用独立的 PROFILE.md、来源账本、备份和 pending 恢复机制,所有文件入口共用范围锁。它不属于知识 manifest,也不与知识提交构成同一个原子事务。

forget 使指定知识退出当前有效集合,并保存规范化正文的精确指纹以抑制相同内容重新提交。该机制只匹配精确正文指纹,不保证阻止同一事实被语义改写后再次提炼。原始 Session、Job 中的来源正文副本及历史记录仍保留;遗忘不等于物理擦除全部副本。

配置与布局

const memory_power = new MemoryPower({
  platform_root_path: "/absolute/platform-root",
});

本地 User 读写无需身份回调。来源授权、可访问范围与 Memory Session 的工具权限由宿主和 Coordinator 校验。

<platform-root>/user/user.json
<platform-root>/user/PROFILE.md
<platform-root>/user/memory/runtime/knowledge/current.json
<platform-root>/agents/<agent_id>/PROFILE.md
<platform-root>/agents/<agent_id>/memory/runtime/knowledge/current.json
<shared-root>/workspaces/<encoded-id>/runtime/knowledge/current.json
<platform-root>/memory/dreaming/scopes/<scope-hash>.json

此架构面向单使用者本地环境,获授权的渠道共享本地 User;宿主负责渠道访问授权。数据转换需要确认数据根与备份方案。

记忆工具提供 status、list、search、read、remember、digest、revise、forget、optimize,以及 jobs、job_status、job_detail、retry。search 按当前有效记忆检索;明确保存和按 ID 删除通过确定性接口执行,digest、revise 与 optimize 进入异步处理。处理没有值得保存的内容时明确跳过。