Skip to content

docs(rfc): introduce atomic memory as independent artifacts - #1809

Merged
Teingi merged 2 commits into
oceanbase:masterfrom
frf12:codex/automatic-memory-rfc
Oct 9, 2026
Merged

Teingi merged 2 commits into
oceanbase:masterfrom
frf12:codex/automatic-memory-rfc

Conversation

@frf12

@frf12 frf12 commented Sep 30, 2026 •

Copy link
Copy Markdown
Member

Which issue or RFC does this PR close?

RFC #1809 proposal; no issue is closed by this documentation PR.

Depends on #1803 for the common search contract and #1771 for offline migration. Amends RFCs 0014, 0019, 1345, 1652, and 1718; related contracts include RFCs 1417 and 1549.

Rationale for this change

Legacy Memory versions a Scope-level collection containing a full manifest of entry-version references. Changing one entry stores another complete manifest and updates the shared collection head. Built-in extraction supplies all active entries to the model as memories accumulate.

Independent memory Artifacts align identity and history with Scope. Retrieval before reconciliation reduces unrelated model input, while explicit merge and restoration behavior lets users correct automatic decisions.

What changes are included in this PR?

  • English and Chinese RFCs for the atomic-memory Family: one independently maintained memory per Artifact, with its own identity, revisions, evidence, and state.
  • Candidate generation followed by retrieval of related active memories in the same Scope that the processing identity may both read and write. All results meeting the relevance threshold enter comparison; batching does not impose a fixed total cutoff. Deployments without vector search still retrieve related memories.
  • Automatic creation, revision, and merging without per-operation approval or category preauthorization. The proposal explicitly changes RFC 1652's merge approval requirement for Atomic Memory.
  • Merges create a new Artifact and freeze the inputs. Four states distinguish active, forgotten, merged, and retired memories.
  • Content correction, historical revision restoration, and merge undo have distinct effects. One request can restore a merged input through successive merges; retired results remain readable but cannot be reactivated.
  • Separate restoration preview and execution, with optional preview checks. Direct callers need no preview, while permission, current-state, and concurrency checks always apply.
  • Search follows docs(rfc): define artifact search projections and join-free retrieval #1803. Offline migration follows docs(rfc): define unified versioned database migrations #1771, with compatibility adapters for supported old API contracts and explicit release arrangements for deprecation and cleanup.
  • Open questions cover correction context captured by Agent integrations and adoption of the four states by other Artifact families.

Are there any user-facing changes?

Documentation only. The proposal describes a future breaking change to Memory identities and storage, with an offline upgrade. Compatible old memory APIs adapt requests and responses to the new Family while retaining their contract. Incompatible operations require declared replacements and deprecation/removal arrangements under #1771.

The RFC specifies behavior, compatibility, and tradeoffs. Table schemas, SQL, API parameters, and locking implementation remain in the separate implementation design.

How was this change tested?

  • Checked relative Markdown links, the nine RFC sections, literal UTF-8 text, and whitespace.
  • Reviewed English and Chinese content for consistency with the agreed behavior.
  • git diff --cached --check and repository commit hooks.
  • Verified that the PR contains one commit and only the two RFC documents.

No application tests or database benchmarks were run for this documentation-only change.

AI usage statement

Prepared with OpenAI Codex (GPT-6), including document drafting and source-grounded review, under maintainer direction.

@frf12
frf12 force-pushed the codex/automatic-memory-rfc branch 5 times, most recently from 620da34 to ef7ce28 Compare October 4, 2026 19:48
@frf12 frf12 changed the title docs(rfc): introduce automatic memory as independent artifacts docs(rfc): introduce atomic memory as independent artifacts Oct 4, 2026
Comment thread docs/en/rfcs/1809-atomic-memory.md Outdated
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] 声明取消 RFC 1345 的约束,但未覆盖 1345 明确要求承接 RFC 定义的项

此处写「removes RFC 1345's requirement for one active Memory collection per Scope」。1345 的原文是「One Scope has one active Memory progression line」(docs/en/rfcs/1345_scope_organization_and_agent_integration.md:469),且位于 Future work 的「Several Memory Artifacts in one Scope」一节;该节紧接着规定:「A later RFC supporting several Memory progression lines in one Scope must define a stable Memory binding, Source assignment, per-Memory cursors, Prepare Context selection, and concurrency conflicts」(1345:474-475)。

