From 33f5949e4f72efc4c9bb2cee1a6b18f0987d21da Mon Sep 17 00:00:00 2001 From: frf12 Date: Wed, 30 Sep 2026 12:17:21 +0800 Subject: [PATCH 1/2] docs(rfc): propose atomic memory as independent artifacts --- docs/en/rfcs/1809-atomic-memory.md | 282 +++++++++++++++++++++++++++++ docs/zh/rfcs/1809-atomic-memory.md | 233 ++++++++++++++++++++++++ 2 files changed, 515 insertions(+) create mode 100644 docs/en/rfcs/1809-atomic-memory.md create mode 100644 docs/zh/rfcs/1809-atomic-memory.md diff --git a/docs/en/rfcs/1809-atomic-memory.md b/docs/en/rfcs/1809-atomic-memory.md new file mode 100644 index 0000000000..6419255899 --- /dev/null +++ b/docs/en/rfcs/1809-atomic-memory.md @@ -0,0 +1,282 @@ +--- +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, each Scope still retained one +active Memory 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. Independent memory Artifacts do not each consume Source separately; the Scope's extraction +flow still owns processing progress. + +This proposal replaces the collection and entry version layers of RFCs 0014 and 0019 and removes RFC 1345's requirement +for one active Memory collection per Scope. + +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 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. + +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..62bbee8e85 --- /dev/null +++ b/docs/zh/rfcs/1809-atomic-memory.md @@ -0,0 +1,233 @@ +--- +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 集合。因此，一条记忆同时涉及集合的 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。 +多条记忆成为独立 Artifact，不意味着每条记忆分别消费 Source；处理进度仍由所属 Scope 的抽取流程维护。 + +本提案替代 RFC 0014、0019 中集合与 entry 分别维护版本的模型，并取消 RFC 1345 中每个 Scope 只有一个活跃 +Memory 集合的要求。 + +RFC 1652 的证据保留原则继续适用。Atomic Memory 的新增、更新与语义合并默认自动执行，冲突按时间自动处理， +不适用其中语义合并逐次审批和保留未解决冲突的要求；多条记忆合并采用“新建结果、冻结输入”的方式。 +本提案不修改其他制品的审批及冲突处理规则。 + +RFC 1718 针对完整 manifest 设置的集合容量限制不适用于新 Family，不将其换算为 Scope 记忆总量上限， +也不新增历史版本到期删除策略。旧配置的处理在发布兼容说明中明确。 + +## 检索与并发 + +检索投影及其更新遵守 [RFC #1803](https://github.com/oceanbase/powercontext/pull/1803)。Atomic Memory 可以 +使用宽表或独立投影；全文、向量召回不使用业务表 JOIN。抽取选择可修改的记忆时，Scope、读写权限和在役状态 +须在候选选择阶段生效。 + +单批大小用于控制每次读取和模型输入，不得截断达到阈值的总结果集。处理尚未完成时，不能将其报告为“没有新记忆”。 +具体阈值、分批方式和索引选择由实现设计确定。 + +合并、恢复及撤销涉及的记忆状态、关系和当前检索数据必须一起生效。不能出现原记忆已经恢复，而合并结果仍在 +正常检索中的中间状态；同一在役记忆也不能被并发合并进两个同时有效的结果。 + +执行恢复时，服务端在写入事务内检查当前正文版本、状态和合并关系。带预览标识时，还要检查是否符合预览； +不带标识时，按当前状态处理。检查结果须在提交时仍然成立，不能覆盖期间发生的更新。 + +## 升级与兼容 + +现有部署按照 [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。 + +# 后续可能性 + +管理界面可以展示记忆版本与合并关系图，帮助用户查看原文、比较版本和选择恢复目标。更完整的历史展示不改变 +上述状态和恢复规则，也不作为基础预览与恢复能力的前置条件。 From 9be690e61cf4f141084fd773d740d2599977a555 Mon Sep 17 00:00:00 2001 From: frf12 Date: Thu, 8 Oct 2026 00:26:27 +0800 Subject: [PATCH 2/2] docs(rfc): clarify atomic memory retrieval and lifecycle --- docs/en/rfcs/1809-atomic-memory.md | 32 +++++++++++++++++++++--------- docs/zh/rfcs/1809-atomic-memory.md | 24 +++++++++++++++------- 2 files changed, 40 insertions(+), 16 deletions(-) diff --git a/docs/en/rfcs/1809-atomic-memory.md b/docs/en/rfcs/1809-atomic-memory.md index 6419255899..59f68e8094 100644 --- a/docs/en/rfcs/1809-atomic-memory.md +++ b/docs/en/rfcs/1809-atomic-memory.md @@ -31,10 +31,10 @@ RFC #1771. 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, each Scope still retained one -active Memory 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. +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 @@ -158,17 +158,24 @@ restoration; routine extraction and merging remain automatic. ## 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. Independent memory Artifacts do not each consume Source separately; the Scope's extraction -flow still owns processing progress. +evidence follow RFC 1549. -This proposal replaces the collection and entry version layers of RFCs 0014 and 0019 and removes RFC 1345's requirement -for one active Memory collection per Scope. +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. @@ -180,7 +187,14 @@ Memory may use wide tables or separate projections, with no business-table joins When extraction selects memories it may modify, Scope, read/write permissions, and active state take effect during candidate selection. -Batch sizes bound individual reads and model inputs without truncating the total set meeting the threshold. +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. diff --git a/docs/zh/rfcs/1809-atomic-memory.md b/docs/zh/rfcs/1809-atomic-memory.md index 62bbee8e85..5aac9e458b 100644 --- a/docs/zh/rfcs/1809-atomic-memory.md +++ b/docs/zh/rfcs/1809-atomic-memory.md @@ -29,9 +29,9 @@ title: Atomic Memory 独立记忆制品 （manifest），其中每一项指向一个不可变的 entry version。修改一条记忆，需要写入新的 entry version， 再生成引用它的集合版本。 -[RFC 1345](1345_scope_organization_and_agent_integration.md) 引入 Scope 后，同一 Scope 仍然只有一个活跃的 -Memory 集合。因此，一条记忆同时涉及集合的 ID 和版本，以及 entry 的 ID 和版本。Scope 已经可以组织记忆， -Artifact 也已经提供版本、证据、权限和标签，这层集合保留了额外的维护规则。 +[RFC 1345](1345_scope_organization_and_agent_integration.md) 引入 Scope 后，仍规定每个 Scope 只有一条活跃的 +Memory 推进线，由一个 Memory head 维护集合。因此，一条记忆同时涉及集合的 ID 和版本，以及 entry 的 ID 和 +版本。Scope 已经可以组织记忆，Artifact 也已经提供版本、证据、权限和标签，这层集合保留了额外的维护规则。 ## 修改一条记忆，也要保存整个集合的目录 @@ -135,15 +135,20 @@ A、B 合并时，创建新的记忆 C。C 记录这次合并所使用的 A、B ## 沿用的规范与本次调整 Scope 归属和组织沿用 RFC 1345，Source 处理沿用 RFC 0019，身份、版本和证据沿用 RFC 1549。 -多条记忆成为独立 Artifact，不意味着每条记忆分别消费 Source；处理进度仍由所属 Scope 的抽取流程维护。 -本提案替代 RFC 0014、0019 中集合与 entry 分别维护版本的模型，并取消 RFC 1345 中每个 Scope 只有一个活跃 -Memory 集合的要求。 +本提案替代 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 记忆总量上限， 也不新增历史版本到期删除策略。旧配置的处理在发布兼容说明中明确。 @@ -153,7 +158,12 @@ RFC 1718 针对完整 manifest 设置的集合容量限制不适用于新 Family 使用宽表或独立投影；全文、向量召回不使用业务表 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 的精确版本引用。它采用有界召回；抽取则需要 +完整枚举达到阈值的相关记忆。 + +抽取过程中，单批大小用于控制每次读取和模型输入，不得截断达到阈值的总结果集。处理尚未完成时，不能将其报告为“没有新记忆”。 具体阈值、分批方式和索引选择由实现设计确定。 合并、恢复及撤销涉及的记忆状态、关系和当前检索数据必须一起生效。不能出现原记忆已经恢复，而合并结果仍在