Tighten supersession preview preference topics

Author: cafitac

.dev/roadmap/memory-consolidation/current-progress-and-next-steps.md

@@ -1,11 +1,28 @@
 # agent-memory memory-consolidation current progress and next steps
 
 Status: AI-authored draft. Not yet human-approved.
-Last updated: 2026-05-28 10:18 KST
+Last updated: 2026-05-28 10:43 KST
 
 
 
 
+## Current checkpoint: topic-aware supersession preview fixed; live supersession lane now has no exact candidate
+
+- Continued from the fresh live read-only automation-policy checkpoint using the real live DB `/Users/reddit/.agent-memory/memory.db`; no mock DB or smoke DB was used for the live decision.
+- Primary run directory: `/tmp/agent-memory-next-candidate-review-20260528T103752Z`.
+- Re-ran the concrete next-lane preview artifacts as review material only: reinforcement refinement, decay collapse, and supersession.
+- Reinforcement refinement remained review-only with 7 candidates: high-tier `procedure:1`, `fact:1`, `episode:1`, `fact:6`, `fact:4`, `fact:8`; low-tier `fact:5`. No mutation/apply path was supported by the preview.
+- Decay collapse remained review-only with 1 candidate, `fact:5`, whose resolution hint is `collect_more_activation_evidence_before_decay_action`; this does not support collapse/deprecation/delete.
+- The live supersession preview originally reported one high-tier `same_claim_slot_conflict` between `fact:5` and `fact:9`. Real DB review/history/graph evidence showed they are independent user preferences under the broad `(user, prefers, project:agent-memory)` slot, not a replacement/supersession pair.
+- Code change: `dogfood supersession-preview` now groups `user prefers ...` memories by the existing remember-preference topic key before treating them as same-slot supersession candidates, and its review command templates now use valid `review explain` / `review history` / `review replacements` commands. Independent preference topics no longer produce false positive supersession candidates; same-topic preference contradictions and non-preference same-slot conflicts remain reviewable.
+- Post-fix live artifact: `/tmp/agent-memory-next-candidate-review-20260528T103752Z/supersession-preview-topic-aware.json` reports `candidate_count=0`, `read_only=true`, `mutated=false`, and `default_retrieval_unchanged=true`; quality gate is red only on `no_supersession_candidates_ready`.
+- Focused verification: `uv run pytest tests/test_cli.py -q -k 'supersession_preview'` passed (`3 passed, 254 deselected`).
+- No apply, fact/procedure/episode promotion, ranking mutation, core memory-status write, relation write, collapse/delete, telemetry reset, or background/default automation was executed.
+
+Next step: do not open a supersession/replacement corridor from `fact:5`/`fact:9`. Continue with real live read-only evidence; reinforcement refinement still needs a separate guarded policy before any mutation, and `fact:5` decay remains collect-more-evidence only.
+
+Reference: `.dev/roadmap/memory-consolidation/references/post-v0.1.162-live-topic-aware-supersession-preview.md`
+
 ## Current checkpoint: fresh live read-only automation-policy checks green; lifecycle/apply lanes still stopped
 
 - Continued from the generated trace-candidate cleanup checkpoint using the real live DB `/Users/reddit/.agent-memory/memory.db`; no mock DB or smoke DB was used.

.dev/roadmap/memory-consolidation/references/post-v0.1.162-live-topic-aware-supersession-preview.md

