diff --git a/docs/en/rfcs/1809-atomic-memory.md b/docs/en/rfcs/1809-atomic-memory.md new file mode 100644 index 0000000000..59f68e8094 --- /dev/null +++ b/docs/en/rfcs/1809-atomic-memory.md @@ -0,0 +1,296 @@ +--- +title: Atomic Memory as Independent Artifacts +--- + +- Proposal Name: `atomic_memory` +- Start Date: 2026-09-30 +- RFC PR: [oceanbase/powercontext#1809](https://github.com/oceanbase/powercontext/pull/1809) +- Depends on: [Artifact Search Projections and Join-Free Retrieval, #1803](https://github.com/oceanbase/powercontext/pull/1803) +- Migration dependency: [Unified Versioned Database Migrations, #1771](https://github.com/oceanbase/powercontext/pull/1771) +- Amends: [0014](0014_memory_layer_design.md), [0019](0019_local_source_memory_runtime.md), + [1345](1345_scope_organization_and_agent_integration.md), [1652](1652_memory_quality_and_lifecycle.md), + [1718](1718_memory_capacity_contract.md) +- Related: [1417](1417_topic_memory.md), [1549](1549_artifact_family_unification.md) + +# Summary + +This RFC introduces the `atomic-memory` Family. Each memory previously held in a Memory collection becomes an +independent Artifact organized by Scope, with its own ID, revisions, evidence, and state. + +Extraction first generates candidates from Source, then retrieves related active memories in the same Scope that +the processing identity may both read and write. The model automatically decides whether to create, revise, merge, +or make no write. Merging multiple memories creates a new Artifact; the inputs retain their history and stop evolving. +Users can edit the result or undo the merge. Search follows RFC #1803, and existing deployments upgrade offline under +RFC #1771. + +# Motivation + +## Memory collections duplicate Scope responsibilities + +[RFC 0014](0014_memory_layer_design.md) models Memory as a collection. A Memory Artifact stores a complete manifest, +with each member pointing to an immutable entry version. Changing one memory writes a new entry version and then a +collection revision that references it. + +After [RFC 1345](1345_scope_organization_and_agent_integration.md) introduced Scope, it still required one active +Memory progression line per Scope, with one Memory head maintaining the collection. A memory therefore involves both +collection and entry IDs and versions. Scope already organizes memories, and Artifact already provides revisions, +evidence, permissions, and tags. The collection layer retains additional maintenance rules. + +## Changing one memory still stores the whole collection directory + +The current implementation supports entry revision, historical reads, capacity limits, and optional manifest cleanup +through compaction. Content and search projections can be updated for changed entries, but every effective change +still constructs and stores the complete manifest, even when most entries are unchanged. + +Continued writes accumulate repeated directory information. Tasks editing different memories still update the same +collection head. Independent Artifacts make a single-memory update add history only for that memory. + +## Extraction context grows with memory count + +Built-in extraction gives the model every active entry of the selected Memory head. The model can revise memories +from earlier Source windows, but context size and input costs grow as memories accumulate. + +This change needs related-memory retrieval after candidate generation, before the model makes its decisions, together +with rules for merging multiple memories and undoing those merges. An entry replacement endpoint alone does not +resolve these problems. + +# Guide-level explanation + +## One memory, one Artifact + +Atomic Memory represents a fact, preference, or rule that can be understood and updated independently. Atomicity +refers to content granularity, not a requirement that each memory be one sentence. Times, reasons, and applicability +conditions needed to understand a fact remain part of it. + +For example, the default deployment region being East China and production releases requiring owner approval are +two memories. Changing the region to North China creates a new revision of only the first memory. Exact historical +references still return their original content. + +Memories can be extracted automatically from Source or written manually by an authorized caller. + +## Retrieve related memories before deciding what to write + +Processing new Source first generates candidates, then retrieves related active memories in the same Scope that the +processing identity may both read and write. Similarity finds related content; the model uses candidates, existing +memories, and evidence to decide whether to create, revise, merge, or make no write. These operations run automatically +by default, without per-operation approval or preauthorization of a category of merges. + +Read-only shared content cannot be a target of revision, merging, or deactivation. When statements about the same fact +conflict under the same conditions, the model uses time to select the newer applicable information and automatically +revises or merges the memories. It prioritizes explicit effective, event, or source-recording times and falls back to +Source ingestion order when comparable times are unavailable. Atomic Memory does not retain conflicts for users to +resolve or require confirmation of each decision. + +Times and applicability conditions remain part of the evidence: late-arriving historical material does not become a +new fact merely because it was just ingested, and rules for different environments should not overwrite each other. +A revision or merge does not refresh the time of the underlying fact. Historical content and lineage remain available; +later Source, user edits, or restoration can correct an incorrect decision. + +Every memory meeting the relevance threshold enters the comparison set. A fixed top-N cutoff must not discard other +qualifying results. Retrieval and model processing may use batches when there are many results. When vector search +is disabled or unavailable, full-text search or another retrieval method still selects related memories; extraction +must not put the whole Scope's memory collection directly into model context. + +## A merge creates a new memory + +Merging A and B creates a new memory C. C records the exact input revisions. A and B enter the merged state, stop +content evolution, and leave normal search, while remaining readable by exact reference. Later Source or user edits +continue updating C. + +The model may discard invalidated content based on new evidence. Prompts must distinguish invalidation from omission +and preserve still-valid facts, applicability conditions, and evidence during rewriting. Prompts cannot eliminate +all mistakes, so input memories and merge history remain available for correction and undo. + +## Four states + +| State | Normal search | Authorized exact reads | Restoration | +| --- | --- | --- | --- | +| Active | Included | Allowed | — | +| Forgotten | Excluded | Allowed | May be restored independently to active | +| Merged | Excluded | Allowed | Restore by undoing related merges; a standalone state change cannot bypass the merge relationship | +| Retired | Excluded | Allowed | The original identity cannot be restored | + +Only active memories participate in new merges. If C is forgotten, A and B remain merged. Restoring C restores only C; +restoring A or B requires undoing the merge that created C. Historical reads do not automatically restore memories. + +## Correct content or undo a merge + +Users may edit C through an Agent or management interface, or allow later collected Source to drive its evolution. +Restoring an older revision of C creates a new revision from that content. It neither rewrites history nor changes +the states of A and B. + +Undoing the merge that created C restores A and B at their frozen revisions and retires C. Content added to C later +also leaves normal search; it is not automatically distributed back to A and B. All of C's history remains readable +by exact reference. A restoration request targeting A or B makes the server perform this group operation. + +The server also handles successive merges. If A and B form C, and C later merges with D into E, a request to restore B +undoes E and then C. The final result restores A, B, and D and retires C and E, with one client request. If D was itself +a merge result, it is restored intact rather than split further. + +By default, undo restores each input at the exact revision used in its merge. A request may also select a historical +revision of the target: first undo subsequent merges that keep it in the merged state, then create a new target revision +from the selected content. Other restored inputs retain their frozen revisions. For example, restoring an older +revision of C requires undoing E, but not the merge that created C. This still takes one client request. Selecting a +historical revision cannot restore a retired memory. + +Only merge relationships still in effect are followed; ordinary evidence references do not cause other Artifacts to +roll back. Undo does not rewind Source consumption. +New Source may lead the model to merge the memories again, creating a new identity. + +## Preview a restoration or call it directly + +The service provides separate restoration preview and execution operations. A preview does not change data. It returns +the memories and revisions to restore, the merge results to retire, and later content that will leave current search. +A management interface displays this impact before the user confirms execution. + +Client-side state is only a hint; the server determines the actual impact. Execution against a preview checks that the +target memory, selected revision, and restoration operation match the preview, and that the current merge endpoint's +content and state versions have not changed. A mismatch rejects execution and requires a new preview rather than +expanding the scope the user confirmed. + +A user or Agent may also request restoration directly, without a preview or manually traversing merge results. The +server computes and performs restoration against execution-time state and returns the affected objects. Direct calls +still require permission, state, and concurrency checks. Confirmation after a preview applies only to user-initiated +restoration; routine extraction and merging remain automatic. + +# Reference-level explanation + +## Existing contracts and changes made here + +Scope membership and organization follow RFC 1345, Source processing follows RFC 0019, and identity, revisions, and +evidence follow RFC 1549. + +This proposal replaces the collection and entry version layers of RFCs 0014 and 0019 and gives each Atomic Memory an +independent head in place of RFC 1345's single Memory head per Scope. The Scope still uses one Source journal, and its +extraction flow owns processing progress. Individual memories do not consume Source separately or have independent +cursors. + +RFC 1652's evidence-preservation principles remain applicable. Atomic Memory creation, revision, and semantic merging +run automatically, and the model resolves conflicts using time. Its per-operation merge approval and unresolved-conflict +retention requirements do not apply to Atomic Memory. Merging multiple memories creates a new result and freezes the +inputs. This RFC does not change approval or conflict-handling rules for other Artifact families. + +RFC 1652's `superseded` is derived validity for an exact entry version; it does not directly map to an entire Artifact's +lifecycle state. The new Family uses the four Artifact lifecycle states defined here: when A advances from revision 1 +to revision 2, A remains active; revision 1 leaves normal search and remains readable by exact reference. +Merging A and B into C freezes A and B as merged. Generic Artifact revisions, lineage, and explicit merge relationships +preserve evidence and successor references. + +RFC 1718's collection capacity limits for complete manifests do not apply to the new Family. They are not converted +into a Scope-wide memory count limit, and this proposal introduces no historical revision expiry policy. Release +compatibility documentation states how old configuration is handled. + +## Search and concurrency + +Search projections and their updates follow [RFC #1803](https://github.com/oceanbase/powercontext/pull/1803). Atomic +Memory may use wide tables or separate projections, with no business-table joins in full-text or vector retrieval. +When extraction selects memories it may modify, Scope, read/write permissions, and active state take effect during +candidate selection. + +Ordinary Prepare Context follows existing Scope selection and authorization rules to retrieve active Atomic Memory +Artifacts that the caller may read. +Selection, ordering, entry limits, UTF-8 byte budgets, and assembly follow [Context Pack (RFC 0028)](0028_context_pack.md) and +[Prepared Context Text Assembly (RFC 1489)](1489_prepared_context_text_assembly.md), retaining exact revision references +to the selected Artifacts. Ordinary Prepare Context uses bounded recall; extraction requires complete enumeration of +related memories meeting the threshold. + +During extraction, batch sizes bound individual reads and model inputs without truncating the total set meeting the threshold. +Incomplete processing must not be reported as no new memory. Implementation design determines thresholds, batching, +and index choices. + +Memory states, relationships, and current search data affected by a merge, restoration, or merge undo become visible +together. Original memories must not reappear in normal search while their merge result remains searchable. One +active memory cannot be concurrently consumed into two merge results that are both in effect. + +During restoration, the server checks current content versions, states, and merge relationships inside the write +transaction. A preview identifier adds validation against the preview; requests without one use current state. +The checked conditions must still hold at commit, without overwriting intervening updates. + +## Upgrade and compatibility + +Existing deployments upgrade offline under [RFC #1771](https://github.com/oceanbase/powercontext/pull/1771). Its unified +process governs schema changes, data conversion, projection rebuilding, and old-table cleanup. + +Migration preserves existing content, evidence, lifecycle history, exact references, permissions, tags, and Source +processing progress. The change does not re-extract already processed Source. Old collection snapshots and references +retain a corresponding read path; a collection reference cannot be reinterpreted as a single new memory. Entries that +were recoverable or non-reactivatable retain those respective semantics. Missing or unexplained history cannot be +silently discarded. + +Legacy `memory` APIs are adapted where possible at the API layer. Compatibility does not add tables or continue +maintaining collection versions and membership history in other tables. Existing exact references remain readable +as history, and legacy entry identities can resolve to the new Artifacts. Requests, responses, tags, and concurrency +preconditions retain their original meaning where supported. Authorization and execution must target the same object; +collection-version preconditions must not be ignored. Operations requiring post-upgrade collection snapshots, +collection CAS, or a continuous collection change history are no longer supported. Retained routes with changed +responses and unsupported operations follow RFC #1771's declarations of contract changes, replacement calls, and +retirement schedules. Compatibility does not promise that old clients can continue unchanged. + +Each release declares old-API compatibility periods and cleanup conditions for objects retained during migration. +This proposal does not require permanent support for collection writes, and removing old physical tables does not +authorize deleting historical content. + +# Drawbacks + +- Memory identities and APIs require adaptation. Complete historical migration needs downtime and additional storage. +- Each merge adds an Artifact and retains its inputs and relationships. Undo can involve several memories, requiring + permission and concurrency handling for the group. +- Many memories may meet the threshold and require batches for comparison. Thresholds and model decisions can still + miss relationships or produce incorrect merges. +- Automatic conflict resolution using time may accept incorrect newer information, especially when missing times + require relying on Source order. Later evolution, edits, or restoration provide correction. +- Undo removes later revisions of the merge result from normal search. Other Artifacts already referencing those + revisions do not automatically roll back. +- During compatibility periods, old requests, responses, and references require adapters; ending support needs an + explicit release arrangement. + +# Rationale and alternatives + +**Independent Artifacts.** Scope organizes memories, while Artifact handles individual revisions, evidence, and state. +A single-memory update no longer creates a collection directory revision. Incremental manifests or smaller collections +can reduce directory copying but retain two identity layers. + +**The `atomic-memory` Family.** The name expresses independently maintained memory granularity for both extraction and +manual writes. Keeping `memory` would give old collections and new individual memories the same Family meaning. A new +Family separates them while supporting compatibility for specific old operations. + +**Create C and freeze A and B.** Revising A in place to absorb B can later require disentangling B's content from an A +that has continued evolving. A new C preserves explicit pre-merge inputs: edits affect C, and undo restores the inputs. +Irreversibly retiring A and B would prevent restoration of their original identities. + +**Automatic merging by default.** Merging is part of Source extraction and runs automatically alongside ordinary +creation and revision. Per-operation approval or category preauthorization adds maintenance steps. This proposal uses +retained history, correction, and undo to handle mistakes without requiring users to approve each model merge decision. + +**Resolve conflicts automatically using time.** Atomic memories are produced continuously in large numbers. Leaving +each contradiction for users to resolve would accumulate maintenance work. The model updates current memories using +time, with history and restoration supporting correction, without a separate unresolved-conflict workflow. + +# Prior art + +- [RFC 1345](1345_scope_organization_and_agent_integration.md) and [1549](1549_artifact_family_unification.md) provide + Scope organization and shared Artifact capabilities. +- [RFC 0019](0019_local_source_memory_runtime.md) defines Source consumption and extraction progress. +- [RFC 1417](1417_topic_memory.md) generates candidates before selecting related Topics, informing related-memory retrieval. +- [RFC 1652](1652_memory_quality_and_lifecycle.md) defines evidence, validity, conflict, and lifecycle rules. This proposal + changes its merge approval and conflict-retention requirements for Atomic Memory. +- [RFC 1718](1718_memory_capacity_contract.md) describes complete-manifest capacity costs and historical protection. +- [RFC #1803](https://github.com/oceanbase/powercontext/pull/1803) defines the common search contract, and + [RFC #1771](https://github.com/oceanbase/powercontext/pull/1771) defines the unified migration process. + +# Unresolved questions + +- When a user corrects a memory through an Agent, should Source retain the corrected memory's reference and surrounding + context? Can existing Agent integrations and capture paths provide them, and which integrations need changes? +- Should other Artifact families adopt these four states? How should the existing `deprecated` state map to forgotten + and merged? This RFC defines Atomic Memory behavior; adoption and adaptation by other families remain separate decisions. + +Physical deletion, automatic merging across Scopes, and whole-Scope snapshot rollback are outside this proposal. +Table schemas, API parameters, locking, and transaction implementation belong in the implementation design. Migration +follows RFC #1771. + +# Future possibilities + +A management interface could visualize memory revisions and merge relationships to help users inspect original +content, compare revisions, and choose restoration targets. Richer history views do not change these state and +restoration rules and are not prerequisites for basic preview and restoration capabilities. diff --git a/docs/zh/rfcs/1809-atomic-memory.md b/docs/zh/rfcs/1809-atomic-memory.md new file mode 100644 index 0000000000..5aac9e458b --- /dev/null +++ b/docs/zh/rfcs/1809-atomic-memory.md @@ -0,0 +1,243 @@ +--- +title: Atomic Memory 独立记忆制品 +--- + +- 提案名称:`atomic_memory` +- 起始日期:2026-09-30 +- RFC PR:[oceanbase/powercontext#1809](https://github.com/oceanbase/powercontext/pull/1809) +- 前置 RFC:[制品检索投影与无 JOIN 召回,#1803](https://github.com/oceanbase/powercontext/pull/1803) +- 迁移依赖:[统一版本化数据库迁移,#1771](https://github.com/oceanbase/powercontext/pull/1771) +- 修订 RFC:[0014](0014_memory_layer_design.md)、[0019](0019_local_source_memory_runtime.md)、 + [1345](1345_scope_organization_and_agent_integration.md)、[1652](1652_memory_quality_and_lifecycle.md)、 + [1718](1718_memory_capacity_contract.md) +- 相关 RFC:[1417](1417_topic_memory.md)、[1549](1549_artifact_family_unification.md) + +# 摘要 + +本 RFC 引入 `atomic-memory` Family,将原来 Memory 集合中的每条记忆改为独立 Artifact,由 Scope 组织。 +每条记忆分别维护自己的 ID、版本、证据和状态。 + +抽取先从 Source 生成候选记忆,再检索同一 Scope 内有权读写的相关在役记忆,由模型自动决定新建、更新、合并或 +不写入。多条记忆合并时创建新 Artifact,原记忆保留历史并停止演进;用户可以编辑合并结果,也可以撤销合并。 +检索遵守 RFC #1803,现有部署按照 RFC #1771 停服升级。 + +# 动机 + +## Memory 集合与 Scope 的职责重叠 + +[RFC 0014](0014_memory_layer_design.md) 将 Memory 设计为一个记忆集合:Memory Artifact 保存完整条目目录 +(manifest),其中每一项指向一个不可变的 entry version。修改一条记忆,需要写入新的 entry version, +再生成引用它的集合版本。 + +[RFC 1345](1345_scope_organization_and_agent_integration.md) 引入 Scope 后,仍规定每个 Scope 只有一条活跃的 +Memory 推进线,由一个 Memory head 维护集合。因此,一条记忆同时涉及集合的 ID 和版本,以及 entry 的 ID 和 +版本。Scope 已经可以组织记忆,Artifact 也已经提供版本、证据、权限和标签,这层集合保留了额外的维护规则。 + +## 修改一条记忆,也要保存整个集合的目录 + +当前实现已经支持 entry 修订、历史读取、容量限制和可选的目录清理(compact)。正文和检索投影可以按变化的 +条目更新,但每次有效修改仍需重新构造并保存完整 manifest,其中大部分条目可能没有变化。 + +持续写入会积累重复的目录信息。两个任务即使修改不同记忆,也需要更新同一个集合的当前版本(head)。 +将每条记忆改为独立 Artifact 后,单条更新只增加该记忆的历史版本。 + +## 抽取上下文随记忆数量增长 + +当前内置抽取会把所选 Memory head 中的全部活跃 entry 交给模型。模型可以修订之前 Source window 产生的记忆, +但随着记忆积累,每次抽取的上下文和输入成本都会增长。 + +本次改造需要在生成候选后先检索相关记忆,再交给模型判断,同时补充多条记忆合并及撤销合并的规则。 +仅增加 entry 替换接口,无法解决这些问题。 + +# 使用说明 + +## 一条记忆,一个 Artifact + +Atomic Memory 表示一项可以独立理解、更新的事实、偏好或规则。“原子”描述内容粒度,不要求每条记忆只有一句话。 +一项事实需要时间、原因或适用条件才能说清楚时,应保留这些内容。 + +例如,“默认部署区域为华东”和“生产发布需要负责人审批”是两条记忆。部署区域改为华北时,只为第一条记忆生成 +新版本。旧版本的精确引用仍返回当时的正文。 + +记忆可以从 Source 自动抽取,也可以由有权限的调用方手工写入。 + +## 先检索,再由模型决定如何写入 + +处理新的 Source 时,先生成候选记忆,再检索同一 Scope 内在役、且执行身份有权读写的相关记忆。相似度用于寻找 +相关内容,模型结合候选、已有记忆和证据,决定新建、更新、合并或不写入。这些操作默认自动执行,无需逐次审批, +也无需预先授权某一类合并。 + +只读共享内容不能成为本次更新、合并或停用的对象。同一事实在相同适用条件下出现冲突时,模型按时间采用较新的 +有效内容,自动完成修订或合并。优先依据明确的生效、事件或来源记录时间,缺少可比较时间时按 Source 采集顺序 +处理。Atomic Memory 不保留等待用户处理的冲突,也不要求用户逐项确认。 + +时间和适用条件仍需保留:迟到的旧资料不因刚被采集就成为新事实,不同环境的规则也不应互相覆盖。 +修订或合并本身不会更新事实的时间。旧内容和依据保留在历史与 lineage 中,判断有误时可由后续 Source、用户编辑 +或恢复操作纠正。 + +达到相关度阈值的记忆都应进入比较范围,不能只取固定的前 N 条并忽略其余结果。数量较多时可以分批检索、分批交给 +模型处理。未启用或无法使用向量检索时,也要通过全文检索等方式筛选相关记忆,不能将整个 Scope 的记忆直接放进 +模型上下文。 + +## 合并产生新的记忆 + +A、B 合并时,创建新的记忆 C。C 记录这次合并所使用的 A、B 的精确版本;A、B 进入“被合并”状态,停止正文演进, +退出正常检索,但历史仍可点查。后续 Source 或用户修改继续更新 C。 + +模型可以根据新证据舍弃失效内容。提示词应区分失效与遗漏,保留仍然有效的事实、适用条件和证据,避免在改写时 +丢失信息。提示词无法消除所有误判,因此需要保留原记忆和合并历史,让用户能够纠正或撤销。 + +## 四种状态 + +| 状态 | 正常检索 | 有权限时点查 | 恢复方式 | +| --- | --- | --- | --- | +| 在役 | 可以 | 可以 | — | +| 遗忘 | 不参与 | 可以 | 可以单独恢复为在役 | +| 被合并 | 不参与 | 可以 | 撤销相关合并后恢复,不能单独修改状态绕过合并关系 | +| 退役 | 不参与 | 可以 | 不可恢复原身份 | + +只有在役记忆参与新的合并。C 被遗忘后,A、B 仍处于“被合并”状态;恢复 C 只恢复 C,恢复 A 或 B 则需要撤销 +产生 C 的合并。点查历史不会自动恢复记忆。 + +## 纠正内容与撤销合并 + +用户可以通过 Agent 或管理界面编辑 C,也可以让后续采集的 Source 继续推动 C 演化。恢复 C 的旧版本时,以旧内容 +生成一个新版本,不改写历史,也不改变 A、B 的状态。 + +撤销产生 C 的合并,则恢复 A、B 被冻结时的版本,并将 C 退役。C 后续增加的内容也随之退出正常检索,不会自动 +分配回 A、B;C 的全部历史仍可点查。用户从 A 或 B 发起恢复时,由服务端完成这次整组操作。 + +连续合并同样由服务端处理。例如 A、B 合并成 C,C 又与 D 合并成 E。用户请求恢复 B,服务端依次撤销 E、C, +最终恢复 A、B、D,退役 C、E。用户只需发起一次请求。若 D 也由其他记忆合并而来,恢复 D 即可,不继续拆开 D。 + +撤销合并默认恢复各输入被合并时的精确版本。请求也可以指定目标记忆的历史版本:先撤销使它处于“被合并”状态的 +后续合并,再用所选内容为目标生成新版本,其他被恢复的输入仍使用冻结版本。例如,恢复 C 的旧版本只需撤销 E, +不撤销产生 C 的合并。上述过程仍由同一次请求完成;指定历史版本也不能恢复已退役的记忆。 + +只沿当前仍生效的合并关系处理,不沿普通证据引用回滚其他制品。 +撤销不回退 Source 消费进度;新的 Source 到来后,模型仍可决定再次合并,并创建新的记忆身份。 + +## 回滚预览与直接调用 + +服务提供独立的回滚预览和执行操作。预览不修改数据,返回将恢复的记忆及版本、将退役的合并结果,以及会退出 +当前检索的后续内容。管理界面据此展示影响,用户确认后执行。 + +前端已有状态只用于提示,实际影响范围由服务端确定。按预览执行时,服务端检查目标记忆及其版本、恢复操作是否 +与预览一致,以及当前合并终点的正文版本和状态版本是否改变;不一致则拒绝这次执行,要求重新预览,不能扩大 +用户已经确认的范围。 + +用户或 Agent 也可以直接请求恢复目标,无需先预览或逐层寻找合并结果。服务端按执行时的状态计算并完成恢复, +返回实际受影响的对象。直接调用仍须通过权限、状态和并发检查。预览后的确认仅用于用户主动回滚,日常抽取和 +合并继续自动执行。 + +# 参考级说明 + +## 沿用的规范与本次调整 + +Scope 归属和组织沿用 RFC 1345,Source 处理沿用 RFC 0019,身份、版本和证据沿用 RFC 1549。 + +本提案替代 RFC 0014、0019 中集合与 entry 分别维护版本的模型,将 RFC 1345 中每个 Scope 的单一 Memory head +改为各 Atomic Memory 的独立 head。Scope 仍使用一个 Source journal,并由 Scope 的抽取流程维护处理进度; +每条记忆不分别消费 Source,也没有独立 cursor。 + +RFC 1652 的证据保留原则继续适用。Atomic Memory 的新增、更新与语义合并默认自动执行,冲突按时间自动处理, +不适用其中语义合并逐次审批和保留未解决冲突的要求;多条记忆合并采用“新建结果、冻结输入”的方式。 +本提案不修改其他制品的审批及冲突处理规则。 + +RFC 1652 的 `superseded` 是针对精确 entry version 的派生有效性,不直接对应整个 Artifact 的生命周期状态。 +新 Family 使用本文的四种 Artifact 生命周期状态:A 从版本 1 修订为版本 2 时,A 仍在役;版本 1 退出正常检索, +仍可精确读取。A、B 合并成 C 时,才将 A、B 冻结为“被合并”。证据与后继引用由通用 Artifact 版本、 +lineage 和显式合并关系保留。 + +RFC 1718 针对完整 manifest 设置的集合容量限制不适用于新 Family,不将其换算为 Scope 记忆总量上限, +也不新增历史版本到期删除策略。旧配置的处理在发布兼容说明中明确。 + +## 检索与并发 + +检索投影及其更新遵守 [RFC #1803](https://github.com/oceanbase/powercontext/pull/1803)。Atomic Memory 可以 +使用宽表或独立投影;全文、向量召回不使用业务表 JOIN。抽取选择可修改的记忆时,Scope、读写权限和在役状态 +须在候选选择阶段生效。 + +普通 Prepare Context 按现有 Scope 选择和授权规则,召回有权读取的在役 Atomic Memory,沿用 +[Context Pack(RFC 0028)](0028_context_pack.md) 和 [上下文文本组装(RFC 1489)](1489_prepared_context_text_assembly.md) +的选择、顺序、条数上限和 UTF-8 字节预算规则,并保留所选 Artifact 的精确版本引用。它采用有界召回;抽取则需要 +完整枚举达到阈值的相关记忆。 + +抽取过程中,单批大小用于控制每次读取和模型输入,不得截断达到阈值的总结果集。处理尚未完成时,不能将其报告为“没有新记忆”。 +具体阈值、分批方式和索引选择由实现设计确定。 + +合并、恢复及撤销涉及的记忆状态、关系和当前检索数据必须一起生效。不能出现原记忆已经恢复,而合并结果仍在 +正常检索中的中间状态;同一在役记忆也不能被并发合并进两个同时有效的结果。 + +执行恢复时,服务端在写入事务内检查当前正文版本、状态和合并关系。带预览标识时,还要检查是否符合预览; +不带标识时,按当前状态处理。检查结果须在提交时仍然成立,不能覆盖期间发生的更新。 + +## 升级与兼容 + +现有部署按照 [RFC #1771](https://github.com/oceanbase/powercontext/pull/1771) 停服升级。数据库结构变更、 +数据转换、投影重建及旧表清理由其统一流程管理。 + +迁移保留已有正文、证据、生命周期历史、精确引用、权限、标签和 Source 处理进度,不因改造重新抽取已处理的 +Source。旧集合快照和引用仍有对应的读取方式,不能把集合引用直接解释为某一条新记忆。迁移前可恢复与不可直接 +恢复的条目须保持各自语义;缺失或无法解释的历史不能静默丢弃。 + +旧 `memory` API 在接口层尽可能适配,不为兼容新增表,也不在其他表中继续维护旧集合版本和成员历史。 +保留已有精确引用的历史读取,并提供旧条目身份到新制品的定位;请求、响应、标签和并发前提能保持原义的部分继续支持。 +鉴权与执行须指向同一对象,不能忽略旧请求中的集合版本前提。依赖升级后集合快照、集合 CAS 和连续变更历史的操作不再支持。 +保留路由但调整响应的接口,以及停止支持的操作,均按 RFC #1771 声明契约变化、替代调用及退出安排,不承诺旧客户端无需调整。 + +旧接口的兼容期和迁移保留对象的后续清理条件由对应发布声明。本提案不要求永久维护旧集合写入机制,也不以删除 +旧物理表作为删除历史内容的授权。 + +# 缺点 + +- 记忆身份与接口需要适配,完整历史迁移需要停服时间和额外空间。 +- 每次合并都会增加一个 Artifact,并保留输入记忆和合并关系。撤销可能涉及多条记忆,需要整组处理权限与并发变化。 +- 达到阈值的相关记忆可能很多,需要分批完成比较。阈值和模型判断仍可能遗漏关系或产生错误合并。 +- 按时间自动处理冲突可能采纳有误的新内容,时间缺失时尤其依赖 Source 顺序;纠正通过后续演化、编辑或恢复完成。 +- 撤销合并后,结果记忆上的后续修订退出正常检索;已经引用这些版本的其他制品不会自动回滚。 +- 兼容期内需要维护旧请求、响应及引用的适配,结束兼容需要明确的发布安排。 + +# 设计理由与替代方案 + +**每条记忆使用独立 Artifact。** Scope 负责组织,Artifact 负责单条记忆的版本、证据和状态,单条更新不再生成 +整个集合的目录版本。增量 manifest 或多个小集合可以缓解目录复制,但仍保留集合与 entry 两层身份。 + +**使用 `atomic-memory` Family。** 名称表达可独立维护的记忆粒度,适用于自动抽取和手工写入。继续使用 `memory` +会让旧集合与新单条记忆共用一种 Family 含义;新 Family 可以明确区分它们,并按操作提供旧接口兼容。 + +**合并生成 C,冻结 A、B。** 原地把 B 并入 A 后,纠正合并可能需要从不断更新的 A 中重新拆出 B 的内容。 +新建 C 保留了明确的合并前状态,后续编辑作用于 C,撤销则恢复输入记忆。直接将 A、B 不可逆退役,会失去恢复 +原身份的能力。 + +**默认自动合并。** 合并作为 Source 抽取的一部分,与普通新增、更新采用同样的自动执行方式。逐次审批或按类别 +预授权都会增加维护步骤。本提案通过保留历史、允许纠正和撤销处理错误,不要求用户逐次确认模型的合并判断。 + +**冲突按时间自动处理。** 原子记忆持续大量产生,把每次矛盾留给用户判断会积累维护工作。模型按时间更新当前 +记忆,历史与恢复能力承担纠错需要,不建立独立的待处理冲突流程。 + +# 先例 + +- [RFC 1345](1345_scope_organization_and_agent_integration.md) 和 [1549](1549_artifact_family_unification.md) + 分别提供 Scope 组织方式和通用 Artifact 能力。 +- [RFC 0019](0019_local_source_memory_runtime.md) 定义 Source 消费与抽取进度。 +- [RFC 1417](1417_topic_memory.md) 先生成候选,再选择相关 Topic,可供相关记忆检索参考。 +- [RFC 1652](1652_memory_quality_and_lifecycle.md) 定义证据、有效性、冲突与生命周期规则,本提案调整 Atomic Memory 的合并审批及冲突保留要求。 +- [RFC 1718](1718_memory_capacity_contract.md) 说明完整 manifest 的容量成本及历史保护要求。 +- [RFC #1803](https://github.com/oceanbase/powercontext/pull/1803) 定义公共检索规范, + [RFC #1771](https://github.com/oceanbase/powercontext/pull/1771) 定义统一迁移流程。 + +# 未解决问题 + +- 用户通过 Agent 纠正记忆时,Source 是否需要保留被纠正记忆的引用及相关上下文?现有 Agent 集成和采集方式 + 能否提供这些信息,哪些地方需要调整? +- 其他制品是否也采用这四种状态?现有 `deprecated` 状态如何对应“遗忘”和“被合并”?Atomic Memory 的行为 + 在本提案中明确,其他制品是否统一及如何改造另行讨论。 + +本提案不包含物理删除、跨 Scope 自动合并或整个 Scope 的快照回滚。具体表结构、接口参数、锁与事务实现放在 +实现方案中;迁移遵守 RFC #1771。 + +# 后续可能性 + +管理界面可以展示记忆版本与合并关系图,帮助用户查看原文、比较版本和选择恢复目标。更完整的历史展示不改变 +上述状态和恢复规则,也不作为基础预览与恢复能力的前置条件。