From 578e858bc7bad65d2a9b0641c217d0eadb7f8b4c Mon Sep 17 00:00:00 2001 From: "lusendong.6789" Date: Mon, 16 Nov 2026 23:52:04 +0800 Subject: [PATCH 1/4] docs(rfc): propose sparse working memory at context compaction Signed-off-by: lusendong.6789 --- docs/architecture/rfcs/README.md | 9 + docs/architecture/rfcs/STATUS.md | 3 +- docs/architecture/rfcs/STATUS.zh-CN.md | 3 +- .../sparse-compaction-working-memory-v0.md | 229 ++++++++++++++++++ ...arse-compaction-working-memory-v0.zh-CN.md | 229 ++++++++++++++++++ 5 files changed, 471 insertions(+), 2 deletions(-) create mode 100644 docs/architecture/rfcs/sparse-compaction-working-memory-v0.md create mode 100644 docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index 7fba976dd8..0ef9a53ebc 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -210,6 +210,15 @@ Paired diffs do not certify translation accuracy. source-bound historical views and optional provider extensions. Source retention, original readback, actual adoption and complete-cost evidence remain unqualified; no runtime, default or experiment change. +- [Sparse Working Memory at Context Compaction v0](sparse-compaction-working-memory-v0.md) + ([中文版](sparse-compaction-working-memory-v0.zh-CN.md)) + - **Delivery on `main`:** Proposal only; no runtime or default change. + - **Current boundary:** A bounded T02 companion to history working sets: + consolidate source-bound working memory at compaction and retain or restore + a short recognizable structure. Compare deterministic sparse selection, + optional semantic consolidation and the current host path on accepted task + outcomes and complete costs. Host retention, expansion, utility and product + qualification remain open; no model experiment starts with this RFC. - [TypeScript Control-Plane Migration v0](typescript-control-plane-migration-v0.md) ([中文版](typescript-control-plane-migration-v0.zh-CN.md)) - **Delivery on `main`:** Substantially implemented; active migration. diff --git a/docs/architecture/rfcs/STATUS.md b/docs/architecture/rfcs/STATUS.md index 01c954c37f..04ee67753b 100644 --- a/docs/architecture/rfcs/STATUS.md +++ b/docs/architecture/rfcs/STATUS.md @@ -18,7 +18,7 @@ appendix may keep dated history, but no dated log heading may precede it. [中文版](STATUS.zh-CN.md) is the semantic mirror of this file. -## Accepted (52) +## Accepted (53) | RFC | Header status | Supersedes / closes | Ledger | | --- | --- | --- | --- | @@ -72,6 +72,7 @@ appendix may keep dated history, but no dated log heading may precede it. | [RFC: Shared Goal Alignment and Governed Amendment Protocol (v0)](shared-goal-alignment-and-governed-amendment-v0.md) | Accepted | none | [2 entries](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC: LoopX Shared Control-Plane Authority and Pluggable State Providers (v0)](shared-goal-authority-state-provider-v0.md) | Accepted | none | [24 entries](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | Accepted | none | — | +| [RFC: Sparse Working Memory at Context Compaction (v0)](sparse-compaction-working-memory-v0.md) | Accepted | none | — | | [RFC: Joint Target, Yardstick and Stride Decisions (v0)](target-yardstick-stride-decisions-v0.md) | Accepted | none | — | | [RFC: TypeScript Control-Plane Migration Direction v0](typescript-control-plane-migration-v0.md) | Accepted | none | [27 entries](ledger/typescript-control-plane-migration-v0/) | diff --git a/docs/architecture/rfcs/STATUS.zh-CN.md b/docs/architecture/rfcs/STATUS.zh-CN.md index a36c022ee0..17cd1d3f15 100644 --- a/docs/architecture/rfcs/STATUS.zh-CN.md +++ b/docs/architecture/rfcs/STATUS.zh-CN.md @@ -15,7 +15,7 @@ [English](STATUS.md) 与本文互为语义镜像。 -## 已接受 (52) +## 已接受 (53) | RFC | 头部状态 | 替代 / 关闭 | Ledger | | --- | --- | --- | --- | @@ -69,6 +69,7 @@ | [RFC:共享 Goal 对齐与受治理 Amendment 协议(v0)](shared-goal-alignment-and-governed-amendment-v0.zh-CN.md) | 已接受 | 无 | [2 条](ledger/shared-goal-alignment-and-governed-amendment-v0/) | | [RFC:LoopX 共享控制面权威与可插拔状态 Provider(v0)](shared-goal-authority-state-provider-v0.zh-CN.md) | 已接受 | 无 | [24 条](ledger/shared-goal-authority-state-provider-v0/) | | [RFC: Single-Owner Local Daemon (v0)](single-owner-local-daemon-v0.md) | 已接受 | none | — | +| [RFC:上下文压缩时的稀疏工作记忆(v0)](sparse-compaction-working-memory-v0.zh-CN.md) | 已接受 | 无 | — | | [RFC:Target、Yardstick 与 Stride 联合决策(v0)](target-yardstick-stride-decisions-v0.zh-CN.md) | 已接受 | none | — | | [RFC:LoopX 控制面 TypeScript 渐进迁移方向 v0](typescript-control-plane-migration-v0.zh-CN.md) | 已接受 | 无 | [27 条](ledger/typescript-control-plane-migration-v0/) | diff --git a/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md new file mode 100644 index 0000000000..ed29876140 --- /dev/null +++ b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md @@ -0,0 +1,229 @@ +# RFC: Sparse Working Memory at Context Compaction (v0) + +- **RFC status:** Accepted (upon merge) +- **Supersedes / closes:** none +- **Delivery maturity:** Proposal +- **Authors / owners:** AI-assisted proposal; context presentation, native-host, history-working-set and T02 maintainers. +- **Created:** 2026-11-16 +- **Last normative revision:** 2026-11-16 +- **Implementation baseline:** [`0c3b2fd21800a536ccaa61bad85c4dd8257aad8e`](https://github.com/loopx-project/loopx/commit/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e). +- **Related contracts:** [History working sets](history-working-set-context-policy-v0.md), [unified work contract](controller-executor-unified-contract-v0.md), [explicit continuation](cross-session-memory-substrate-v0.md), [required work context](../../reference/required-work-context.md), [T02 research](long-horizon-harness-benchmark-research-program-v0.md). +- **Language mirror:** [中文版 — semantic mirror](sparse-compaction-working-memory-v0.zh-CN.md). + +## Document map and maintenance contract + +Sections 1–12 define this bounded proposal; §4 records audited code facts. The appendices contain sources and decision attribution. Accepted status takes effect only upon merge and accepts a design basis, not implemented behavior or measured benefit. This PR ships documentation only. Future execution records follow the [ledger contract](ledger/README.md); maintain both language mirrors together. + +**Request versus proposal:** The requester asks to retain LoopX-recognizable structured information during context compaction, expects a sparser representation, identifies **FSoft-AI4Code/CodeWiki** as a reference, and raises Manus's use of compression as memory as a research lead. These are the requested direction, not approval of the schema, integration or claimed improvement below. All concrete design choices and experimental targets in this RFC are AI proposals pending review. “Compaction” here means conversation-context reduction, not model-weight compression. + +## 1. Decision summary + +Investigate **compaction as a working-memory consolidation point**: retain a small, versioned, source-bound representation of decision-relevant knowledge; keep originals and detail outside the active context; let LoopX recognize and expand that representation after compaction. + +Recommend a two-part design within existing owners: + +1. A persisted working-memory view contains sourced findings, rejected approaches, decision rationale and unresolved questions that are useful to continued work. It is derived material, not another Goal/Todo or permission ledger. +2. A short model-facing structure identifies that view and exposes its current decision frontier. The host retains it during compaction where a qualified integration permits, or the existing recovery adapter restores it afterward. An ordinary summary that mentions LoopX does not qualify as a recognized structure. + +Begin with one local native-host profile and existing capture/read infrastructure. The feature defaults off. First compare deterministic selection with current delivery; add semantic consolidation only if it yields additional benefit. This RFC starts no paid runs, changes no runtime default, approves no source deletion and promises no cost reduction. + +## 2. Problem and motivation + +Current durable work state answers what is required and who owns it. A conversation also accumulates why an approach failed, which observation changed a hypothesis, and which apparent success still lacks verification. Some of that knowledge may not yet have an appropriate durable source. Losing it can change the next decision even when Todo state survives. + +Synthetic example: R1 failed cache isolation; an R2 fix passes the targeted check but rollback remains unverified. After compaction, “cache fix complete” loses both a rejected approach and unfinished acceptance. Replaying the whole investigation preserves more evidence but adds input and recovery cost. The desired memory is the discriminating conclusion and its exact evidence, not a shorter activity log. + +**Sparser** means fewer always-visible facts and fewer repeated canonical bodies. It does not mean less recoverable source coverage or silently weaker obligations. A smaller initial block that causes repeated full reads can be worse. + +### Invariants + +- Preserve complete current intent, requirements, stops and original execution/settlement identity through their existing owners and reading contracts. Unrecorded direct-user corrections must be captured as exact sources before their surrounding context is eligible for removal. +- Historical observations, model interpretations, accepted decisions and current authority remain distinguishable. A memory never grants permission, claims a Todo, passes acceptance or refreshes an old fact. +- Preserve negative evidence and unresolved distinctions that affect the next decision. No keyword-based inference of completion, rejection, trust or authority. +- A reference establishes neither reading nor comprehension, model retention or a Delta baseline. Missing essential facts retain existing dependent-action stops; independent authorized work may continue. +- An optimization can fall back; it cannot erase a missing required source or change an existing work/settlement operation. + +## 3. Scope and reference designs + +Scope is Goal-scoped working memory across context compactions on one machine. Cross-session expansion is qualified only within a demonstrated retention profile. Global user memory, automatic long-term experience promotion, cross-Goal recall, full-transcript ingestion, new schedulers and a new memory database are outside v0. + +| Primary reference | Verified public description | What to borrow / boundary | +| --- | --- | --- | +| [FSoft-AI4Code/CodeWiki README][CW1], pinned at `7fcf9354` | Dependency graph → module hierarchy → module pages and overview | Use relationships and layered navigation rather than a chronological transcript. Its repository-documentation design does not prove conversation-compaction benefit. | +| [CodeWiki incremental updates][CW2], same revision | Saved graph/tree/build metadata; component changes drive affected-page updates | Bind memories to sources and update affected views. Reuse LoopX's work/evidence relationships; do not introduce a code dependency analyzer or copy upstream thresholds. | +| [Manus context-engineering article][M1], published 2025-07-18 | File-based externalized memory and recoverable compression retaining locators; task recitation and failure evidence | Borrow externalization, retrieval and useful failures. This source does **not** establish a fixed structured-memory schema or that every compaction performs a memory write. That specific claim remains unverified. | + +This proposal applies CodeWiki's navigation idea to changing work knowledge, rather than generating a repository wiki at every compaction. The comparison is a design inference, not an existing integration. + +## 4. Current-system contract: audited baseline + +At the implementation baseline, source inspection confirms: + +| Existing owner | Observed behavior | Remaining gap for this proposal | +| --- | --- | --- | +| [`native_context_lifecycle.ts`][LX1], `updateNativeContextLifecycle()` | Pre/PostCompact invalidates continuity evidence idempotently; SessionStart/resume and verified selected reads have separate handling | Epoch invalidation does not itself consolidate semantic working memory. | +| [`codex_context.py`][LX2], `codex_context_hook()` and `_context_continuation_instructions()` | Journals exact recovery refs; SessionStart can deliver recovery instructions; baseline loss does not invalidate the admitted Turn or require full rereading | No fixed sparse working-memory object is produced by these functions. Host-generated summary retention is not proved by hook output. | +| [`codex_context_history.py`][LX3] | Qualifies supported native replay metadata and observed read intervals; rejects unsupported/incomplete histories | A recognized memory object cannot replace these checks or extend the host qualification list. | +| [`progressive_context.ts`][LX4] and [`context_delivery.ts`][LX5] | Deterministic selected views and exact, source-bound full/Delta delivery, including saved-file continuity | A smaller representation is already possible; compare against this path, not an invented always-full baseline. Exact delivery does not prove summary fidelity. | +| [History-working-set RFC](history-working-set-context-policy-v0.md), §§5/9/11 | Accepted design for source-bound historical views, retention, optional generation and full-cost controls; Proposal maturity | Reuse its owners and gates. This RFC narrows the consolidation trigger and post-compaction representation; it does not replace that RFC or complete its milestones. | + +These are static code/design findings, not installed-host, final-model-input or task-effectiveness measurements. The current-source audit and [related open work](https://github.com/loopx-project/loopx/pull/8266) must be refreshed before implementation; candidate changes are not main facts. + +## 5. Proposed architecture + +```mermaid +flowchart LR + A["Existing work facts and exact evidence"] --> B["Existing capture / artifact owner"] + B --> C["Bounded working-memory selection"] + C --> D["Persisted sourced memory view"] + D --> E["Short recognizable structure"] + E --> F["Qualified host compaction / recovery"] + F --> G["Next decision and task outcome"] + G -->|"Expand necessary facts"| B +``` + +### 5.1 Ownership and representation + +The shared TypeScript presentation boundary owns selection and validation. Existing capture/artifact IO owns persistence and exact readers; native-host adapters own event translation and delivery. Goal, request, Todo, claim/lease, admission, authorization and settlement retain their current owners. Placement is an internal extension of existing context delivery: **no new capability id, provider id or extension distribution in v0**. Later semantic generation reuses the history-working-set provider boundary rather than adding model IO to synchronous hooks. + +The persisted memory view reuses existing source identities, revisions, scope and trust. Bind it to the original Goal/Agent, execution/capture, session/profile, observed compaction generation and schema/producer version. Store that binding once in the capture metadata rather than repeating all fields in the short block. A digest proves byte identity, not authorship or authorization; the reader must resolve an owner-issued reference under current access checks. + +Retain only useful sourced increments: a conclusion plus its applicability basis, why a rejected attempt should not be retried unchanged, a changed assumption and contrary evidence, or an unresolved distinction. Canonical goals, Todo bodies, permissions and completed tool transcripts are referenced through their existing sources. A current decision is not inferred from a remembered historical one. Where the source has no typed classification, retain it verbatim or leave it in the ordinary context; do not classify prose as authority. + +Illustrative model-facing shape; **not a shipped schema, URI scheme or CLI**: + +```json +{ + "schema_version": "loopx_compaction_memory_v0", + "memory_ref": "example-memory-17", + "focus": "Verify R2 cache isolation; rollback is still unverified.", + "frontier": [ + {"ref": "example-finding-4", "note": "R1 failed isolation; retain the failing condition."}, + {"ref": "example-question-2", "note": "Does R2 survive rollback?"} + ], + "needed_reads": ["example-original-capture:selected_todo"] +} +``` + +| Part | Why it exists | +| --- | --- | +| `schema_version`, `memory_ref` | Deterministic recognition and owner-validated expansion; a user/tool-supplied lookalike is untrusted content. | +| `focus`, `frontier` | Enough meaning to choose the next useful read or decision. Notes are advisory; original source refs retain provenance and distinctions. | +| `needed_reads` | Discover pending dependencies from the original contract. This is a view, not a replacement list that can silently clear or narrow that contract. | + +The five top-level fields are a starting proposal, not a field-count target. Empty optional arrays can be omitted under the eventual versioned schema. Required immediate controls stay in the existing mandatory delivery. Preserve any obligation not safely representable under that contract; if the candidate exceeds budget, keep the existing view instead of clipping it. Do not reintroduce full Goal/Todo/authority snapshots merely to make the memory “structured.” + +### 5.2 Compaction lifecycle + +1. **Prepare:** Resolve existing sources and exact coverage while available. Consolidate only observed material; record unread/partial coverage. Persist any otherwise-unrecorded user correction through the owning source adapter, preserving trust and ordering. +2. **Publish:** Save recoverable originals, then the bound derived memory, then its selectable ref. Reuse original capture/operation identity for retries; a partial write cannot advertise a valid memory. Memory publication settles no work and spends no work quota by itself; generation costs still count. +3. **Compact:** Where a supported host exposes a qualified preservation mechanism, request verbatim retention of the short structure. A pre-compaction hook alone does not establish the ability to replace the host's compactor or customize its output. Otherwise use the existing post-compaction recovery boundary to restore the same persisted representation. +4. **Recognize and resume:** Parse only the supported version and validate the reference against its owner and expected scope. Resolve the original Turn/capture rather than silently selecting a newer one. Recheck current authority only when the existing action contract requires it; compaction alone neither readmits work nor forces a full read. Expand missing decision-relevant detail before dependent effects. +5. **Revise:** Update only affected sourced findings/frontier entries. Preserve supersession and contrary evidence in the underlying sources; do not recursively summarize yesterday's summary without leaf coverage. Repeated compactions must not grow the block into a second journal. + +Repeated Pre/PostCompact and SessionStart events map to one observed boundary. Missing events, reordered events, abrupt context loss or invalid output fall back through existing recovery. A parseable object in a disk transcript proves neither that the host replayed it nor that the model saw it. Record persistence, host submission, observed model-visible delivery, decision adoption and accepted outcome separately; mark unobservable layers unknown. + +### 5.3 Extraction and sparsity policy + +First use deterministic selection of existing typed findings and exact references, without an extra model call. This establishes what selection and structure alone buy. Where relevant knowledge exists only in conversation, a later bounded model/host-compactor contribution can propose sourced memory, with exact input coverage and explicit observation-versus-interpretation attribution. It cannot manufacture a canonical decision or edit authorization. + +Do not call another LLM synchronously from a compaction hook. Reuse a verified existing preparation/execution boundary or the host compactor only after its actual contract is qualified. If no legal source or execution boundary exists, that semantic mode remains unavailable and the original context path continues. Critical missing meaning is not repaired by pretending an empty deterministic view is sufficient. + +## 6. Alternatives and trade-offs + +| Alternative | Benefit | Cost / recommendation | +| --- | --- | --- | +| Existing native summary + current Progressive/Delta | No new memory lifecycle | Required baseline; may already be sufficient. | +| Full structured snapshot at every compaction | Easy schema recognition | Repeats state, costs input and can confuse stale snapshots with authority; not the preferred first experiment. | +| Sparse refs and deterministic frontier | Smallest new mechanism; no extra model generation | May require extra reads or miss conversational knowledge. Recommended first treatment, not a proven winner. | +| Sparse semantic working memory + originals | Can retain causal findings absent from task records | Extraction/drift, coverage, cost and host-integration risks; qualify only for incremental value over deterministic selection. | +| Generate a complete CodeWiki-style wiki | Rich long-lived repository navigation | Different scope and substantially more lifecycle/dependency work; reuse navigation ideas without importing the product. | + +## 7. Safety, privacy and compatibility + +Default-off means no new extraction, model calls, memory writes, parser-dependent continuation or extra required reads on existing paths. Existing raw machine consumers and historical capture readers keep their formats. The proposed schema is a new derived view, not removal of any stored field; register shared vocabulary and verify old/new readers before implementation. Unknown versions or fields cannot be silently treated as equivalent or eligible for deletion. + +Keep private conversation and sources in their original access scope. No raw reasoning traces, secrets or new cross-Goal sharing; equal hashes do not authorize reuse. Retrieved text remains data. Resolve references through existing readers, not arbitrary file paths or shell commands embedded in memory. Revocation/deletion/source loss invalidates expansion and any affected derived view; a retained summary cannot bypass that boundary. + +An unavailable optional memory falls back to ordinary delivery. An unavailable required original blocks only its dependent action under the existing contract. Rollback, stale-Goal changes and same-source/different-Agent cases must not create new admission, ownership, lease, accounting or settlement authority. + +## 8. Migration and rollback + +Opt in one explicitly qualified local host/profile without rewriting existing sources. During shadow inspection, persist the candidate but do not reduce model input; that phase validates bindings, not effectiveness. Then replace eligible active-context material with the short representation on that profile, retaining required controls and exact expansion. + +Disablement stops new consolidation and adoption; later input uses existing delivery. Already promised references remain readable for their declared lifecycle, subject to explicit deletion/revocation. Retention must survive compaction, process restart and normal cleanup for every claimed scope; current temporary captures are not automatically durable memory. Extend the existing retention owner if necessary. No destructive migration or source GC change is authorized here. + +## 9. Validation and acceptance + +### 9.1 Conformance and real-path evidence + +| ID | Scenario | Required result / boundary | +| --- | --- | --- | +| A1 | Real supported host compacts, then resumes through the production entry | Supported structure is validated and delivered or restored; show actual available input evidence, not just hook stdout or a saved file. | +| A2 | Two further compactions; interruption between source save and publication; duplicate/reordered events | Same original work/settlement identity, bounded view growth, recoverable publication and no repeated completed effect or debit. | +| A3 | Only revision, failed condition, unresolved check or user correction differs | Continued decisions preserve the distinction; ending an attempt is not passing acceptance. Originals and decisive tail evidence expand exactly. | +| A4 | Source missing/changed, access revoked, forged ref, foreign Goal/Agent or unknown schema | Reject affected reuse; ordinary fallback or existing dependent-action stop, with no authority escalation. | +| A5 | Hook omitted, object truncated/rewritten or host preservation unsupported | Existing recovery remains usable; no claim of structure retention or model continuity from unobserved events. | +| A6 | Off, no-benefit and mixed-version paths | Feature-off parity; no new model IO when off; preserve unknown material and existing machine/capture contracts. | +| A7 | Declared restart/cleanup scope | Promised sources remain resolvable; invalidate visibly when an explicit deletion/revocation supersedes retention. | +| A8 | Packaged enable → compact → inspect source/failure → disable | Existing settings and readback share the typed owner; qualify affected frontend/Lark/CLI entrypoints before product promotion. A single-host prototype is partial delivery. | + +Structural conformance cannot prove semantic usefulness. No A-row is passed by this documentation PR. + +### 9.2 Does it actually help? + +Reuse [T02 / #4391](https://github.com/loopx-project/loopx/issues/4391) and the [history-working-set measurement contract](history-working-set-context-policy-v0.md#92-controls-and-complete-cost-accounting). Freeze controls, task sample, budgets, independent acceptance and decision thresholds before observing outcomes: + +- **B0:** Best current legal host path, including qualified Progressive/Delta and its ordinary native summary. +- **T1:** Same tasks and compaction points, with deterministic sparse structure and exact original refs; no additional semantic generation. +- **T2, conditional:** Same sparse budget plus sourced semantic consolidation, to test memory extraction's incremental value. Do not run it merely to add an experimental arm. + +Use complete continuation episodes as units: include rejected attempts, late corrections, revision changes, long-tail evidence, multiple compactions and unavailable sources. Match model/tools/environment and **total** resource limits; count preparation and readback against the same budget. Repeated calls/compactions in one episode are not independent samples. Predefine paired repetitions and a sample size appropriate to the claim; a small feasibility pilot cannot establish general superiority. + +Measure independently accepted task outcomes and critical-constraint omissions first, then repeated failed approaches, human intervention, post-compaction recovery time, actual/estimated input at each observable layer, all model generation and cached/uncached usage, detail reads/retries, wall time and retained disk. Preserve every failure, fallback, no-benefit episode and budget overrun; invisible provider/model layers remain unknown. + +Promote only with predeclared quality non-inferiority and material **complete-cost** improvement, or better accepted outcomes at comparable complete cost. A smaller bootstrap block, parser pass, retrieval relevance or a memory file is insufficient. If readback or cache invalidation offsets savings, retain B0 and report the negative result. This RFC contains no measured effect size or frozen numerical promotion threshold. + +## 10. Operational cost and product contract + +Expected first scale is one local Goal/session with many tool observations and repeated compactions; no fleet-scale demand is assumed. Deterministic mode adds bounded view selection, capture metadata and local reads, with no new model dependency. Semantic mode adds generation/input/output, retries and possible cache disruption. Storage follows retained source coverage, not just the small block; quantify lifecycle and disk growth before making long-term-memory claims. + +Keep the stable prefix stable and update only changed view content. Charge extra extraction, regeneration and expansion to the complete task. Break-even depends on later input actually avoided after preparation, reads and cache effects, not an upstream compression percentage. Existing source/capture failure handling and usage observation remain the owners; no resident worker, graph database or CodeWiki install is needed. + +Expose effective enablement and supported host, current source binding/coverage, restore/fallback reason, available originals and measured cost through existing context settings/readback. Users can inspect, disable or remove memory under existing data controls. Do not expose raw memory text or private locators in public telemetry. Enabling this optional path does not need per-compaction confirmation; existing scope and paid-execution authority still apply. + +## 11. Normative delivery plan + +| Milestone | Reviewable outcome | Entry / decisive exit evidence | Rollback | +| --- | --- | --- | --- | +| M0: Review | Agreed compaction-memory hypothesis, owner split and bounded profile | Current-source audit; D1–D3 decisions at their dependent boundaries; design acceptance does not start execution | Documentation only | +| M1: One real compaction path | Deterministic sparse view survives or is restored and expands exact originals on one supported host | Qualified host contract and retention; A1–A7 plus observed final delivery and original-identity recovery | Existing host/recovery delivery | +| M2: Utility comparison | B0/T1 outcome and full-cost comparison; T2 only for demonstrated missing semantic knowledge | Frozen sample/budgets/thresholds; §9.2 evidence, including negative results | Keep B0 or T1; no forced promotion | +| M3: Product qualification | Enablement, inspection, failure/recovery and disablement through affected surfaces | A8, mixed-version/off parity; separately qualify broader hosts and retention | Disable optional view; preserve valid refs | + +First implementation candidates are narrow changes to `quota/progressive_context.ts` and `native_context_lifecycle.ts` for view/lifecycle semantics; `turn_driver/decision_capture.py`, `codex_context.py` and its history adapter for capture and host IO; existing context configuration/readback and their tests. Confirm the actual first caller before editing; reuse current source/reader contracts rather than a second memory service. No implementation or migration is part of this PR. + +## 12. Open decisions + +| ID | Options and AI recommendation | Owner / decision point | +| --- | --- | --- | +| D1 | Native-compactor structured output versus persisted view with post-compaction restoration: prefer existing recovery integration first; qualify actual host ability to preserve a structure before claiming native retention | Native-host / context maintainers, before M1 | +| D2 | Which findings, source coverage, retention scope and sparse budget: start with typed investigation results and unresolved distinctions on one Goal; exact unrecorded corrections remain mandatory. Choose schema/limits from measured workload, not field-count aesthetics | Context / history / source owners, before M1 | +| D3 | Whether semantic extraction is needed and when it runs: deterministic T1 first; reuse a bounded verified execution boundary for T2 if conversation-only knowledge makes T1 insufficient | History / runtime owners, before semantic implementation or runs | +| D4 | Task sample, non-inferiority margin and material benefit: predeclare complete-cost and outcome criteria; do not import CodeWiki/Manus numbers or infer success from fewer bytes | T02 / evaluation owners, before any model experiment | + +## Appendix A: Evidence and decision record + +- Static audit: named LoopX sources at `0c3b2fd21800`; CodeWiki README/update guide at `7fcf9354f70a5468bc739d849055f8cbab9d46aa`; Manus's dated primary article. This does not certify current proprietary Manus internals or upstream implementation quality. +- Request-confirmed direction: recognizable, sparser structure at compaction; AI4Code reference. Manus's exact compression-time memory-write behavior remains a lead, not a verified premise. +- Proposed, unapproved: schema, field selection, host profile, lifecycle details, thresholds and implementation sequence. No runtime/default change, paid/model experiment, measured saving, host-install acceptance or product promotion has been performed. +- No RFC is superseded, stored field removed or existing acceptance milestone closed. Future dated execution evidence belongs in the ledger only after real work exists. + +[CW1]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/README.md +[CW2]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/guides/incremental-updates.md +[M1]: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus +[LX1]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/native_context_lifecycle.ts +[LX2]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context.py +[LX3]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context_history.py +[LX4]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/progressive_context.ts +[LX5]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/context_delivery.ts diff --git a/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md new file mode 100644 index 0000000000..79768ab305 --- /dev/null +++ b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md @@ -0,0 +1,229 @@ +# RFC:上下文压缩时的稀疏工作记忆(v0) + +- **RFC status:** Accepted (upon merge) +- **替代 / 关闭:** 无 +- **Delivery maturity:** Proposal +- **作者 / 负责人:** AI 辅助提案;上下文呈现、原生宿主、历史工作集与 T02 维护者。 +- **创建日期:** 2026-11-16 +- **最近规范修订:** 2026-11-16 +- **实现基线:** [`0c3b2fd21800a536ccaa61bad85c4dd8257aad8e`](https://github.com/loopx-project/loopx/commit/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e)。 +- **相关契约:** [历史工作集](history-working-set-context-policy-v0.zh-CN.md)、[统一工作契约](controller-executor-unified-contract-v0.zh-CN.md)、[显式接续](cross-session-memory-substrate-v0.zh-CN.md)、[必需工作上下文](../../reference/required-work-context.md)、[T02 研究](long-horizon-harness-benchmark-research-program-v0.zh-CN.md)。 +- **语言镜像:** [English(语义镜像)](sparse-compaction-working-memory-v0.md)。 + +## 文档地图与维护契约 + +第 1–12 节定义本次有界提案;第 4 节记录已核对的代码事实。附录记录来源与观点归属。Accepted 仅在合入时生效,表示设计基础被接受,不代表功能已实现或收益已验证。本 PR 只交付文档。未来执行记录遵循[账本契约](ledger/README.zh-CN.md),中英镜像同步维护。 + +**用户方向与 AI 方案:** 用户希望在上下文压缩时保留 LoopX 可识别的结构化信息,预期表示更稀疏;明确参考 **FSoft-AI4Code/CodeWiki**,并提出 Manus 将压缩作为记忆的研究线索。这些是请求方向,不表示用户已批准下文的 schema、集成方式或收益结论。本文具体设计和实验目标均为 AI 提案,待评审。“压缩”指对话上下文缩减,不指模型权重压缩。 + +## 1. 决策摘要 + +研究把**上下文压缩作为工作记忆的整理时机**:保存少量有版本、绑定原始来源、会影响后续决策的知识;原文与详情留在活动上下文之外;压缩后由 LoopX 识别并展开。 + +建议在现有 owner 内分为两部分: + +1. 持久化工作记忆视图,包含有来源的发现、已否定路径、决策理由和未决问题,服务继续工作。它是派生材料,不是另一套 Goal/Todo 或权限账本。 +2. 面向模型的短结构,标识该视图并展示当前最需要处理的决策问题。已资格化的宿主集成可以在压缩时保留它,也可以由现有恢复适配器在压缩后恢复它。普通摘要提到 LoopX,不等于存在可识别结构。 + +从一个本地原生宿主 profile 和现有 capture/read 链路开始,默认关闭。先比较确定性选取与现有交付,只有语义整理带来额外价值时才加入。本文不启动付费实验、不改变运行时默认、不批准删除来源,也不承诺成本下降。 + +## 2. 问题与动机 + +现有持久工作状态回答“要求是什么、谁负责”。对话还积累了“某个方案为什么失败、什么观察改变了假设、哪个表面成功仍缺验证”。其中一些知识可能尚未进入合适的持久来源。即使 Todo 状态保住,丢失这些知识仍可能改变后续决策。 + +合成例子:R1 的缓存隔离检查失败;R2 修复通过了针对性检查,但回滚尚未验证。压缩成“缓存修复完成”会同时丢掉已否定路径与未完成验收;重放完整调查则增加输入与恢复成本。希望保留的是有区分力的结论及其精确证据,而非缩短的操作流水账。 + +**更稀疏**指常驻事实更少、权威正文重复更少,不代表可恢复来源覆盖减少或义务被悄悄弱化。如果短首屏引发反复全量补读,结果可能更差。 + +### 不变量 + +- 完整的当前意图、要求、停止条件和原始执行/结算身份,继续由现有 owner 与读取契约保留。尚未记录的用户直接纠正,必须先成为精确来源,相关上下文才有资格被移出。 +- 历史观察、模型解释、已接受决策和当前权限必须可区分。记忆不授予权限、不认领 Todo、不通过验收,也不刷新旧事实。 +- 保留影响后续决策的反证和未决区别。不通过关键词推断完成、否定、信任或权限。 +- 引用不证明已读、理解、模型保留或 Delta baseline。缺少必要事实时沿用原有依赖动作停止规则;独立授权工作可以继续。 +- 优化可以回退,但不能抹掉缺失的必需来源,也不能改变已有工作/结算操作。 + +## 3. 范围与参考设计 + +范围是同机、Goal 范围内跨上下文压缩的工作记忆。跨会话展开只在已证明的保留 profile 内成立。全局用户记忆、自动晋升长期经验、跨 Goal 召回、摄入完整宿主轨迹、新调度器和新记忆数据库不在 v0 范围内。 + +| 一手参考 | 已核对的公开说明 | 借鉴点与边界 | +| --- | --- | --- | +| [FSoft-AI4Code/CodeWiki README][CW1],固定 `7fcf9354` | 依赖图 → 模块层级 → 模块文档与概览 | 用关系和分层导航代替时间顺序流水账。仓库文档设计不能证明对话压缩有效。 | +| [CodeWiki 增量更新指南][CW2],同一版本 | 保存图、树和构建元数据,由组件变化驱动相关页面更新 | 记忆绑定来源,变化影响对应视图。复用 LoopX 工作/证据关系,不引入代码依赖分析器或照搬上游阈值。 | +| [Manus 上下文工程文章][M1],发表于 2025-07-18 | 文件作为外置记忆;压缩保留可恢复定位;复述任务并保留失败证据 | 借鉴外置、取回与有用失败。这篇来源**没有证实**固定结构化记忆 schema,也没有证实每次压缩都会写记忆;该具体说法仍待核实。 | + +本提案把 CodeWiki 的导航思路用于变化中的工作知识,不是在每次压缩时生成仓库 wiki。这是设计推论,不是已有集成。 + +## 4. 当前系统契约:已核对基线 + +在实现基线,源码检查确认: + +| 现有 owner | 已观察行为 | 本提案仍缺什么 | +| --- | --- | --- | +| [`native_context_lifecycle.ts`][LX1] 的 `updateNativeContextLifecycle()` | Pre/PostCompact 幂等失效连续性证据;SessionStart/resume 与已验证选读分别处理 | epoch 失效本身不整理语义工作记忆。 | +| [`codex_context.py`][LX2] 的 `codex_context_hook()` 与 `_context_continuation_instructions()` | journal 保留精确恢复引用;SessionStart 可交付恢复指令;baseline 丢失不使已准入 Turn 失效,也不要求全量重读 | 这些函数尚不产生固定的稀疏工作记忆对象。hook 输出不能证明宿主摘要保留了它。 | +| [`codex_context_history.py`][LX3] | 检查支持的原生重放元数据与已观察读取区间,拒绝不支持或不完整的历史 | 记忆结构被识别,不能替代这些检查或扩大宿主资格范围。 | +| [`progressive_context.ts`][LX4] 与 [`context_delivery.ts`][LX5] | 确定性选读视图、有来源绑定的精确 full/Delta 交付,包括保存文件的连续性 | 当前已有缩减表示;必须与此路径比较,不能虚构“当前总是全量”的基线。精确交付不证明语义摘要忠实。 | +| [历史工作集 RFC](history-working-set-context-policy-v0.zh-CN.md) 第 5/9/11 节 | 已接受来源绑定历史视图、保留、可选生成与完整成本对照的设计;成熟度为 Proposal | 复用其 owner 与门槛。本 RFC 收窄整理触发点和压缩后表示,不替代旧 RFC,也不完成其里程碑。 | + +以上是静态代码/设计事实,不是已安装宿主、最终模型输入或任务效果测量。实施前须重查当前来源与[相关开放工作](https://github.com/loopx-project/loopx/pull/8266),候选分支能力不等于 main 事实。 + +## 5. 提议架构 + +```mermaid +flowchart LR + A["现有工作事实与精确证据"] --> B["现有 capture / artifact owner"] + B --> C["有界工作记忆选取"] + C --> D["有来源的持久记忆视图"] + D --> E["可识别短结构"] + E --> F["已资格化的宿主压缩 / 恢复"] + F --> G["后续决策与任务结果"] + G -->|"展开必要事实"| B +``` + +### 5.1 归属与表示 + +共享 TypeScript 呈现边界负责选取与校验;现有 capture/artifact IO 负责持久化与精确读取;原生宿主适配器负责事件转换和交付。Goal、请求、Todo、claim/lease、准入、权限和结算保留原 owner。归属是现有上下文交付的内部扩展:**v0 不新增 capability id、provider id 或 extension 发行包**。后续语义生成复用历史工作集 provider 边界,不在同步 hook 中加入模型 IO。 + +持久记忆视图复用现有来源身份、revision、范围和信任级别,绑定原始 Goal/Agent、执行/capture、session/profile、已观察压缩代际和 schema/producer 版本。绑定在 capture 元数据中保存一次,短结构不重复全部字段。digest 证明字节相同,不证明作者或权限;reader 仍须按当前访问检查解析 owner 签发的引用。 + +只保留有用且有来源的增量:结论与适用依据、已否定尝试为何不能原样重试、改变的假设与反证、未决区别。权威目标、Todo 正文、权限和已完成工具轨迹通过已有来源引用。不能从记住的历史决策推断当前决策。来源缺少类型化分类时,保留原文或留在普通上下文,不把自然语言分类为权限依据。 + +面向模型的示意结构,**不是已发布 schema、URI 方案或 CLI**: + +```json +{ + "schema_version": "loopx_compaction_memory_v0", + "memory_ref": "example-memory-17", + "focus": "Verify R2 cache isolation; rollback is still unverified.", + "frontier": [ + {"ref": "example-finding-4", "note": "R1 failed isolation; retain the failing condition."}, + {"ref": "example-question-2", "note": "Does R2 survive rollback?"} + ], + "needed_reads": ["example-original-capture:selected_todo"] +} +``` + +| 部分 | 为什么保留 | +| --- | --- | +| `schema_version`、`memory_ref` | 确定性识别与经 owner 校验的展开。用户/工具提供的同形对象仍是不可信内容。 | +| `focus`、`frontier` | 为下一次有用的读取或决策提供必要含义。短注释是建议;原始引用保留来源与区别。 | +| `needed_reads` | 展示原契约的未完成依赖,只是视图,不能作为可悄悄清空或收窄原契约的替代清单。 | + +五个顶层字段是起始提案,不是字段数目标。最终版本化 schema 可省略可选空数组。立即必需的控制仍由现有强制交付承担。不能安全表示的义务继续保留;候选超预算时沿用现有视图,不裁断内容。不为“结构化”重新内联整份 Goal/Todo/权限快照。 + +### 5.2 压缩生命周期 + +1. **准备:** 来源尚可用时解析现有来源和精确覆盖,只整理实际观察的材料,记录未读/部分覆盖。原本未记录的用户纠正先经所属来源适配器持久化,保留信任与先后关系。 +2. **发布:** 先存可恢复原文,再存绑定后的派生记忆,最后发布可选读引用。重试复用原 capture/operation 身份,部分写入不能宣称记忆有效。记忆发布本身不结算工作、不自行消耗工作配额;生成成本仍计入。 +3. **压缩:** 支持的宿主存在已资格化保留机制时,请求逐字保留短结构。仅有压缩前 hook,不能证明可替换宿主 compactor 或定制其输出。否则由现有压缩后恢复边界补回同一持久表示。 +4. **识别与续接:** 只解析支持的版本,并由引用 owner 校验预期范围。定位原 Turn/capture,不暗中换为更新版本。只按既有动作契约重新检查当前权限;压缩本身既不重新准入,也不强制全读。依赖动作前展开缺失且影响决策的详情。 +5. **更新:** 只更新受影响的有来源发现/当前问题。底层来源保留替代关系与反证;没有叶子覆盖,不递归摘要昨日摘要。多次压缩不能使短结构长成第二本 journal。 + +重复 Pre/PostCompact 与 SessionStart 映射到同一次已观察边界。事件丢失、乱序、突然上下文丢失或输出无效时,经现有恢复回退。磁盘轨迹里有可解析对象,既不证明宿主重放了它,也不证明模型看见了它。持久化、提交宿主、观察到的模型可见交付、决策采用、验收结果分别记录,不可观察层标 unknown。 + +### 5.3 提取与稀疏策略 + +第一步确定性选取已有类型化发现与精确引用,不增加模型调用,先弄清选取与结构本身的价值。相关知识只存在对话时,后续有界模型/宿主 compactor 贡献可提议有来源记忆,标明精确输入覆盖和观察/解释归属,不能制造权威决策或改写权限。 + +不在压缩 hook 内同步调用另一个 LLM。复用已验证的准备/执行边界,或在实际契约资格化后复用宿主 compactor。没有合法来源或执行边界时,该语义模式保持不可用,沿用原上下文路径。不能把空的确定性视图假称为已补足关键含义。 + +## 6. 替代方案与取舍 + +| 方案 | 收益 | 成本与建议 | +| --- | --- | --- | +| 原生摘要 + 当前 Progressive/Delta | 没有新增记忆生命周期 | 必备基线;当前路径可能已足够。 | +| 每次压缩完整结构化快照 | schema 容易识别 | 重复状态、消耗输入,也容易把过期快照混为权限;不优先实验。 | +| 稀疏引用 + 确定性当前问题 | 新机制最少,不增加模型生成 | 可能增加补读或漏掉对话知识。建议作为首个处理组,不预先认定胜出。 | +| 稀疏语义工作记忆 + 原文 | 能保留任务记录之外的因果发现 | 有提取/漂移、覆盖、成本和宿主集成风险;须证明比确定性选取多出的价值。 | +| 生成完整 CodeWiki 式 wiki | 丰富的长期仓库导航 | 范围不同,生命周期和依赖负担显著增加;借鉴导航思路,不导入整套产品。 | + +## 7. 安全、隐私与兼容性 + +默认关闭时,现有路径不新增提取、模型调用、记忆写入、依赖 parser 的接续或必需读取。已有原始机器消费者和历史 capture reader 保留原格式。提议 schema 是新派生视图,不删除任何已存字段;实施前登记共享语义词汇、验证新旧 reader。未知版本/字段不得被暗中认定等价或可删除。 + +私有对话与来源保持原访问范围。不保存原始推理轨迹、秘密或新增跨 Goal 共享;相同 hash 不授权复用。取回内容仍是数据。通过现有 reader 解析引用,不执行记忆中的任意路径或 shell 命令。撤销/删除/来源丢失使相关展开与派生视图失效;残留摘要不能绕过边界。 + +可选记忆不可用时回到普通交付。必需原文不可用,只按原契约阻断依赖动作。回滚、Goal 变化、同来源但不同 Agent 等情况,均不能生成新的准入、所有权、lease、记账或结算权限。 + +## 8. 迁移与回滚 + +对一个明确资格化的本地宿主/profile 显式开启,不重写现有来源。shadow 检查阶段保存候选但不减少模型输入;该阶段只验证绑定,不验证效果。随后才在该 profile 上以短表示替换有资格移出的活动上下文材料,保留必需控制与精确展开。 + +关闭后停止新的整理与采用,后续输入沿用现有交付。已承诺引用按声明生命周期可读,显式删除/撤销优先。所有宣称范围都要验证跨压缩、进程重启与正常清理后的保留;当前临时 capture 不自动成为持久记忆。必要时扩展现有保留 owner。本文不授权破坏性迁移或来源 GC 变更。 + +## 9. 验证与验收 + +### 9.1 契约与真实路径证据 + +| ID | 场景 | 必需结果与边界 | +| --- | --- | --- | +| A1 | 支持的真实宿主压缩后经生产入口续接 | 支持的结构被校验并交付或恢复;展示实际可取得的输入证据,不能只看 hook stdout 或保存文件。 | +| A2 | 再压缩两次;原文保存与发布之间中断;重复/乱序事件 | 原工作/结算身份不变、视图增长有界、发布可恢复,不重复已完成 effect 或扣额。 | +| A3 | 只改变 revision、失败条件、未完成检查或用户纠正 | 后续决策保留区别;尝试结束不等于通过验收。原文与尾部关键证据可精确展开。 | +| A4 | 来源缺失/变化、访问撤销、伪造引用、异 Goal/Agent、未知 schema | 拒绝相关复用;普通回退或原依赖动作停止,不提升权限。 | +| A5 | hook 缺失、对象截断/改写、宿主不支持保留 | 现有恢复仍可用,不从未观察事件推断结构保留或模型连续性。 | +| A6 | 关闭、无收益、混合版本 | 关闭行为等价,无新增模型 IO;保留未知材料与机器/capture 契约。 | +| A7 | 声明的重启/清理范围 | 承诺来源仍可解析;显式删除/撤销覆盖保留时,可见失效。 | +| A8 | 打包后开启 → 压缩 → 查看来源/失败 → 关闭 | 现有设置与读回复用 typed owner;产品晋升前资格化受影响 frontend/Lark/CLI。单宿主原型仅为部分交付。 | + +结构正确不能证明语义有用。本次文档 PR 不通过任何 A 项。 + +### 9.2 是否真的更好 + +复用 [T02 / #4391](https://github.com/loopx-project/loopx/issues/4391) 与[历史工作集测量契约](history-working-set-context-policy-v0.zh-CN.md#92-对照设计与成本口径)。看到结果前冻结对照、任务样本、预算、独立验收和决策阈值: + +- **B0:** 当前最佳合法宿主路径,包括已资格化 Progressive/Delta 及普通原生摘要。 +- **T1:** 相同任务与压缩点,加入确定性稀疏结构和精确原文引用,不增加语义生成。 +- **T2,有条件:** 相同稀疏预算,加有来源语义整理,测提取记忆的增量价值。不为增加实验组而运行。 + +以完整续接 episode 为单位,覆盖已否定尝试、较晚纠正、revision 变化、尾部证据、多次压缩和来源不可用。同模型/工具/环境、同**完整**资源上限;准备与补读计入同一预算。一次 episode 内重复调用/压缩不是独立样本。预先确定配对重复与足以支撑结论的样本量,小型可行性试验不能证明普遍优越。 + +首先测独立验收结果与关键约束遗漏,再测重复失败路径、人工介入、压缩后恢复耗时、各可观察层的实际/估算输入、全部模型生成与缓存/非缓存用量、补读/重试、总墙钟和保留磁盘。所有失败、回退、无收益样本及超预算均保留;不可见 provider/模型层保持 unknown。 + +只有达到预先声明的质量非劣标准并显著改善**完整成本**,或在可比完整成本下取得更好的验收成果,才考虑晋升。短首块、parser 通过、检索相关或生成了记忆文件都不够。补读/缓存失效抵消节省时保留 B0,报告负结果。本文不包含已测效果量或已冻结的数值晋升阈值。 + +## 10. 运行成本与产品契约 + +首个预期规模为本地单 Goal/session,包含多次工具观察与重复压缩,不假设集群规模需求。确定性模式增加有界选取、capture 元数据与本地读取,无新增模型依赖。语义模式增加生成输入/输出、重试与潜在缓存扰动。存储成本由保留的来源覆盖决定,不由短结构大小决定;宣称长期记忆前测生命周期与磁盘增长。 + +稳定前缀保持稳定,只更新变化的视图内容。额外提取、再生成与展开全部计入任务成本。盈亏取决于扣除准备、读取和缓存影响后,未来实际少处理了多少输入,不取决于上游压缩百分比。仍由现有来源/capture 失败处理和 usage 观察负责,不需要常驻 worker、图数据库或安装 CodeWiki。 + +通过现有上下文设置/读回展示有效开关与支持宿主、当前来源绑定/覆盖、恢复/回退原因、可用原文和已测成本。用户沿用现有数据控制查看、关闭或移除记忆。公开遥测不暴露记忆正文或私有定位。启用后无需每次压缩再确认;原有范围与付费执行权限继续生效。 + +## 11. 规范交付计划 + +| 里程碑 | 可评审成果 | 进入条件与决定性退出证据 | 回滚 | +| --- | --- | --- | --- | +| M0:评审 | 明确压缩记忆假设、owner 分工与有界 profile | 当前源码核对;在相关步骤前解决 D1–D3;接受设计不启动执行 | 仅文档 | +| M1:一条真实压缩路径 | 确定性稀疏视图在一个支持宿主保留或恢复,并精确展开原文 | 已资格化宿主契约与保留;A1–A7,加实际最终交付和原身份恢复 | 原宿主/恢复交付 | +| M2:效果比较 | B0/T1 成果与完整成本比较;只为已证明缺失的语义知识加入 T2 | 冻结样本/预算/阈值;第 9.2 节证据包含负结果 | 保留 B0 或 T1,不强制晋升 | +| M3:产品资格 | 受影响入口可开启、查看、处理失败/恢复与关闭 | A8,混合版本与关闭等价;其他宿主和保留范围分别验收 | 关闭可选视图,保留有效引用 | + +首个实现候选是对 `quota/progressive_context.ts`、`native_context_lifecycle.ts` 的视图/生命周期语义做有界改动;由 `turn_driver/decision_capture.py`、`codex_context.py` 及历史适配器承担 capture/宿主 IO;复用现有上下文配置、读回和测试。修改前确认真实首个调用者;复用当前来源/reader 契约,不建第二套记忆服务。本 PR 不包含实现或迁移。 + +## 12. 未决问题 + +| ID | 选项与 AI 建议 | 决策 owner / 时点 | +| --- | --- | --- | +| D1 | 宿主 compactor 结构化输出,或持久视图加压缩后恢复:优先已有恢复集成;宣称原生保留前先资格化真实宿主能力 | 原生宿主/上下文维护者,M1 前 | +| D2 | 哪些发现、来源覆盖、保留范围与稀疏预算:从单 Goal 类型化调查结果与未决区别开始;未记录的精确纠正必须保留。schema/限额依据实测负载,不按字段数审美决定 | 上下文/历史/来源 owner,M1 前 | +| D3 | 是否需要语义提取、何时执行:先做确定性 T1;对话独有知识使 T1 不足时,T2 复用有界且验证过的执行边界 | 历史/运行时 owner,语义实现或运行前 | +| D4 | 样本、非劣界与实质收益标准:预先声明完整成本与结果标准,不照搬 CodeWiki/Manus 数字,不从更少字节推断成功 | T02/评估 owner,任何模型实验前 | + +## 附录 A:证据与决策记录 + +- 静态核对:LoopX 指定来源位于 `0c3b2fd21800`;CodeWiki README/更新指南位于 `7fcf9354f70a5468bc739d849055f8cbab9d46aa`;Manus 使用已注明日期的一手文章。这不认证 Manus 当前闭源内部实现或上游实现质量。 +- 用户确认方向:压缩时保留可识别、更稀疏的结构,参考 AI4Code。Manus 在压缩时写记忆的确切行为仍是线索,不是已验证前提。 +- AI 提议、尚未批准:schema、字段选取、宿主 profile、生命周期细节、阈值与实施顺序。未实施运行时/默认变更、付费/模型实验、收益测量、宿主安装验收或产品晋升。 +- 不替代 RFC、不删除已存字段、不关闭已有验收里程碑。真正执行后才创建对应日期账本。 + +[CW1]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/README.md +[CW2]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/guides/incremental-updates.md +[M1]: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus +[LX1]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/native_context_lifecycle.ts +[LX2]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context.py +[LX3]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context_history.py +[LX4]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/progressive_context.ts +[LX5]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/context_delivery.ts From a4965bea50d7010c457006214da3a45cca37e040 Mon Sep 17 00:00:00 2001 From: "lusendong.6789" Date: Tue, 17 Nov 2026 00:17:21 +0800 Subject: [PATCH 2/4] docs(rfc): clarify experimental activation and main compatibility Signed-off-by: lusendong.6789 --- docs/architecture/rfcs/README.md | 3 +- .../sparse-compaction-working-memory-v0.md | 60 ++++++++++++++----- ...arse-compaction-working-memory-v0.zh-CN.md | 60 ++++++++++++++----- 3 files changed, 92 insertions(+), 31 deletions(-) diff --git a/docs/architecture/rfcs/README.md b/docs/architecture/rfcs/README.md index 0ef9a53ebc..c86b9f4847 100644 --- a/docs/architecture/rfcs/README.md +++ b/docs/architecture/rfcs/README.md @@ -212,7 +212,8 @@ Paired diffs do not certify translation accuracy. remain unqualified; no runtime, default or experiment change. - [Sparse Working Memory at Context Compaction v0](sparse-compaction-working-memory-v0.md) ([中文版](sparse-compaction-working-memory-v0.zh-CN.md)) - - **Delivery on `main`:** Proposal only; no runtime or default change. + - **Delivery on `main`:** Experimental proposal only; independently opt-in, + off by default, with no runtime or default change in this RFC. - **Current boundary:** A bounded T02 companion to history working sets: consolidate source-bound working memory at compaction and retain or restore a short recognizable structure. Compare deterministic sparse selection, diff --git a/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md index ed29876140..6e14cfcfd7 100644 --- a/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md +++ b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.md @@ -3,10 +3,11 @@ - **RFC status:** Accepted (upon merge) - **Supersedes / closes:** none - **Delivery maturity:** Proposal +- **Feature status:** Experimental proposal; independently opt-in and off by default. - **Authors / owners:** AI-assisted proposal; context presentation, native-host, history-working-set and T02 maintainers. - **Created:** 2026-11-16 -- **Last normative revision:** 2026-11-16 -- **Implementation baseline:** [`0c3b2fd21800a536ccaa61bad85c4dd8257aad8e`](https://github.com/loopx-project/loopx/commit/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e). +- **Last normative revision:** 2026-11-17 +- **Implementation baseline:** [`b9f2e2a516b58e62cbb0da6978625388322b5a90`](https://github.com/loopx-project/loopx/commit/b9f2e2a516b58e62cbb0da6978625388322b5a90). - **Related contracts:** [History working sets](history-working-set-context-policy-v0.md), [unified work contract](controller-executor-unified-contract-v0.md), [explicit continuation](cross-session-memory-substrate-v0.md), [required work context](../../reference/required-work-context.md), [T02 research](long-horizon-harness-benchmark-research-program-v0.md). - **Language mirror:** [中文版 — semantic mirror](sparse-compaction-working-memory-v0.zh-CN.md). @@ -14,7 +15,7 @@ Sections 1–12 define this bounded proposal; §4 records audited code facts. The appendices contain sources and decision attribution. Accepted status takes effect only upon merge and accepts a design basis, not implemented behavior or measured benefit. This PR ships documentation only. Future execution records follow the [ledger contract](ledger/README.md); maintain both language mirrors together. -**Request versus proposal:** The requester asks to retain LoopX-recognizable structured information during context compaction, expects a sparser representation, identifies **FSoft-AI4Code/CodeWiki** as a reference, and raises Manus's use of compression as memory as a research lead. These are the requested direction, not approval of the schema, integration or claimed improvement below. All concrete design choices and experimental targets in this RFC are AI proposals pending review. “Compaction” here means conversation-context reduction, not model-weight compression. +**Request versus proposal:** The requester asks to retain LoopX-recognizable structured information during context compaction, expects a sparser representation, identifies **FSoft-AI4Code/CodeWiki** as a reference, raises Manus's use of compression as memory as a research lead, and confirms that this is an **experimental feature**. These are the requested direction, not approval of the schema, integration or claimed improvement below. All concrete design choices and experimental targets in this RFC are AI proposals pending review. “Compaction” here means conversation-context reduction, not model-weight compression. ## 1. Decision summary @@ -25,7 +26,7 @@ Recommend a two-part design within existing owners: 1. A persisted working-memory view contains sourced findings, rejected approaches, decision rationale and unresolved questions that are useful to continued work. It is derived material, not another Goal/Todo or permission ledger. 2. A short model-facing structure identifies that view and exposes its current decision frontier. The host retains it during compaction where a qualified integration permits, or the existing recovery adapter restores it afterward. An ordinary summary that mentions LoopX does not qualify as a recognized structure. -Begin with one local native-host profile and existing capture/read infrastructure. The feature defaults off. First compare deterministic selection with current delivery; add semantic consolidation only if it yields additional benefit. This RFC starts no paid runs, changes no runtime default, approves no source deletion and promises no cost reduction. +Begin with one local native-host profile and existing capture/read infrastructure. This is an independently enabled experiment, off by default; accepting its design does not promote it. First qualify persistence/restoration without replacing required content, then compare eligible deterministic selection with current delivery; add semantic consolidation only if it yields additional benefit. This RFC starts no paid runs, changes no runtime default, approves no source deletion and promises no cost reduction. ## 2. Problem and motivation @@ -65,6 +66,8 @@ At the implementation baseline, source inspection confirms: | [`codex_context.py`][LX2], `codex_context_hook()` and `_context_continuation_instructions()` | Journals exact recovery refs; SessionStart can deliver recovery instructions; baseline loss does not invalidate the admitted Turn or require full rereading | No fixed sparse working-memory object is produced by these functions. Host-generated summary retention is not proved by hook output. | | [`codex_context_history.py`][LX3] | Qualifies supported native replay metadata and observed read intervals; rejects unsupported/incomplete histories | A recognized memory object cannot replace these checks or extend the host qualification list. | | [`progressive_context.ts`][LX4] and [`context_delivery.ts`][LX5] | Deterministic selected views and exact, source-bound full/Delta delivery, including saved-file continuity | A smaller representation is already possible; compare against this path, not an invented always-full baseline. Exact delivery does not prove summary fidelity. | +| [`decision_capture.py`][LX6], capture writer and reader | Write-once complete captures; reader checks the exact byte digest; the projection helper accepts only its existing filenames | Memory must be a separate immutable derived artifact, not fields appended to an already-published source or an assumed new helper argument. | +| [`machine_configuration/context_delivery.py`][LX7] and [`context_machine.py`][LX8] | Current template is `mode:on`, `delta_delivery:auto`; its v0/v1 normalizer rejects unknown keys. Explicit saved-file reads bypass unrelated configuration discovery; a read-only query creates no Turn | Existing context enablement cannot enable experimental memory. New settings need an independently scoped gate and compatibility design, not an unversioned extra key. | | [History-working-set RFC](history-working-set-context-policy-v0.md), §§5/9/11 | Accepted design for source-bound historical views, retention, optional generation and full-cost controls; Proposal maturity | Reuse its owners and gates. This RFC narrows the consolidation trigger and post-compaction representation; it does not replace that RFC or complete its milestones. | These are static code/design findings, not installed-host, final-model-input or task-effectiveness measurements. The current-source audit and [related open work](https://github.com/loopx-project/loopx/pull/8266) must be refreshed before implementation; candidate changes are not main facts. @@ -86,7 +89,9 @@ flowchart LR The shared TypeScript presentation boundary owns selection and validation. Existing capture/artifact IO owns persistence and exact readers; native-host adapters own event translation and delivery. Goal, request, Todo, claim/lease, admission, authorization and settlement retain their current owners. Placement is an internal extension of existing context delivery: **no new capability id, provider id or extension distribution in v0**. Later semantic generation reuses the history-working-set provider boundary rather than adding model IO to synchronous hooks. -The persisted memory view reuses existing source identities, revisions, scope and trust. Bind it to the original Goal/Agent, execution/capture, session/profile, observed compaction generation and schema/producer version. Store that binding once in the capture metadata rather than repeating all fields in the short block. A digest proves byte identity, not authorship or authorization; the reader must resolve an owner-issued reference under current access checks. +The persisted memory view reuses existing source identities, revisions, scope and trust. Bind it to the original Goal/Agent, source capture, session/profile and schema/producer version; preserve the original Turn/settlement identity **when one exists**, without manufacturing a Turn for a read-only/unbound caller. Put this binding in a **new immutable derived artifact/reference**, using existing private writer/reader primitives. Never append metadata to or replace an already-published `projection.json`, `required-context.json` or reader reference. The current projection helper is not an API for an arbitrary memory filename. A digest proves byte identity, not authorship or authorization; the reader must resolve an owner-issued reference under current access checks. + +Memory revision and native `context_epoch` have different lifetimes. Derive memory identity from its source coverage and producer/schema version; use the existing lifecycle observation for deduplication, without making a memory write rotate the Delta epoch. Native compaction invalidation still runs even if memory preparation fails. A surviving memory never restores `candidate`, `pending`, consumed-pointer evidence, a claim or a Delta baseline; missing memory does not invalidate original saved work. Root/child and supported-replay restrictions remain attached to the native adapter. Retain only useful sourced increments: a conclusion plus its applicability basis, why a rejected attempt should not be retried unchanged, a changed assumption and contrary evidence, or an unresolved distinction. Canonical goals, Todo bodies, permissions and completed tool transcripts are referenced through their existing sources. A current decision is not inferred from a remembered historical one. Where the source has no typed classification, retain it verbatim or leave it in the ordinary context; do not classify prose as authority. @@ -123,12 +128,31 @@ The five top-level fields are a starting proposal, not a field-count target. Emp Repeated Pre/PostCompact and SessionStart events map to one observed boundary. Missing events, reordered events, abrupt context loss or invalid output fall back through existing recovery. A parseable object in a disk transcript proves neither that the host replayed it nor that the model saw it. Record persistence, host submission, observed model-visible delivery, decision adoption and accepted outcome separately; mark unobservable layers unknown. +**Compaction is a trigger, not removal eligibility.** M1 may restore an advisory memory view while retaining the existing required input. Replacement is limited to historical support that satisfies the accepted [history eligibility contract](history-working-set-context-policy-v0.md#52-historical-eligibility): typed ended attempt and recorded result, exact retained sources, protected current obligations, and no outstanding complete-first-read requirement. Current work, live corrections, unknown shapes, signed envelopes and machine/off paths do not become replaceable merely because their information appears in memory. Saving a correction alone does not satisfy its reading obligation. If no such source adapter is available, preserve the original context instead of claiming capture or extraction succeeded. + ### 5.3 Extraction and sparsity policy -First use deterministic selection of existing typed findings and exact references, without an extra model call. This establishes what selection and structure alone buy. Where relevant knowledge exists only in conversation, a later bounded model/host-compactor contribution can propose sourced memory, with exact input coverage and explicit observation-versus-interpretation attribution. It cannot manufacture a canonical decision or edit authorization. +First use deterministic selection of existing typed attempt/result/evidence facts **where available**, with exact references and without an extra model call. This does not assume main already has a standalone findings store or a structured host-compaction result. It establishes what selection and structure alone buy. Where relevant knowledge exists only in conversation, a later bounded model/host-compactor contribution can propose sourced memory, with exact input coverage and explicit observation-versus-interpretation attribution. It cannot manufacture a canonical decision or edit authorization. Do not call another LLM synchronously from a compaction hook. Reuse a verified existing preparation/execution boundary or the host compactor only after its actual contract is qualified. If no legal source or execution boundary exists, that semantic mode remains unavailable and the original context path continues. Critical missing meaning is not repaired by pretending an empty deterministic view is sufficient. +### 5.4 Compatibility with main and experimental activation + +Activation must independently bind the selected Goal, Agent, root session and qualified host profile **before** memory-specific selection, IO, instructions or model calls. Existing Progressive/Delta settings, installed hooks, readable captures, provider readiness and an object naming this schema are not activation. Absent/disabled activation and enabled-but-out-of-scope callers keep their previous schema, guidance, accepted inputs and effects. The first experiment should use an explicit scope-local profile; persist settings only after their registered producer/reader version and downgrade behavior are qualified. Do not add a key to current `context_delivery_machine_defaults_v0/v1` and assume old readers accept it, or make experimental configuration failure disable ordinary context delivery. + +| Main boundary | Required experimental behavior | Decisive qualification | +| --- | --- | --- | +| Progressive on / Delta auto is the current default [LX7] | Memory remains off independently; existing off preferences stay off | Gate absent/off, enabled in scope and enabled outside scope; compare with main on the same input | +| Exact capture bytes and references are immutable [LX6] | Publish a separate derived artifact; original body/digest/reader remain unchanged | Read the old capture before/after publication and downgrade; reject overwrite and substituted refs | +| `context_epoch` is not work identity [LX1]/[LX2] | Keep existing invalidation and original recovery; memory revision grants no continuity | Duplicate Pre/PostCompact, failed preparation and later SessionStart preserve the native transition | +| Same-Turn continuation versus a new guard [LX2] | Within a Turn recover needed facts from its original capture; a new Turn obtains its current guard | No second admission, repeated settlement or substitution of a newer capture on transport retry | +| A saved-file read may have no admitted Turn [LX8] | Read/inspect never creates a Turn, claim or lease; unqualified callers retain their existing path | Explicit historical file read with no Goal/default discovery or begin-turn side effect | +| Parent/child hooks and native replay qualification [LX1]/[LX3] | Preserve child rejection and existing unsupported/forked-history fallback | A child cannot write or restore the parent's memory/journal; unknown hosts remain unqualified | +| Required reads and historical eligibility [LX4] | Memory is advisory; reduce only qualified historical support, never current required content | Pending read, live correction, unknown fields and signed/off/machine cases keep their original obligations | +| Path-bound retained originals [LX6] | Claim only verified same-machine lifetime; source loss uses existing dependency/fallback rules | Restart, cleanup, deletion and revocation within the explicitly claimed scope | + +These are implementation acceptance obligations, not a claim that an unimplemented feature has passed compatibility tests. They add no parser to main and do not expand the default host or product surface. + ## 6. Alternatives and trade-offs | Alternative | Benefit | Cost / recommendation | @@ -149,7 +173,7 @@ An unavailable optional memory falls back to ordinary delivery. An unavailable r ## 8. Migration and rollback -Opt in one explicitly qualified local host/profile without rewriting existing sources. During shadow inspection, persist the candidate but do not reduce model input; that phase validates bindings, not effectiveness. Then replace eligible active-context material with the short representation on that profile, retaining required controls and exact expansion. +Opt in one explicitly qualified local host/profile without rewriting existing sources. During shadow inspection, persist the candidate but do not reduce model input; that phase validates bindings, not effectiveness. Then replace only historical support qualified under §5.2 on that profile, retaining required controls, original reading obligations and exact expansion. Where eligibility is unproved, restoration stays additive and cannot be reported as input reduction. Disablement stops new consolidation and adoption; later input uses existing delivery. Already promised references remain readable for their declared lifecycle, subject to explicit deletion/revocation. Retention must survive compaction, process restart and normal cleanup for every claimed scope; current temporary captures are not automatically durable memory. Extend the existing retention owner if necessary. No destructive migration or source GC change is authorized here. @@ -167,6 +191,8 @@ Disablement stops new consolidation and adoption; later input uses existing deli | A6 | Off, no-benefit and mixed-version paths | Feature-off parity; no new model IO when off; preserve unknown material and existing machine/capture contracts. | | A7 | Declared restart/cleanup scope | Promised sources remain resolvable; invalidate visibly when an explicit deletion/revocation supersedes retention. | | A8 | Packaged enable → compact → inspect source/failure → disable | Existing settings and readback share the typed owner; qualify affected frontend/Lark/CLI entrypoints before product promotion. A single-host prototype is partial delivery. | +| A9 | Independent experimental gate with identical inputs | Absent/off and enabled-but-out-of-scope paths match main, including settings failure, instructions, accepted inputs and IO; Progressive/Delta on alone never activates memory. | +| A10 | Separate immutable memory and original readers | Original capture/reference bytes and original read obligations survive publication, retry and downgrade; memory cannot acknowledge native retention or invent a missing Turn. | Structural conformance cannot prove semantic usefulness. No A-row is passed by this documentation PR. @@ -197,7 +223,7 @@ Expose effective enablement and supported host, current source binding/coverage, | Milestone | Reviewable outcome | Entry / decisive exit evidence | Rollback | | --- | --- | --- | --- | | M0: Review | Agreed compaction-memory hypothesis, owner split and bounded profile | Current-source audit; D1–D3 decisions at their dependent boundaries; design acceptance does not start execution | Documentation only | -| M1: One real compaction path | Deterministic sparse view survives or is restored and expands exact originals on one supported host | Qualified host contract and retention; A1–A7 plus observed final delivery and original-identity recovery | Existing host/recovery delivery | +| M1: One real compaction path | Deterministic sparse view survives or is restored and expands exact originals on one supported host; required content remains intact | Independent scope-local activation, qualified host contract and retention; A1–A7/A9/A10 plus observed final delivery and original-identity recovery | Existing host/recovery delivery | | M2: Utility comparison | B0/T1 outcome and full-cost comparison; T2 only for demonstrated missing semantic knowledge | Frozen sample/budgets/thresholds; §9.2 evidence, including negative results | Keep B0 or T1; no forced promotion | | M3: Product qualification | Enablement, inspection, failure/recovery and disablement through affected surfaces | A8, mixed-version/off parity; separately qualify broader hosts and retention | Disable optional view; preserve valid refs | @@ -211,19 +237,23 @@ First implementation candidates are narrow changes to `quota/progressive_context | D2 | Which findings, source coverage, retention scope and sparse budget: start with typed investigation results and unresolved distinctions on one Goal; exact unrecorded corrections remain mandatory. Choose schema/limits from measured workload, not field-count aesthetics | Context / history / source owners, before M1 | | D3 | Whether semantic extraction is needed and when it runs: deterministic T1 first; reuse a bounded verified execution boundary for T2 if conversation-only knowledge makes T1 insufficient | History / runtime owners, before semantic implementation or runs | | D4 | Task sample, non-inferiority margin and material benefit: predeclare complete-cost and outcome criteria; do not import CodeWiki/Manus numbers or infer success from fewer bytes | T02 / evaluation owners, before any model experiment | +| D5 | Experimental activation/configuration: prefer an explicit scope-local profile first; qualify any persistent registered settings separately from Progressive/Delta, including older readers and gate-off/out-of-scope parity | Configuration / native-host owners, before M1 activation | ## Appendix A: Evidence and decision record -- Static audit: named LoopX sources at `0c3b2fd21800`; CodeWiki README/update guide at `7fcf9354f70a5468bc739d849055f8cbab9d46aa`; Manus's dated primary article. This does not certify current proprietary Manus internals or upstream implementation quality. -- Request-confirmed direction: recognizable, sparser structure at compaction; AI4Code reference. Manus's exact compression-time memory-write behavior remains a lead, not a verified premise. +- Static audit: named LoopX sources rechecked against main `b9f2e2a516b58e62cbb0da6978625388322b5a90`; the original five source files are unchanged since `0c3b2fd21800`. CodeWiki README/update guide remains pinned at `7fcf9354f70a5468bc739d849055f8cbab9d46aa`; Manus uses its dated primary article. This does not certify current proprietary Manus internals or upstream implementation quality. +- Request-confirmed direction: recognizable, sparser structure at compaction; AI4Code reference; experimental feature. Manus's exact compression-time memory-write behavior remains a lead, not a verified premise. - Proposed, unapproved: schema, field selection, host profile, lifecycle details, thresholds and implementation sequence. No runtime/default change, paid/model experiment, measured saving, host-install acceptance or product promotion has been performed. - No RFC is superseded, stored field removed or existing acceptance milestone closed. Future dated execution evidence belongs in the ledger only after real work exists. [CW1]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/README.md [CW2]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/guides/incremental-updates.md [M1]: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus -[LX1]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/native_context_lifecycle.ts -[LX2]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context.py -[LX3]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context_history.py -[LX4]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/progressive_context.ts -[LX5]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/context_delivery.ts +[LX1]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/quota/native_context_lifecycle.ts +[LX2]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/turn_driver/codex_context.py +[LX3]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/turn_driver/codex_context_history.py +[LX4]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/quota/progressive_context.ts +[LX5]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/quota/context_delivery.ts +[LX6]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/turn_driver/decision_capture.py +[LX7]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/capabilities/machine_configuration/context_delivery.py +[LX8]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/cli_commands/context_machine.py diff --git a/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md index 79768ab305..f0e5d2593b 100644 --- a/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md +++ b/docs/architecture/rfcs/sparse-compaction-working-memory-v0.zh-CN.md @@ -3,10 +3,11 @@ - **RFC status:** Accepted (upon merge) - **替代 / 关闭:** 无 - **Delivery maturity:** Proposal +- **功能状态:** 实验性提案;独立显式开启,默认关闭。 - **作者 / 负责人:** AI 辅助提案;上下文呈现、原生宿主、历史工作集与 T02 维护者。 - **创建日期:** 2026-11-16 -- **最近规范修订:** 2026-11-16 -- **实现基线:** [`0c3b2fd21800a536ccaa61bad85c4dd8257aad8e`](https://github.com/loopx-project/loopx/commit/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e)。 +- **最近规范修订:** 2026-11-17 +- **实现基线:** [`b9f2e2a516b58e62cbb0da6978625388322b5a90`](https://github.com/loopx-project/loopx/commit/b9f2e2a516b58e62cbb0da6978625388322b5a90)。 - **相关契约:** [历史工作集](history-working-set-context-policy-v0.zh-CN.md)、[统一工作契约](controller-executor-unified-contract-v0.zh-CN.md)、[显式接续](cross-session-memory-substrate-v0.zh-CN.md)、[必需工作上下文](../../reference/required-work-context.md)、[T02 研究](long-horizon-harness-benchmark-research-program-v0.zh-CN.md)。 - **语言镜像:** [English(语义镜像)](sparse-compaction-working-memory-v0.md)。 @@ -14,7 +15,7 @@ 第 1–12 节定义本次有界提案;第 4 节记录已核对的代码事实。附录记录来源与观点归属。Accepted 仅在合入时生效,表示设计基础被接受,不代表功能已实现或收益已验证。本 PR 只交付文档。未来执行记录遵循[账本契约](ledger/README.zh-CN.md),中英镜像同步维护。 -**用户方向与 AI 方案:** 用户希望在上下文压缩时保留 LoopX 可识别的结构化信息,预期表示更稀疏;明确参考 **FSoft-AI4Code/CodeWiki**,并提出 Manus 将压缩作为记忆的研究线索。这些是请求方向,不表示用户已批准下文的 schema、集成方式或收益结论。本文具体设计和实验目标均为 AI 提案,待评审。“压缩”指对话上下文缩减,不指模型权重压缩。 +**用户方向与 AI 方案:** 用户希望在上下文压缩时保留 LoopX 可识别的结构化信息,预期表示更稀疏;明确参考 **FSoft-AI4Code/CodeWiki**,提出 Manus 将压缩作为记忆的研究线索,并确认这是**实验性功能**。这些是请求方向,不表示用户已批准下文的 schema、集成方式或收益结论。本文具体设计和实验目标均为 AI 提案,待评审。“压缩”指对话上下文缩减,不指模型权重压缩。 ## 1. 决策摘要 @@ -25,7 +26,7 @@ 1. 持久化工作记忆视图,包含有来源的发现、已否定路径、决策理由和未决问题,服务继续工作。它是派生材料,不是另一套 Goal/Todo 或权限账本。 2. 面向模型的短结构,标识该视图并展示当前最需要处理的决策问题。已资格化的宿主集成可以在压缩时保留它,也可以由现有恢复适配器在压缩后恢复它。普通摘要提到 LoopX,不等于存在可识别结构。 -从一个本地原生宿主 profile 和现有 capture/read 链路开始,默认关闭。先比较确定性选取与现有交付,只有语义整理带来额外价值时才加入。本文不启动付费实验、不改变运行时默认、不批准删除来源,也不承诺成本下降。 +从一个本地原生宿主 profile 和现有 capture/read 链路开始。这是独立开启、默认关闭的实验;接受设计不表示功能晋升。先资格化持久化/恢复而不替换必需内容,再比较合格的确定性选取与现有交付,只有语义整理带来额外价值时才加入。本文不启动付费实验、不改变运行时默认、不批准删除来源,也不承诺成本下降。 ## 2. 问题与动机 @@ -65,6 +66,8 @@ | [`codex_context.py`][LX2] 的 `codex_context_hook()` 与 `_context_continuation_instructions()` | journal 保留精确恢复引用;SessionStart 可交付恢复指令;baseline 丢失不使已准入 Turn 失效,也不要求全量重读 | 这些函数尚不产生固定的稀疏工作记忆对象。hook 输出不能证明宿主摘要保留了它。 | | [`codex_context_history.py`][LX3] | 检查支持的原生重放元数据与已观察读取区间,拒绝不支持或不完整的历史 | 记忆结构被识别,不能替代这些检查或扩大宿主资格范围。 | | [`progressive_context.ts`][LX4] 与 [`context_delivery.ts`][LX5] | 确定性选读视图、有来源绑定的精确 full/Delta 交付,包括保存文件的连续性 | 当前已有缩减表示;必须与此路径比较,不能虚构“当前总是全量”的基线。精确交付不证明语义摘要忠实。 | +| [`decision_capture.py`][LX6] 的 capture writer/reader | 完整 capture 只写一次,reader 校验精确字节 digest;projection helper 只接受现有文件名 | 记忆必须是独立不可变派生产物,不能向已发布来源追加字段,也不能假定 helper 已支持新参数。 | +| [`machine_configuration/context_delivery.py`][LX7] 与 [`context_machine.py`][LX8] | 当前模板为 `mode:on`、`delta_delivery:auto`,v0/v1 normalizer 拒绝未知字段;显式保存文件读取绕过无关配置发现,只读查询不创建 Turn | 现有上下文开关不能启用实验记忆;新设置需要独立作用域开关及兼容设计,不能直接追加无版本字段。 | | [历史工作集 RFC](history-working-set-context-policy-v0.zh-CN.md) 第 5/9/11 节 | 已接受来源绑定历史视图、保留、可选生成与完整成本对照的设计;成熟度为 Proposal | 复用其 owner 与门槛。本 RFC 收窄整理触发点和压缩后表示,不替代旧 RFC,也不完成其里程碑。 | 以上是静态代码/设计事实,不是已安装宿主、最终模型输入或任务效果测量。实施前须重查当前来源与[相关开放工作](https://github.com/loopx-project/loopx/pull/8266),候选分支能力不等于 main 事实。 @@ -86,7 +89,9 @@ flowchart LR 共享 TypeScript 呈现边界负责选取与校验;现有 capture/artifact IO 负责持久化与精确读取;原生宿主适配器负责事件转换和交付。Goal、请求、Todo、claim/lease、准入、权限和结算保留原 owner。归属是现有上下文交付的内部扩展:**v0 不新增 capability id、provider id 或 extension 发行包**。后续语义生成复用历史工作集 provider 边界,不在同步 hook 中加入模型 IO。 -持久记忆视图复用现有来源身份、revision、范围和信任级别,绑定原始 Goal/Agent、执行/capture、session/profile、已观察压缩代际和 schema/producer 版本。绑定在 capture 元数据中保存一次,短结构不重复全部字段。digest 证明字节相同,不证明作者或权限;reader 仍须按当前访问检查解析 owner 签发的引用。 +持久记忆视图复用现有来源身份、revision、范围和信任级别,绑定原始 Goal/Agent、来源 capture、session/profile 和 schema/producer 版本;**已有** Turn/结算身份时保留它,不为只读/未绑定调用者制造 Turn。使用现有私有 writer/reader 原语,把绑定放在**新建的不可变派生产物/引用**中。不能向已发布 `projection.json`、`required-context.json` 或 reader reference 追加元数据或覆盖它们;当前 projection helper 也不是任意 memory 文件名的 API。digest 证明字节相同,不证明作者或权限;reader 仍须按当前访问检查解析 owner 签发的引用。 + +记忆 revision 与原生 `context_epoch` 生命周期不同。记忆身份从来源覆盖与 producer/schema 版本导出,沿用现有生命周期观察去重,不因写记忆而轮换 Delta epoch。即使记忆准备失败,原生压缩失效逻辑仍执行。记忆保留不能恢复 `candidate`、`pending`、已消费 pointer 证据、claim 或 Delta baseline;记忆缺失也不使原保存工作失效。根/子会话与支持的重放限制继续由原生适配器承担。 只保留有用且有来源的增量:结论与适用依据、已否定尝试为何不能原样重试、改变的假设与反证、未决区别。权威目标、Todo 正文、权限和已完成工具轨迹通过已有来源引用。不能从记住的历史决策推断当前决策。来源缺少类型化分类时,保留原文或留在普通上下文,不把自然语言分类为权限依据。 @@ -123,12 +128,31 @@ flowchart LR 重复 Pre/PostCompact 与 SessionStart 映射到同一次已观察边界。事件丢失、乱序、突然上下文丢失或输出无效时,经现有恢复回退。磁盘轨迹里有可解析对象,既不证明宿主重放了它,也不证明模型看见了它。持久化、提交宿主、观察到的模型可见交付、决策采用、验收结果分别记录,不可观察层标 unknown。 +**压缩是触发点,不是移出资格。** M1 可在保留原必需输入的同时恢复建议性记忆视图。替换只限满足已接受[历史材料资格契约](history-working-set-context-policy-v0.zh-CN.md#52-哪些材料允许进入候选集)的支持材料:类型化已结束尝试与已记录结果、精确保留来源、当前义务受保护、没有未完成的完整首读要求。当前工作、实时纠正、未知形状、签名 envelope、机器/off 路径,不因信息出现在记忆里就可被替换。保存纠正本身不完成读取义务。没有相应来源适配器时,保留原上下文,不能宣称已成功捕获或提取。 + ### 5.3 提取与稀疏策略 -第一步确定性选取已有类型化发现与精确引用,不增加模型调用,先弄清选取与结构本身的价值。相关知识只存在对话时,后续有界模型/宿主 compactor 贡献可提议有来源记忆,标明精确输入覆盖和观察/解释归属,不能制造权威决策或改写权限。 +第一步从**实际可用**的已有类型化 attempt/result/evidence 事实中确定性选取,并保留精确引用,不增加模型调用。不假定 main 已有独立 findings store 或结构化宿主压缩结果,先弄清选取与结构本身的价值。相关知识只存在对话时,后续有界模型/宿主 compactor 贡献可提议有来源记忆,标明精确输入覆盖和观察/解释归属,不能制造权威决策或改写权限。 不在压缩 hook 内同步调用另一个 LLM。复用已验证的准备/执行边界,或在实际契约资格化后复用宿主 compactor。没有合法来源或执行边界时,该语义模式保持不可用,沿用原上下文路径。不能把空的确定性视图假称为已补足关键含义。 +### 5.4 与 main 的兼容及实验启用 + +开启必须独立绑定选定 Goal、Agent、根 session 和已资格化宿主 profile,并发生在记忆特有的选取、IO、指令或模型调用**之前**。现有 Progressive/Delta 设置、已安装 hook、可读 capture、provider 就绪、对象声明本 schema,都不是启用。未配置/关闭,以及已开启但不在作用域内的调用者,保持原 schema、指令、可接受输入与效果。首个实验建议使用显式且局部作用域的 profile;持久化设置前,先资格化注册后的 producer/reader 版本及降级行为。不能向现有 `context_delivery_machine_defaults_v0/v1` 加字段后假定旧 reader 接受,也不能让实验配置失败关闭普通上下文交付。 + +| main 边界 | 实验必须保持的行为 | 决定性验证 | +| --- | --- | --- | +| Progressive on / Delta auto 是当前默认 [LX7] | 记忆独立默认关闭,已有 off 偏好仍为 off | 未配置/关闭、开启且命中范围、开启但范围外,与 main 对比同一输入 | +| capture 精确字节与引用不可变 [LX6] | 发布独立派生产物,原正文/digest/reader 不变 | 发布及降级前后读原 capture;拒绝覆盖与替换引用 | +| `context_epoch` 不是工作身份 [LX1]/[LX2] | 保留原失效与恢复语义,记忆 revision 不授予连续性 | 重复 Pre/PostCompact、准备失败、后续 SessionStart 保持原生迁移 | +| 同 Turn 接续与新 guard 分开 [LX2] | Turn 内从原 capture 恢复必要事实,新 Turn 获取当前 guard | 传输重试不二次准入、不重复结算、不换成更新 capture | +| 保存文件读取可能没有已准入 Turn [LX8] | 读取/查看不创建 Turn、claim 或 lease;未资格化调用者保持原路径 | 无 Goal/default 发现、无 begin-turn 效果的显式历史文件读取 | +| 父/子 hook 与原生重放资格 [LX1]/[LX3] | 保留子会话拒绝及未知/派生历史的原有回退 | 子会话不能写入或恢复父会话记忆/journal,未知宿主仍未资格化 | +| 必需读取与历史材料资格 [LX4] | 记忆仅为建议,只缩减合格历史支持材料,不缩减当前必需内容 | 待读、实时纠正、未知字段、签名/off/机器场景保留原义务 | +| 绑定路径的保留原文 [LX6] | 只宣称已验证的同机生命周期;来源丢失沿用原依赖/回退 | 验证所声明范围内的重启、清理、删除与撤销 | + +以上是实施验收义务,不是尚未实现功能已经通过兼容测试的结论。本文不向 main 加 parser,也不扩大默认宿主或产品入口。 + ## 6. 替代方案与取舍 | 方案 | 收益 | 成本与建议 | @@ -149,7 +173,7 @@ flowchart LR ## 8. 迁移与回滚 -对一个明确资格化的本地宿主/profile 显式开启,不重写现有来源。shadow 检查阶段保存候选但不减少模型输入;该阶段只验证绑定,不验证效果。随后才在该 profile 上以短表示替换有资格移出的活动上下文材料,保留必需控制与精确展开。 +对一个明确资格化的本地宿主/profile 显式开启,不重写现有来源。shadow 检查阶段保存候选但不减少模型输入;该阶段只验证绑定,不验证效果。随后才在该 profile 上替换满足第 5.2 节资格的历史支持材料,保留必需控制、原读取义务与精确展开。资格未证明时,恢复仅是附加,不得报告为输入缩减。 关闭后停止新的整理与采用,后续输入沿用现有交付。已承诺引用按声明生命周期可读,显式删除/撤销优先。所有宣称范围都要验证跨压缩、进程重启与正常清理后的保留;当前临时 capture 不自动成为持久记忆。必要时扩展现有保留 owner。本文不授权破坏性迁移或来源 GC 变更。 @@ -167,6 +191,8 @@ flowchart LR | A6 | 关闭、无收益、混合版本 | 关闭行为等价,无新增模型 IO;保留未知材料与机器/capture 契约。 | | A7 | 声明的重启/清理范围 | 承诺来源仍可解析;显式删除/撤销覆盖保留时,可见失效。 | | A8 | 打包后开启 → 压缩 → 查看来源/失败 → 关闭 | 现有设置与读回复用 typed owner;产品晋升前资格化受影响 frontend/Lark/CLI。单宿主原型仅为部分交付。 | +| A9 | 同输入下的独立实验开关 | 未配置/关闭、开启但作用域外路径与 main 一致,覆盖设置失败、指令、可接受输入和 IO;仅 Progressive/Delta 开启不启用记忆。 | +| A10 | 记忆独立不可变,原 reader 保留 | 发布、重试与降级后原 capture/reference 字节和读取义务不变;记忆不能确认原生 retention,也不能创建缺失 Turn。 | 结构正确不能证明语义有用。本次文档 PR 不通过任何 A 项。 @@ -197,7 +223,7 @@ flowchart LR | 里程碑 | 可评审成果 | 进入条件与决定性退出证据 | 回滚 | | --- | --- | --- | --- | | M0:评审 | 明确压缩记忆假设、owner 分工与有界 profile | 当前源码核对;在相关步骤前解决 D1–D3;接受设计不启动执行 | 仅文档 | -| M1:一条真实压缩路径 | 确定性稀疏视图在一个支持宿主保留或恢复,并精确展开原文 | 已资格化宿主契约与保留;A1–A7,加实际最终交付和原身份恢复 | 原宿主/恢复交付 | +| M1:一条真实压缩路径 | 确定性稀疏视图在一个支持宿主保留或恢复,并精确展开原文;必需内容完整保留 | 独立局部作用域开关、已资格化宿主契约与保留;A1–A7/A9/A10,加实际最终交付和原身份恢复 | 原宿主/恢复交付 | | M2:效果比较 | B0/T1 成果与完整成本比较;只为已证明缺失的语义知识加入 T2 | 冻结样本/预算/阈值;第 9.2 节证据包含负结果 | 保留 B0 或 T1,不强制晋升 | | M3:产品资格 | 受影响入口可开启、查看、处理失败/恢复与关闭 | A8,混合版本与关闭等价;其他宿主和保留范围分别验收 | 关闭可选视图,保留有效引用 | @@ -211,19 +237,23 @@ flowchart LR | D2 | 哪些发现、来源覆盖、保留范围与稀疏预算:从单 Goal 类型化调查结果与未决区别开始;未记录的精确纠正必须保留。schema/限额依据实测负载,不按字段数审美决定 | 上下文/历史/来源 owner,M1 前 | | D3 | 是否需要语义提取、何时执行:先做确定性 T1;对话独有知识使 T1 不足时,T2 复用有界且验证过的执行边界 | 历史/运行时 owner,语义实现或运行前 | | D4 | 样本、非劣界与实质收益标准:预先声明完整成本与结果标准,不照搬 CodeWiki/Manus 数字,不从更少字节推断成功 | T02/评估 owner,任何模型实验前 | +| D5 | 实验开启/配置:优先显式局部作用域 profile;持久注册设置与 Progressive/Delta 分别资格化,覆盖旧 reader、关闭及作用域外等价 | 配置/原生宿主 owner,M1 开启前 | ## 附录 A:证据与决策记录 -- 静态核对:LoopX 指定来源位于 `0c3b2fd21800`;CodeWiki README/更新指南位于 `7fcf9354f70a5468bc739d849055f8cbab9d46aa`;Manus 使用已注明日期的一手文章。这不认证 Manus 当前闭源内部实现或上游实现质量。 -- 用户确认方向:压缩时保留可识别、更稀疏的结构,参考 AI4Code。Manus 在压缩时写记忆的确切行为仍是线索,不是已验证前提。 +- 静态核对:LoopX 指定来源已对 main `b9f2e2a516b58e62cbb0da6978625388322b5a90` 重查;最初五个源码文件从 `0c3b2fd21800` 起未变化。CodeWiki README/更新指南仍固定为 `7fcf9354f70a5468bc739d849055f8cbab9d46aa`;Manus 使用已注明日期的一手文章。这不认证 Manus 当前闭源内部实现或上游实现质量。 +- 用户确认方向:压缩时保留可识别、更稀疏的结构,参考 AI4Code,属于实验性功能。Manus 在压缩时写记忆的确切行为仍是线索,不是已验证前提。 - AI 提议、尚未批准:schema、字段选取、宿主 profile、生命周期细节、阈值与实施顺序。未实施运行时/默认变更、付费/模型实验、收益测量、宿主安装验收或产品晋升。 - 不替代 RFC、不删除已存字段、不关闭已有验收里程碑。真正执行后才创建对应日期账本。 [CW1]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/README.md [CW2]: https://github.com/FSoft-AI4Code/CodeWiki/blob/7fcf9354f70a5468bc739d849055f8cbab9d46aa/guides/incremental-updates.md [M1]: https://manus.im/blog/Context-Engineering-for-AI-Agents-Lessons-from-Building-Manus -[LX1]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/native_context_lifecycle.ts -[LX2]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context.py -[LX3]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/turn_driver/codex_context_history.py -[LX4]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/progressive_context.ts -[LX5]: https://github.com/loopx-project/loopx/blob/0c3b2fd21800a536ccaa61bad85c4dd8257aad8e/loopx/control_plane/quota/context_delivery.ts +[LX1]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/quota/native_context_lifecycle.ts +[LX2]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/turn_driver/codex_context.py +[LX3]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/turn_driver/codex_context_history.py +[LX4]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/quota/progressive_context.ts +[LX5]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/quota/context_delivery.ts +[LX6]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/control_plane/turn_driver/decision_capture.py +[LX7]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/capabilities/machine_configuration/context_delivery.py +[LX8]: https://github.com/loopx-project/loopx/blob/b9f2e2a516b58e62cbb0da6978625388322b5a90/loopx/cli_commands/context_machine.py From e5faf0afdf7047fd55d0869044d15cd314881d4a Mon Sep 17 00:00:00 2001 From: "lusendong.6789" Date: Tue, 17 Nov 2026 01:25:59 +0800 Subject: [PATCH 3/4] feat(context): add experimental compaction memory and Workbench opt-in Signed-off-by: lusendong.6789 --- .../smoke/compaction-memory-browser-smoke.mjs | 119 +++++++++ .../capability-localization.ts | 2 + .../machine-configuration-settings.tsx | 46 +++- docs/architecture/rfcs/README.md | 16 +- docs/architecture/rfcs/STATUS.md | 2 +- docs/architecture/rfcs/STATUS.zh-CN.md | 2 +- .../2026-11-17-native-kernel-and-workbench.md | 70 ++++++ ...11-17-native-kernel-and-workbench.zh-CN.md | 54 +++++ .../sparse-compaction-working-memory-v0.md | 36 ++- ...arse-compaction-working-memory-v0.zh-CN.md | 36 ++- .../assets/compaction-memory-narrow.png | Bin 0 -> 47940 bytes .../assets/compaction-memory-off.png | Bin 0 -> 95279 bytes .../reference/assets/compaction-memory-on.png | Bin 0 -> 95260 bytes docs/reference/required-work-context.md | 71 ++++++ loopx/capabilities/configuration_ui.py | 5 + .../machine_configuration/builtins.py | 5 + .../compaction_memory.py | 47 ++++ loopx/cli_commands/quota_capture.py | 9 + .../control_plane/quota/compaction_memory.ts | 80 ++++++ loopx/control_plane/quota/turn_envelope.ts | 2 + .../turn_driver/compaction_memory.py | 129 ++++++++++ .../test_machine_configuration_contract.py | 1 + .../test_codex_context_boundary.py | 16 +- tests/control_plane/test_compaction_memory.py | 229 ++++++++++++++++++ .../compaction_memory.test.ts | 60 +++++ tests/test_chat_machine_configuration_api.py | 5 +- 26 files changed, 996 insertions(+), 46 deletions(-) create mode 100644 apps/presentation/dashboard/smoke/compaction-memory-browser-smoke.mjs create mode 100644 docs/architecture/rfcs/ledger/sparse-compaction-working-memory-v0/2026-11-17-native-kernel-and-workbench.md create mode 100644 docs/architecture/rfcs/ledger/sparse-compaction-working-memory-v0/2026-11-17-native-kernel-and-workbench.zh-CN.md create mode 100644 docs/reference/assets/compaction-memory-narrow.png create mode 100644 docs/reference/assets/compaction-memory-off.png create mode 100644 docs/reference/assets/compaction-memory-on.png create mode 100644 loopx/capabilities/machine_configuration/compaction_memory.py create mode 100644 loopx/control_plane/quota/compaction_memory.ts create mode 100644 loopx/control_plane/turn_driver/compaction_memory.py create mode 100644 tests/control_plane/test_compaction_memory.py create mode 100644 tests/control_plane_ts/compaction_memory.test.ts diff --git a/apps/presentation/dashboard/smoke/compaction-memory-browser-smoke.mjs b/apps/presentation/dashboard/smoke/compaction-memory-browser-smoke.mjs new file mode 100644 index 0000000000..9e929b2566 --- /dev/null +++ b/apps/presentation/dashboard/smoke/compaction-memory-browser-smoke.mjs @@ -0,0 +1,119 @@ +// PR-scoped regression: a packaged switch uses real preview/apply/readback, +// survives reload, rejects stale writes and removes its opt-in on disablement. +// Isolated machine, empty registry, unavailable native host; no model calls. +import assert from "node:assert/strict"; +import {spawn} from "node:child_process"; +import {mkdtemp, mkdir, rm, writeFile} from "node:fs/promises"; +import {tmpdir} from "node:os"; +import {join, resolve} from "node:path"; +import {resolveTestPython} from "../../../../scripts/test-python.mjs"; +import {launchBrowser, loadPlaywright, waitForHttp} from "../../../../examples/dashboard-browser-smoke-support.mjs"; + +const repoRoot = resolve(import.meta.dirname, "../../../.."); +const root = await mkdtemp(join(tmpdir(), "loopx-compaction-preference-")); +const port = Number(process.env.LOOPX_COMPACTION_MEMORY_PORT ?? 5414); +const screenshots = process.env.LOOPX_COMPACTION_MEMORY_SCREENSHOTS; +const registry = join(root, "registry.json"); +await writeFile(registry, '{"goals":[]}'); +await mkdir(join(root, "home")); +if (screenshots) await mkdir(screenshots, {recursive: true}); +const server = spawn(resolveTestPython({repoRoot}), ["-m", "loopx.cli", "--registry", registry, + "--runtime-root", join(root, "runtime"), "chat", "--port", String(port), "--no-open", + "--codex-bin", join(root, "unavailable-native-host"), "--assets-dir", join(repoRoot, "loopx/web/chat")], { + cwd: root, env: {...process.env, HOME: join(root, "home"), PYTHONPATH: repoRoot, LOOPX_USAGE_PING: "0"}, + stdio: ["ignore", "pipe", "pipe"], +}); +let serverError = "", browser; +for (const stream of [server.stdout, server.stderr]) stream.on("data", chunk => {serverError += String(chunk);}); +try { + const base = `http://127.0.0.1:${port}`; + await waitForHttp(`${base}/chat/`).catch(error => {throw new Error(`${error.message}\n${serverError}`);}); + browser = await launchBrowser(loadPlaywright().chromium); + const page = await browser.newPage({locale: "en-US", viewport: {width: 1440, height: 1000}}); + const workRequests = []; + page.on("request", request => { + if (request.method() === "POST") { + const path = new URL(request.url()).pathname; + if (path === "/api/chat/sessions" || /^\/api\/chat\/sessions\/[^/]+\/turns$/u.test(path)) workRequests.push(path); + } + }); + const open = async () => { + await page.goto(`${base}/chat/?settings_scope=machine&settings_tab=capabilities`, {waitUntil: "networkidle"}); + await page.getByText("Compaction working memory (experimental)", {exact: true}).first().click(); + }; + const toggle = page.getByRole("switch", {name: "Enable experimental compaction working memory"}); + const configuration = async () => (await (await page.request.get(`${base}/api/chat/machine-configuration`)).json()).machine_configuration; + const capture = async name => { + if (screenshots) await page.screenshot({path: join(screenshots, name)}); + }; + await open(); + assert.equal(await toggle.isChecked(), false); + await capture("desktop-off.png"); + let beforeSave = workRequests.length; + await toggle.click(); + await page.getByText("Compaction working memory preference saved.", {exact: true}).waitFor(); + assert.equal(workRequests.length, beforeSave, "Enabling does not create a conversation or Turn"); + assert.equal(await toggle.isChecked(), true); + assert.equal((await configuration()).namespaces.compaction_memory.enabled, true); + await open(); + assert.equal(await toggle.isChecked(), true, "Persisted readback survives a fresh page"); + await capture("desktop-on.png"); + await page.setViewportSize({width: 430, height: 932}); + assert.equal(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth), true); + await capture("narrow-on.png"); + await page.setViewportSize({width: 1440, height: 1000}); + + // Keep the actual backend and invalidate only the request's CAS expectation. + const apply = "**/api/chat/machine-configuration/apply"; + await page.route(apply, route => route.continue({postData: JSON.stringify({ + ...route.request().postDataJSON(), expected_plan_revision: `sha256:${"0".repeat(64)}`, + })})); + beforeSave = workRequests.length; + await toggle.click(); + await page.getByText(/machine-configuration plan revision changed/u).waitFor(); + assert.equal(workRequests.length, beforeSave, "A rejected setting starts no work"); + assert.equal(await toggle.isChecked(), true, "A rejected save must not look disabled"); + assert.equal((await configuration()).namespaces.compaction_memory.enabled, true); + await capture("desktop-rejected.png"); + await page.unroute(apply); + beforeSave = workRequests.length; + await toggle.click(); + await page.getByText("Compaction working memory preference saved.", {exact: true}).waitFor(); + assert.equal(workRequests.length, beforeSave, "Disabling starts no work"); + assert.equal(await toggle.isChecked(), false); + assert.equal((await configuration())?.namespaces.compaction_memory, undefined, "Disable restores older-editor compatibility"); + await open(); + assert.equal(await toggle.isChecked(), false); + // Exercise the shared save helper with the pre-existing switches while the + // experiment is absent. Each setting preserves the other's confirmed value. + await page.getByText("Progressive context", {exact: true}).first().click(); + const progressive = page.getByRole("switch", {name: "Read context progressively"}); + const delta = page.getByRole("switch", {name: "Use cross-turn delta automatically on supported hosts"}); + assert.equal(await progressive.isChecked(), true); + assert.equal(await delta.isChecked(), true); + await progressive.click(); + await page.getByText("Progressive reads preference saved.", {exact: true}).waitFor(); + assert.equal((await configuration()).namespaces.context_delivery.mode, "off"); + assert.equal(await delta.isChecked(), true); + await delta.click(); + await page.getByText("Cross-turn delta preference saved.", {exact: true}).waitFor(); + assert.equal((await configuration()).namespaces.context_delivery.delta_delivery, "off"); + assert.equal(await progressive.isChecked(), false); + assert.equal((await configuration()).namespaces.compaction_memory, undefined); + await page.evaluate(() => localStorage.setItem("loopx-pw-locale", "zh-CN")); + await page.reload({waitUntil: "networkidle"}); + await page.getByText("压缩工作记忆(实验)", {exact: true}).first().click(); + assert.equal(await page.getByRole("switch", {name: "启用实验性压缩工作记忆"}).isChecked(), false); + await capture("chinese-off.png"); + // Existing Workbench entry may create Session metadata; no Turn is dispatched. + assert.equal(workRequests.some(path => path.endsWith("/turns")), false); + console.log("compaction working memory: packaged enable/reload/stale-save/disable/Chinese readback passed"); +} finally { + await browser?.close(); + if (server.exitCode === null) { + const exited = new Promise(resolveExit => server.once("exit", resolveExit)); + server.kill(); + await exited; + } + await rm(root, {recursive: true, force: true}); +} diff --git a/apps/presentation/dashboard/src/features/personal-workspace/capability-localization.ts b/apps/presentation/dashboard/src/features/personal-workspace/capability-localization.ts index bb4d4f76dc..7ea0c17994 100644 --- a/apps/presentation/dashboard/src/features/personal-workspace/capability-localization.ts +++ b/apps/presentation/dashboard/src/features/personal-workspace/capability-localization.ts @@ -12,6 +12,7 @@ type FieldCopy = Record> = { en: { + compaction_memory: {displayName: "Compaction working memory (experimental)", description: "Restore source-backed work notes after context compaction."}, context_delivery: {displayName: "Progressive context", description: "Read current requirements before supporting material. Supported hosts can reuse unchanged context independently."}, codex_chat: {displayName: "Codex Goal conversation defaults", description: "Choose the native Codex profile, model, speed tier and reasoning effort for new Goal conversations. Existing conversations keep their original history. This does not start or reconfigure an active Agent Loop, worker or steward."}, decision_context: {displayName: "Find evidence", description: "Find advisory evidence with a temporary private profile. OpenViking and BM25 are retrieval implementations; this page does not save a binding or enable automatic memory."}, @@ -82,6 +83,7 @@ const capabilityCopy: Record> = { }, }, "zh-CN": { + compaction_memory: {displayName: "压缩工作记忆(实验)", description: "上下文压缩后恢复有来源的工作要点。"}, context_delivery: {displayName: "渐进上下文", description: "先展示当前目标与约束,按需读取材料;支持的宿主可独立复用跨轮上下文。"}, codex_chat: {displayName: "Codex Goal 对话默认值", description: "分别选择 Codex 配置来源、模型、速度档和推理强度,作用于本机的新 Goal 对话。已有对话保留原历史;不会启动或重配正在运行的 Agent Loop、工作 Agent 或管家。"}, decision_context: {displayName: "资料召回", description: "通过临时私有配置查找参考证据。OpenViking、BM25 是检索实现;本页不保存绑定,也不启用自动记忆。"}, diff --git a/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx b/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx index db40e45e4c..73481eb4f4 100644 --- a/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx +++ b/apps/presentation/dashboard/src/features/personal-workspace/machine-configuration-settings.tsx @@ -281,15 +281,32 @@ export function MachineConfigurationSettings({ section, onChanged }: { async function setContextDelivery(mode: "off" | "on" | "auto", key: "mode" | "delta_delivery" = "mode") { if (busy || !editorAvailable || selected?.capability_id !== "context_delivery" || !selected.machine_namespace) return; - const namespace = selected.machine_namespace; const configuration: Record = {...selected.default, ...selectedCurrent, schema_version: selected.default?.schema_version ?? selectedCurrent?.schema_version, [key]: mode}; + const label = key === "delta_delivery" + ? locale === "zh-CN" ? "跨轮差分" : "Cross-turn delta" + : locale === "zh-CN" ? "渐进读取" : "Progressive reads"; + await saveImmediatePreference(configuration, label); + } + + async function setCompactionMemory(enabled: boolean) { + if (busy || !editorAvailable || selected?.capability_id !== "compaction_memory") return; + // Removing the opt-in namespace also restores compatibility with older editors. + await saveImmediatePreference(enabled ? {...selected.default, enabled: true} : null, + locale === "zh-CN" ? "压缩工作记忆" : "Compaction working memory"); + } + + async function saveImmediatePreference(configuration: Record | null, label: string) { + if (busy || !editorAvailable || !selected?.machine_namespace) return; + const namespace = selected.machine_namespace; const generation = editorGeneration.current; setBusy("apply"); setError(null); setNotice(null); try { - const plan = await previewMachineConfiguration(namespace, configuration); + const plan = configuration === null ? await previewMachineConfigurationRemoval(namespace) + : await previewMachineConfiguration(namespace, configuration); if (generation !== editorGeneration.current) return; - await applyMachineConfiguration(namespace, configuration, plan.plan_revision); + if (configuration === null) await applyMachineConfigurationRemoval(namespace, plan.plan_revision); + else await applyMachineConfiguration(namespace, configuration, plan.plan_revision); if (generation !== editorGeneration.current) { onChanged?.(); return; } setReadbackPending(selected.display_name); const next = await fetchMachineConfiguration(); @@ -297,13 +314,11 @@ export function MachineConfigurationSettings({ section, onChanged }: { setInspection(next); setReadbackPending(null); const saved = next.machine_configuration?.namespaces[namespace]; - if (saved?.mode !== configuration.mode || saved?.delta_delivery !== configuration.delta_delivery) { + if (next.status === "invalid" || (configuration === null ? saved !== undefined + : Object.entries(configuration).some(([key, value]) => saved?.[key] !== value))) { throw new Error(locale === "zh-CN" ? "保存后的配置已变化,请刷新后重试。" : "The saved configuration changed. Refresh and retry."); } - const targetLabel = key === "delta_delivery" - ? locale === "zh-CN" ? "跨轮差分" : "Cross-turn delta" - : locale === "zh-CN" ? "渐进读取" : "Progressive reads"; - setNotice(locale === "zh-CN" ? `${targetLabel}偏好已保存。` : `${targetLabel} preference saved.`); + setNotice(locale === "zh-CN" ? `${label}偏好已保存。` : `${label} preference saved.`); onChanged?.(); } catch (cause) { if (generation === editorGeneration.current) setError(cause instanceof Error ? cause.message : t("machine.applyError")); @@ -546,7 +561,18 @@ export function MachineConfigurationSettings({ section, onChanged }: { ? "渐进读取先提供当前要求,支持材料按需展开,适用于所有宿主。跨轮差分独立控制:仅在受支持的 POSIX Codex App/SSH、benchmark 心跳已保留完整旧上下文时自动使用,否则恢复完整当前输入。关闭偏好和实验显式关闭均继续生效。保存不会安装 hook、启动实验或证明当前会话已采用差分。" : "Progressive reads present current requirements before expandable supporting material on every host. Cross-turn delta is independent: automatic reuse requires a supported POSIX Codex App/SSH or benchmark heartbeat and complete retained context; otherwise the current full input is restored. Saved off preferences and explicit experiment opt-outs remain effective. Saving installs no hook, starts no experiment and does not prove current-session delta use."}

: null} - {editorAvailable && selected.capability_id !== "context_delivery" ? <>{editorMode === "json" || !selected.configuration_editor.fields.some((field) => field.key === "enabled" && field.input_kind === "boolean") ?
+ {selected.capability_id === "compaction_memory" ?
+
+

{locale === "zh-CN" + ? "仅作用于本机已经支持上下文恢复的原生根会话。压缩时保留有来源的工作标题、短注记及引用,之后恢复;不增加模型调用,不安装 hook,也不省略当前必读要求。关闭会移除实验设置以支持旧版编辑器,已保存的引用仍保留。尚未验证任务效果与完整成本收益。" + : "Applies to this device's native root sessions that already support context recovery. Keeps source-bound work titles, short notes and references at compaction and restores them afterward. No additional model calls, hook installation or skipped required reads. Disabling removes the experiment setting for older editors and retains saved references. Task effectiveness and total-cost gains remain unverified."}

+
: null} + {editorAvailable && selected.capability_id !== "context_delivery" && selected.capability_id !== "compaction_memory" ? <>{editorMode === "json" || !selected.configuration_editor.fields.some((field) => field.key === "enabled" && field.input_kind === "boolean") ?
@@ -595,7 +621,7 @@ export function MachineConfigurationSettings({ section, onChanged }: { ) : null} - {editorAvailable && selected.capability_id !== "context_delivery" ?