@@ -0,0 +1,90 @@
+# Post-v0.1.162 live topic-aware supersession preview
+
+Status: AI-authored draft. Not yet human-approved.
+Last updated: 2026-05-28 10:43 KST
+
+## Scope
+
+Continued from the fresh live read-only automation-policy checkpoint and inspected the concrete next-lane preview candidates against the real live DB `/Users/reddit/.agent-memory/memory.db`.
+
+Primary run directory: `/tmp/agent-memory-next-candidate-review-20260528T103752Z`
+
+No mock DB or smoke DB was used for the live decision. Focused tests were used only because the supersession preview code changed.
+
+## Live evidence inspected
+
+Re-ran the documented review-only next-lane previews:
+
+- `/tmp/agent-memory-next-candidate-review-20260528T103752Z/reinforcement-refinement-preview.json`
+  - `kind=dogfood_reinforcement_refinement_preview`
+  - `read_only=true`, `mutated=false`, `default_retrieval_unchanged=true`
+  - `candidate_count=7`
+  - high-tier reinforcement review candidates: `procedure:1`, `fact:1`, `episode:1`, `fact:6`, `fact:4`, `fact:8`
+  - `fact:5` remained low-tier with activation count `1`
+- `/tmp/agent-memory-next-candidate-review-20260528T103752Z/decay-collapse-preview.json`
+  - `kind=dogfood_decay_collapse_preview`
+  - `read_only=true`, `mutated=false`, `default_retrieval_unchanged=true`
+  - `candidate_count=1`
+  - candidate `fact:5`, `resolution_hint=collect_more_activation_evidence_before_decay_action`
+  - ref-safe evidence says the memory exists, is approved/default-visible elsewhere, has scope and one relation; no raw content included
+- `/tmp/agent-memory-next-candidate-review-20260528T103752Z/supersession-preview.json`
+  - pre-fix preview returned one high-tier `same_claim_slot_conflict`: `fact:5` vs `fact:9`
+  - live review artifacts showed this was not a semantic supersession candidate; both facts are independent user preferences under the broad `(user, prefers, project:agent-memory)` slot:
+    - `fact:5`: real downloaded-install QA for agent-memory milestone releases
+    - `fact:9`: autonomous agent-memory progress when next steps are clear
+  - both have independent auto-approval graph evidence and approval history
+
+## Code change
+
+The supersession preview now reuses the existing remember-preference topic key for `subject_ref=user` and `predicate=prefers` before treating preference memories as same-slot supersession candidates.
+
+Effect:
+
+- independent preference topics no longer appear as supersession/replacement candidates just because they share `(user, prefers, scope)`
+- same-topic preference contradictions still appear for human review
+- non-preference facts keep the previous subject/predicate/scope behavior
+- preview remains read-only and does not write review rows, relations, status transitions, ranking data, or core memories
+- ref-safe review command templates now use existing CLI verbs (`review explain`, `review history`, and `review replacements`) instead of the stale invalid `review fact` shape
+
+Post-fix live artifact:
+
+- `/tmp/agent-memory-next-candidate-review-20260528T103752Z/supersession-preview-topic-aware.json`
+  - `read_only=true`
+  - `mutated=false`
+  - `default_retrieval_unchanged=true`
+  - `candidate_count=0`
+  - quality gate red only on `no_supersession_candidates_ready`
+
+This resolves the only live supersession review candidate as a topic-grouping false positive. No supersession/replacement corridor should be opened from it.
+
+## Verification
+
+Focused code tests:
+
+```text
+uv run pytest tests/test_cli.py -q -k 'supersession_preview'
+3 passed, 254 deselected
+```
+
+Live real-DB verification:
+
+```text
+uv run agent-memory dogfood supersession-preview /Users/reddit/.agent-memory/memory.db --limit 200 --top 20 --output /tmp/agent-memory-next-candidate-review-20260528T103752Z/supersession-preview-topic-aware.json
+```
+
+Result: zero supersession candidates after topic-aware grouping, with no mutation.
+
+## Current stop gates
+
+- Do not create a supersession/replacement relation for `fact:5` and `fact:9`; they are independent preference topics.
+- Do not collapse/deprecate/delete `fact:5`; decay preview still recommends collecting more activation evidence, not mutation.
+- Do not persist duplicate lifecycle reinforcement candidates; refresh preview previously had no new unapplied targets.
+- Keep broad/background/default mutation, ordinary conversation auto-approval, default-ranking mutation, telemetry reset, core memory-status writes, retrieval-ranking writes, and unreviewed promotion blocked.
+
+## Next safe action
+
+Continue with real live read-only evidence. The remaining concrete review material is:
+
+1. reinforcement refinement candidates, especially high-activation approved memories, but mutation still needs a separate guarded policy/corridor;
+2. `fact:5` decay monitoring, where current evidence supports more activation collection rather than collapse/deprecation;
+3. ordinary-turn auto-approval readiness, which remains blocked until explicit remember-intent evidence exists.

.dev/status/current-handoff.md

@@ -1,11 +1,28 @@
 # agent-memory current handoff
 
 Status: AI-authored draft. Not yet human-approved.
-Last updated: 2026-05-28 10:18 KST
+Last updated: 2026-05-28 10:43 KST
 
 
 
 
+## Current checkpoint: topic-aware supersession preview fixed; live supersession lane now has no exact candidate
+
+- Continued from the fresh live read-only automation-policy checkpoint using the real live DB `/Users/reddit/.agent-memory/memory.db`; no mock DB or smoke DB was used for the live decision.
+- Primary run directory: `/tmp/agent-memory-next-candidate-review-20260528T103752Z`.
+- Re-ran the concrete next-lane preview artifacts as review material only: reinforcement refinement, decay collapse, and supersession.
+- Reinforcement refinement remained review-only with 7 candidates: high-tier `procedure:1`, `fact:1`, `episode:1`, `fact:6`, `fact:4`, `fact:8`; low-tier `fact:5`. No mutation/apply path was supported by the preview.
+- Decay collapse remained review-only with 1 candidate, `fact:5`, whose resolution hint is `collect_more_activation_evidence_before_decay_action`; this does not support collapse/deprecation/delete.
+- The live supersession preview originally reported one high-tier `same_claim_slot_conflict` between `fact:5` and `fact:9`. Real DB review/history/graph evidence showed they are independent user preferences under the broad `(user, prefers, project:agent-memory)` slot, not a replacement/supersession pair.
+- Code change: `dogfood supersession-preview` now groups `user prefers ...` memories by the existing remember-preference topic key before treating them as same-slot supersession candidates, and its review command templates now use valid `review explain` / `review history` / `review replacements` commands. Independent preference topics no longer produce false positive supersession candidates; same-topic preference contradictions and non-preference same-slot conflicts remain reviewable.
+- Post-fix live artifact: `/tmp/agent-memory-next-candidate-review-20260528T103752Z/supersession-preview-topic-aware.json` reports `candidate_count=0`, `read_only=true`, `mutated=false`, and `default_retrieval_unchanged=true`; quality gate is red only on `no_supersession_candidates_ready`.
+- Focused verification: `uv run pytest tests/test_cli.py -q -k 'supersession_preview'` passed (`3 passed, 254 deselected`).
+- No apply, fact/procedure/episode promotion, ranking mutation, core memory-status write, relation write, collapse/delete, telemetry reset, or background/default automation was executed.
+
+Next step: do not open a supersession/replacement corridor from `fact:5`/`fact:9`. Continue with real live read-only evidence; reinforcement refinement still needs a separate guarded policy before any mutation, and `fact:5` decay remains collect-more-evidence only.
+
+Reference: `.dev/roadmap/memory-consolidation/references/post-v0.1.162-live-topic-aware-supersession-preview.md`
+
 ## Current checkpoint: fresh live read-only automation-policy checks green; lifecycle/apply lanes still stopped
 
 - Continued from the generated trace-candidate cleanup checkpoint using the real live DB `/Users/reddit/.agent-memory/memory.db`; no mock DB or smoke DB was used.

.dev/status/next-agent-memory-action.md

@@ -1,11 +1,35 @@
 # agent-memory next action
 
 Status: AI-authored draft. Not yet human-approved.
-Last updated: 2026-05-28 10:18 KST
+Last updated: 2026-05-28 10:43 KST
 
 
 
 
+## Current checkpoint: topic-aware supersession preview fixed; next lanes remain bounded/read-only
+
+Completed the documented candidate inspection step against the real live DB.
+
+Completed work:
+
+- Run directory: `/tmp/agent-memory-next-candidate-review-20260528T103752Z`.
+- Live next-lane previews:
+  - reinforcement refinement: 7 review-only candidates; no preview-supported mutation path.
+  - decay collapse: 1 review-only candidate, `fact:5`, with `collect_more_activation_evidence_before_decay_action`.
+  - supersession: initial one-candidate result was a false positive caused by grouping independent `user prefers ...` facts only by broad claim slot.
+- Implemented topic-aware grouping in `dogfood supersession-preview` for `user/prefers` facts using the existing remember-preference topic key, and corrected its review command templates to existing `review explain` / `review history` / `review replacements` commands.
+- Post-fix live supersession artifact: `/tmp/agent-memory-next-candidate-review-20260528T103752Z/supersession-preview-topic-aware.json`, `candidate_count=0`, `read_only=true`, `mutated=false`, `default_retrieval_unchanged=true`.
+- Focused verification: `uv run pytest tests/test_cli.py -q -k 'supersession_preview'` passed (`3 passed, 254 deselected`).
+
+Next safe action:
+
+1. Do not create supersession/replacement edges for `fact:5` and `fact:9`; they are independent preference topics.
+2. Do not collapse/deprecate/delete `fact:5`; decay review still says collect more activation evidence.
+3. Continue from real live read-only evidence and only open a new bounded corridor if exact human-review evidence supports a specific candidate.
+4. Keep broad/background/default mutation, ordinary conversation auto-approval, default-ranking mutation, collapse/delete, telemetry reset, core memory-status writes, retrieval-ranking writes, and unreviewed promotion blocked.
+
+Reference: `.dev/roadmap/memory-consolidation/references/post-v0.1.162-live-topic-aware-supersession-preview.md`
+
 ## Current checkpoint: fresh read-only automation-policy pass complete; next lanes are review-only
 
 Completed the next documented fresh live read-only pass against the real live DB.

src/agent_memory/api/cli.py

@@ -2862,14 +2862,21 @@ def _supersession_review_recommendation(review_score: dict[str, Any]) -> dict[st
     }
 
 
+def _supersession_group_key(fact) -> tuple[str, str, str, str | None]:
+    topic_key: str | None = None
+    if fact.subject_ref == "user" and fact.predicate == "prefers":
+        topic_key = _remember_preference_topic_key(fact.object_ref_or_value)
+    return (fact.subject_ref, fact.predicate, fact.scope, topic_key)
+
+
 def _same_claim_slot_supersession_candidates(db_path: Path, *, limit: int, top: int) -> list[dict[str, Any]]:
     facts = _list_supersession_preview_facts(db_path, limit=limit)
-    grouped: dict[tuple[str, str, str], list[Any]] = defaultdict(list)
+    grouped: dict[tuple[str, str, str, str | None], list[Any]] = defaultdict(list)
     for fact in facts:
-        grouped[(fact.subject_ref, fact.predicate, fact.scope)].append(fact)
+        grouped[_supersession_group_key(fact)].append(fact)
 
     candidates: list[dict[str, Any]] = []
-    for (subject_ref, predicate, scope), slot_facts in grouped.items():
+    for (subject_ref, predicate, scope, topic_key), slot_facts in grouped.items():
         object_values = {fact.object_ref_or_value for fact in slot_facts}
         if len(slot_facts) < 2 or len(object_values) < 2:
             continue
@@ -2889,6 +2896,7 @@ def _same_claim_slot_supersession_candidates(db_path: Path, *, limit: int, top:
                     "predicate": predicate,
                     "scope": scope,
                     "fact_count": len(slot_facts),
+                    "preference_topic_key": topic_key,
                 },
                 "older_fact_ref": _fact_review_ref(older_fact.id),
                 "newer_fact_ref": _fact_review_ref(newer_fact.id),
@@ -2912,8 +2920,9 @@ def _same_claim_slot_supersession_candidates(db_path: Path, *, limit: int, top:
                 "review_score": review_score,
                 "review_recommendation": _supersession_review_recommendation(review_score),
                 "review_commands": {
-                    "review_older": f"agent-memory review fact {db_path} {older_fact.id}",
-                    "review_newer": f"agent-memory review fact {db_path} {newer_fact.id}",
+                    "review_older": f"agent-memory review explain fact {db_path} {older_fact.id}",
+                    "review_newer": f"agent-memory review explain fact {db_path} {newer_fact.id}",
+                    "review_history_older": f"agent-memory review history fact {db_path} {older_fact.id}",
                     "review_replacements_older": f"agent-memory review replacements fact {db_path} {older_fact.id}",
                     "future_guarded_apply": "not_supported_by_preview",
                 },