Say something when SupersedeReplacedFacts is on and inert

[joslat]

SupersedeReplacedFacts = true does nothing at all unless the extracted predicate is one of the six
relations the vocabulary declares single-valued (belongs to, costs, expires, lives in, weighs, works at). CanSupersede is documented "false for anything unrecognised", so free-form predicates —
was at, assigned to, department — are refused. No :SUPERSEDED_BY edge, no invalidated_at,
and no signal of any kind.

This is not hypothetical. Four scored benchmark arms ran against precisely that state and were
reported as measurements of the feature. The cause was found only because the graph could be queried
directly and a probe was written to count edges. A consumer has neither recourse — they would
conclude bitemporal memory does not work.

Three signals, each at the level it belongs

• Debug, per refusal — names the refused predicate and the qualifying set. Makes the warning
  actionable once you are looking.
• Warning, once per batch — only when the option is enabled and nothing qualified: "on and
  inert". Per-batch so a large ingestion cannot bury it; conditioned on the option so a feature
  nobody asked for never warns.
• The option's own docs — where someone enabling it will read the constraint.

Tested both directions

A guard that cannot stay quiet is as bad as one that cannot speak, so: an unrecognised predicate
warns and names both the predicate and the qualifying relations; a qualifying predicate does
not warn; the feature off is silent.

Release 0-warn; 5191 + 730 + 54 unit tests green. No behaviour change — nothing supersedes that did
not supersede before.

[Copilot]

🟡 Changes recommended

The new refusal debug log currently duplicates a structured placeholder name and allocates string.Join(...) even when Debug is disabled, and the updated test file has an unused using directive.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Improves observability for ExtractionOptions.SupersedeReplacedFacts when enabled against non-single-valued predicates by emitting per-refusal debug logs and a once-per-batch warning when the feature is effectively inert, plus documents the constraint on the option.

Changes:

• Add per-refusal debug logging and a batch-level warning when supersession is enabled but no facts qualify.
• Extend unit coverage to assert the “on and inert” warning behavior (and silence when qualifying/off).
• Update option documentation to clarify the single-valued predicate constraint and the new signals.

File summaries

File	Description
tests/AgentMemory.Tests.Unit/Extraction/WriteTimeSupersessionTests.cs	Adds logger-capture-based assertions to verify the new warning/debug signals and silence cases.
src/AgentMemory.Core/Extraction/PersistenceStage.cs	Implements refusal counters, debug logging per refusal, and a batch-level warning when supersession is enabled but inapplicable.
src/AgentMemory.Abstractions/Options/ExtractionOptions.cs	Documents that supersession only applies to vocabulary-declared single-valued predicates and explains the new signals.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.