本 RFC 正是那个承接者。已覆盖 Source assignment(「the Scope's extraction flow still owns processing progress」)与并发(「Search and concurrency」一节),但全文(英文版与中文版均)没有出现 Prepare Context / cursor / recall 任何一词。多记忆 Artifact 之后,「Prepare Context 注入哪些记忆、按什么边界截断」恰是 1345 点名要定义的项之一。

建议:在「Search and concurrency」或「Unresolved questions」显式写出对该项的处置(即使结论是「由 #1803 的检索契约覆盖」也应写明);并考虑把「Memory collection」与 1345 的「Memory progression line」用语对齐,否则读者对照原文会找不到依据。中文版此处表述一致(docs/zh/rfcs/1809-atomic-memory.md:135-136),需同步修改。

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Rechecked at 33f5949e (the branch moved from ef7ce289): both points still stand, and GitHub has already re-anchored this thread to line 164, so no new thread is needed.

Terminology: line 164 still reads removes RFC 1345's requirement for one active Memory collection per Scope, while RFC 1345's actual constraint is One Scope has one active Memory progression line (docs/en/rfcs/1345_scope_organization_and_agent_integration.md:469). grep -ci collection over 1345 returns 0 — the word this RFC cancels does not appear in the RFC it cites. A reader checking the reference cannot match the two.

Uncovered item: 1345:474-475 requires a later RFC to define five things — a stable Memory binding, Source assignment, per-Memory cursors, Prepare Context selection, and concurrency conflicts. This RFC covers Source assignment and concurrency, but grep -ciE "prepare context|per-Memory cursor" over both 1809-atomic-memory.md files returns 0. Prepare Context selection is therefore cancelled-by-omission rather than explicitly disposed of, even though prepared_context.py already carries truncation and omission rules (_MIN_TRUNCATED_CONTENT_BYTES, dropped_below_min_bytes, dropped_no_fitting_truncation) whose meaning changes once a Scope can hold several Memory Artifacts.

Narrowing the ask: an explicit sentence in "Retrieval and concurrency" or "Unresolved questions" saying how this item is handled — even "covered by RFC #1803's retrieval contract" would close it. Same for the wording: align to progression line (推进线), or state that collection here names what 1345 calls a progression line.

Also worth noting while this is open: this branch is 11 commits behind master, and the RFC's stated prerequisites (#1771 at :9, :197, :265, :276, and #1803 at :23) are both still unmerged open PRs, so the file-path-vs-PR-link convention is currently correct but time-limited.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarified in 9be690e6, in both languages. The text now distinguishes RFC 1345's single Memory progression line/head from independent Atomic Memory heads. The Scope continues to own one Source journal and extraction progress; individual memories do not consume Source independently or gain per-memory cursors.

Prepare Context explicitly retains the existing Scope-selection and authorization rules and references RFCs 0028 and 1489 for selection, ordering, limits, byte budgets, and exact citations. Complete threshold-based enumeration is explicitly limited to extraction; RFC 1803 remains the search-projection contract.

@frf12
frf12 force-pushed the codex/automatic-memory-rfc branch from ef7ce28 to 33f5949 Compare October 5, 2026 21:47

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] unresolved_conflict is cancelled here, but superseded is left without a mapping to the new four states

This paragraph withdraws one 1652 requirement and then describes merging:

RFC 1652's ... 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.

1652's projected validity has four values — current | inactive | superseded | unresolved_conflict (docs/en/rfcs/1652_memory_quality_and_lifecycle.md:166) — and superseded carries real semantics there: lineage: validity_reason, successor identity when known (:167).

unresolved_conflict is now explicitly withdrawn, but superseded has no disposition anywhere in this RFC. grep -ci superseded over 1809-atomic-memory.md returns 0. Meanwhile the four states defined at :106-111 line up closely with it: Merged (a new result exists and the inputs are frozen) is exactly what superseded describes, and Forgotten is the plausible target for inactive.

The mapping is not derivable by a reader either, because it does not exist yet on the implementation side: MemoryEntryState is Literal["active", "inactive"] (src/powercontext/builtin/artifacts/memory/models.py:30), and superseded appears nowhere under builtin/artifacts/memory/ or builtin/persistence/. So a migration from 1652's four values to this RFC's four states has no written rule to follow, and one entry can satisfy both an inactive and a superseded rule at once (1652:262-263) with nothing saying which wins.

Suggested direction: state the mapping explicitly near this paragraph — superseded → Merged, inactive → Forgotten — and say whether 1652's projected validity enum changes as a result. One sentence here removes the ambiguity for whoever implements the family split.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Clarified in 9be690e6. RFC 1652's validity projection is keyed to an exact entry version, whereas these four states describe an Artifact's lifecycle. An ordinary A_v1→A_v2 revision leaves A active and makes v1 historical; A+B→C puts the input identities A and B into Merged.

A blanket superseded → Merged mapping would incorrectly freeze A after an ordinary revision, so the RFC now states this distinction rather than prescribing that mapping. It also explicitly retains evidence and successor references through Artifact revisions, lineage, and merge relationships.

@Teingi
Teingi merged commit e8e9344 into oceanbase:master Oct 9, 2026
26 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants