oceanbase / oceanbase/powercontext
RFC: define quality-aware Memory retrieval, forgetting, and reversible lifecycle
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 1.1k
- Forks
- 212
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 199
Description
Feature description
This issue proposes a concrete direction for a future RFC: quality-aware Memory retrieval and a reversible Memory lifecycle.
The proposal addresses one Memory entry from admission through retrieval, maintenance, retirement, recovery, and eventual capacity observation. It preserves PowerContext's existing immutable entry text, revision lineage, and exact-citation semantics. The purpose of this issue is to review the design before an RFC is authored; the implementation, public API, and numeric defaults are not being adopted by this issue alone.
Motivation
The current Memory write path is broadly:
evidence → extraction / explicit input / deterministic adapter
→ structural and evidence-bound validation
→ exact content-hash deduplication and no-op check
→ revision commit and active-head projection rebuild
The current read path is broadly:
FTS and vector recall → admission → lifecycle-validity filtering → RRF over an explicitly bounded pool
→ quality reorder → optional listwise rerank → final limit → Context Pack candidate/byte budget
This has three observable gaps:
- No quality signal. A durable constraint such as “documentation changes must run
make docs-test” and a one-off failed experiment can have equal status in the active retrieval surface. Extraction guidance may say “retain cross-task-useful information,” but that rule cannot be calibrated, traced, or used by ranking and maintenance. - No semantic near-duplicate control or deterministic validity policy. Exact hashes catch identical text only. Paraphrased copies of one instruction all remain active and repeatedly occupy top-k slots. An entry stays active until someone explicitly retires it, and ordinary current-state recall has no explicit, quality-independent rule for withholding a known inactive or superseded record.
- No compaction decision. It is unclear whether the remedy should be body summarization, write-side suppression, retrieval ranking, reversible retirement, or a storage operation. These solve different problems and have different risks.
The key premise is candidate density: reranking can only choose among candidates that entered the pool. A low-value or near-duplicate entry has almost no cost when written, but can occupy a limited retrieval slot for every future related query. The proposed policy is permissive writing without uncontrolled accumulation, quality-aware ranking, and reversible maintenance—not automatic destruction or rewriting of Memory history. CoALA is the conceptual reference for separating working, episodic, semantic, and procedural concerns and tying memory operations to the agent loop; this proposal applies that distinction without introducing a new cognitive architecture. Additional proposer-supplied background: 1, 2, 3.
Proposed solution
Design invariants
- Immutable authority remains intact. Entry body text, Artifact Revisions, evidence citations, and content-hash semantics do not change. New lifecycle data belongs only to a rebuildable active-head projection, alongside FTS and embedding projections.
- No-regression defaults. Existing behavior remains exact when lifecycle features are disabled or neutral:
importance=normal, ranking adjustment disabled, automated deactivation disabled, and semantic maintenance disabled. - Validity is separate from quality. A lifecycle state already determined by PowerContext (
inactiveor explicitlysuperseded) is enforced before RRF and before optional reranking for ordinary current-state recall. This filter does not depend on quality, decay, or a reranker. Exact historical reads remain able to retrieve preserved originals with their lifecycle reason. - Quality is not an admission gate. A low-importance entry remains valid to store and can still be recalled if it is valid for the requested temporal view and satisfies ordinary channel admission. Quality affects ordering and maintenance eligibility only.
- Unknown conflicts fail safe. A semantic conflict without a reliable lifecycle edge, or with unknown/incomparable time, retains both records and exposes
unresolved_conflict; RRF order and relevance are never treated as a proxy for time order. - Automatic actions are explainable and reversible. Every automatic deactivation has a stable reason (for example,
auto_decay:v1) visible through change history.reactivate()restores the original entry version; rollback of side effects from an automatic action is a separate capability and must have an operation record. - Backend semantics must agree. SQLite and OceanBase must expose the same lifecycle projection and ranking behavior. A missing optional capability degrades to lifecycle-disabled behavior rather than backend-specific results.
1. Write-time quality signals
Keep MemoryEntryVersion unchanged. Extend the rebuildable memory_entry_heads projection with derived metadata similar to:
importance INTEGER NOT NULL DEFAULT 1 # low=0, normal=1, high=2, critical=3
evidence_strength TEXT NOT NULL DEFAULT 'weak' # weak | direct
validity TEXT NOT NULL DEFAULT 'current' # current | inactive | superseded | unresolved_conflict
validity_reason TEXT NULL
successor_entry_id TEXT NULL
recorded_at/effective_at DATETIME NULL # explicit unknown state when absent
provenance_summary bounded counts/categories only
created_at DATETIME NOT NULL
revised_at DATETIME NULL
last_recalled_at DATETIME NULL # optional later enhancement
recall_count INTEGER NOT NULL DEFAULT 0 # optional later enhancement
These fields do not participate in the entry content hash. They are computed during add/revise projection work, reused when an unchanged entry projection is reused, and can be rebuilt from authoritative revisions plus bounded lifecycle observations. Old data begins with neutral defaults; freshness behavior stays disabled when the necessary time information is unknown.
Stage-1 quality keeps four independent dimensions: provenance/verification, importance, novelty, and current-state status. They have separate purposes and must not be collapsed into one model score:
- provenance/verification is a reconstructible Source-level declaration of authority and verification state;
- importance is a deterministic, version-scoped estimate of operational salience;
- novelty records exact/near-duplicate relationships and evidence increments, without lowering importance by itself; and
- current-state status determines whether a query-gated freshness hint is eligible.
The first dimension is not present in current models. MemoryEntryVersion retains sources, artifacts, predecessor version identity, and created_in_revision, while Source and SourceDefinition have no authority or verification field. A new reconstructible Source/SourceDefinition adapter contract for that declaration is therefore a prerequisite for stage 1, not a field inferred from SourceRef, evidence type, or an LLM. Until that contract lands, stage-1 quality ranking remains disabled rather than substituting a verified_source_bonus.
Stage 1 has no model salience output and no model ranking bonus. Extraction may still use its existing model behavior to extract Memory content, but it does not emit importance_band or importance_reason for this policy. Generative Agents supports treating relevance, recency, and importance as separate signals; this proposal does not import its free-form 1–10 importance mechanism.
The deterministic importance component is a calibration seed, not a final constant:
base(kind): fact=1, preference=1, decision=2, constraint=2, working_note=0
updates_state: +1 when a changed revise updates current state
thin_penalty: -1 for insufficiently self-contained content
importance = clamp(base + updates_state - thin_penalty, 0..3)
caps (take the lowest): weak evidence, session tier, or an uncorroborated
working note may not exceed normal.
The score is a snapshot for the entry body version: it is recomputed on an add or evidence-backed revise, not periodically rejudged across the whole store. Importance can rise through an explicit revise, later corroborating evidence, or an explicit override; it can fall when a new revision supersedes the previous state. Validity is maintained separately and is never inferred from the quality score.
2. Bounded near-duplicate suppression at admission
Move beyond byte-identical deduplication with three progressively more expensive checks, scoped to the target Memory:
normalized content hash → bounded lexical candidates → optional top-k semantic neighbors
For a candidate new entry, the following are calibration seeds only:
cosine >= τ_same
→ duplicate proposal: do not add or discard automatically without direct evidence/review
τ_similar <= cosine < τ_same
→ near-duplicate relation/proposal; retain both entries unless an approved
semantic/revision path establishes the successor and evidence union
The existing extraction call may optionally identify near_duplicate_of=<entry_id>, but the server verifies the claim using the bounded candidate check before acting on it. Similarity alone must not lower importance to low, because that would indirectly turn a relationship finding into an automatic-deactivation signal. Explicit writes and deterministic adapters may opt out when they already establish idempotency. Bulk import may defer checks to an offline health pass.
Deployments without embeddings must fail safe: they can use the model's structured self-report plus a review gate, but must not automatically merge or discard semantically similar entries. All similarity cutoffs, including values discussed in ProMem or other early implementations, are calibration inputs rather than adopted constants. VoiceMem supports the candidate-density hypothesis under small retrieval budgets; it is not evidence for time decay or freshness ranking.
3. Quality-aware retrieval and L0 soft forgetting
Validity enforcement and quality ranking are different stages. For ordinary current-state recall, a record whose inactive/revoked state or explicit supersession edge is already known must be withheld before RRF and before any optional listwise reranker. Exact historical reads may request the preserved predecessor and its lifecycle reason. A semantic conflict without a reliable lifecycle relation is not adjudicated by this stage: retain both records, annotate unresolved_conflict, and do not infer temporal order from retrieval relevance.
The stage-1 logical pipeline is:
per-channel search candidates
→ FTS/vector admission
→ deterministic validity filter for the requested temporal view
→ RRF and coarse-pool truncation (fixed membership)
→ stable quality/currentness reorder within that fixed pool, at most ±2 ranks
→ optional listwise reranker over the same fixed members
→ final limit
→ Context Pack candidate-count and byte-budget truncation
The current implementation already makes this boundary concrete: fuse_rankings(fts, vector, limit) truncates inside fusion.py with [:limit], while service.py passes coarse_limit. Stage 1 applies the bounded quality reorder only after this call. It cannot extend fusion, run before coarse-pool truncation, or otherwise bring a pool-external item to the reranker. A membership-changing quality mechanism is explicitly out of scope for this stage and requires a separately evaluated proposal.
This composes with the disabled-by-default recall sufficiency gate in #1596 / RFC 1560. A gate expansion is a new, bounded search issuance that may relax its admission floor; it is not a quality-ranking membership change. For every issued round, lifecycle validity filtering occurs after that round's channel admission and before RRF, then quality reorders only that round's already truncated coarse pool. Quality policy must not alter AdmissionFloor, gate rounds, query-embedding reuse, admission/cost accounting, or the in-process RecallEffort sink. MemoryRankingTrace remains separate from the gate's aggregate effort trace.
Use a bounded rank adjustment, not a multiplicative band:
quality_order = stable rank shift of at most ±2 within the fixed,
validity-filtered RRF pool, using the independent dimensions
defined in §1 and query-gated freshness where eligible
The shift bound is a calibration parameter and must be small relative to the measured RRF spread. In the current code, _RRF_CONSTANT = 60; ordinary limit=10 requests ask each backend channel for at most max(10*4, 32)=40 candidates, while prepare_context uses 16 candidates and therefore requests at most 64 per channel. The single-channel rank-1 to rank-64 RRF ratio is only about 2.03x (and rank-1 to rank-10 is about 1.15x), so the former 0.5..2.0 multiplier range could reorder essentially the whole pool rather than act as a tiebreaker. With the default reranker candidate limit of 30, the service requests at most 120 per channel and fuses a 30-item coarse pool; the rank-1 to rank-30 ratio is about 1.48x.
Freshness remains separate from importance and is only a query-gated ranking input:
decay = α + (1 - α) × 2^(-Δt / half_life)
α and half_life are seed values for calibration, not fixed policy.
It is enabled only when the entry represents current-state material and the query expresses current/temporal intent. Historical facts and completed decisions keep a neutral freshness factor. Use the evidence event time when known, otherwise revised_at/created_at; an unknown time means no freshness penalty. Freshness cannot lower a high-authority or critical entry, and it is not multiplied by importance. Generative Agents motivates signal separation, while its sandbox-hour retrieval anchor and free-form importance values are not being copied here. mem0's recency discussion is background for a query-gated freshness experiment, not a deletion rule.
MemoryRankingTrace is a proposed new internal carrier, not an existing master feature and not a reuse of MemoryRerankTrace. It records the fixed baseline member identities, the quality-adjusted ordering, applied rules, bounded parameters, and the invariant membership_changed=false; it does not model a membership-changing path in stage 1. The current MemoryHit contains only exact identity, text, public RRF score, and matched channels; MemoryRerankTrace exists only when a reranker is enabled. The public score therefore remains the baseline RRF score, and no HTTP field is required in the first stage.
4. Recall feedback without search-path writes
Selection frequency could eventually make freshness more realistic, but ordinary search currently does not lock or write. The first stage therefore uses revision age as an activity proxy.
A later optional design may asynchronously append bounded (scope, memory, entry, recalled_at) events to a small recall-event table, then fold them into the derived projection in a maintenance job. It must be batched, bounded, privacy-conscious, and independent of search success. ACT-R is a theoretical motivation for a future usage-event stream: its base-level is a power-law sum over multiple practice timestamps, not the single exponential age proxy proposed here. A low-authority record promoted merely because it is frequently accessed is a known governance risk, so frequency must be introduced together with authority/verification signals, not as a replacement for them.
5. L1 reversible automated deactivation and lifecycle tiers
A disabled-by-default scheduler job may scan active entries with a dry-run-first configuration. A candidate is automatically deactivated only when all conditions hold:
- it is active;
- its importance is at or below the configured floor (initially only
low; neverhighorcritical); - it is older than its applicable retention window, based on creation/revision and eventually validated recall activity;
- it is not explicitly protected or pinned;
- it is not a session-tier entry handled by an explicit session/task boundary;
- it has no unresolved inbound references or unhandled derived views that would break evidence lineage.
The initial seed retention window is 180 days and must be evaluated, not assumed. A match calls existing forget(..., reason="auto_decay:v1"), producing an ordinary auditable deactivate revision. reactivate() restores that exact entry version, rebuilds its active projection, and starts a new lifecycle interval. This is reversible deactivation, not rollback: it does not undo summaries, promotions, consolidations, or other side effects already caused by the entry. Any future rollbackable automatic action needs an operation record and an explicit list of non-rollbackable effects. Runs are bounded per scope, use the normal scope lock and head-CAS discipline, and remain idempotent.
Derived lifetime tiers make temporary material explicit without taking ownership of raw transcripts:
session: caller-marked notes that deterministically deactivate on session/task completion withreason="session_end", but remain recoverable;short: temporary working notes with a shorter retention window;long: durable constraints, decisions, and historical facts using the normal protection and retention path.
This time-scale distinction is comparable to mem0's memory-type model and the bounded core/recall/archive layers of MemGPT / Letta, while preserving PowerContext's immutable entry authority.
Time alone misses a burst of fresh working notes that has already crowded a candidate pool. A capacity trigger therefore complements age scanning: when low-importance growth or near-duplicate density reaches a configured threshold (a seed example is every 50 new low entries), generate a bounded cleanup proposal. Capacity numbers are operational seeds tied to neither current RRF depth nor the Context Pack byte budget; they must be calibrated and are not evidence-backed defaults. The proposal may identify similar entries, meaningless notes, or contradictions, but requires review before any high-impact change.
Explicit user operations always win: explicitly retired entries are not revisited by automatic maintenance; a manual restore starts a new retention interval; a user revise refreshes its derived time and quality; future pin/protection controls prevent automation from touching the entry.
6. L2 semantic maintenance behind a review gate
Semantic operations have a higher cost of error and must remain disabled unless a review workflow is available. RFC 0050 explicitly keeps ordinary Memory writes direct while Experience and Skill require Review. L2 is therefore a Memory-specific policy extension to the existing candidate mechanism: ordinary remember/forget operations remain direct, while consolidation, inferred supersession, and promotion proposals require review. Approval alone invokes the existing remember(revise) and forget primitives.
Two proposal types are in scope:
- Near-duplicate consolidation: revise one entry with the evidence union and deactivate the redundant entry only after approval. Similarity alone is not sufficient evidence.
- Contradiction handling, supersede-first: when newer evidence has a reliable explicit lifecycle relation to an old active entry, preserve both entries, record the old state as
supersededwith successor identity/reason, and withhold the old record from ordinary current-state recall before RRF. Exact historical reads can still retrieve it. When no reliable relation or comparable time exists, preserve both records and markunresolved_conflict; do not arbitrarily rank one as newer.
The read path must carry enough bounded evidence for this decision without requiring an agent to infer temporal authority from two plain texts:
validity = current | inactive | superseded | unresolved_conflict
validity_reason / successor identity when known
recorded/effective time, including explicit unknown
bounded provenance summary (for example, source/artifact reference counts)
The Context Pack should label retained current/history/conflict evidence. The trace can preserve the full decision without exposing Memory content or changing the existing public RRF score. Every proposal must carry precise affected entry versions, its similarity or contradiction evidence, and the proposed body/state changes. Approval is required before any Revision exists. Consolidation must preserve the evidence union and names, numbers, dates, and other specific details. A rewrite must be driven by new evidence; the system must not repeatedly “polish” already stored bodies, because repeated lossy rewriting eventually erodes exact facts. Topic-level rolling summaries belong to Topic Memory, not to immutable individual Memory entry bodies.
At task/session boundaries, a consolidation pass may propose promotion of a working_note only after the same theme recurs across independent windows. A single occurrence stays short-lived; repeated evidence can create an evidence-backed promotion proposal to a durable kind. A non-model deployment can use a deterministic repeated-reference rule. This makes “becoming more valuable” a reviewed, evidence-based process rather than a periodic model reclassification. Letta's sleep-time compute work is the relevant precedent for placing consolidation outside the critical interaction path.
The paper boundary is intentional: ProMem supports later extract-align-verify work; Selective Memory supports reversible retirement and write-side candidate control; MERIT motivates action-level evaluation; LazyMem motivates preserving raw Source/Artifact evidence; UMA is out of scope because its learned CRUD policy requires an automatically scored task distribution; Revoked motivates deterministic retrieval-time enforcement of known validity; and MemoryLACE supports bounded lifecycle edges without body compaction.
7. Compression decision and capacity boundary
This proposal deliberately rejects body-level summary/compression. Memory entries are already bounded, self-contained texts designed for independent interpretation and exact citation. Summarizing them risks losing dates, numbers, names, and auditability without solving the primary retrieval problem. Rate–Distortion Theory for Agent Memory Compaction treats KV eviction, prompt pruning, bounded state, and agent-memory consolidation as one cross-layer budget problem. It warns that query-unknown, irreversible pre-query discarding can remove information later needed, and that repeated compaction is rarely measured under one shared budget. This supports preserving authoritative evidence and measuring all budget layers, rather than claiming the paper separates two unrelated problems.
The priority order is:
prevent redundant writes → enforce known validity for the requested temporal view
→ rank the valid active pool by quality/currentness
→ reversibly remove eligible low-value entries
→ observe inactive/manifest growth
→ design a separate physical compaction operation only when data warrants it
The implementation should distinguish three granularities: the authoritative entry body, discardable derived views, and Topic Memory summaries. Only the latter two may be compacted by a future policy; this issue does not authorize rewriting authoritative Memory bodies.
Expose inventory such as active_count, inactive_count, manifest_bytes, importance distribution, automatic-deactivation counts by reason, and near-duplicate rejections. A seed operational alert is inactive share above 60% with more than 1,000 total entries. It is an alert, not an automatic physical compaction command; these values are calibration seeds unrelated to current RRF depth or Context Pack byte budget. Manifest/tombstone archival must be designed separately because it affects history and exact citation resolution; it belongs alongside #1321 rather than being smuggled into retrieval maintenance.
Compatibility and API impact
- No change to entry body, Revision, manifest, evidence, Handoff citation, search identity, or existing public score semantics.
- No endpoint is required for the first stage. A proposed internal hit/context annotation and
MemoryRankingTracemay be introduced before any HTTP/MCP/CLI surface; the current HTTPSearchMemoryResponsedoes not expose rerank trace, and the public RRF score remains unchanged. - Lifecycle configuration is opt-in. Defaults preserve present behavior. User-owned project instruction files such as
CLAUDE.mdandAGENTS.mdare a separate, file-backed form of durable context (example discussion); they remain source-authoritative and are outside automatic Memory lifecycle control. - Existing data migrates with neutral derived values; derived projection rebuild must be supported on SQLite and OceanBase.
- Statistics gain only bounded counts and decision categories, never Memory content, prompts, responses, or vectors.
Evaluation and calibration
Mechanism shape is proposed here; numeric values are seeds only. Before enabling any non-neutral default, evaluate the following with RFC 0080 and RFC 1229 conventions:
- Quality-ranking benefit: compare Recall@k, MRR, and downstream answer/task results with and without quality ordering under the same Context Pack byte budget and judge policy.
- Freshness safety: use a synthetic corpus containing stale current state, durable constraints, and historical facts. Verify that current-state material can decline appropriately while historical facts do not receive a generic newer-wins penalty.
- Candidate-density interference: hold a relevant entry fixed, inject increasing counts of near-duplicate or low-value entries, and measure the top-k degradation curve. Use it to calibrate duplicate thresholds and bounded rank shifts.
- L1 dry-run precision: inspect proposed automatic deactivations for false retirement before enabling mutation. Report protection, inbound-reference, restore, and error behavior.
- Consolidation quality: simulate cross-task recurrence to measure promotion proposal precision/recall; require explicit approval and verify no Revision appears before approval.
- Cost and latency: report answer quality x injected bytes x latency/cost and a Top-1...Top-100 sweep. Lifecycle-disabled benchmarks must match current behavior.
- Full-context reference: report a full-material reference separately from the baseline, so failures of retrieval/attribution are not mistaken for model reading failures.
- Temporal validity conformance: with FTS/vector/hybrid and reranker on/off, verify that a same-
entry_idrevise returns only the successor for ordinary recall while an exact historical read returns the predecessor; directly inactive/superseded entries cannot reach the reranker; and unknown/incomparable-time contradictions remain present and markedunresolved_conflict. - Longitudinal task regression: run a Ledger-QA-style sequence of N revisions and score both "what is current?" and "what was true at revision/time T?" by final tool/world state as well as retrieval metrics.
- Cross-backend and poisoning conformance: verify derived projections, ordering, lifecycle reasons, recovery, and rebuilds on SQLite and OceanBase. Add low-authority/high-frequency poisoning cases and report retrieval, task, safety, and cost separately. Jointly calibrate with #1556 that the fixed-membership quality reorder preserves the reranker's member set.
If calibration yields no stable benefit, quality ordering and decay remain off; existing RRF and optional listwise reranking remain the fallback.
Suggested delivery sequence
- Metadata and ranking: derived quality projection, trace/statistics, opt-in quality boost, and L0 age proxy; no search-path writes and no automated state mutation.
- Write-side suppression and dry-run L1: bounded near-duplicate admission, inventory, lifecycle tiers, capacity-trigger proposals, and automated-deactivation dry run.
- Review-gated L2: semantic consolidation, supersession proposals, repeated-pattern promotion, and the review integration. Physical manifest compaction remains a separate RFC if observation shows it is needed.
Each stage is independently deployable and reversible.
Acceptance criteria for a future implementation
- With every lifecycle option disabled, write semantics, ranking, public contracts, and backend conformance are identical to current behavior.
- Importance, evidence strength, and lifecycle observations are rebuildable from authoritative revisions and declared bounded event records; none change entry content hashes.
- Low-importance entries remain eligible for ordinary recall. Only explicit or policy deactivation removes an entry from the active candidate surface;
reactivate()returns the original version without a new body version. - Automatic L1 deactivation affects only eligible low-tier, expired, unprotected entries; records
auto_decay:v1; is dry-run-capable, auditable, idempotent, and reversible. - Session-tier deactivation records
session_endand is recoverable. - No L2 proposal changes authority before approval. Approved consolidation preserves evidence lineage; explicit supersession preserves both old and new states and filters the old state only for ordinary current-state recall; unresolved conflicts preserve both states without inferred time order.
- Near-duplicate suppression never performs unverified semantic merging or discarding, and similarity findings do not silently lower importance into the deactivation floor; proposals and rejected candidates are observable through bounded statistics.
- Known inactive/superseded records are filtered before RRF and reranking for ordinary current-state recall; historical reads preserve exact originals, while unknown conflicts remain marked and are not ordered by relevance.
- Quality ordering never changes channel admission, fixed RRF-pool membership, or public RRF score semantics;
MemoryRankingTracemakes validity, membership invariance, and quality influence auditable. - The evaluation plan demonstrates non-regression and reports the retrieval, task, safety, and cost metrics above for both supported backends.
Drawbacks and alternatives considered
- Rerank/final truncation only: cheap but cannot repair a low-density candidate pool or accumulate lifecycle evidence.
- Manual
forget/reactivateonly: maximally safe but leaves operational growth and retrieval interference unmanaged. - Age-based deletion: conflates relevance, user intent, and retention; breaks recovery and citation expectations.
- Fully automatic ADD/UPDATE/DELETE-style memory management: fast but not sufficiently auditable or reversible for revisioned Memory.
- A temporal knowledge graph: potentially powerful for contradictions, but introduces a second authority and a large schema beyond the current Memory family.
- Pure ACT-R decay: theoretically elegant but parameter-sensitive and unsafe for historical facts; this proposal adopts only a conservative, query- and kind-gated ranking subset.
- Free-form model importance scoring: non-reproducible and provider-dependent; the proposal uses deterministic features plus a capped structured hint.
- Body summaries/compression: risks citation loss and does not fix top-k interference.
Additional context
- #1425 defines retention, physical erasure, legal/administrative policy, and projection cleanup across artifact families. This proposal does not cover physical deletion, external deletion obligations, or compliance retention. Lifecycle ranking/deactivation remains separately configurable and never silently rewrites or erases history.
- #1321 documents Memory storage and append write amplification. This proposal supplies observability and a retrieval/lifecycle boundary, but does not decide splitting, manifest compaction, or storage architecture.
- #1556 and its implementation PR #1596 consider recall sufficiency and bounded candidate expansion. That work asks whether the candidate pool is broad enough; this proposal asks how valid, useful, and healthy the entries within each fixed post-RRF pool are. They compose by applying validity and fixed-membership quality ordering independently to every issued recall round; quality does not alter admission floors, gate expansion, or reranker membership.
- PR #1586 adds an Experience-specific recurrence ledger, Review routing, statistics, and public API fields. Memory L2 must not reuse or overload that ledger, alter its event semantics, or change its Experience review path. Any later Memory review integration must be separately staged after #1586, preserve existing Experience/Skill Candidate contracts, and use Memory-specific operation records for its rollback/compensation semantics.
- #1242 is closed and is not a delivery dependency for this proposal.
Related RFCs: RFC 0014 (Memory Layer Design), RFC 0019 (Local Source Memory Runtime), RFC 0028 (Context Pack), RFC 0080 (Memory Search Reranking), and RFC 1229 (Unified Workloads and Long-Horizon Memory Evaluation). RFC 0050 (Artifact Candidate Review Inbox) is a related mechanism, but L2 here is explicitly a Memory-specific policy extension; ordinary Memory writes remain direct. #1425 defines the broader retention/lifecycle boundary.
- I am willing to contribute code, docs, or design feedback.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading fusion.py and service.py to understand the existing bounded retrieval boundary, then review MemoryEntryVersion, Source, and SourceDefinition because the proposal identifies those models and their adapter contract as prerequisites. Done means producing a reviewed RFC that resolves the lifecycle, quality, conflict, backend-parity, and reversibility design without adopting implementation or numeric defaults.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python, sqlite
- Domain
- backend-api-design, databases
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 30/100