diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7310c9a61..d601b299f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Added
+
+- **Valid-time recall (opt-in).** `RecallOptions.ValidTime = ValidTimeMode.Current` filters facts on
+ their real-world window (`valid_from`/`valid_until`) rather than only on the transaction clock.
+ Default `Ignore`, which is byte-for-byte today's behaviour, and `MemoryProfile.Parity` resolves to
+ `Ignore` — parity means parity. **TCK exposure is zero**: the bridge exposes neither `/search_facts`
+ nor `/get_facts_about`, so no conformance surface can observe this.
+
+ Two things write validity bounds, and only two: temporal extraction, when
+ `TemporalValidityMode.Extract` asks the model for a window, and **supersession**, which stamps
+ `valid_until` as it closes a fact. The second is worth knowing about because it changes nothing
+ here — supersession also stamps `invalidated_at`, and the transaction-clock filter already removes
+ the fact from live recall whatever this option says. **So the gate is redundant for superseded
+ facts and load-bearing only for windows the conversation actually stated.** Reaching for it to hide
+ superseded data solves a problem that is already solved.
+
+- **Reasoning traces carry a trust level.** `ReasoningMemoryOptions.DefaultTraceTrustLevel`, default
+ `ModelGenerated` — a trace is the agent's own record of what it did. Traces were the one recall
+ category with no trust signal: caller-supplied `trust_level` is stripped (a caller must never
+ self-assign a level that bypasses admission checks) and nothing then stamped one, so every trace
+ read back as `Untrusted` — indistinguishable from "no signal recorded". Safe at shipped defaults:
+ `MinimumTrustForAdmissionBypass` is `ApplicationTrusted`, which `ModelGenerated` does not reach.
+
+- **Owner-starvation rescue for short results (opt-in).** `MemoryOptions.RescueShortOwnerResults`.
+ Neo4j's vector index is global, so an owner filter is a post-filter on a top-K drawn from every
+ tenant — measured, a mean of **7 of 60** candidates reached the querying owner. Previously only a
+ *totally empty* result triggered a rescue, on the argument that a short result still answers the
+ question. It does for a small tenant and does not for a crowded one: one measured question returned
+ **2 facts from a 710-fact graph** with the answer present, and was answered wrongly.
+
+ The rescue is the owner-bounded **scan**, not a wider index query — widening is another draw on the
+ same global index, and a tenant losing to 50 neighbours at top-60 usually loses again at top-480.
+ The scan's cost scales with one owner's rows, so the small tenant the original argument protected
+ pays *less* for it than for a wider index query. Off by default, and it takes whichever result is
+ larger, so a genuinely sparse owner never loses indexed rows.
+
### Changed
- **A greeting no longer costs a full recall.** Measured on the hermetic `PERF-R-01` scenario — a
diff --git a/docs/architecture.md b/docs/architecture.md
index c9407fb97..81d0aa5ae 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -142,7 +142,7 @@ graph TD
| **Purpose** | Domain contracts — all models, interfaces, and configuration types shared across the system |
| **Dependencies** | **Microsoft.Extensions.AI.Abstractions** 10.8.0 (approved, D-AR2-1) — .NET BCL otherwise (multi-targets net8.0/net9.0/net10.0) |
| **MUST NOT reference** | Neo4j.Driver, Microsoft.Agents.*, any GraphRAG SDK, any MCP SDK, any NuGet package **except** Microsoft.Extensions.AI.Abstractions |
-| **Key types** | 52 domain records (Conversation, Message, Entity, Fact, Preference, Relationship, MemoryHistoryQuery, MemoryHistoryRecord, ReasoningTrace, ReasoningStep, ToolCall, ToolCallStats, IngestionItemOutcome, MemoryContextRankedItem, MemoryContextSectionDiagnostics, UnifiedExtractionResult, etc.), 41 service interfaces (incl. `IMemoryIsolationPolicy`, `IUnifiedMemoryExtractor`, and `IMultiSessionUnifiedMemoryExtractor`), 11 repository interfaces, 16 configuration types (incl. `MemoryRankingOptions`, `MemoryIsolationOptions`), 26 enums (incl. `MemoryProfile`, `RankingIntent`, `DuplicateStatus`, `EntityMatchType`, `MemoryNodeKind`, `MemoryOperationAccess`, `MemoryIsolationMode`, `IngestionStatus`, `IngestionStage`, `IngestionItemStatus`, `MemoryItemKind`, `IngestionFailureMode`, `MemoryTrustLevel`, `AssistantContentMode`, `TemporalValidityMode`, `TraceKind`, `ExtractionProvenanceMode`) |
+| **Key types** | 59 domain records (Conversation, Message, Entity, Fact, Preference, Relationship, MemoryHistoryQuery, MemoryHistoryRecord, ReasoningTrace, ReasoningStep, ToolCall, ToolCallStats, IngestionItemOutcome, MemoryContextRankedItem, MemoryContextSectionDiagnostics, UnifiedExtractionResult, ExtractionWindow, EntitySummary, MemoryBlock, BulkIngestionResult, etc.), 44 service interfaces (incl. `IMemoryIsolationPolicy`, `IUnifiedMemoryExtractor`, `IMultiSessionUnifiedMemoryExtractor`, and `IMemoryReranker`, `IEntitySummaryService`), 12 repository interfaces, 16 configuration types (incl. `MemoryRankingOptions`, `MemoryIsolationOptions`), 26 enums (incl. `MemoryProfile`, `RankingIntent`, `DuplicateStatus`, `EntityMatchType`, `MemoryNodeKind`, `MemoryOperationAccess`, `MemoryIsolationMode`, `IngestionStatus`, `IngestionStage`, `IngestionItemStatus`, `MemoryItemKind`, `IngestionFailureMode`, `MemoryTrustLevel`, `AssistantContentMode`, `TemporalValidityMode`, `TraceKind`, `ExtractionProvenanceMode`) |
**Namespace structure:**
```
diff --git a/docs/performance/README.md b/docs/performance/README.md
index c9002eef1..6420c6204 100644
--- a/docs/performance/README.md
+++ b/docs/performance/README.md
@@ -7,6 +7,7 @@ What AgentMemory costs you per agent turn, how that cost is measured, and how to
| **README.md** (this file) | The two phases, what is and isn't measured, how to run it yourself |
| [`hermetic-S.json`](../../eng/perf/baselines/hermetic-S.json) | Machine-readable counter + quality baseline enforced on pull requests |
| [baseline-1.3.0.md](baseline-1.3.0.md) | The measured cost model for release 1.3.0 |
+| [bulk-ingestion.md](bulk-ingestion.md) | Loading a backlog without degrading p99 for everyone else in the process |
---
diff --git a/docs/performance/bulk-ingestion.md b/docs/performance/bulk-ingestion.md
new file mode 100644
index 000000000..f734738e3
--- /dev/null
+++ b/docs/performance/bulk-ingestion.md
@@ -0,0 +1,75 @@
+# Bulk ingestion
+
+Loading a backlog — a year of transcripts, an export from another system, a migration — is a
+different problem from ingesting a live turn, and the two obvious ways to do it are both wrong.
+
+A serial loop over `ExtractAndPersistAsync` is correct and takes hours: extraction is a model call,
+and one at a time means one round trip at a time.
+
+An unbounded `Parallel.ForEachAsync` is fast until it isn't. It saturates the provider quota and the
+Neo4j connection pool, and the damage is not to the bulk load — it is to **everything else sharing
+the process**. Median latency barely moves, which is what makes it hard to notice; p99 degrades by
+20–70% under saturation, so the tenants who suffer are the ones already having the worst time.
+
+## The documented path
+
+```csharp
+var result = await memory.IngestBulkAsync(
+ requests,
+ new BulkIngestionOptions { MaxConcurrency = 4 },
+ cancellationToken);
+
+Console.WriteLine($"{result.SucceededCount} ingested, {result.FailedCount} failed, " +
+ $"{result.NotAttemptedCount} not attempted");
+
+foreach (var failure in result.Outcomes.Where(o => !o.Succeeded))
+ Console.WriteLine($" request {failure.Index}: {failure.Error!.Message}");
+```
+
+`IngestBulkAsync` is a **default interface method on `IMemoryIngestion`**. It paces calls the host
+could have made itself; it is not a second ingestion pipeline. That distinction matters more than it
+sounds: a separate bulk path would be a second place for trust stamping, provenance and owner scoping
+to drift out of agreement with the per-request path, and the drift would only show up in the corpus
+months later.
+
+## What the options actually buy
+
+| Option | Default | Why |
+|---|---|---|
+| `MaxConcurrency` | `4` | High enough to beat a serial loop, low enough that a caller who never tunes it does not saturate a shared quota by accident. Bounding this does not make the bulk load faster — it stops the bulk load making everything else slower. |
+| `ContinueOnError` | `true` | In a ten-thousand-conversation load, one malformed transcript aborting the other 9,999 is rarely what was wanted. Continuing is not ignoring: every failure comes back in `Outcomes`. |
+
+## Failures are reported per request, not counted
+
+A bulk API that returns *"8,412 of 10,000 succeeded"* tells you that you have a problem and nothing
+about which inputs to retry — so the realistic response is to re-run all ten thousand, which costs
+more than the failure did. Every outcome carries its `Index` into the submitted list and the
+`Exception` that stopped it.
+
+`NotAttemptedCount` is kept separate from `FailedCount` on purpose. **"Tried and failed" and "never
+tried" call for different actions**: re-running a request that was never attempted is always safe,
+re-running one that failed part-way may not be. Collapsing them makes a stopped run look like a
+partially broken corpus.
+
+## Cancellation
+
+A run stopped by `ContinueOnError = false` **completes normally** and returns its report — the
+failure that stopped it is already in `Outcomes`, and throwing would discard the record of what did
+succeed.
+
+A cancellation *you* requested throws `OperationCanceledException`. That is a different event and is
+not swallowed into a tidy report.
+
+## What this is not
+
+This is not the 10.70× figure from the throughput analysis. That number is ten-owner concurrent
+throughput, and it has always been available to any caller willing to parallelise across owners —
+it is a property of the store, not of this API. What is documented here is the safe way to do the
+parallelising, which is a smaller and more honest claim.
+
+## Related
+
+- [Performance baselines](README.md)
+- Extraction batching (`MaxConcurrentExtractionBatches`) bounds concurrency *inside* one extraction;
+ this bounds concurrency *across* requests. They compose, and multiply — a `MaxConcurrency` of 4
+ over batches of 6 is 24 in-flight provider calls.
diff --git a/src/AgentMemory.Abstractions/Domain/Context/MemoryContext.cs b/src/AgentMemory.Abstractions/Domain/Context/MemoryContext.cs
index d628d151f..c9351f8f8 100644
--- a/src/AgentMemory.Abstractions/Domain/Context/MemoryContext.cs
+++ b/src/AgentMemory.Abstractions/Domain/Context/MemoryContext.cs
@@ -106,6 +106,24 @@ public sealed record MemoryContext
///
public bool Truncated { get; init; }
+ ///
+ /// At least one section was abandoned because the recall latency budget expired (rank 13).
+ ///
+ ///
+ ///
+ /// Separate from , which means something else. Truncation is the
+ /// context budget trimming items that were retrieved; this is a retrieval that never came back.
+ /// A caller told only "truncated" would reasonably conclude the memories exist and were dropped
+ /// to fit — here they may exist and were never looked at.
+ ///
+ ///
+ /// Which sections were lost is on their own diagnostics. This flag exists so a caller can notice
+ /// at all without inspecting every section, because a partial context that looks complete is
+ /// worse than a slow one: the answer is given confidently from memory that was never consulted.
+ ///
+ ///
+ public bool LatencyBudgetExceeded { get; init; }
+
///
/// Additional metadata.
///
diff --git a/src/AgentMemory.Abstractions/Domain/Context/MemoryContextSection.cs b/src/AgentMemory.Abstractions/Domain/Context/MemoryContextSection.cs
index 80e05caa8..5c662c96c 100644
--- a/src/AgentMemory.Abstractions/Domain/Context/MemoryContextSection.cs
+++ b/src/AgentMemory.Abstractions/Domain/Context/MemoryContextSection.cs
@@ -74,14 +74,31 @@ public sealed record MemoryContextRankedItem(
///
/// Lowest returned score, or under the same rules.
/// The similarity floor in force, so "all below threshold" is checkable.
+///
+/// Whether this section was abandoned because the recall latency budget expired (rank 13). Without
+/// it, a section cut short is byte-identical to one that searched and found nothing.
+///
public sealed record MemoryContextSectionDiagnostics(
bool Searched,
int RequestedLimit,
int Returned,
double? TopScore,
double? LowestScore,
- double MinimumScore)
+ double MinimumScore,
+ bool TimedOut = false)
{
+ ///
+ /// This section was abandoned because the recall latency budget expired (rank 13).
+ ///
+ ///
+ /// The reason a latency budget needs a flag at all. A section cut short reports
+ /// Searched = true and Returned = 0, which is byte-identical to a section that ran
+ /// to completion and genuinely found nothing. Without this, degrading under load would look
+ /// exactly like an owner having no memories — and a partial recall that looks complete is worse
+ /// than a slow one, because the caller answers confidently from a context they believe is whole.
+ ///
+ public bool AbandonedToLatencyBudget => TimedOut;
+
///
/// The retrieval ran and came back with nothing — as opposed to never having run.
///
diff --git a/src/AgentMemory.Abstractions/Domain/Extraction/BulkIngestion.cs b/src/AgentMemory.Abstractions/Domain/Extraction/BulkIngestion.cs
new file mode 100644
index 000000000..553abd4d4
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Domain/Extraction/BulkIngestion.cs
@@ -0,0 +1,77 @@
+namespace AgentMemory.Abstractions.Domain;
+
+///
+/// How a bulk ingestion run is paced (rank 27).
+///
+///
+///
+/// Backpressure is the whole point. A caller with ten thousand conversations to load will otherwise
+/// issue them all at once, and the failure is not a clean rejection — it is provider throttling,
+/// connection-pool exhaustion and a p99 that degrades for every other tenant sharing the
+/// process while median latency looks untouched.
+///
+///
+public sealed record BulkIngestionOptions
+{
+ ///
+ /// How many requests may be in flight at once.
+ ///
+ ///
+ /// Defaults to 4: high enough to be worth using over a serial loop, low enough that a caller who
+ /// never tunes it does not saturate a shared provider quota by accident. The measured effect of
+ /// bounding this is small at the median and 20–70% at p99 under saturation — which is to
+ /// say it does not make bulk loading faster, it stops bulk loading making everything else slower.
+ ///
+ public int MaxConcurrency { get; init; } = 4;
+
+ ///
+ /// Whether a failed request stops the run.
+ ///
+ ///
+ /// Defaults to : in a ten-thousand-conversation load, one malformed
+ /// transcript aborting the other 9,999 is rarely what the caller wanted. Failures are returned
+ /// per request rather than thrown, so continuing is not the same as ignoring.
+ ///
+ public bool ContinueOnError { get; init; } = true;
+}
+
+/// What happened to one request in a bulk run.
+/// Position in the submitted list, so a failure can be traced to its input.
+/// The extraction result, or if it failed.
+/// The failure, or if it succeeded.
+public sealed record BulkIngestionOutcome(int Index, ExtractionResult? Result, Exception? Error)
+{
+ /// Whether this request was ingested.
+ public bool Succeeded => Error is null;
+}
+
+///
+/// The result of a bulk ingestion run (rank 27).
+///
+///
+/// Per-request outcomes, not an aggregate count. A bulk API that returns "8,412 of 10,000
+/// succeeded" tells the caller they have a problem and nothing about which inputs to retry — so the
+/// realistic response is to re-run everything, which is worse than the failure. Every outcome carries
+/// its index and its exception.
+///
+public sealed record BulkIngestionResult
+{
+ /// One entry per submitted request, in submission order.
+ public required IReadOnlyList Outcomes { get; init; }
+
+ /// How many requests were ingested.
+ public int SucceededCount => Outcomes.Count(o => o.Succeeded);
+
+ /// How many requests failed.
+ public int FailedCount => Outcomes.Count(o => !o.Succeeded);
+
+ ///
+ /// Requests that were never attempted because the run stopped early.
+ ///
+ ///
+ /// Distinct from a failure, and reported separately for the same reason 6.5's trace counts are
+ /// nullable: "tried and failed" and "never tried" call for different actions, and collapsing them
+ /// makes a stopped run look like a partially broken corpus.
+ ///
+ public int NotAttemptedCount { get; init; }
+}
diff --git a/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionRequest.cs b/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionRequest.cs
index 0b0460151..ced298846 100644
--- a/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionRequest.cs
+++ b/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionRequest.cs
@@ -10,6 +10,25 @@ public sealed record ExtractionRequest
///
public required IReadOnlyList Messages { get; init; }
+ ///
+ /// Earlier turns supplied only so can be understood (E2).
+ ///
+ ///
+ ///
+ /// Nothing is extracted from these and nothing is attributed to them — they exist so
+ /// "I moved there last year" can resolve the place named a few turns earlier. Empty by default,
+ /// which is exactly the pre-E2 behaviour.
+ ///
+ ///
+ /// Kept separate from rather than prepended to it, because
+ /// extracting from them would re-assert stored facts — and a re-assertion now earns confidence
+ /// (S2) and increments the mention_count the salience reranker reads (R7). A fact would
+ /// gain both every time it happened to sit inside a sliding window, so corroboration would
+ /// quietly become recency.
+ ///
+ ///
+ public IReadOnlyList ContextMessages { get; init; } = [];
+
///
/// Session context for the extraction.
///
diff --git a/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionWindow.cs b/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionWindow.cs
new file mode 100644
index 000000000..a876a0e30
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Domain/Extraction/ExtractionWindow.cs
@@ -0,0 +1,50 @@
+namespace AgentMemory.Abstractions.Domain;
+
+///
+/// The turns an extractor should extract from, plus the earlier turns it may read to understand them
+/// (E2).
+///
+///
+///
+/// Extraction has always seen one batch — typically a user turn and the reply — which is often not
+/// enough to resolve what was said. "I moved there last year" needs the turn that named the place;
+/// "she recommended it" needs the turn that named her. Widening the batch fixes the reference and
+/// creates a worse problem, which is why this type exists rather than a bigger messages list.
+///
+///
+/// Context is not a target, and the distinction is now a correctness property rather than a
+/// question of token efficiency. Re-extracting the preceding turns re-asserts facts already
+/// stored. That used to be merely wasteful — the exact triple MERGEs, so nothing was corrupted — but
+/// with confidence reinforcement (S2) a re-assertion earns α, and the salience reranker (R7) reads a
+/// mention_count the MERGE increments. If context turns were extracted as targets, a fact
+/// would gain confidence and mentions every time it happened to sit inside a sliding window, so both
+/// signals would measure how recently something was said rather than how often the world
+/// asserted it. Corroboration would quietly become recency.
+///
+///
+/// So the contract is: read to disambiguate, extract only from
+/// , and attribute provenance only to .
+///
+///
+public sealed record ExtractionWindow
+{
+ /// The turns to extract memories from. Provenance is attributed here and nowhere else.
+ public required IReadOnlyList Targets { get; init; }
+
+ ///
+ /// Earlier turns, in order, supplied purely so the targets can be understood.
+ ///
+ ///
+ /// Nothing may be extracted from these. They carry no provenance and must never appear in
+ /// SourceMessageIds: an EXTRACTED_FROM edge to a context turn would claim the fact
+ /// was stated there, which is exactly the turn the extractor was told not to extract from.
+ ///
+ public IReadOnlyList Context { get; init; } = [];
+
+ /// A window with no context — identical in effect to the pre-E2 ExtractAsync(messages).
+ public static ExtractionWindow ForTargets(IReadOnlyList targets) =>
+ new() { Targets = targets };
+
+ /// when there is context to render at all.
+ public bool HasContext => Context.Count > 0;
+}
diff --git a/src/AgentMemory.Abstractions/Domain/LongTerm/EntitySummary.cs b/src/AgentMemory.Abstractions/Domain/LongTerm/EntitySummary.cs
new file mode 100644
index 000000000..910ad58c9
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Domain/LongTerm/EntitySummary.cs
@@ -0,0 +1,107 @@
+using System.Globalization;
+using System.Security.Cryptography;
+using System.Text;
+
+namespace AgentMemory.Abstractions.Domain;
+
+///
+/// A synthesized description of everything memory holds about one entity (S1).
+///
+///
+///
+/// Recall about a well-known entity returns twenty separate facts that each cost context and say one
+/// thing. A summary says the same in one item — but a summary is a derived memory, and derived
+/// memory is where stores quietly start lying: the sources change, the summary does not, and nothing
+/// about it looks any different afterwards.
+///
+///
+/// So staleness here is proved, never assumed. is computed
+/// from the exact set of live facts the summary was written from. Before a summary is used, that
+/// fingerprint is recomputed from the store; if it does not match — a source superseded, a new fact
+/// added, a confidence moved — the summary is not used. It is not repaired on the read path
+/// and it is not returned with a caveat, because a caveat is something a caller can ignore.
+///
+///
+/// That check is also why this earns its place in a graph rather than a summary column in a
+/// relational row: the fingerprint is derived from the very provenance edges the store already keeps,
+/// so "is this still true?" is a query rather than a convention someone has to remember to follow.
+///
+///
+public sealed record EntitySummary
+{
+ /// Unique identifier for the summary node.
+ public required string SummaryId { get; init; }
+
+ /// The entity this summarises.
+ public required string EntityId { get; init; }
+
+ /// The synthesized text.
+ public required string Content { get; init; }
+
+ ///
+ /// The facts this summary was written from, in the order they were read.
+ ///
+ ///
+ /// Retained rather than merely hashed so a stale summary can say what changed, and so the
+ /// EXTRACTED_FROM edges to the underlying sources can be rebuilt without re-synthesising.
+ ///
+ public required IReadOnlyList SourceFactIds { get; init; }
+
+ ///
+ /// Hash of the source facts as they stood when the summary was written.
+ ///
+ ///
+ /// The staleness proof. Recompute it from the store and compare: equal means every source is
+ /// still live and unchanged, anything else means this text describes a state of the world that
+ /// no longer exists.
+ ///
+ public required string SourceFingerprint { get; init; }
+
+ /// Owner (R1). Null = shared/global.
+ public string? OwnerId { get; init; }
+
+ /// When the summary was synthesized.
+ public required DateTimeOffset GeneratedAtUtc { get; init; }
+
+ /// Embedding of , when one has been generated.
+ public IReadOnlyList? Embedding { get; init; }
+
+ ///
+ /// Computes the fingerprint of a set of source facts.
+ ///
+ ///
+ ///
+ /// Covers each fact's id, its confidence and whether it has been invalidated — the three things
+ /// that change what a truthful summary would say. Confidence is included deliberately:
+ /// reinforcement (S2) moves it, and a summary asserting something the store has since grown
+ /// doubtful about is exactly the stale shadow this design exists to prevent.
+ ///
+ ///
+ /// Order-independent, because the fingerprint must answer "are these the same facts?" and not
+ /// "did they come back in the same order?" — a query plan change would otherwise invalidate every
+ /// summary in the store without a single fact having moved.
+ ///
+ ///
+ public static string ComputeFingerprint(IEnumerable sources)
+ {
+ ArgumentNullException.ThrowIfNull(sources);
+
+ var canonical = sources
+ .Select(s => string.Create(
+ CultureInfo.InvariantCulture,
+ $"{s.FactId}|{s.Confidence:F6}|{(s.Invalidated ? 1 : 0)}"))
+ .OrderBy(s => s, StringComparer.Ordinal)
+ .ToList();
+
+ var joined = string.Join("\n", canonical);
+ return Convert.ToHexString(SHA256.HashData(Encoding.UTF8.GetBytes(joined))).ToLowerInvariant();
+ }
+}
+
+///
+/// One fact's contribution to a summary's fingerprint (S1).
+///
+/// The fact.
+/// Its confidence at the time of reading.
+/// Whether it has been superseded or otherwise invalidated.
+public readonly record struct EntitySummarySource(string FactId, double Confidence, bool Invalidated);
diff --git a/src/AgentMemory.Abstractions/Domain/LongTerm/Fact.cs b/src/AgentMemory.Abstractions/Domain/LongTerm/Fact.cs
index 7814e5440..4128323ed 100644
--- a/src/AgentMemory.Abstractions/Domain/LongTerm/Fact.cs
+++ b/src/AgentMemory.Abstractions/Domain/LongTerm/Fact.cs
@@ -53,6 +53,24 @@ public sealed record Fact
///
public DateTimeOffset? ValidUntil { get; init; }
+ ///
+ /// When this fact was superseded or otherwise invalidated; while it is live.
+ ///
+ ///
+ ///
+ /// The transaction clock, distinct from 's real-world one:
+ /// ValidUntil says when a fact stopped being true, this says when the store stopped
+ /// believing it. A contradicted fact is invalidated without its validity period changing at all.
+ ///
+ ///
+ /// The store has always recorded this — supersession is non-destructive precisely so as-of recall
+ /// can still reach it — but it was never projected onto the domain record, so a caller reading
+ /// facts had no way to tell a superseded one from a live one. Anything deriving from a fact set
+ /// (S1's summaries first among them) needs exactly that distinction.
+ ///
+ ///
+ public DateTimeOffset? InvalidatedAtUtc { get; init; }
+
///
/// Optional embedding vector for semantic search.
///
diff --git a/src/AgentMemory.Abstractions/Domain/MemoryBlock.cs b/src/AgentMemory.Abstractions/Domain/MemoryBlock.cs
new file mode 100644
index 000000000..41c61930d
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Domain/MemoryBlock.cs
@@ -0,0 +1,59 @@
+namespace AgentMemory.Abstractions.Domain;
+
+///
+/// One addressable line of a memory block (S4).
+///
+/// The id of the underlying memory — what makes this line actionable.
+/// Entity, fact or preference.
+/// The rendered line.
+public sealed record MemoryBlockLine(string MemoryId, MemoryItemKind Kind, string Text);
+
+///
+/// A small, human-readable projection of what memory holds (S4).
+///
+///
+///
+/// The honest assessment of this store was "capable but opaque". A developer could not look at
+/// an owner's memory and see it; they could query it, which is not the same thing. This is the view
+/// that closes that gap.
+///
+///
+/// Rendered on demand and never stored. That is the deliberate divergence from the
+/// block-memory designs this borrows legibility from. A stored block is a second copy of the truth
+/// that drifts from the graph the moment anything is written, and once an agent is allowed to edit
+/// the block directly, the block — not the audited store — becomes where memory actually lives. Every
+/// provenance edge, every trust level and every supersession record then describes a shadow of what
+/// the system believes.
+///
+///
+/// So this is a read surface. Changing memory goes through the ordinary write path, which
+/// stamps trust, records provenance and leaves a history. To make that practical rather than
+/// obstructive, each line carries its : a human who spots
+/// something wrong can act on that exact item instead of rewriting prose and hoping a parser agrees.
+///
+///
+public sealed record MemoryBlock
+{
+ /// The owner this block describes; null = shared/global.
+ public string? OwnerId { get; init; }
+
+ /// When the block was rendered. It is a snapshot, and it says so.
+ public required DateTimeOffset RenderedAtUtc { get; init; }
+
+ /// The lines, in rendering order.
+ public required IReadOnlyList Lines { get; init; }
+
+ ///
+ /// How many memories were left out because the block was full.
+ ///
+ ///
+ /// Counted and surfaced rather than silently dropped. A block is a view a human trusts to
+ /// show them what memory holds; one that quietly stops short reads as "this is everything" and is
+ /// worse than no view at all, because it invites the conclusion that a missing memory was never
+ /// stored.
+ ///
+ public int OmittedCount { get; init; }
+
+ /// Whether anything was left out.
+ public bool IsTruncated => OmittedCount > 0;
+}
diff --git a/src/AgentMemory.Abstractions/Options/ExtractionOptions.cs b/src/AgentMemory.Abstractions/Options/ExtractionOptions.cs
index 535dc33a0..f4fb37145 100644
--- a/src/AgentMemory.Abstractions/Options/ExtractionOptions.cs
+++ b/src/AgentMemory.Abstractions/Options/ExtractionOptions.cs
@@ -95,6 +95,60 @@ public sealed class ExtractionOptions
///
///
public bool SupersedeReplacedFacts { get; set; }
+
+ ///
+ /// Skips the extraction call entirely for turns that cannot carry a fact — greetings, thanks,
+ /// bare acknowledgement (E4).
+ ///
+ ///
+ ///
+ /// The extraction call is where the money is: the write is one round trip to Neo4j, while
+ /// extraction is a model call over the rendered transcript and on a corpus build it is
+ /// essentially the whole bill. An "ok, thanks!" turn pays it for nothing.
+ ///
+ ///
+ /// Deliberately not a write-side gate. Skipping the persistence of a triple already in the
+ /// store looks like the more obvious saving and would silently disable two features that depend
+ /// on the duplicate write happening: ,
+ /// where a re-asserted fact earns α, and the mention_count the salience reranker reads.
+ /// Corroboration is the repeated write.
+ ///
+ ///
+ /// Detection is a closed vocabulary, deterministic, and biased hard toward extracting: a missed
+ /// skip costs one call, while gating a turn that did carry a fact means the memory is never
+ /// formed and nothing downstream can recover it. "yes", "no" and "sure" are therefore treated as
+ /// contentful — each is a complete answer to a question.
+ ///
+ ///
+ /// Off by default: it changes what gets extracted, and prompt-and-transcript bytes are
+ /// fingerprinted into every measured run.
+ ///
+ ///
+ public bool SkipUninformativeTurns { get; set; }
+
+ ///
+ /// How many earlier turns to hand the extractors as read-only context (E2). 0 — the
+ /// default — is the pre-E2 behaviour of extracting from the batch alone.
+ ///
+ ///
+ ///
+ /// One batch is often not enough to understand itself: "I moved there last year" needs the turn
+ /// that named the place, and "she recommended it" needs the turn that named her. Without context
+ /// those either extract nothing or extract an unresolved pronoun as an entity.
+ ///
+ ///
+ /// Context turns are read, never extracted from, and never attributed to. Extracting them
+ /// would re-assert facts already stored — which now earns confidence
+ /// () and increments the
+ /// mention_count the salience reranker reads, so a fact would gain both merely by sitting
+ /// inside a sliding window. Corroboration would become recency.
+ ///
+ ///
+ /// Costs input tokens on every extraction, which is why it is off rather than defaulted to a
+ /// nominal value. Zep uses 4.
+ ///
+ ///
+ public int ExtractionContextTurns { get; set; }
}
/// Controls which matching strategies are used for entity resolution.
@@ -125,4 +179,5 @@ public sealed class EntityValidationOptions
public bool RejectPunctuationOnly { get; set; } = true;
/// Reject entities whose names are common stop-words.
public bool UseStopwordFilter { get; set; } = true;
+
}
diff --git a/src/AgentMemory.Abstractions/Options/MemoryOptions.cs b/src/AgentMemory.Abstractions/Options/MemoryOptions.cs
index 68fc61138..da84abcc7 100644
--- a/src/AgentMemory.Abstractions/Options/MemoryOptions.cs
+++ b/src/AgentMemory.Abstractions/Options/MemoryOptions.cs
@@ -23,6 +23,157 @@ public sealed record MemoryOptions
/// Whether to enable GraphRAG integration.
public bool EnableGraphRag { get; init; }
+ ///
+ /// Falls back to an owner-bounded similarity scan when an owner-scoped vector search returns
+ /// fewer rows than were asked for.
+ ///
+ ///
+ ///
+ /// Neo4j's vector index is global, so an owner filter is a POST-filter on a top-K drawn from every
+ /// tenant. Measured on a 50-owner corpus, a mean of 7 of 60 candidates reached the querying
+ /// owner. Today only a totally empty result triggers a rescue; a search returning 2 rows of
+ /// a requested 10 is accepted as the answer.
+ ///
+ ///
+ /// That is sometimes right and sometimes badly wrong: question 5d3d2817 returned 2 facts
+ /// from a 710-fact graph with the answer present, and was answered incorrectly in both arms.
+ ///
+ ///
+ /// Off by default. It costs one extra query per short result — bounded by the owner's own rows,
+ /// not the corpus — and every recorded measurement was taken without it, so turning it on is a
+ /// stated decision rather than an inherited one.
+ ///
+ ///
+ public bool RescueShortOwnerResults { get; init; }
+
+ ///
+ /// Boosts recalled facts that sit close, in the graph, to the entity the query is about (R6).
+ ///
+ ///
+ ///
+ /// Vector similarity asks whether a row looks like the query; this asks whether it is
+ /// about what the query is about. A plainly-worded fact hanging directly off the named
+ /// entity is often the answer, while a fact that paraphrases the query beautifully may concern
+ /// someone else entirely.
+ ///
+ ///
+ /// Reuses MemoryRankingOptions.StructuralDecayGamma as its decay constant rather than
+ /// introducing a second one, and does nothing unless that decay is also enabled -- at gamma = 1
+ /// every boost is 1.0, so the two extra queries could not change an ordering.
+ ///
+ ///
+ /// Off by default: it changes recall ordering, costs two bounded queries per fact section, and
+ /// every recorded measurement was taken without it.
+ ///
+ ///
+ public bool NodeDistanceReranking { get; init; }
+
+ ///
+ /// Boosts recalled facts the conversation keeps returning to (R7).
+ ///
+ ///
+ ///
+ /// A fact the world asserted five times is usually more central than one mentioned once, and
+ /// similarity cannot see that: two facts phrased alike score alike however often either was said.
+ ///
+ ///
+ /// Ingestion-side. It counts how often the WORLD re-asserted a fact, not how often we
+ /// retrieved it. Ranking on our own retrievals -- the :MemoryReadAudit trail -- would be a
+ /// rich-get-richer loop: whatever ranks highly gets retrieved, which raises its count, which
+ /// raises its rank. That looks like learning and is self-reinforcement.
+ ///
+ ///
+ /// Logarithmic, so the gap between one mention and three counts while the gap between thirty and
+ /// thirty-two does not. Off by default; every recorded measurement was taken without it.
+ ///
+ ///
+ public bool MentionFrequencyReranking { get; init; }
+
+ ///
+ /// Starts the post-recall access-tracking write without waiting for it.
+ ///
+ ///
+ ///
+ /// Access tracking is bookkeeping — it feeds decay and retention, and nothing in the recall the
+ /// caller is waiting for depends on it. Awaiting it puts a write burst on the pre-model read path:
+ /// at shipped defaults, up to 25 nodes updated before the model is invoked.
+ ///
+ ///
+ /// Off by default, and the reason is a hazard rather than caution. The write runs on scoped
+ /// services — a driver session, a repository — and a host that disposes its DI scope when the
+ /// response is returned will dispose them out from under a deferred write. That surfaces as an
+ /// ObjectDisposedException in a log nobody reads, and access tracking silently stops. Hosts
+ /// whose scope outlives the response (a long-lived agent, a hosted service) can turn it on; a
+ /// short-lived request scope should not.
+ ///
+ ///
+ /// Deferred work is detached from the request's cancellation token deliberately: that token is
+ /// cancelled as soon as the response completes, so passing it through would cancel the very write
+ /// that was deferred — a feature that looks enabled and does nothing.
+ ///
+ ///
+ public bool DeferAccessTracking { get; init; }
+
+ ///
+ /// How much a fact's confidence moves when the world corroborates or contradicts it (S2).
+ ///
+ ///
+ ///
+ /// Today confidence is set once by extraction and never earns or loses anything: a fact stated
+ /// five times and one stated in passing carry whatever number the extractor happened to report.
+ /// With α > 0 a re-asserted triple gains α, and a fact superseded by a contradiction loses 2α.
+ ///
+ ///
+ /// Asymmetric on purpose. Being contradicted is stronger evidence against a fact than one
+ /// more restatement is for it — a claim that is simply repeated may just be a habit of phrasing,
+ /// while a claim the world has replaced is one the world stopped believing.
+ ///
+ ///
+ /// Clamped to [0,1] at both ends. Confidence is read by ranking, dedup and decay, and a value
+ /// outside that range would propagate into computations where it means nothing.
+ ///
+ ///
+ /// 0 (off) by default, and it is the off switch in Cypher too: at α = 0 the upsert's
+ /// confidence assignment is byte-for-byte what it was, so no sealed measurement moves. A sensible
+ /// starting value is 0.02–0.05 — large enough to separate a well-attested fact over a
+ /// conversation, small enough that a single restatement does not overwhelm what extraction judged.
+ ///
+ ///
+ public double ConfidenceReinforcementAlpha { get; init; }
+
+ ///
+ /// Routes a turn that names a past time to bitemporal recall at that time (R4).
+ ///
+ ///
+ ///
+ /// RecallAsOfAsync has existed since the bitemporal work, and until now nothing in an
+ /// ordinary conversation could reach it: "what did I think back in March?" recalled against now,
+ /// exactly like every other question. Without this, the bitemporal read path is a capability
+ /// nothing can ask for.
+ ///
+ ///
+ /// Detection is deterministic, needs no model call, and errs heavily toward not matching:
+ /// a missed expression costs nothing (the turn recalls against now, today's behaviour), while a
+ /// false positive silently narrows recall to a window the user never asked about and returns an
+ /// answer that looks entirely ordinary. So "in March" resolves and a bare "March" does not;
+ /// "last week" resolves and "the last item" does not.
+ ///
+ ///
+ /// Off by default: it changes which memories a temporal question sees.
+ ///
+ ///
+ /// Scope. Honoured by IMemoryService.RecallAsync, and therefore by everything that
+ /// recalls through it — the MCP memory tools, the Agent Framework and Semantic Kernel adapters.
+ /// The memory://context/{session_id} MCP resource is the one read surface that does
+ /// not: it composes IMemoryContextAssembler directly, and the MCP server references only
+ /// AgentMemory.Abstractions by design. Reaching the resolver from there would mean a project
+ /// reference to AgentMemory.Core purely for a secondary surface, so the divergence is recorded
+ /// here rather than papered over — a temporal question asked through that resource recalls against
+ /// now.
+ ///
+ ///
+ public bool ResolveTemporalQueries { get; init; }
+
// NOTE: extraction at the Core layer is explicit (call ExtractAndPersistAsync /
// ExtractFromSessionAsync). Automatic extraction on message persist is an adapter concern, configured
// by AgentFrameworkOptions.AutoExtractOnPersist. The former EnableAutoExtraction flag here was read
diff --git a/src/AgentMemory.Abstractions/Options/ReasoningMemoryOptions.cs b/src/AgentMemory.Abstractions/Options/ReasoningMemoryOptions.cs
index e31ce4a13..07183c322 100644
--- a/src/AgentMemory.Abstractions/Options/ReasoningMemoryOptions.cs
+++ b/src/AgentMemory.Abstractions/Options/ReasoningMemoryOptions.cs
@@ -1,3 +1,5 @@
+using AgentMemory.Abstractions.Domain;
+
namespace AgentMemory.Abstractions.Options;
///
@@ -13,4 +15,31 @@ public sealed record ReasoningMemoryOptions
/// Maximum number of traces to retain per session.
public int? MaxTracesPerSession { get; init; }
+
+ ///
+ /// The trust level stamped on every reasoning trace.
+ ///
+ ///
+ ///
+ /// Traces were the one recall category with no trust level at all: StartTraceAsync strips
+ /// any caller-supplied trust_level — correctly, since a caller must never self-assign a
+ /// level that bypasses the admission policy — and then nothing stamped one, so every trace read
+ /// back as . That is indistinguishable from "no signal
+ /// recorded", which is exactly what the enum exists to avoid.
+ ///
+ ///
+ /// is the accurate label: a trace is the agent's own
+ /// record of what it did, not something a user asserted.
+ ///
+ ///
+ /// Safe at shipped defaults, and worth stating why. MinimumTrustForAdmissionBypass
+ /// defaults to , which
+ /// does not reach, so no trace gains an admission
+ /// bypass. MinimumTrustForSystemRole defaults to ,
+ /// which everything already met. A host that has lowered the bypass threshold to
+ /// or below is the one case where this changes
+ /// behaviour, and it can set this back to .
+ ///
+ ///
+ public MemoryTrustLevel DefaultTraceTrustLevel { get; init; } = MemoryTrustLevel.ModelGenerated;
}
diff --git a/src/AgentMemory.Abstractions/Options/RecallOptions.cs b/src/AgentMemory.Abstractions/Options/RecallOptions.cs
index 281e5a572..6fec728dd 100644
--- a/src/AgentMemory.Abstractions/Options/RecallOptions.cs
+++ b/src/AgentMemory.Abstractions/Options/RecallOptions.cs
@@ -5,6 +5,29 @@
///
public sealed record RecallOptions
{
+ ///
+ /// How long recall may spend assembling context before returning what it has (rank 13).
+ ///
+ ///
+ ///
+ /// — the default — waits for every section, which is exactly today's
+ /// behaviour. When set, sections still running when the budget expires are dropped and the
+ /// context comes back without them.
+ ///
+ ///
+ /// Degradation is marked, never silent. Every dropped section reports
+ /// TimedOut in its diagnostics, and RecallResult.Metadata["latencyBudgetExceeded"]
+ /// is set. A section cut short otherwise looks identical to one that searched and found nothing,
+ /// and a caller answering from a context it believes is complete is worse off than one that
+ /// waited.
+ ///
+ ///
+ /// Abandoned work is not cancelled mid-flight — the queries are already in the driver, and
+ /// tearing them down buys nothing the caller is waiting for. Their results are simply not used.
+ ///
+ ///
+ public TimeSpan? LatencyBudget { get; init; }
+
/// Maximum recent messages to include.
public int MaxRecentMessages { get; init; } = 10;
diff --git a/src/AgentMemory.Abstractions/Repositories/IEntitySummaryRepository.cs b/src/AgentMemory.Abstractions/Repositories/IEntitySummaryRepository.cs
new file mode 100644
index 000000000..ef44c9db2
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Repositories/IEntitySummaryRepository.cs
@@ -0,0 +1,33 @@
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Options;
+
+namespace AgentMemory.Abstractions.Repositories;
+
+///
+/// Persistence for synthesized entity summaries (S1).
+///
+///
+/// One summary per entity per owner. There is no history: a summary is derived, so an old one is not
+/// a record of what was believed — it is a record of what a synthesizer produced from facts the store
+/// still has, and those facts carry their own bitemporal history already.
+///
+public interface IEntitySummaryRepository
+{
+ /// Stores a summary, replacing the entity's existing one.
+ Task UpsertAsync(EntitySummary summary, CancellationToken cancellationToken = default);
+
+ ///
+ /// Reads the entity's summary, if any. Owner-confined (R1).
+ ///
+ ///
+ /// Returns whatever is stored, without judging freshness: staleness is decided against the
+ /// live facts by the caller that has them, and a repository silently withholding a stale row
+ /// would make "no summary" and "outdated summary" indistinguishable to a regeneration pass.
+ ///
+ Task GetByEntityAsync(
+ string entityId, MemoryScope scope, CancellationToken cancellationToken = default);
+
+ /// Removes an entity's summary.
+ Task DeleteByEntityAsync(
+ string entityId, MemoryScope scope, CancellationToken cancellationToken = default);
+}
diff --git a/src/AgentMemory.Abstractions/Services/IEntityExtractor.cs b/src/AgentMemory.Abstractions/Services/IEntityExtractor.cs
index 3c815b99a..7917430a6 100644
--- a/src/AgentMemory.Abstractions/Services/IEntityExtractor.cs
+++ b/src/AgentMemory.Abstractions/Services/IEntityExtractor.cs
@@ -13,4 +13,29 @@ public interface IEntityExtractor
Task> ExtractAsync(
IReadOnlyList messages,
CancellationToken cancellationToken = default);
+
+ ///
+ /// Extracts from , reading
+ /// only to understand them (E2).
+ ///
+ ///
+ ///
+ /// The default implementation ignores the context entirely and calls the existing overload
+ /// with the targets — byte-identical to pre-E2 behaviour. An extractor that cannot use context is
+ /// therefore correct by doing nothing, rather than being broken by a widened window.
+ ///
+ ///
+ /// A default interface method rather than a new required member: the extractor interfaces are
+ /// public and locked under SemVer, and a third-party extractor must keep compiling.
+ ///
+ ///
+ /// Implementers must not extract from the context turns. Doing so re-asserts facts already stored,
+ /// which now inflates confidence (S2) and mention_count (R7) purely because a fact sat
+ /// inside a sliding window — turning corroboration into recency.
+ ///
+ ///
+ Task> ExtractWithContextAsync(
+ ExtractionWindow window,
+ CancellationToken cancellationToken = default)
+ => ExtractAsync(window.Targets, cancellationToken);
}
diff --git a/src/AgentMemory.Abstractions/Services/IEntitySummaryService.cs b/src/AgentMemory.Abstractions/Services/IEntitySummaryService.cs
new file mode 100644
index 000000000..8255392b5
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Services/IEntitySummaryService.cs
@@ -0,0 +1,37 @@
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Options;
+
+namespace AgentMemory.Abstractions.Services;
+
+///
+/// Writes entity summaries and withholds any that can no longer prove it is current (S1).
+///
+///
+/// A summary is derived memory, which is where a store quietly starts lying: the sources change, the
+/// summary does not, and nothing about it looks any different afterwards. Every read here is checked
+/// against the live facts before it is handed back.
+///
+public interface IEntitySummaryService
+{
+ ///
+ /// Synthesizes and stores a summary for the entity, replacing any existing one.
+ ///
+ /// The stored summary, or when there was nothing to summarise.
+ Task RefreshAsync(
+ Entity entity, MemoryScope scope, CancellationToken cancellationToken = default);
+
+ ///
+ /// Returns the entity's summary only if it still describes the current facts.
+ ///
+ ///
+ /// The summary when its fingerprint still matches the store; when there is
+ /// none or when the one on record has gone stale.
+ ///
+ ///
+ /// Null for stale rather than a summary carrying an IsStale flag. A flag puts the decision
+ /// in every caller's hands, and one caller forgetting to check it is indistinguishable from
+ /// correct memory.
+ ///
+ Task GetIfCurrentAsync(
+ Entity entity, MemoryScope scope, CancellationToken cancellationToken = default);
+}
diff --git a/src/AgentMemory.Abstractions/Services/IEntitySummarySynthesizer.cs b/src/AgentMemory.Abstractions/Services/IEntitySummarySynthesizer.cs
new file mode 100644
index 000000000..e5e03c5a9
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Services/IEntitySummarySynthesizer.cs
@@ -0,0 +1,34 @@
+using AgentMemory.Abstractions.Domain;
+
+namespace AgentMemory.Abstractions.Services;
+
+///
+/// Turns an entity's facts into one synthesized description (S1).
+///
+///
+///
+/// A seam rather than a fixed implementation because the two reasonable answers have opposite cost
+/// profiles. The shipped default composes the text deterministically — no completion, reproducible
+/// across runs, and free to regenerate whenever sources move, which matters because sources move
+/// constantly. A host that wants prose can supply an LLM implementation and pay for it.
+///
+///
+/// Whatever synthesises, it may only use the facts it is given. The summary's fingerprint is
+/// computed from exactly those facts, so a synthesizer that reached for anything else would produce
+/// text whose staleness could never be detected — the one failure this design exists to rule out.
+///
+///
+public interface IEntitySummarySynthesizer
+{
+ ///
+ /// Composes a description of from .
+ ///
+ ///
+ /// The summary text, or when there is nothing worth summarising — which is
+ /// a real answer, not a failure, and must not be stored as an empty summary.
+ ///
+ Task SynthesizeAsync(
+ Entity entity,
+ IReadOnlyList facts,
+ CancellationToken cancellationToken = default);
+}
diff --git a/src/AgentMemory.Abstractions/Services/IFactExtractor.cs b/src/AgentMemory.Abstractions/Services/IFactExtractor.cs
index 2ebaa4533..ff26a9b40 100644
--- a/src/AgentMemory.Abstractions/Services/IFactExtractor.cs
+++ b/src/AgentMemory.Abstractions/Services/IFactExtractor.cs
@@ -13,4 +13,29 @@ public interface IFactExtractor
Task> ExtractAsync(
IReadOnlyList messages,
CancellationToken cancellationToken = default);
+
+ ///
+ /// Extracts from , reading
+ /// only to understand them (E2).
+ ///
+ ///
+ ///
+ /// The default implementation ignores the context entirely and calls the existing overload
+ /// with the targets — byte-identical to pre-E2 behaviour. An extractor that cannot use context is
+ /// therefore correct by doing nothing, rather than being broken by a widened window.
+ ///
+ ///
+ /// A default interface method rather than a new required member: the extractor interfaces are
+ /// public and locked under SemVer, and a third-party extractor must keep compiling.
+ ///
+ ///
+ /// Implementers must not extract from the context turns. Doing so re-asserts facts already stored,
+ /// which now inflates confidence (S2) and mention_count (R7) purely because a fact sat
+ /// inside a sliding window — turning corroboration into recency.
+ ///
+ ///
+ Task> ExtractWithContextAsync(
+ ExtractionWindow window,
+ CancellationToken cancellationToken = default)
+ => ExtractAsync(window.Targets, cancellationToken);
}
diff --git a/src/AgentMemory.Abstractions/Services/IMemoryIngestion.cs b/src/AgentMemory.Abstractions/Services/IMemoryIngestion.cs
index 47ed4cf4b..235ac609b 100644
--- a/src/AgentMemory.Abstractions/Services/IMemoryIngestion.cs
+++ b/src/AgentMemory.Abstractions/Services/IMemoryIngestion.cs
@@ -86,4 +86,100 @@ Task ExtractFromConversationAsync(
string conversationId,
string? userId = null,
CancellationToken cancellationToken = default);
+
+ ///
+ /// Ingests many extraction requests with bounded concurrency (rank 27).
+ ///
+ ///
+ ///
+ /// The documented bulk path. Loading a backlog was always possible — call
+ /// in a loop, or in a Parallel.ForEachAsync — and both
+ /// obvious ways are wrong in opposite directions: the serial loop wastes hours, and the unbounded
+ /// parallel one saturates the provider quota and the connection pool, degrading p99 for every
+ /// other tenant in the process while median latency looks fine.
+ ///
+ ///
+ /// Composed, not new machinery. This paces calls the host could have made itself; it does
+ /// not add a second ingestion path. That matters because a separate bulk pipeline would be a
+ /// second place for trust stamping, provenance and owner scoping to drift out of agreement with
+ /// the per-request one.
+ ///
+ ///
+ /// A default implementation is supplied so the interface stays SemVer-compatible: an existing
+ /// implementation keeps compiling and gets a correct, if
+ /// unoptimised, bulk path for free.
+ ///
+ ///
+ async Task IngestBulkAsync(
+ IReadOnlyList requests,
+ BulkIngestionOptions? options = null,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(requests);
+ options ??= new BulkIngestionOptions();
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(options.MaxConcurrency);
+
+ var outcomes = new BulkIngestionOutcome?[requests.Count];
+ using var gate = new SemaphoreSlim(options.MaxConcurrency, options.MaxConcurrency);
+ // Cancels the remaining work when ContinueOnError is false. Linked rather than replacing the
+ // caller's token, so a stop-on-error run still honours an outer cancellation.
+ using var stop = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+
+ var running = new List(requests.Count);
+ for (var i = 0; i < requests.Count; i++)
+ {
+ if (stop.IsCancellationRequested) break;
+
+ var index = i;
+ running.Add(Task.Run(async () =>
+ {
+ try
+ {
+ await gate.WaitAsync(stop.Token).ConfigureAwait(false);
+ }
+ catch (OperationCanceledException)
+ {
+ // Queued behind the gate when the run stopped. Left unattempted -- and caught
+ // HERE rather than by the block below, whose finally would Release a slot this
+ // task never acquired.
+ return;
+ }
+
+ try
+ {
+ var result = await ExtractAndPersistAsync(requests[index], stop.Token)
+ .ConfigureAwait(false);
+ outcomes[index] = new BulkIngestionOutcome(index, result, null);
+ }
+ catch (OperationCanceledException) when (stop.IsCancellationRequested)
+ {
+ // Left null: never attempted, or abandoned mid-flight. Recorded as
+ // NotAttemptedCount rather than as a failure, because re-running a cancelled
+ // request is correct and re-running a failed one may not be.
+ }
+ catch (Exception ex)
+ {
+ outcomes[index] = new BulkIngestionOutcome(index, null, ex);
+ if (!options.ContinueOnError) await stop.CancelAsync().ConfigureAwait(false);
+ }
+ finally
+ {
+ gate.Release();
+ }
+ }, CancellationToken.None));
+ }
+
+ await Task.WhenAll(running).ConfigureAwait(false);
+
+ // An outer cancellation is still an error for the caller; a stop-on-first-failure is not,
+ // because the failure it stopped for is already reported in the outcomes.
+ cancellationToken.ThrowIfCancellationRequested();
+
+ var completed = outcomes.Where(o => o is not null).Select(o => o!).ToList();
+ return new BulkIngestionResult
+ {
+ Outcomes = completed,
+ NotAttemptedCount = requests.Count - completed.Count,
+ };
+ }
}
diff --git a/src/AgentMemory.Abstractions/Services/IMemoryReranker.cs b/src/AgentMemory.Abstractions/Services/IMemoryReranker.cs
new file mode 100644
index 000000000..b9634b83d
--- /dev/null
+++ b/src/AgentMemory.Abstractions/Services/IMemoryReranker.cs
@@ -0,0 +1,93 @@
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Options;
+
+namespace AgentMemory.Abstractions.Services;
+
+///
+/// Reorders the candidates a retrieval returned, before context budgeting truncates them.
+///
+///
+///
+/// This seam is deliberately narrower than the task that proposed it. R2 asked for a reranker
+/// in order to fuse GraphRAG as a distinct retrieval channel, and that premise was killed on
+/// measurement: of 132 GraphRAG items, 132 were duplicates of what the structured surface had
+/// already retrieved and 0 verdicts changed. Fusing a channel that returns the same rows in a
+/// different order cannot help, and the trigger for revisiting it — a corpus with a genuinely separate
+/// knowledge graph — has not fired.
+///
+///
+/// What survives is the extension point, which R6 (node-distance) and R7 (mention frequency)
+/// both need and neither of which is about fusion. Keeping the seam and dropping the fusion is the
+/// honest reading of that measurement: the mechanism was worth building, the use case was not.
+///
+///
+/// Reranking reorders survivors; it cannot rescue what retrieval never returned. That is why
+/// this ships behind the retrieval-sufficiency work rather than before it — a reranker over a starved
+/// candidate set reorders seven of an owner's 504 facts and reports success. The signal now measures
+/// AUC 0.709–0.768, which is what made this safe to build.
+///
+///
+/// Implementations must be pure and fast: this runs inside recall, on the blocking path, once
+/// per section. Anything needing a database round trip should issue one bounded query, never
+/// one per candidate.
+///
+///
+public interface IMemoryReranker
+{
+ ///
+ /// Whether this reranker should run at all for the current request.
+ ///
+ ///
+ /// Checked before the candidates are materialised, so a disabled reranker costs nothing — not even
+ /// the allocation of the list it would have reordered.
+ ///
+ bool IsEnabled { get; }
+
+ ///
+ /// Returns reordered, or the same sequence when nothing changed.
+ ///
+ ///
+ /// The retrieval's own ranking, best first. Scores are the provider's, comparable within this
+ /// section and meaningless across sections.
+ ///
+ /// What the request knows: the query, its embedding, and the owner scope.
+ /// Cancels the reordering; a cancelled rerank leaves the provider order.
+ ///
+ ///
+ /// Returning a different set — adding or dropping candidates — is not supported and not
+ /// checked for cheaply, so it would corrupt the section's diagnostics silently. A reranker
+ /// reorders; a filter belongs in retrieval, where its effect on recall is measurable.
+ ///
+ ///
+ /// A reranker that throws must not fail the recall: callers treat an exception as "no reordering"
+ /// and continue with the provider's own ranking, because a degraded order is recoverable and a
+ /// failed recall is not.
+ ///
+ ///
+ Task> RerankAsync(
+ IReadOnlyList candidates,
+ MemoryRerankContext context,
+ CancellationToken cancellationToken = default);
+}
+
+///
+/// What a reranker is told about the request it is reordering for.
+///
+/// The user's query text, for a reranker that reads language.
+///
+/// The query vector, when one was generated. Null on a turn narrowed to categories that need no
+/// vector — a reranker depending on it must handle that rather than assume.
+///
+///
+/// The owner scope the retrieval ran under. A reranker issuing its own query must carry this:
+/// a reordering pass that reads another owner's graph is an isolation breach wearing a ranking hat.
+///
+///
+/// Which recall category is being reordered, so one reranker can serve several and behave differently
+/// per kind rather than pretending a fact and a trace rank alike.
+///
+public sealed record MemoryRerankContext(
+ string? Query,
+ float[]? QueryEmbedding,
+ MemoryScope? Scope,
+ MemoryItemKind SectionKind);
diff --git a/src/AgentMemory.Abstractions/Services/IPreferenceExtractor.cs b/src/AgentMemory.Abstractions/Services/IPreferenceExtractor.cs
index 348262991..c5d6f29a4 100644
--- a/src/AgentMemory.Abstractions/Services/IPreferenceExtractor.cs
+++ b/src/AgentMemory.Abstractions/Services/IPreferenceExtractor.cs
@@ -13,4 +13,29 @@ public interface IPreferenceExtractor
Task> ExtractAsync(
IReadOnlyList messages,
CancellationToken cancellationToken = default);
+
+ ///
+ /// Extracts from , reading
+ /// only to understand them (E2).
+ ///
+ ///
+ ///
+ /// The default implementation ignores the context entirely and calls the existing overload
+ /// with the targets — byte-identical to pre-E2 behaviour. An extractor that cannot use context is
+ /// therefore correct by doing nothing, rather than being broken by a widened window.
+ ///
+ ///
+ /// A default interface method rather than a new required member: the extractor interfaces are
+ /// public and locked under SemVer, and a third-party extractor must keep compiling.
+ ///
+ ///
+ /// Implementers must not extract from the context turns. Doing so re-asserts facts already stored,
+ /// which now inflates confidence (S2) and mention_count (R7) purely because a fact sat
+ /// inside a sliding window — turning corroboration into recency.
+ ///
+ ///
+ Task> ExtractWithContextAsync(
+ ExtractionWindow window,
+ CancellationToken cancellationToken = default)
+ => ExtractAsync(window.Targets, cancellationToken);
}
diff --git a/src/AgentMemory.Abstractions/Services/IRelationshipExtractor.cs b/src/AgentMemory.Abstractions/Services/IRelationshipExtractor.cs
index 32592025d..2b1a77613 100644
--- a/src/AgentMemory.Abstractions/Services/IRelationshipExtractor.cs
+++ b/src/AgentMemory.Abstractions/Services/IRelationshipExtractor.cs
@@ -13,4 +13,29 @@ public interface IRelationshipExtractor
Task> ExtractAsync(
IReadOnlyList messages,
CancellationToken cancellationToken = default);
+
+ ///
+ /// Extracts from , reading
+ /// only to understand them (E2).
+ ///
+ ///
+ ///
+ /// The default implementation ignores the context entirely and calls the existing overload
+ /// with the targets — byte-identical to pre-E2 behaviour. An extractor that cannot use context is
+ /// therefore correct by doing nothing, rather than being broken by a widened window.
+ ///
+ ///
+ /// A default interface method rather than a new required member: the extractor interfaces are
+ /// public and locked under SemVer, and a third-party extractor must keep compiling.
+ ///
+ ///
+ /// Implementers must not extract from the context turns. Doing so re-asserts facts already stored,
+ /// which now inflates confidence (S2) and mention_count (R7) purely because a fact sat
+ /// inside a sliding window — turning corroboration into recency.
+ ///
+ ///
+ Task> ExtractWithContextAsync(
+ ExtractionWindow window,
+ CancellationToken cancellationToken = default)
+ => ExtractAsync(window.Targets, cancellationToken);
}
diff --git a/src/AgentMemory.Abstractions/Services/IUnifiedMemoryExtractor.cs b/src/AgentMemory.Abstractions/Services/IUnifiedMemoryExtractor.cs
index fc3420f71..47d3e50aa 100644
--- a/src/AgentMemory.Abstractions/Services/IUnifiedMemoryExtractor.cs
+++ b/src/AgentMemory.Abstractions/Services/IUnifiedMemoryExtractor.cs
@@ -12,4 +12,18 @@ public interface IUnifiedMemoryExtractor
Task ExtractAsync(
IReadOnlyList messages,
CancellationToken cancellationToken = default);
+
+ ///
+ /// Extracts every supported category from , reading
+ /// only to understand them (E2).
+ ///
+ ///
+ /// The default implementation ignores the context and calls the existing overload — byte-identical
+ /// to pre-E2 behaviour. Implementers must not extract from context turns: doing so re-asserts
+ /// stored facts and inflates confidence (S2) and mention_count (R7) on nothing but recency.
+ ///
+ Task ExtractWithContextAsync(
+ ExtractionWindow window,
+ CancellationToken cancellationToken = default)
+ => ExtractAsync(window.Targets, cancellationToken);
}
diff --git a/src/AgentMemory.AgentFramework/AgentFrameworkOptions.cs b/src/AgentMemory.AgentFramework/AgentFrameworkOptions.cs
index d74aa781b..03e243468 100644
--- a/src/AgentMemory.AgentFramework/AgentFrameworkOptions.cs
+++ b/src/AgentMemory.AgentFramework/AgentFrameworkOptions.cs
@@ -11,6 +11,33 @@ public sealed class AgentFrameworkOptions
///
public ContextFormatOptions ContextFormat { get; set; } = new();
+ ///
+ /// Drops recalled chat history the host is already sending in the live thread.
+ ///
+ ///
+ ///
+ /// The provider sees the full live thread and, until now, discarded it — so recall's
+ /// RecentMessages re-sent turns the model was already being given, and the host paid for
+ /// both copies.
+ ///
+ ///
+ /// Filtered before MaxChatHistoryMessages applies, so this is a quality change as
+ /// much as a cost one: the same budget then carries that many genuinely new messages instead of
+ /// duplicates of the current turn.
+ ///
+ ///
+ /// Matching is on content only, never role. RecalledMessageRoleGate rewrites a
+ /// recalled message's role — privileged down to user below the trust threshold — while leaving its
+ /// content identical, so a role-keyed comparison would miss every match on exactly the hosts that
+ /// raised MinimumTrustForSystemRole.
+ ///
+ ///
+ /// On by default: sending the model two copies of the same turn has no upside, and the comparison
+ /// is a hash set over the thread the provider already holds.
+ ///
+ ///
+ public bool DeduplicateRecalledHistory { get; set; } = true;
+
///
/// When , the memory service runs extraction (entity/fact/preference)
/// automatically each time a message is persisted. Set to to extract
diff --git a/src/AgentMemory.AgentFramework/Mapping/MafTypeMapper.cs b/src/AgentMemory.AgentFramework/Mapping/MafTypeMapper.cs
index b95beb03b..58f45d79b 100644
--- a/src/AgentMemory.AgentFramework/Mapping/MafTypeMapper.cs
+++ b/src/AgentMemory.AgentFramework/Mapping/MafTypeMapper.cs
@@ -59,7 +59,8 @@ public static IReadOnlyList ToContextMessages(
MemoryContext context,
ContextFormatOptions? formatOptions = null,
IMemoryContextAdmissionPolicy? admissionPolicy = null,
- ILogger? logger = null)
+ ILogger? logger = null,
+ IReadOnlyList? liveThread = null)
{
var options = formatOptions ?? new ContextFormatOptions();
var admission = admissionPolicy ?? new DefaultMemoryContextAdmissionPolicy();
@@ -199,6 +200,38 @@ List CategoryMessages(
// newest `chatBudget` items are the FRONT of the list — Take(chatBudget). (R6-D: the previous
// Skip(count - chatBudget) kept the TAIL, i.e. the OLDEST messages, dropping the newest turns
// first — the opposite of "most recent".) Order is preserved (lead → chat → memory).
+ // The host already sends the live thread, and recall returns the same recent turns from
+ // storage, so the model sees them twice. Filtered BEFORE the budget on purpose: dropping
+ // duplicates first turns the same `chatBudget` slots into that many genuinely new messages
+ // rather than merely shortening the block -- a quality gain, not only a token saving.
+ //
+ // Fingerprinted on CONTENT ONLY, never role. RecalledMessageRoleGate rewrites a recalled
+ // message's role -- privileged to "user" below the trust threshold -- while leaving its
+ // content untouched, so a role-keyed fingerprint would fail to match precisely for the hosts
+ // that hardened MinimumTrustForSystemRole: the feature would silently no-op for the
+ // security-conscious configuration and work everywhere else.
+ if (liveThread is { Count: > 0 })
+ {
+ var live = liveThread
+ .Select(message => NormalizeForDedup(message.Text))
+ .Where(text => text.Length > 0)
+ .ToHashSet(StringComparer.Ordinal);
+
+ if (live.Count > 0)
+ {
+ var deduped = chatMessages
+ .Where(message => !live.Contains(NormalizeForDedup(message.Text)))
+ .ToList();
+ if (deduped.Count != chatMessages.Count)
+ {
+ logger?.LogDebug(
+ "Dropped {Dropped} recalled message(s) already present in the live thread.",
+ chatMessages.Count - deduped.Count);
+ }
+ chatMessages = deduped;
+ }
+ }
+
int chatBudget = Math.Max(0, options.MaxChatHistoryMessages);
var keptChat = chatMessages.Count > chatBudget
? chatMessages.Take(chatBudget).ToList()
@@ -211,6 +244,28 @@ List CategoryMessages(
return result;
}
+ ///
+ /// The dedup key for a chat message: its content, normalised for whitespace and case.
+ ///
+ ///
+ ///
+ /// Content only. Role is excluded because RecalledMessageRoleGate rewrites a recalled
+ /// message's role while leaving its content identical, so keying on role would miss every match on
+ /// exactly the hosts that raised MinimumTrustForSystemRole.
+ ///
+ ///
+ /// Whitespace-collapsed and case-folded because the live thread and the stored copy travel
+ /// different paths — one through the host's own formatting, one through persistence and back — and
+ /// a trailing newline is not a different message. Ordinal comparison after folding, so this stays
+ /// culture-independent.
+ ///
+ ///
+ internal static string NormalizeForDedup(string? text) =>
+ string.IsNullOrWhiteSpace(text)
+ ? string.Empty
+ : string.Join(' ', text.Split((char[]?)null, StringSplitOptions.RemoveEmptyEntries))
+ .ToUpperInvariant();
+
// Extracted from ToContextMessages' local Admit closure (stabilization fix) so it can be shared with
// ToGatedChatMessages below, instead of the two call sites re-deriving the same admission decision and
// logging independently. Behavior is unchanged from the closure this replaces.
diff --git a/src/AgentMemory.AgentFramework/Neo4jMemoryContextProvider.cs b/src/AgentMemory.AgentFramework/Neo4jMemoryContextProvider.cs
index f06fdce70..63e7f756c 100644
--- a/src/AgentMemory.AgentFramework/Neo4jMemoryContextProvider.cs
+++ b/src/AgentMemory.AgentFramework/Neo4jMemoryContextProvider.cs
@@ -103,7 +103,12 @@ internal async Task BuildContextAsync(
using var ownerScope = _ownerContext?.BeginOwnerScope(userId);
try
{
- var userMessages = messages
+ // Materialised once: the thread is enumerated for the query below AND handed to the
+ // mapper for dedup, and `messages` is an IEnumerable that a caller may well have built
+ // lazily. Enumerating it twice would be a silent correctness bug for a generator source.
+ var liveThread = messages as IReadOnlyList ?? messages.ToList();
+
+ var userMessages = liveThread
.Where(m => m.Role == ChatRole.User && !string.IsNullOrWhiteSpace(m.Text))
.ToList();
@@ -194,7 +199,13 @@ internal async Task BuildContextAsync(
return BuildResult();
}
- var contextMessages = MafTypeMapper.ToContextMessages(recallResult.Context, _formatOptions, _admissionPolicy, _logger);
+ // 2.5. The host is already sending the live thread; recall returns the same recent turns
+ // from storage, so without this the model sees them twice and pays for both. Passed here
+ // rather than filtered afterwards because the mapper drops duplicates BEFORE applying
+ // MaxChatHistoryMessages -- so the same budget carries that many genuinely new messages.
+ var contextMessages = MafTypeMapper.ToContextMessages(
+ recallResult.Context, _formatOptions, _admissionPolicy, _logger,
+ _agentOptions.DeduplicateRecalledHistory ? liveThread : null);
if (contextMessages.Count == 0)
return BuildResult();
diff --git a/src/AgentMemory.Core/Extraction/ConversationTextBuilder.cs b/src/AgentMemory.Core/Extraction/ConversationTextBuilder.cs
index 6d43797d5..966cd217f 100644
--- a/src/AgentMemory.Core/Extraction/ConversationTextBuilder.cs
+++ b/src/AgentMemory.Core/Extraction/ConversationTextBuilder.cs
@@ -50,4 +50,42 @@ public static string BuildNumbered(IReadOnlyList messages)
}
return builder.ToString();
}
+
+ ///
+ /// Renders a window as a fenced, unnumbered context block followed by the turns to extract from
+ /// (E2). Falls back to the plain rendering when the window carries no context.
+ ///
+ ///
+ ///
+ /// The context block is deliberately not numbered. Per-item provenance (L3c) numbers turns
+ /// from 1 and resolves turn N positionally to Targets[N-1]. Numbering the context
+ /// into the same sequence would shift every target index by the context length, and the failure
+ /// would not look like a crash — each fact would simply be attributed to a turn a few places
+ /// earlier, which afterwards is indistinguishable from correct attribution.
+ ///
+ ///
+ /// The fence is explicit text rather than a formatting convention because the model has to act on
+ /// it: everything inside is to be read and nothing inside is to be extracted.
+ ///
+ ///
+ public static string BuildWindow(ExtractionWindow window, bool numbered)
+ {
+ var targets = numbered ? BuildNumbered(window.Targets) : Build(window.Targets);
+ if (!window.HasContext) return targets;
+
+ var builder = new StringBuilder();
+ builder.Append(ContextOpen).Append('\n')
+ .Append(Build(window.Context)).Append('\n')
+ .Append(ContextClose).Append("\n\n")
+ .Append(targets);
+ return builder.ToString();
+ }
+
+ /// Opening fence of the read-only context block.
+ internal const string ContextOpen =
+ "--- EARLIER CONVERSATION (for reference only — do NOT extract anything from these turns) ---";
+
+ /// Closing fence of the read-only context block.
+ internal const string ContextClose =
+ "--- END OF EARLIER CONVERSATION. Extract ONLY from the turns below. ---";
}
diff --git a/src/AgentMemory.Core/Extraction/ExtractionNoveltyGate.cs b/src/AgentMemory.Core/Extraction/ExtractionNoveltyGate.cs
new file mode 100644
index 000000000..46e4490b5
--- /dev/null
+++ b/src/AgentMemory.Core/Extraction/ExtractionNoveltyGate.cs
@@ -0,0 +1,120 @@
+using AgentMemory.Abstractions.Domain;
+
+namespace AgentMemory.Core.Extraction;
+
+///
+/// Decides whether a batch of turns is worth spending an extraction call on (E4).
+///
+///
+///
+/// This gate sits before the completion, not before the write, and that placement is the whole
+/// design. A gate on the write path would skip persisting a triple already in the store — which
+/// sounds like the obvious saving and would silently disable two things that depend on the duplicate
+/// write actually happening: S2 confidence reinforcement, where a re-asserted fact earns α, and R7's
+/// mention_count, which is incremented by the MERGE. Corroboration is the repeated write.
+/// Gating it away would leave both features enabled and inert.
+///
+///
+/// The completion is also where the money is. The write is one round trip to Neo4j; the extraction is
+/// a model call over the rendered transcript, and on a corpus build it is essentially the entire bill.
+///
+///
+/// Precision over recall, and the asymmetry is worse here than anywhere else in the system.
+/// Declining to gate costs one extraction we might not have needed. Gating a turn that did carry a
+/// fact loses that fact until the user happens to say it again — the memory is simply never formed,
+/// and nothing downstream can recover it or even report that it is missing. So the gate fires only on
+/// turns that cannot carry a proposition at all: greetings, thanks, acknowledgement. Every genuinely
+/// ambiguous token is left OUT of the vocabulary on purpose — "yes", "no" and "sure" answer questions
+/// and are therefore contentful, however short they look.
+///
+///
+/// Deterministic and vocabulary-based rather than model-scored, for the same reason 9.1's resolver is:
+/// a gate that cost a completion to decide whether to spend a completion saves nothing, and one that
+/// varied between runs would make every measured build unreproducible.
+///
+///
+internal static class ExtractionNoveltyGate
+{
+ ///
+ /// Tokens that cannot assert anything on their own — greetings, gratitude, acknowledgement, and
+ /// the filler words that glue them together ("thanks so much", "hi there").
+ ///
+ ///
+ /// Deliberately absent: yes, no, yep, nope, sure, right,
+ /// correct. Each is a complete answer to a question, and a batch may hold the answer while
+ /// the question sat in the previous batch — so the question-mark check below cannot save them.
+ ///
+ private static readonly HashSet Uninformative = new(StringComparer.OrdinalIgnoreCase)
+ {
+ // acknowledgement
+ "ok", "okay", "k", "kk", "got", "it", "understood", "noted", "alright", "gotcha",
+ // gratitude
+ "thanks", "thank", "you", "thx", "ty", "cheers", "welcome", "youre", "pleasure", "my",
+ // appraisal with no object
+ "great", "cool", "nice", "perfect", "awesome", "excellent", "brilliant", "good", "fine",
+ // greeting and farewell
+ "hi", "hello", "hey", "there", "bye", "goodbye", "morning", "afternoon", "evening", "night",
+ // apology and politeness
+ "sorry", "apologies", "np", "problem", "worries",
+ // filler that binds the above
+ "a", "the", "so", "much", "very", "really", "that", "is", "was", "and", "then", "well",
+ "lol", "haha", "hah", "yay",
+ };
+
+ ///
+ /// when this batch is worth an extraction call.
+ ///
+ ///
+ /// Biased hard toward : anything the vocabulary does not fully explain is
+ /// treated as potentially contentful, including empty input, which is cheap to extract from and
+ /// whose handling belongs to the extractors rather than here.
+ ///
+ internal static bool IsWorthExtracting(IReadOnlyList messages)
+ {
+ if (messages is null || messages.Count == 0) return true;
+
+ foreach (var message in messages)
+ {
+ var content = message.Content;
+ if (string.IsNullOrWhiteSpace(content)) continue;
+
+ // A question mark means someone asked something, and the answer -- possibly a single word
+ // -- is exactly the kind of content this gate must never discard.
+ if (content.Contains('?', StringComparison.Ordinal)) return true;
+
+ if (!IsPurelyUninformative(content)) return true;
+ }
+
+ return false;
+ }
+
+ private static bool IsPurelyUninformative(string content)
+ {
+ var tokens = content.Split(
+ (char[]?)null, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+
+ foreach (var token in tokens)
+ {
+ var trimmed = token.Trim(Punctuation);
+ if (trimmed.Length == 0) continue;
+
+ // Any digit makes it contentful: "3" answers "how many?", and a bare number is data.
+ foreach (var c in trimmed)
+ {
+ if (char.IsDigit(c)) return false;
+ }
+
+ if (!Uninformative.Contains(trimmed.ToLowerInvariant())
+ && !Uninformative.Contains(
+ trimmed.Replace("'", string.Empty, StringComparison.Ordinal).ToLowerInvariant()))
+ {
+ return false;
+ }
+ }
+
+ return true;
+ }
+
+ private static readonly char[] Punctuation =
+ ['.', ',', '!', '?', ';', ':', '-', '—', '–', '"', '\'', '(', ')', '[', ']', '…'];
+}
diff --git a/src/AgentMemory.Core/Extraction/ExtractionStage.cs b/src/AgentMemory.Core/Extraction/ExtractionStage.cs
index a2f5fb5a2..077190cbb 100644
--- a/src/AgentMemory.Core/Extraction/ExtractionStage.cs
+++ b/src/AgentMemory.Core/Extraction/ExtractionStage.cs
@@ -58,7 +58,15 @@ public Task ExtractAsync(
ExtractionTypes typesToExtract,
MemoryScope? scope = null,
CancellationToken cancellationToken = default) =>
- ExtractCoreAsync(messages, typesToExtract, scope, preExtracted: null, cancellationToken);
+ ExtractCoreAsync(
+ ExtractionWindow.ForTargets(messages), typesToExtract, scope, preExtracted: null, cancellationToken);
+
+ public Task ExtractWithContextAsync(
+ ExtractionWindow window,
+ ExtractionTypes typesToExtract,
+ MemoryScope? scope = null,
+ CancellationToken cancellationToken = default) =>
+ ExtractCoreAsync(window, typesToExtract, scope, preExtracted: null, cancellationToken);
public Task ProcessUnifiedAsync(
IReadOnlyList messages,
@@ -68,17 +76,39 @@ public Task ProcessUnifiedAsync(
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(extracted);
- return ExtractCoreAsync(messages, typesToExtract, scope, extracted, cancellationToken);
+ return ExtractCoreAsync(
+ ExtractionWindow.ForTargets(messages), typesToExtract, scope, extracted, cancellationToken);
}
private async Task ExtractCoreAsync(
- IReadOnlyList messages,
+ ExtractionWindow window,
ExtractionTypes typesToExtract,
MemoryScope? scope,
UnifiedExtractionResult? preExtracted,
CancellationToken cancellationToken)
{
+ var messages = window.Targets;
+
+ // Targets only, never the context (E2). A context turn in here would become an EXTRACTED_FROM
+ // edge asserting the memory was stated in a turn the extractors were told not to extract from
+ // -- and afterwards that is indistinguishable from correct attribution.
var sourceMessageIds = messages.Select(m => m.MessageId).ToList();
+
+ // E4. Turns that cannot carry a fact -- "ok, thanks!" -- are not worth a completion. Only on
+ // the paying path: when preExtracted is non-null the caller has already spent the call, and
+ // gating there would discard a result that has been paid for rather than avoid the cost.
+ if (_options.SkipUninformativeTurns
+ && preExtracted is null
+ && !ExtractionNoveltyGate.IsWorthExtracting(messages))
+ {
+ // Logged rather than silent: a gate that quietly drops turns is indistinguishable from an
+ // extractor that found nothing, and the saving it claims would be unverifiable.
+ _logger.LogDebug(
+ "Skipping extraction for {Count} turn(s) carrying no extractable content (E4).",
+ messages.Count);
+ return new ExtractionStageResult { SourceMessageIds = sourceMessageIds };
+ }
+
var strategy = _options.MergeStrategy;
var failFast = _options.FailureMode == IngestionFailureMode.FailFast;
@@ -105,7 +135,7 @@ private async Task ExtractCoreAsync(
else if (unifiedExtractor is not null)
{
var unifiedRun = await ExtractUnifiedSafeAsync(
- unifiedExtractor, messages, typesToExtract, cancellationToken).ConfigureAwait(false);
+ unifiedExtractor, window, typesToExtract, cancellationToken).ConfigureAwait(false);
var unified = unifiedRun.Result;
unifiedOutcomes = unifiedRun.Outcomes;
entityRun = CompletedRun(typesToExtract.HasFlag(ExtractionTypes.Entities) ? unified.Entities : []);
@@ -116,22 +146,30 @@ private async Task ExtractCoreAsync(
else
{
entityRun = typesToExtract.HasFlag(ExtractionTypes.Entities)
- ? RunExtractorsAsync(_entityExtractors, e => e.ExtractAsync(messages, cancellationToken),
+ ? RunExtractorsAsync(_entityExtractors, e => window.HasContext
+ ? e.ExtractWithContextAsync(window, cancellationToken)
+ : e.ExtractAsync(messages, cancellationToken),
strategy, MergeStrategyFactory.CreateEntityStrategy, "entity",
MemoryItemKind.Entity, MemoryErrorCodes.EntityExtractionFailed, cancellationToken)
: EmptyRun();
factRun = typesToExtract.HasFlag(ExtractionTypes.Facts)
- ? RunExtractorsAsync(_factExtractors, f => f.ExtractAsync(messages, cancellationToken),
+ ? RunExtractorsAsync(_factExtractors, f => window.HasContext
+ ? f.ExtractWithContextAsync(window, cancellationToken)
+ : f.ExtractAsync(messages, cancellationToken),
strategy, MergeStrategyFactory.CreateFactStrategy, "fact",
MemoryItemKind.Fact, MemoryErrorCodes.FactExtractionFailed, cancellationToken)
: EmptyRun();
prefRun = typesToExtract.HasFlag(ExtractionTypes.Preferences)
- ? RunExtractorsAsync(_preferenceExtractors, p => p.ExtractAsync(messages, cancellationToken),
+ ? RunExtractorsAsync(_preferenceExtractors, p => window.HasContext
+ ? p.ExtractWithContextAsync(window, cancellationToken)
+ : p.ExtractAsync(messages, cancellationToken),
strategy, MergeStrategyFactory.CreatePreferenceStrategy, "preference",
MemoryItemKind.Preference, MemoryErrorCodes.PreferenceExtractionFailed, cancellationToken)
: EmptyRun();
relRun = typesToExtract.HasFlag(ExtractionTypes.Relationships)
- ? RunExtractorsAsync(_relationshipExtractors, r => r.ExtractAsync(messages, cancellationToken),
+ ? RunExtractorsAsync(_relationshipExtractors, r => window.HasContext
+ ? r.ExtractWithContextAsync(window, cancellationToken)
+ : r.ExtractAsync(messages, cancellationToken),
strategy, MergeStrategyFactory.CreateRelationshipStrategy, "relationship",
MemoryItemKind.Relationship, MemoryErrorCodes.RelationshipExtractionFailed, cancellationToken)
: EmptyRun();
@@ -359,13 +397,19 @@ await batchResolver.PrepareCandidatesAsync(candidateTypes, scope, cancellationTo
private async Task<(UnifiedExtractionResult Result, IReadOnlyList Outcomes)> ExtractUnifiedSafeAsync(
IUnifiedMemoryExtractor extractor,
- IReadOnlyList messages,
+ ExtractionWindow window,
ExtractionTypes typesToExtract,
CancellationToken cancellationToken)
{
try
{
- return (await extractor.ExtractAsync(messages, cancellationToken).ConfigureAwait(false),
+ // Without context, the ORIGINAL call. Not a shortcut: it keeps the off state identical at
+ // the call itself rather than only in the rendered transcript, so an extractor that never
+ // implemented the window overload -- including any third party's -- takes the exact path
+ // it always did.
+ return (await (window.HasContext
+ ? extractor.ExtractWithContextAsync(window, cancellationToken)
+ : extractor.ExtractAsync(window.Targets, cancellationToken)).ConfigureAwait(false),
Array.Empty());
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
diff --git a/src/AgentMemory.Core/Extraction/ExtractorBase.cs b/src/AgentMemory.Core/Extraction/ExtractorBase.cs
index bb6dd8ece..fd747587c 100644
--- a/src/AgentMemory.Core/Extraction/ExtractorBase.cs
+++ b/src/AgentMemory.Core/Extraction/ExtractorBase.cs
@@ -35,6 +35,18 @@ protected ExtractorBase(ILogger logger)
protected abstract Task> ExtractCoreAsync(
IReadOnlyList messages, CancellationToken cancellationToken);
+ ///
+ /// The window-aware core (E2). Reads to resolve references
+ /// and extracts only from .
+ ///
+ ///
+ /// Defaults to the context-free core, so an extractor that has not opted in behaves byte-identically
+ /// to its pre-E2 self rather than silently widening what it extracts.
+ ///
+ protected virtual Task> ExtractCoreWithContextAsync(
+ ExtractionWindow window, CancellationToken cancellationToken)
+ => ExtractCoreAsync(window.Targets, cancellationToken);
+
///
/// Extracts items from the supplied messages, returning an empty list when no messages
/// are provided or when the underlying extraction fails.
@@ -45,13 +57,24 @@ protected abstract Task> ExtractCoreAsync(
/// A task that resolves to the extracted items, or an empty list if there are no
/// messages or an error occurs during extraction.
///
- public async Task> ExtractAsync(
+ public Task> ExtractAsync(
IReadOnlyList messages, CancellationToken cancellationToken = default)
+ => ExtractWithContextAsync(ExtractionWindow.ForTargets(messages), cancellationToken);
+
+ ///
+ /// Extracts from the window's targets, reading its context only to understand them (E2), with the
+ /// same failure containment as the message overload.
+ ///
+ public async Task> ExtractWithContextAsync(
+ ExtractionWindow window, CancellationToken cancellationToken = default)
{
- if (messages.Count == 0) return Array.Empty();
+ // Emptiness is judged on the TARGETS. A window carrying context but nothing to extract from
+ // has nothing to do -- calling out with only background would spend a completion on turns the
+ // extractor has been told not to extract from.
+ if (window.Targets.Count == 0) return Array.Empty();
try
{
- return await ExtractCoreAsync(messages, cancellationToken).ConfigureAwait(false);
+ return await ExtractCoreWithContextAsync(window, cancellationToken).ConfigureAwait(false);
}
catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
{
diff --git a/src/AgentMemory.Core/Extraction/IExtractionStage.cs b/src/AgentMemory.Core/Extraction/IExtractionStage.cs
index 171c153f6..166c286d0 100644
--- a/src/AgentMemory.Core/Extraction/IExtractionStage.cs
+++ b/src/AgentMemory.Core/Extraction/IExtractionStage.cs
@@ -23,6 +23,22 @@ Task ExtractAsync(
MemoryScope? scope = null,
CancellationToken cancellationToken = default);
+ ///
+ /// As ,
+ /// but supplying earlier turns the extractors may read to resolve references (E2).
+ ///
+ ///
+ /// Provenance is attributed to only. A context turn must
+ /// never appear in SourceMessageIds: an EXTRACTED_FROM edge pointing at one would
+ /// claim the memory was stated in a turn the extractor was explicitly told not to extract from.
+ ///
+ Task ExtractWithContextAsync(
+ ExtractionWindow window,
+ ExtractionTypes typesToExtract,
+ MemoryScope? scope = null,
+ CancellationToken cancellationToken = default)
+ => ExtractAsync(window.Targets, typesToExtract, scope, cancellationToken);
+
///
/// Applies the normal validation, owner-scoped resolution, and filtering stages to a unified
/// result that was already extracted by a validated multi-session batch.
diff --git a/src/AgentMemory.Core/Memory/DeterministicEntitySummarySynthesizer.cs b/src/AgentMemory.Core/Memory/DeterministicEntitySummarySynthesizer.cs
new file mode 100644
index 000000000..3c4781ee4
--- /dev/null
+++ b/src/AgentMemory.Core/Memory/DeterministicEntitySummarySynthesizer.cs
@@ -0,0 +1,87 @@
+using System.Globalization;
+using System.Text;
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Services;
+
+namespace AgentMemory.Core.Memory;
+
+///
+/// Composes an entity summary from its facts without a model call (S1).
+///
+///
+///
+/// The shipped default, and deliberately not an LLM. A summary is invalidated whenever any of its
+/// sources moves, so it is regenerated often; a completion per entity per change would make the
+/// feature cost scale with how much the conversation talks about its subjects — which is exactly the
+/// entities that get summarised most.
+///
+///
+/// It is also reproducible. Two runs over the same facts produce the same bytes, so a summary can be
+/// compared, fingerprinted and diffed, and a change in the text always means a change in the facts
+/// rather than a change in a sampler's mood.
+///
+///
+/// The output is a grouped rendering, not prose: predicates gathered with their objects, ordered
+/// deterministically, most-confident first within each predicate. Honest about what it is — a
+/// compact projection of the graph, which is what a caller needs when the alternative is twenty
+/// separate facts each spending context to say one thing.
+///
+///
+internal sealed class DeterministicEntitySummarySynthesizer : IEntitySummarySynthesizer
+{
+ /// Facts below this confidence are left out of the summary.
+ ///
+ /// A summary states things flatly, with none of the per-fact confidence a caller would otherwise
+ /// see. Folding a 0.2-confidence guess into that sentence would present it with the same
+ /// authority as everything else and remove the only signal that it was doubtful.
+ ///
+ public double MinimumConfidence { get; init; } = 0.5;
+
+ ///
+ public Task SynthesizeAsync(
+ Entity entity,
+ IReadOnlyList facts,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(entity);
+ ArgumentNullException.ThrowIfNull(facts);
+
+ var usable = facts
+ .Where(f => f.Confidence >= MinimumConfidence)
+ .Where(f => !string.IsNullOrWhiteSpace(f.Predicate) && !string.IsNullOrWhiteSpace(f.Object))
+ .ToList();
+
+ // Null, not an empty summary. "Nothing is known about this entity above the confidence floor"
+ // is a real answer, and storing it as an empty string would create a node that satisfies every
+ // has-a-summary check while saying nothing.
+ if (usable.Count == 0) return Task.FromResult(null);
+
+ var builder = new StringBuilder();
+ builder.Append(entity.Name);
+ if (!string.IsNullOrWhiteSpace(entity.Type))
+ builder.Append(" (").Append(entity.Type).Append(')');
+ builder.Append(':');
+
+ var grouped = usable
+ .GroupBy(f => f.Predicate, StringComparer.OrdinalIgnoreCase)
+ .OrderBy(g => g.Key, StringComparer.OrdinalIgnoreCase);
+
+ foreach (var group in grouped)
+ {
+ var objects = group
+ // Most-confident first, then alphabetical: confidence alone leaves ties resolved by
+ // whatever order the store happened to return, which would make the text -- and so its
+ // fingerprint -- vary between identical runs.
+ .OrderByDescending(f => f.Confidence)
+ .ThenBy(f => f.Object, StringComparer.OrdinalIgnoreCase)
+ .Select(f => f.Object)
+ .Distinct(StringComparer.OrdinalIgnoreCase);
+
+ builder.Append(string.Create(
+ CultureInfo.InvariantCulture,
+ $"\n- {group.Key}: {string.Join("; ", objects)}"));
+ }
+
+ return Task.FromResult(builder.ToString());
+ }
+}
diff --git a/src/AgentMemory.Core/Memory/EntitySummaryService.cs b/src/AgentMemory.Core/Memory/EntitySummaryService.cs
new file mode 100644
index 000000000..6fe1c53ea
--- /dev/null
+++ b/src/AgentMemory.Core/Memory/EntitySummaryService.cs
@@ -0,0 +1,134 @@
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Options;
+using AgentMemory.Abstractions.Repositories;
+using AgentMemory.Abstractions.Services;
+using Microsoft.Extensions.Logging;
+
+namespace AgentMemory.Core.Memory;
+
+///
+/// Writes entity summaries, and refuses to hand back one that can no longer prove it is current (S1).
+///
+///
+///
+/// The synthesis is the easy half. The half that decides whether this feature is an asset or a
+/// liability is what happens after a source fact is superseded — and the answer here is that
+/// the summary stops being used, immediately, without anything having to remember to delete it.
+///
+///
+/// Detection rather than invalidation-on-write. A supersession could instead go and mark every
+/// affected summary, and that is the design that fails quietly: it has to find them all, it has to run
+/// in the same transaction, and any path that writes a fact without going through it leaves a summary
+/// that looks current and is not. Recomputing the fingerprint on read cannot be bypassed by a writer
+/// that did not know summaries existed.
+///
+///
+/// The cost is one extra read of the entity's facts before a summary is used. That is the same read
+/// the summary is saving the caller, so a stale summary costs what not having one would have cost —
+/// and a fresh summary still saves the context, which is what it was for.
+///
+///
+internal sealed class EntitySummaryService : IEntitySummaryService
+{
+ private readonly IFactRepository _facts;
+ private readonly IEntitySummaryRepository _summaries;
+ private readonly IEntitySummarySynthesizer _synthesizer;
+ private readonly IClock _clock;
+ private readonly IIdGenerator _ids;
+ private readonly ILogger _logger;
+
+ /// Public ctor: the type is internal, and DI can only activate it through one.
+ public EntitySummaryService(
+ IFactRepository facts,
+ IEntitySummaryRepository summaries,
+ IEntitySummarySynthesizer synthesizer,
+ IClock clock,
+ IIdGenerator ids,
+ ILogger logger)
+ {
+ _facts = facts;
+ _summaries = summaries;
+ _synthesizer = synthesizer;
+ _clock = clock;
+ _ids = ids;
+ _logger = logger;
+ }
+
+ ///
+ /// Synthesizes and stores a summary for , replacing any existing one.
+ ///
+ /// The stored summary, or when there was nothing to summarise.
+ public async Task RefreshAsync(
+ Entity entity,
+ MemoryScope scope,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(entity);
+
+ var facts = await _facts.GetBySubjectAsync(entity.Name, scope, cancellationToken).ConfigureAwait(false);
+ var live = facts.Where(f => f.InvalidatedAtUtc is null).ToList();
+
+ var content = await _synthesizer
+ .SynthesizeAsync(entity, live, cancellationToken).ConfigureAwait(false);
+ if (string.IsNullOrWhiteSpace(content))
+ {
+ _logger.LogDebug("Nothing to summarise for entity {EntityId}.", entity.EntityId);
+ return null;
+ }
+
+ // Fingerprinted from the SAME list handed to the synthesizer. Reading the facts twice, or
+ // filtering differently here, would produce a fingerprint describing a set the text was never
+ // written from -- a summary that could be stale from the moment it was stored.
+ var summary = new EntitySummary
+ {
+ SummaryId = _ids.GenerateId(),
+ EntityId = entity.EntityId,
+ Content = content,
+ SourceFactIds = live.Select(f => f.FactId).ToList(),
+ SourceFingerprint = EntitySummary.ComputeFingerprint(Sources(live)),
+ OwnerId = entity.OwnerId,
+ GeneratedAtUtc = _clock.UtcNow,
+ };
+
+ await _summaries.UpsertAsync(summary, cancellationToken).ConfigureAwait(false);
+ return summary;
+ }
+
+ ///
+ /// Returns the entity's summary only if it still describes the current facts.
+ ///
+ ///
+ /// The summary when its fingerprint still matches the store; when there is
+ /// none or when the one on record has gone stale.
+ ///
+ ///
+ /// Null for stale is deliberate and is the whole safety property. Returning it with an
+ /// IsStale flag would put the decision in every caller's hands, and the failure of any one
+ /// of them to check it is indistinguishable from correct memory.
+ ///
+ public async Task GetIfCurrentAsync(
+ Entity entity,
+ MemoryScope scope,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(entity);
+
+ var stored = await _summaries
+ .GetByEntityAsync(entity.EntityId, scope, cancellationToken).ConfigureAwait(false);
+ if (stored is null) return null;
+
+ var facts = await _facts.GetBySubjectAsync(entity.Name, scope, cancellationToken).ConfigureAwait(false);
+ var live = facts.Where(f => f.InvalidatedAtUtc is null).ToList();
+ var current = EntitySummary.ComputeFingerprint(Sources(live));
+
+ if (string.Equals(current, stored.SourceFingerprint, StringComparison.Ordinal)) return stored;
+
+ _logger.LogDebug(
+ "Entity summary for {EntityId} is stale ({Stored} != {Current}); not used.",
+ entity.EntityId, stored.SourceFingerprint, current);
+ return null;
+ }
+
+ private static IEnumerable Sources(IEnumerable facts) =>
+ facts.Select(f => new EntitySummarySource(f.FactId, f.Confidence, Invalidated: false));
+}
diff --git a/src/AgentMemory.Core/Memory/MemoryBlockRenderer.cs b/src/AgentMemory.Core/Memory/MemoryBlockRenderer.cs
new file mode 100644
index 000000000..a3638cf1e
--- /dev/null
+++ b/src/AgentMemory.Core/Memory/MemoryBlockRenderer.cs
@@ -0,0 +1,188 @@
+using System.Globalization;
+using System.Text;
+using AgentMemory.Abstractions.Domain;
+
+namespace AgentMemory.Core.Memory;
+
+///
+/// Renders a memory block from what the graph currently holds (S4).
+///
+///
+///
+/// Deterministic and projection-only. Two renders over the same memory produce the same bytes, so a
+/// developer diffing two blocks sees what changed in memory rather than what changed in a sampler.
+///
+///
+/// There is no inverse. Nothing here parses a block back into memories, and that absence is the
+/// design: a round-trippable block invites an agent to edit it and hand it back, at which point the
+/// block becomes the real store and the graph's provenance, trust and supersession records describe
+/// something else.
+///
+///
+internal static class MemoryBlockRenderer
+{
+ ///
+ /// Builds a block from the supplied memories, newest and most-confident first within each kind.
+ ///
+ /// Entities to include.
+ /// Facts to include. Superseded facts are excluded.
+ /// Preferences to include.
+ /// Render timestamp.
+ /// Owner the block describes.
+ ///
+ /// Hard cap. Anything beyond it is counted into rather
+ /// than dropped quietly.
+ ///
+ public static MemoryBlock Render(
+ IReadOnlyList entities,
+ IReadOnlyList facts,
+ IReadOnlyList preferences,
+ DateTimeOffset renderedAtUtc,
+ string? ownerId = null,
+ int maxLines = 50)
+ {
+ ArgumentNullException.ThrowIfNull(entities);
+ ArgumentNullException.ThrowIfNull(facts);
+ ArgumentNullException.ThrowIfNull(preferences);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxLines);
+
+ var all = new List();
+
+ all.AddRange(entities
+ .OrderByDescending(e => e.Confidence)
+ .ThenBy(e => e.Name, StringComparer.OrdinalIgnoreCase)
+ .Select(e => new MemoryBlockLine(
+ e.EntityId,
+ MemoryItemKind.Entity,
+ string.IsNullOrWhiteSpace(e.Type) ? e.Name : $"{e.Name} — {e.Type}")));
+
+ all.AddRange(facts
+ // A block is what memory believes NOW. Showing a superseded fact beside a live one, with
+ // no per-item history in view, presents a retracted claim as current.
+ .Where(f => f.InvalidatedAtUtc is null)
+ .OrderByDescending(f => f.Confidence)
+ .ThenBy(f => f.Subject, StringComparer.OrdinalIgnoreCase)
+ .ThenBy(f => f.Predicate, StringComparer.OrdinalIgnoreCase)
+ .Select(f => new MemoryBlockLine(
+ f.FactId,
+ MemoryItemKind.Fact,
+ $"{f.Subject} {f.Predicate} {f.Object}")));
+
+ all.AddRange(preferences
+ .OrderByDescending(p => p.Confidence)
+ .ThenBy(p => p.Category, StringComparer.OrdinalIgnoreCase)
+ .Select(p => new MemoryBlockLine(
+ p.PreferenceId,
+ MemoryItemKind.Preference,
+ string.IsNullOrWhiteSpace(p.Category) ? p.PreferenceText : $"{p.Category}: {p.PreferenceText}")));
+
+ return new MemoryBlock
+ {
+ OwnerId = ownerId,
+ RenderedAtUtc = renderedAtUtc,
+ Lines = all.Take(maxLines).ToList(),
+ OmittedCount = Math.Max(0, all.Count - maxLines),
+ };
+ }
+
+ ///
+ /// Builds a block from memory-history rows (S4).
+ ///
+ ///
+ ///
+ /// The practical entry point. IMemoryHistoryService already answers "what does memory hold
+ /// for this owner" across all three kinds through an audited read path, so the block is a
+ /// rendering of an existing query rather than a new way to reach into the store — which is the
+ /// point of calling it a projection.
+ ///
+ ///
+ /// Invalidated rows are dropped here as well as being excludable at the query. Belt and braces on
+ /// purpose: a caller that forgets IncludeInvalidated = false would otherwise get a block
+ /// presenting retracted claims as current, and nothing about it would look wrong.
+ ///
+ ///
+ public static MemoryBlock Render(
+ IReadOnlyList records,
+ DateTimeOffset renderedAtUtc,
+ string? ownerId = null,
+ int maxLines = 50)
+ {
+ ArgumentNullException.ThrowIfNull(records);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(maxLines);
+
+ var lines = records
+ .Where(r => r.Status != MemoryHistoryStatus.Invalidated && r.InvalidatedAtUtc is null)
+ .OrderBy(r => KindOrder(r.Kind))
+ .ThenBy(r => r.Summary, StringComparer.OrdinalIgnoreCase)
+ .Select(r => new MemoryBlockLine(r.Id, ToItemKind(r.Kind), r.Summary))
+ .ToList();
+
+ return new MemoryBlock
+ {
+ OwnerId = ownerId,
+ RenderedAtUtc = renderedAtUtc,
+ Lines = lines.Take(maxLines).ToList(),
+ OmittedCount = Math.Max(0, lines.Count - maxLines),
+ };
+ }
+
+ private static int KindOrder(MemoryHistoryKind kind) => kind switch
+ {
+ MemoryHistoryKind.Entity => 0,
+ MemoryHistoryKind.Fact => 1,
+ _ => 2,
+ };
+
+ private static MemoryItemKind ToItemKind(MemoryHistoryKind kind) => kind switch
+ {
+ MemoryHistoryKind.Entity => MemoryItemKind.Entity,
+ MemoryHistoryKind.Fact => MemoryItemKind.Fact,
+ _ => MemoryItemKind.Preference,
+ };
+
+ ///
+ /// Renders a block as the text a human reads.
+ ///
+ ///
+ /// Ids are shown, not hidden behind the prose. They are what turns "that fact is wrong" into an
+ /// action against a specific memory, which is the whole reason this stayed a read surface: the
+ /// correction goes through the audited write path rather than by editing this text.
+ ///
+ public static string ToText(MemoryBlock block)
+ {
+ ArgumentNullException.ThrowIfNull(block);
+
+ var builder = new StringBuilder();
+ builder.Append("# Memory");
+ if (!string.IsNullOrWhiteSpace(block.OwnerId))
+ builder.Append(" — ").Append(block.OwnerId);
+ builder.Append(string.Create(
+ CultureInfo.InvariantCulture,
+ $"\n_rendered {block.RenderedAtUtc:u} — a snapshot, not a document to edit_\n"));
+
+ foreach (var kind in new[] { MemoryItemKind.Entity, MemoryItemKind.Fact, MemoryItemKind.Preference })
+ {
+ var lines = block.Lines.Where(l => l.Kind == kind).ToList();
+ if (lines.Count == 0) continue;
+
+ builder.Append('\n').Append("## ").Append(kind).Append("\n");
+ foreach (var line in lines)
+ builder.Append(string.Create(CultureInfo.InvariantCulture, $"- {line.Text} `{line.MemoryId}`\n"));
+ }
+
+ if (block.IsTruncated)
+ {
+ // Stated in the text itself, not only on the object. A reader who sees a block ending
+ // cleanly assumes they have seen everything, and the whole value of this view is that it
+ // can be trusted to show what memory holds.
+ builder.Append(string.Create(
+ CultureInfo.InvariantCulture,
+ $"\n_… {block.OmittedCount} more not shown (block limit reached)_\n"));
+ }
+
+ if (block.Lines.Count == 0)
+ builder.Append("\n_Memory holds nothing for this owner yet._\n");
+
+ return builder.ToString();
+ }
+}
diff --git a/src/AgentMemory.Core/Memory/TemporalQueryParser.cs b/src/AgentMemory.Core/Memory/TemporalQueryParser.cs
new file mode 100644
index 000000000..f05afde21
--- /dev/null
+++ b/src/AgentMemory.Core/Memory/TemporalQueryParser.cs
@@ -0,0 +1,161 @@
+using System.Globalization;
+using System.Text.RegularExpressions;
+
+namespace AgentMemory.Core.Memory;
+
+///
+/// Finds the point in time a question is asking about, so bitemporal recall can be reached from a
+/// natural-language turn (R4).
+///
+///
+///
+/// RecallAsOfAsync(validAsOf, systemAsOf) already exists and nothing in an ordinary conversation
+/// can reach it: "what did I think back in March?" recalls against now, exactly like every other
+/// question. Without this the bitemporal read path is a capability nothing can ask for.
+///
+///
+/// Precision over recall, deliberately and asymmetrically. A missed expression costs nothing —
+/// the turn recalls against now, which is today's behaviour. A false positive silently filters memory
+/// to a window the user never asked about, and the answer that comes back looks perfectly ordinary.
+/// Every pattern here therefore requires an explicit temporal marker rather than inferring one:
+/// "in March" is temporal, a bare "March" may be a surname; "last week" is
+/// temporal, "the last item" is not.
+///
+///
+/// No model call and no culture-dependent parsing: this runs on every turn when enabled, and a
+/// resolver that cost a completion would be more expensive than the recall it modifies.
+///
+///
+internal static class TemporalQueryParser
+{
+ private const RegexOptions Options =
+ RegexOptions.IgnoreCase | RegexOptions.CultureInvariant | RegexOptions.ExplicitCapture;
+
+ private static readonly TimeSpan Timeout = TimeSpan.FromMilliseconds(100);
+
+ ///
+ /// last|past N unit(s) ago and the bare last week/month/quarter/year.
+ ///
+ ///
+ /// "last" must be followed by a time unit. Alone it is far more often ordinal — "the last item",
+ /// "last one wins" — and treating those as temporal would rewrite the recall window of ordinary
+ /// questions.
+ ///
+ private static readonly Regex RelativeUnits = new(
+ @"\b(?:(?\d{1,3})\s+)?(?day|days|week|weeks|month|months|quarter|quarters|year|years)\s+ago\b"
+ + @"|\blast\s+(?week|month|quarter|year)\b"
+ + @"|\bpast\s+(?\d{1,3})\s+(?day|days|week|weeks|month|months|year|years)\b",
+ Options, Timeout);
+
+ /// A month name behind a preposition, optionally with a year.
+ ///
+ /// The preposition is required. "March" is a common surname and "may" is a verb in nearly every
+ /// sentence that contains it; "in May" is unambiguous where "may" is not.
+ ///
+ private static readonly Regex MonthName = new(
+ @"\b(?:in|back\s+in|during|around)\s+(?january|february|march|april|may|june|july|august|"
+ + @"september|october|november|december)(?:\s+(?(?:19|20)\d{2}))?\b",
+ Options, Timeout);
+
+ /// A four-digit year behind a preposition.
+ ///
+ /// Bounded to 19xx/20xx and requiring a preposition, so "in 2024" resolves and "in 2024 units of
+ /// stock" — where the number is a quantity — does not accidentally become a date.
+ ///
+ private static readonly Regex Year = new(
+ @"\b(?:in|back\s+in|during)\s+(?(?:19|20)\d{2})\b(?!\s*(?:units?|items?|records?|rows?))",
+ Options, Timeout);
+
+ private static readonly Regex Yesterday = new(@"\byesterday\b", Options, Timeout);
+
+ ///
+ /// The instant this question is asking about, or when it asks about now.
+ ///
+ /// The user's turn.
+ /// The reference instant; relative expressions resolve against it.
+ ///
+ ///
+ /// Null is the overwhelmingly common answer and the safe one: it means "recall as the system
+ /// behaves today". Only an explicit past reference produces an instant.
+ ///
+ ///
+ /// A future reference returns null rather than a future instant. As-of recall reconstructs
+ /// what was known at a past moment; asking it about next month would return everything, which is
+ /// indistinguishable from ordinary recall except that it silently ignored the user's question.
+ ///
+ ///
+ internal static DateTimeOffset? Resolve(string? query, DateTimeOffset now)
+ {
+ if (string.IsNullOrWhiteSpace(query)) return null;
+
+ var resolved = ResolveCore(query, now);
+
+ // Never ahead of the reference instant. A parse that lands in the future is either a
+ // misreading or a question about the future, and neither should narrow a recall window.
+ return resolved is { } instant && instant < now ? instant : null;
+ }
+
+ private static DateTimeOffset? ResolveCore(string query, DateTimeOffset now)
+ {
+ if (Yesterday.IsMatch(query)) return now.AddDays(-1);
+
+ var relative = RelativeUnits.Match(query);
+ if (relative.Success)
+ {
+ var count = relative.Groups["n"].Success
+ ? int.Parse(relative.Groups["n"].Value, CultureInfo.InvariantCulture)
+ : relative.Groups["n2"].Success
+ ? int.Parse(relative.Groups["n2"].Value, CultureInfo.InvariantCulture)
+ : 1;
+
+ var unit = relative.Groups["unit"].Success ? relative.Groups["unit"].Value
+ : relative.Groups["lunit"].Success ? relative.Groups["lunit"].Value
+ : relative.Groups["punit"].Value;
+
+ return unit.ToLowerInvariant().TrimEnd('s') switch
+ {
+ "day" => now.AddDays(-count),
+ "week" => now.AddDays(-7 * count),
+ "month" => now.AddMonths(-count),
+ "quarter" => now.AddMonths(-3 * count),
+ "year" => now.AddYears(-count),
+ _ => null,
+ };
+ }
+
+ var month = MonthName.Match(query);
+ if (month.Success)
+ {
+ var monthNumber = MonthNumber(month.Groups["month"].Value);
+ if (monthNumber == 0) return null;
+
+ var year = month.Groups["year"].Success
+ ? int.Parse(month.Groups["year"].Value, CultureInfo.InvariantCulture)
+ : now.Month >= monthNumber ? now.Year : now.Year - 1;
+
+ // The END of the named month: "what did I think back in March" means anything known by
+ // the close of March, not by its first instant -- which would exclude the whole month.
+ return EndOfMonth(year, monthNumber, now.Offset);
+ }
+
+ var year4 = Year.Match(query);
+ if (year4.Success)
+ {
+ var value = int.Parse(year4.Groups["year"].Value, CultureInfo.InvariantCulture);
+ return EndOfMonth(value, 12, now.Offset);
+ }
+
+ return null;
+ }
+
+ private static DateTimeOffset EndOfMonth(int year, int month, TimeSpan offset) =>
+ new DateTimeOffset(year, month, DateTime.DaysInMonth(year, month), 23, 59, 59, offset);
+
+ private static int MonthNumber(string name) => name.ToLowerInvariant() switch
+ {
+ "january" => 1, "february" => 2, "march" => 3, "april" => 4,
+ "may" => 5, "june" => 6, "july" => 7, "august" => 8,
+ "september" => 9, "october" => 10, "november" => 11, "december" => 12,
+ _ => 0,
+ };
+}
diff --git a/src/AgentMemory.Core/ServiceCollectionExtensions.cs b/src/AgentMemory.Core/ServiceCollectionExtensions.cs
index 62f51cbe0..0d38d0f7f 100644
--- a/src/AgentMemory.Core/ServiceCollectionExtensions.cs
+++ b/src/AgentMemory.Core/ServiceCollectionExtensions.cs
@@ -5,6 +5,7 @@
using AgentMemory.Abstractions.Options;
using AgentMemory.Abstractions.Services;
using AgentMemory.Core.Extraction;
+using AgentMemory.Core.Memory;
using AgentMemory.Core.Resolution;
using AgentMemory.Core.Services;
using AgentMemory.Core.Services.Budgeting;
@@ -228,6 +229,13 @@ public static IServiceCollection AddAgentMemoryCore(
// Callers may override by registering their own IEntityResolver before calling this method.
services.TryAddScoped();
+ // S1. The deterministic synthesizer is the default because a summary is regenerated every
+ // time any of its sources moves; a completion per entity per change would scale cost with
+ // exactly how much the conversation talks about its subjects. TryAdd, so a host wanting
+ // prose registers an LLM synthesizer before calling this and keeps it.
+ services.TryAddScoped();
+ services.TryAddScoped();
+
// Keep StubEntityResolver available for explicit fallback use.
services.TryAddScoped();
diff --git a/src/AgentMemory.Core/Services/MemoryContextAssembler.cs b/src/AgentMemory.Core/Services/MemoryContextAssembler.cs
index 5649003e8..b8bd22433 100644
--- a/src/AgentMemory.Core/Services/MemoryContextAssembler.cs
+++ b/src/AgentMemory.Core/Services/MemoryContextAssembler.cs
@@ -113,7 +113,8 @@ private static MemoryContextSectionDiagnostics Diagnose(
int requestedLimit,
IReadOnlyList items,
IReadOnlyList ranked,
- double minimumScore)
+ double minimumScore,
+ bool timedOut = false)
{
// Scores come from the ranked items, which exist only when the provider could supply them.
// An unscoreable section reports null rather than a placeholder: zero is a real score.
@@ -125,7 +126,7 @@ private static MemoryContextSectionDiagnostics Diagnose(
}
return new MemoryContextSectionDiagnostics(
- searched, requestedLimit, items.Count, top, low, minimumScore);
+ searched, requestedLimit, items.Count, top, low, minimumScore, timedOut);
}
///
@@ -221,6 +222,13 @@ public async Task AssembleContextAsync(
IReadOnlyList<(Fact Fact, double Score)> factScores = Array.Empty<(Fact, double)>();
IReadOnlyList<(ReasoningTrace Trace, double Score)> traceScores = Array.Empty<(ReasoningTrace, double)>();
+ // Rank 13 bookkeeping, at METHOD scope: the fan-out lives in a nested block and these are read
+ // by the diagnostics built after it closes. A section that searched and found nothing and one
+ // that never came back produce an identical section; only one means the answer is incomplete.
+ var budgetExceeded = false;
+ bool droppedRecent = false, droppedRelevant = false, droppedEntities = false,
+ droppedPreferences = false, droppedFacts = false, droppedTraces = false;
+
// J2.2 resolution, computed once at method scope so it can be both used by the fact search
// and reported on the context. Which relations a question resolved to is the difference
// between "expansion had nothing to expand" and "expansion ran and did not help", and those
@@ -399,12 +407,42 @@ public async Task AssembleContextAsync(
// One handle per section, so a fault in any of them is still observed here rather than
// surfacing later as an unobserved task exception.
- await Task.WhenAll(
+ Task[] sections =
+ [
recentTask, relevantTask,
entitiesScoredTask ?? (Task)entitiesTask,
preferencesScoredTask ?? (Task)preferencesTask,
factsScoredTask ?? (Task)factsTask,
- tracesScoredTask ?? (Task)tracesTask).ConfigureAwait(false);
+ tracesScoredTask ?? (Task)tracesTask,
+ ];
+
+ // Rank 13. With no budget this is the original unconditional wait, byte for byte.
+ if (recallOpts.LatencyBudget is { } latencyBudget
+ && await WaitWithinBudgetAsync(sections, latencyBudget, cancellationToken).ConfigureAwait(false))
+ {
+ // Each unfinished section is replaced by an empty result AND recorded, because the two
+ // have to be told apart downstream: "searched and found nothing" and "never came back"
+ // produce an identical section, and only one of them means the answer is incomplete.
+ budgetExceeded = true;
+ if (DropIfUnfinished>(ref recentTask, [])) droppedRecent = true;
+ if (DropIfUnfinished(ref relevantTask, RelevantMessageSearchResult.Empty)) droppedRelevant = true;
+ if (entitiesScoredTask is not null)
+ droppedEntities = DropIfUnfinished>(ref entitiesScoredTask, []);
+ else droppedEntities = DropIfUnfinished>(ref entitiesTask, []);
+ if (preferencesScoredTask is not null)
+ droppedPreferences = DropIfUnfinished>(ref preferencesScoredTask, []);
+ else droppedPreferences = DropIfUnfinished>(ref preferencesTask, []);
+ if (factsScoredTask is not null)
+ droppedFacts = DropIfUnfinished(ref factsScoredTask, new ScoredFactSearchResult([], []));
+ else droppedFacts = DropIfUnfinished>(ref factsTask, []);
+ if (tracesScoredTask is not null)
+ droppedTraces = DropIfUnfinished>(ref tracesScoredTask, []);
+ else droppedTraces = DropIfUnfinished>(ref tracesTask, []);
+
+ _logger.LogWarning(
+ "Recall latency budget of {Budget}ms expired; returning partial context.",
+ latencyBudget.TotalMilliseconds);
+ }
recentMessages = await recentTask.ConfigureAwait(false);
var relevantResult = await relevantTask.ConfigureAwait(false);
@@ -523,7 +561,7 @@ await Task.WhenAll(
// No vector involved: session-scoped and time-ordered, so the limit alone decides.
Diagnostics = recallOpts.IncludeDiagnostics
? Diagnose(recallOpts.MaxRecentMessages > 0, recallOpts.MaxRecentMessages,
- recentMessages, Array.Empty(), minScore)
+ recentMessages, Array.Empty(), minScore, droppedRecent)
: null
},
RelevantMessages = new MemoryContextSection
@@ -532,7 +570,7 @@ await Task.WhenAll(
RankedItems = relevantRanked,
Diagnostics = recallOpts.IncludeDiagnostics
? Diagnose(vectorSearchRan && recallOpts.MaxRelevantMessages > 0,
- recallOpts.MaxRelevantMessages, relevantMessages, relevantRanked, minScore)
+ recallOpts.MaxRelevantMessages, relevantMessages, relevantRanked, minScore, droppedRelevant)
: null
},
RelevantEntities = new MemoryContextSection
@@ -541,7 +579,7 @@ await Task.WhenAll(
RankedItems = entityRanked,
Diagnostics = recallOpts.IncludeDiagnostics
? Diagnose(vectorSearchRan && recallOpts.MaxEntities > 0,
- recallOpts.MaxEntities, entities, entityRanked, minScore)
+ recallOpts.MaxEntities, entities, entityRanked, minScore, droppedEntities)
: null
},
RelevantPreferences = new MemoryContextSection
@@ -550,7 +588,7 @@ await Task.WhenAll(
RankedItems = preferenceRanked,
Diagnostics = recallOpts.IncludeDiagnostics
? Diagnose(vectorSearchRan && recallOpts.MaxPreferences > 0,
- recallOpts.MaxPreferences, preferences, preferenceRanked, minScore)
+ recallOpts.MaxPreferences, preferences, preferenceRanked, minScore, droppedPreferences)
: null
},
RelevantFacts = new MemoryContextSection
@@ -559,7 +597,7 @@ await Task.WhenAll(
RankedItems = factRanked,
Diagnostics = recallOpts.IncludeDiagnostics
? Diagnose(vectorSearchRan && recallOpts.MaxFacts > 0,
- recallOpts.MaxFacts, facts, factRanked, minScore)
+ recallOpts.MaxFacts, facts, factRanked, minScore, droppedFacts)
: null
},
SimilarTraces = new MemoryContextSection
@@ -568,14 +606,15 @@ await Task.WhenAll(
RankedItems = traceRanked,
Diagnostics = recallOpts.IncludeDiagnostics
? Diagnose(vectorSearchRan && recallOpts.MaxTraces > 0,
- recallOpts.MaxTraces, traces, traceRanked, minScore)
+ recallOpts.MaxTraces, traces, traceRanked, minScore, droppedTraces)
: null
},
GraphRagContext = graphRagContext,
GraphRagItems = graphRagItems,
ResolvedQueryRelations = resolvedQueryRelations,
BlendMode = blendMode,
- Truncated = truncated
+ Truncated = truncated,
+ LatencyBudgetExceeded = budgetExceeded
};
_logger.LogDebug(
@@ -1040,4 +1079,54 @@ private ITruncationStrategy ResolveStrategy(TruncationStrategy strategy) =>
_truncationStrategies.TryGetValue(strategy, out var resolved)
? resolved
: _truncationStrategies[TruncationStrategy.OldestFirst];
+
+ ///
+ /// Waits for the section tasks, giving up after (rank 13).
+ ///
+ /// when the budget expired with work still running.
+ ///
+ ///
+ /// The still-running queries are not cancelled. They are already in the driver, and tearing
+ /// them down buys nothing the caller is waiting for — it only turns a wasted result into a wasted
+ /// result plus a cancellation storm. Their faults are observed so a slow section that also fails
+ /// does not surface later as an unobserved task exception.
+ ///
+ ///
+ private static async Task WaitWithinBudgetAsync(
+ Task[] sections, TimeSpan budget, CancellationToken cancellationToken)
+ {
+ var all = Task.WhenAll(sections);
+ using var expiry = CancellationTokenSource.CreateLinkedTokenSource(cancellationToken);
+ var timer = Task.Delay(budget, expiry.Token);
+
+ var finished = await Task.WhenAny(all, timer).ConfigureAwait(false);
+ if (finished == all)
+ {
+ await expiry.CancelAsync().ConfigureAwait(false);
+ await all.ConfigureAwait(false); // rethrow section faults exactly as before
+ return false;
+ }
+
+ foreach (var section in sections)
+ {
+ _ = section.ContinueWith(
+ faulted => _ = faulted.Exception,
+ CancellationToken.None,
+ TaskContinuationOptions.OnlyOnFaulted,
+ TaskScheduler.Default);
+ }
+
+ return true;
+ }
+
+ ///
+ /// Replaces a section that did not finish in time with an empty result (rank 13).
+ ///
+ /// when a substitution happened, i.e. this section was dropped.
+ private static bool DropIfUnfinished(ref Task section, T empty)
+ {
+ if (section.IsCompletedSuccessfully) return false;
+ section = Task.FromResult(empty);
+ return true;
+ }
}
diff --git a/src/AgentMemory.Core/Services/MemoryExtractionPipeline.cs b/src/AgentMemory.Core/Services/MemoryExtractionPipeline.cs
index 6fab1abe2..2ea9b28c0 100644
--- a/src/AgentMemory.Core/Services/MemoryExtractionPipeline.cs
+++ b/src/AgentMemory.Core/Services/MemoryExtractionPipeline.cs
@@ -58,8 +58,17 @@ public async Task ExtractAsync(
var scope = _isolationPolicy.ResolveReadScope(
explicitScope: null, request.UserId, nameof(ExtractAsync), MemoryOperationAccess.Tenant);
- var staged = await _extractionStage.ExtractAsync(
- request.Messages, request.TypesToExtract, scope, cancellationToken).ConfigureAwait(false);
+ // E2. Context reaches the extractors as context; the window keeps it out of provenance and
+ // out of the extraction targets, which is what stops it inflating S2 confidence and R7
+ // mention counts on facts that merely stayed inside the window.
+ // Without context, the original call — the off state stays identical at the call itself, not
+ // merely in what the extractors end up seeing.
+ var staged = request.ContextMessages.Count == 0
+ ? await _extractionStage.ExtractAsync(
+ request.Messages, request.TypesToExtract, scope, cancellationToken).ConfigureAwait(false)
+ : await _extractionStage.ExtractWithContextAsync(
+ new ExtractionWindow { Targets = request.Messages, Context = request.ContextMessages },
+ request.TypesToExtract, scope, cancellationToken).ConfigureAwait(false);
var ownerId = _isolationPolicy.ResolveWriteOwner(request.UserId, nameof(ExtractAsync), MemoryOperationAccess.Tenant);
// #92 Phase 3: a per-request TrustLevel override wins; otherwise fall back to the configured default.
diff --git a/src/AgentMemory.Core/Services/MemoryService.cs b/src/AgentMemory.Core/Services/MemoryService.cs
index 5e6ce04b1..8c0184c4d 100644
--- a/src/AgentMemory.Core/Services/MemoryService.cs
+++ b/src/AgentMemory.Core/Services/MemoryService.cs
@@ -5,6 +5,7 @@
using AgentMemory.Abstractions.Options;
using AgentMemory.Abstractions.Repositories;
using AgentMemory.Abstractions.Services;
+using AgentMemory.Core.Memory;
namespace AgentMemory.Core.Services;
@@ -86,13 +87,55 @@ public async Task RecallAsync(
// outside; both can be present without colliding.
using var activity = AgentMemoryDiagnostics.Source.StartActivity("memory.recall.total");
+ // R4. A turn that names a past time is asking a bitemporal question, and until now no
+ // conversational turn could reach RecallAsOfAsync at all. Resolution is deterministic and
+ // biased hard toward returning null -- see TemporalQueryParser -- so the ordinary turn takes
+ // exactly the path it always did.
+ if (_options.ResolveTemporalQueries
+ && TemporalQueryParser.Resolve(request.Query, _clock.UtcNow) is { } asOf)
+ {
+ activity?.SetTag("memory.recall.resolved_as_of", asOf.ToString("O"));
+ _logger.LogDebug(
+ "Query names a past time ({AsOf}); recalling bitemporally instead of against now.", asOf);
+ // Both clocks: the question is "what did I think then", which is what was true then AS
+ // known then. Passing only the valid clock would answer with today's corrections applied
+ // to the past -- a different question, and a subtly misleading one.
+ return await RecallAsOfCoreAsync(request, asOf, asOf, cancellationToken).ConfigureAwait(false);
+ }
+
var context = await _assembler.AssembleContextAsync(request, cancellationToken).ConfigureAwait(false);
- // Update access timestamps for recalled long-term memories (awaited so failures and
- // cancellation are observed; the method itself is resilient and logs internally).
+ // Update access timestamps for recalled long-term memories. Awaited by default so failures and
+ // cancellation are observed; the method itself is resilient and logs internally.
if (_decayService is not null)
{
- await UpdateAccessTimestampsAsync(context, cancellationToken).ConfigureAwait(false);
+ if (_options.DeferAccessTracking)
+ {
+ // 2.4. Bookkeeping the caller is not waiting for: it feeds decay and retention, and
+ // nothing in the returned context depends on it.
+ //
+ // CancellationToken.None, NOT the request's token. That token is cancelled as soon as
+ // the response completes, so passing it through would cancel the very write being
+ // deferred -- an option that reads as enabled and does nothing.
+ //
+ // The task is deliberately not awaited and deliberately not discarded silently: the
+ // continuation is what keeps a deferred failure from being an unobserved exception.
+ _ = UpdateAccessTimestampsAsync(context, CancellationToken.None)
+ .ContinueWith(
+ task => _logger.LogWarning(
+ task.Exception,
+ "Deferred access tracking failed after recall returned. If this is an "
+ + "ObjectDisposedException, the host's DI scope was disposed before the "
+ + "write completed -- MemoryOptions.DeferAccessTracking is unsafe for a "
+ + "request-scoped host."),
+ CancellationToken.None,
+ TaskContinuationOptions.OnlyOnFaulted,
+ TaskScheduler.Default);
+ }
+ else
+ {
+ await UpdateAccessTimestampsAsync(context, cancellationToken).ConfigureAwait(false);
+ }
}
int totalItems = context.RecentMessages.Items.Count
@@ -255,13 +298,66 @@ public Task> AddMessagesAsync(
}
///
- public Task ExtractAndPersistAsync(
+ public async Task ExtractAndPersistAsync(
ExtractionRequest request,
CancellationToken cancellationToken = default)
{
ArgumentNullException.ThrowIfNull(request);
_logger.LogDebug("Extracting and persisting memory for session {SessionId}", request.SessionId);
- return _extraction.ExtractAsync(request, cancellationToken);
+ request = await WithExtractionContextAsync(request, cancellationToken).ConfigureAwait(false);
+ return await _extraction.ExtractAsync(request, cancellationToken).ConfigureAwait(false);
+ }
+
+ ///
+ /// Attaches the preceding turns an extractor may read to resolve references (E2).
+ ///
+ ///
+ ///
+ /// Filled in here rather than at each call site because this is the one chokepoint every
+ /// incremental extraction passes through — the Agent Framework provider, the Microsoft memory
+ /// facade and the MCP ingest tool all arrive at this method. Resolving it per caller would make
+ /// the window depend on which host was used, which is the failure this codebase has hit
+ /// repeatedly: a setting only some components respect is worse than no setting.
+ ///
+ ///
+ /// An explicitly supplied context always wins — a caller that knows the conversation better than
+ /// a recency query does should not be second-guessed.
+ ///
+ ///
+ private async Task WithExtractionContextAsync(
+ ExtractionRequest request,
+ CancellationToken cancellationToken)
+ {
+ if (_options.Extraction.ExtractionContextTurns <= 0
+ || request.ContextMessages.Count > 0
+ || request.Messages.Count == 0)
+ {
+ return request;
+ }
+
+ var targetIds = request.Messages.Select(m => m.MessageId).ToHashSet(StringComparer.Ordinal);
+
+ // Over-fetch by the batch size: the most recent stored messages usually ARE the batch, so
+ // asking for exactly N would return N turns of which most are excluded and leave the window
+ // short without reporting it.
+ var wanted = _options.Extraction.ExtractionContextTurns;
+ var recent = await _shortTerm.GetRecentMessagesAsync(
+ request.SessionId, wanted + request.Messages.Count, cancellationToken).ConfigureAwait(false);
+
+ // The batch itself is never context. Its turns are the targets, and a message appearing in
+ // both would be handed to the model twice -- once as "do not extract from this".
+ var context = recent
+ .Where(m => !targetIds.Contains(m.MessageId))
+ .TakeLast(wanted)
+ .ToList();
+
+ if (context.Count == 0) return request;
+
+ _logger.LogDebug(
+ "Extraction window: {Targets} target turn(s) with {Context} turn(s) of read-only context (E2).",
+ request.Messages.Count, context.Count);
+
+ return request with { ContextMessages = context };
}
///
diff --git a/src/AgentMemory.Core/Services/ReasoningMemoryService.cs b/src/AgentMemory.Core/Services/ReasoningMemoryService.cs
index c5ac8229b..70f2a3209 100644
--- a/src/AgentMemory.Core/Services/ReasoningMemoryService.cs
+++ b/src/AgentMemory.Core/Services/ReasoningMemoryService.cs
@@ -84,7 +84,13 @@ public async Task StartTraceAsync(
// #92 Phase 3: trust_level is a framework-reserved metadata key -- a caller of this public
// service method must never be able to self-assign a trust level that bypasses the admission
// policy's instruction-like-content detection for this trace's Task text on recall.
- Metadata = (metadata ?? new Dictionary()).WithoutCallerSuppliedTrustLevel()
+ // Stripped first, then stamped from CONFIGURATION -- never from the caller. The strip is
+ // the security property (#92 Phase 3); the stamp closes 6.3, where every trace read back
+ // as Untrusted because nothing ever assigned one, making "the agent generated this" and
+ // "no signal was recorded" the same value.
+ Metadata = (metadata ?? new Dictionary())
+ .WithoutCallerSuppliedTrustLevel()
+ .WithTrustLevel(_options.DefaultTraceTrustLevel)
};
_logger.LogDebug("Starting trace {TraceId} for session {SessionId}", trace.TraceId, sessionId);
diff --git a/src/AgentMemory.Extraction.Llm/ExtractionPromptSemantics.cs b/src/AgentMemory.Extraction.Llm/ExtractionPromptSemantics.cs
index 977f498c9..39c503305 100644
--- a/src/AgentMemory.Extraction.Llm/ExtractionPromptSemantics.cs
+++ b/src/AgentMemory.Extraction.Llm/ExtractionPromptSemantics.cs
@@ -134,4 +134,25 @@ internal static class ExtractionPromptSemantics
_ => string.Empty,
};
+
+ ///
+ /// Tells the model that the fenced earlier turns are background and not extraction targets (E2).
+ ///
+ ///
+ ///
+ /// Appended only when a window actually carries context, so a prompt without context is
+ /// byte-for-byte what it was before E2 existed. Prompt bytes are fingerprinted into every
+ /// measured run in this track; an instruction that appeared unconditionally would invalidate every
+ /// sealed base to say something about turns that were not supplied.
+ ///
+ ///
+ /// Authored here rather than per extractor for the usual reason: an instruction only some
+ /// extractors carry makes what a memory is depend on which performance flag is set.
+ ///
+ ///
+ internal const string ExtractionContextInstruction =
+ "\nThe transcript begins with earlier turns marked as EARLIER CONVERSATION. Read them only to " +
+ "resolve references — who \"she\" is, where \"there\" is, what \"it\" refers to. Do NOT extract " +
+ "any memory whose statement lives in those turns; extract only from the turns after the end " +
+ "marker, even if an earlier turn states something you would otherwise record.";
}
diff --git a/src/AgentMemory.Extraction.Llm/LlmEntityExtractor.cs b/src/AgentMemory.Extraction.Llm/LlmEntityExtractor.cs
index dbed253ca..9c62e397a 100644
--- a/src/AgentMemory.Extraction.Llm/LlmEntityExtractor.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmEntityExtractor.cs
@@ -48,12 +48,18 @@ public LlmEntityExtractor(
_runner = new LlmExtractionRunner(chatClient, _options, logger);
}
- protected override async Task> ExtractCoreAsync(
+ protected override Task> ExtractCoreAsync(
IReadOnlyList messages, CancellationToken cancellationToken)
+ => ExtractCoreWithContextAsync(ExtractionWindow.ForTargets(messages), cancellationToken);
+
+ protected override async Task> ExtractCoreWithContextAsync(
+ ExtractionWindow window, CancellationToken cancellationToken)
{
- var conversationText = ConversationTextBuilder.Build(messages);
+ var conversationText = ConversationTextBuilder.BuildWindow(window, numbered: false);
return await _runner.RunAsync(
- _options.EntityExtractionPrompt ?? BuildSystemPrompt(_options.EntityTypes),
+ (_options.EntityExtractionPrompt ?? BuildSystemPrompt(_options.EntityTypes))
+ // Only when context is present, so a context-free prompt stays byte-identical (E2).
+ + (window.HasContext ? ExtractionPromptSemantics.ExtractionContextInstruction : string.Empty),
"Extract entities from this conversation:",
conversationText,
ProjectEntities,
diff --git a/src/AgentMemory.Extraction.Llm/LlmExtractionBatchDiagnostics.cs b/src/AgentMemory.Extraction.Llm/LlmExtractionBatchDiagnostics.cs
index 5ce9235ee..f3d5278f7 100644
--- a/src/AgentMemory.Extraction.Llm/LlmExtractionBatchDiagnostics.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmExtractionBatchDiagnostics.cs
@@ -8,6 +8,9 @@ internal sealed class LlmExtractionBatchDiagnostics
private readonly ConcurrentQueue _details = new();
private long _splits;
private long _droppedDetails;
+ private long _contentRejections;
+ private long _sessionsRefused;
+ private readonly ConcurrentQueue _refusedSessionIds = new();
internal void RecordSplit(Exception exception, int sourceSessions)
{
@@ -22,11 +25,42 @@ internal void RecordSplit(Exception exception, int sourceSessions)
Interlocked.Increment(ref _droppedDetails);
}
+ ///
+ /// Records a batch the provider refused on content grounds, and the sessions lost with it.
+ ///
+ ///
+ /// Counted separately from splits because it is a different event with a different remedy: a
+ /// split is a recoverable shape problem, a refusal is terminal for that text. The session count
+ /// is what a reader needs — "2 refusals" says nothing about whether the corpus is usable, "2
+ /// refusals costing 6 sessions of 2,418" does.
+ ///
+ internal void RecordContentRejection(
+ Exception exception, int sourceSessions, string? sessionId = null)
+ {
+ ArgumentNullException.ThrowIfNull(exception);
+ ArgumentOutOfRangeException.ThrowIfNegativeOrZero(sourceSessions);
+ Interlocked.Increment(ref _contentRejections);
+ Interlocked.Add(ref _sessionsRefused, sourceSessions);
+ // The identifier, never the text. A refusal that leaves no trace of what caused it cannot be
+ // investigated or reported to the provider -- and this recurs -- but the diagnostics are
+ // deliberately free of dataset content, so the id is the handle and the dataset is the lookup.
+ if (!string.IsNullOrEmpty(sessionId)) _refusedSessionIds.Enqueue(sessionId);
+ _details.Enqueue(new LlmExtractionBatchSplitDetail(
+ "content-rejected",
+ sourceSessions,
+ exception.GetType().FullName ?? exception.GetType().Name));
+ while (_details.Count > MaximumDetails && _details.TryDequeue(out _))
+ Interlocked.Increment(ref _droppedDetails);
+ }
+
internal LlmExtractionBatchDiagnosticsSnapshot Snapshot() =>
new(
Interlocked.Read(ref _splits),
_details.ToArray(),
- Interlocked.Read(ref _droppedDetails));
+ Interlocked.Read(ref _droppedDetails),
+ Interlocked.Read(ref _contentRejections),
+ Interlocked.Read(ref _sessionsRefused),
+ _refusedSessionIds.ToArray());
private static string Classify(Exception exception) =>
exception.Message switch
@@ -46,14 +80,20 @@ private static string Classify(Exception exception) =>
internal sealed record LlmExtractionBatchDiagnosticsSnapshot(
long Splits,
IReadOnlyList Details,
- long DroppedDetails)
+ long DroppedDetails,
+ long ContentRejections = 0,
+ long SessionsRefused = 0,
+ IReadOnlyList? RefusedSessionIds = null)
{
internal LlmExtractionBatchDiagnosticsSnapshot Delta(
LlmExtractionBatchDiagnosticsSnapshot baseline) =>
new(
Splits - baseline.Splits,
Details.Skip(Math.Min(Details.Count, baseline.Details.Count)).ToArray(),
- DroppedDetails - baseline.DroppedDetails);
+ DroppedDetails - baseline.DroppedDetails,
+ ContentRejections - baseline.ContentRejections,
+ SessionsRefused - baseline.SessionsRefused,
+ (RefusedSessionIds ?? []).Skip((baseline.RefusedSessionIds ?? []).Count).ToArray());
}
internal sealed record LlmExtractionBatchSplitDetail(
diff --git a/src/AgentMemory.Extraction.Llm/LlmFactExtractor.cs b/src/AgentMemory.Extraction.Llm/LlmFactExtractor.cs
index 7376919d7..46102e9bd 100644
--- a/src/AgentMemory.Extraction.Llm/LlmFactExtractor.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmFactExtractor.cs
@@ -46,16 +46,21 @@ public LlmFactExtractor(
_runner = new LlmExtractionRunner(chatClient, _options, logger);
}
- protected override async Task> ExtractCoreAsync(
+ protected override Task> ExtractCoreAsync(
IReadOnlyList messages, CancellationToken cancellationToken)
+ => ExtractCoreWithContextAsync(ExtractionWindow.ForTargets(messages), cancellationToken);
+
+ protected override async Task> ExtractCoreWithContextAsync(
+ ExtractionWindow window, CancellationToken cancellationToken)
{
- var conversationText = _options.Provenance == ExtractionProvenanceMode.PerItem
- ? ConversationTextBuilder.BuildNumbered(messages)
- : ConversationTextBuilder.Build(messages);
+ var conversationText = ConversationTextBuilder.BuildWindow(
+ window, numbered: _options.Provenance == ExtractionProvenanceMode.PerItem);
return await _runner.RunAsync(
- _options.FactExtractionPrompt
+ (_options.FactExtractionPrompt
?? BuildSystemPrompt(
- _options.AssistantContent, _options.TemporalValidity, _options.Provenance),
+ _options.AssistantContent, _options.TemporalValidity, _options.Provenance))
+ // Only when context is present: a context-free prompt must stay byte-identical (E2).
+ + (window.HasContext ? ExtractionPromptSemantics.ExtractionContextInstruction : string.Empty),
"Extract facts from this conversation:",
conversationText,
ProjectFacts,
diff --git a/src/AgentMemory.Extraction.Llm/LlmMultiSessionUnifiedMemoryExtractor.cs b/src/AgentMemory.Extraction.Llm/LlmMultiSessionUnifiedMemoryExtractor.cs
index c20368894..778f06e94 100644
--- a/src/AgentMemory.Extraction.Llm/LlmMultiSessionUnifiedMemoryExtractor.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmMultiSessionUnifiedMemoryExtractor.cs
@@ -247,6 +247,50 @@ private async Task> Extract
// count. Removing it does not remove a working recovery; it removes a misleading one. A real
// transport retry is tracked separately, because it must be reconciled with the harness's
// exact-call-count invariant rather than quietly breaking it.
+ // A refusal on a MULTI-session batch is split first, exactly like a shape failure -- not to
+ // retry (the policy is deterministic for the same text) but to ISOLATE. Measured: the batch
+ // that killed a 616-call preparation went 4 -> 2 -> 1 and still failed at 1, so one session's
+ // content was responsible and its three batch-mates were innocent. Skipping the whole batch
+ // would have discarded all four.
+ catch (Exception ex) when (batch.Count > 1 && IsContentRejection(ex))
+ {
+ _batchDiagnostics?.RecordSplit(ex, batch.Count);
+ _logger.LogWarning(
+ ex,
+ "Provider refused a batch of {Count} source sessions; splitting to isolate which "
+ + "one(s) it objects to, so the rest are not lost with it.",
+ batch.Count);
+ var midpoint = batch.Count / 2;
+ var isolatedLeft = await ExtractOrSplitAsync(
+ batch.Take(midpoint).ToArray(), maxInputTokens, cancellationToken).ConfigureAwait(false);
+ var isolatedRight = await ExtractOrSplitAsync(
+ batch.Skip(midpoint).ToArray(), maxInputTokens, cancellationToken).ConfigureAwait(false);
+ return isolatedLeft.Concat(isolatedRight)
+ .ToDictionary(pair => pair.Key, pair => pair.Value, StringComparer.Ordinal);
+ }
+
+ // Isolated to one session, and the provider still refuses it: terminal. No retry and no
+ // further split changes the text or the policy. Skipping costs this session's extraction;
+ // propagating costs the ENTIRE preparation -- ~616 calls and over an hour for 50 questions.
+ //
+ // The SESSION ID is recorded, not the content. A refusal that leaves no trace of what caused
+ // it cannot be investigated or reported to the provider, and this will recur: the id is the
+ // handle an operator needs to look the conversation up in the dataset themselves, without the
+ // diagnostics carrying dataset text they are deliberately free of.
+ catch (Exception ex) when (IsContentRejection(ex))
+ {
+ var refused = batch[0].SessionId;
+ _batchDiagnostics?.RecordContentRejection(ex, batch.Count, refused);
+ _logger.LogWarning(
+ ex,
+ "Provider refused source session '{SessionId}' on content grounds; its extraction is "
+ + "skipped and recorded. Whatever that conversation held is absent from this corpus.",
+ refused);
+ return batch.ToDictionary(
+ request => request.SessionId,
+ _ => new UnifiedExtractionResult(),
+ StringComparer.Ordinal);
+ }
catch (Exception ex) when (batch.Count > 1 && IsBatchShapeFailure(ex))
{
_batchDiagnostics?.RecordSplit(ex, batch.Count);
@@ -508,9 +552,43 @@ internal static bool IsBatchShapeFailure(Exception exception)
if (exception is FormatException)
return true;
+ // A content-filter rejection is a 4xx, but it is NOT a shape failure: the request is
+ // well-formed and the provider is refusing the content. Splitting re-sends the same text to
+ // the same filter, so it can only fail again, one session at a time, until the batch reaches
+ // size 1 and the exception escapes.
+ if (IsContentRejection(exception)) return false;
+
var status = Internal.LlmExtractionRunner.TryGetStatus(exception);
return status is >= 400 and < 500 and not 408 and not 429;
}
+ ///
+ /// Whether the provider refused this content outright, rather than failing to process it.
+ ///
+ ///
+ ///
+ /// Terminal by nature. A retry sends the same text to the same policy, and a split sends smaller
+ /// pieces of the same text; neither can succeed. Measured cost of treating it as retryable: a
+ /// 50-question preparation died after 270 of 616 calls because two sessions of a public
+ /// research dataset tripped an Azure content policy.
+ ///
+ ///
+ /// Matched on the provider's own vocabulary rather than on status alone, because 400 covers both
+ /// "your request is malformed" (which splitting legitimately diagnoses) and "I will not process
+ /// this" (which it cannot).
+ ///
+ ///
+ internal static bool IsContentRejection(Exception exception)
+ {
+ var status = Internal.LlmExtractionRunner.TryGetStatus(exception);
+ if (status != 400) return false;
+
+ var message = exception.Message;
+ return message.Contains("content_filter", StringComparison.OrdinalIgnoreCase)
+ || message.Contains("content filter", StringComparison.OrdinalIgnoreCase)
+ || message.Contains("cyber_policy", StringComparison.OrdinalIgnoreCase)
+ || message.Contains("ResponsibleAIPolicyViolation", StringComparison.OrdinalIgnoreCase);
+ }
+
private sealed class BatchValidationException(string message) : FormatException(message);
}
diff --git a/src/AgentMemory.Extraction.Llm/LlmPreferenceExtractor.cs b/src/AgentMemory.Extraction.Llm/LlmPreferenceExtractor.cs
index bdabaa4fc..7d5a4ba7f 100644
--- a/src/AgentMemory.Extraction.Llm/LlmPreferenceExtractor.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmPreferenceExtractor.cs
@@ -45,14 +45,21 @@ public LlmPreferenceExtractor(
_runner = new LlmExtractionRunner(chatClient, _options, logger);
}
- protected override async Task> ExtractCoreAsync(
+ protected override Task> ExtractCoreAsync(
IReadOnlyList messages, CancellationToken cancellationToken)
+ => ExtractCoreWithContextAsync(ExtractionWindow.ForTargets(messages), cancellationToken);
+
+ protected override async Task> ExtractCoreWithContextAsync(
+ ExtractionWindow window, CancellationToken cancellationToken)
{
+ var messages = window.Targets;
var conversationText = _options.Provenance == ExtractionProvenanceMode.PerItem
- ? ConversationTextBuilder.BuildNumbered(messages)
- : ConversationTextBuilder.Build(messages);
+ ? ConversationTextBuilder.BuildWindow(window, numbered: true)
+ : ConversationTextBuilder.BuildWindow(window, numbered: false);
return await _runner.RunAsync(
- _options.PreferenceExtractionPrompt ?? DefaultSystemPrompt,
+ (_options.PreferenceExtractionPrompt ?? DefaultSystemPrompt)
+ // Only when context is present, so a context-free prompt stays byte-identical (E2).
+ + (window.HasContext ? ExtractionPromptSemantics.ExtractionContextInstruction : string.Empty),
"Extract preferences from this conversation:",
conversationText,
ProjectPreferences,
diff --git a/src/AgentMemory.Extraction.Llm/LlmRelationshipExtractor.cs b/src/AgentMemory.Extraction.Llm/LlmRelationshipExtractor.cs
index 7ea3e4777..152c52780 100644
--- a/src/AgentMemory.Extraction.Llm/LlmRelationshipExtractor.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmRelationshipExtractor.cs
@@ -44,12 +44,18 @@ public LlmRelationshipExtractor(
_runner = new LlmExtractionRunner(chatClient, _options, logger);
}
- protected override async Task> ExtractCoreAsync(
+ protected override Task> ExtractCoreAsync(
IReadOnlyList messages, CancellationToken cancellationToken)
+ => ExtractCoreWithContextAsync(ExtractionWindow.ForTargets(messages), cancellationToken);
+
+ protected override async Task> ExtractCoreWithContextAsync(
+ ExtractionWindow window, CancellationToken cancellationToken)
{
- var conversationText = ConversationTextBuilder.Build(messages);
+ var conversationText = ConversationTextBuilder.BuildWindow(window, numbered: false);
return await _runner.RunAsync(
- _options.RelationshipExtractionPrompt ?? DefaultSystemPrompt,
+ (_options.RelationshipExtractionPrompt ?? DefaultSystemPrompt)
+ // Only when context is present, so a context-free prompt stays byte-identical (E2).
+ + (window.HasContext ? ExtractionPromptSemantics.ExtractionContextInstruction : string.Empty),
"Extract relationships from this conversation:",
conversationText,
ProjectRelationships,
diff --git a/src/AgentMemory.Extraction.Llm/LlmUnifiedMemoryExtractor.cs b/src/AgentMemory.Extraction.Llm/LlmUnifiedMemoryExtractor.cs
index e101d4fa2..2241ca56d 100644
--- a/src/AgentMemory.Extraction.Llm/LlmUnifiedMemoryExtractor.cs
+++ b/src/AgentMemory.Extraction.Llm/LlmUnifiedMemoryExtractor.cs
@@ -44,22 +44,31 @@ public LlmUnifiedMemoryExtractor(
public bool IsEnabled => _options.UseUnifiedExtraction;
- public async Task ExtractAsync(
+ public Task ExtractAsync(
IReadOnlyList messages,
CancellationToken cancellationToken = default)
+ => ExtractWithContextAsync(ExtractionWindow.ForTargets(messages), cancellationToken);
+
+ public async Task ExtractWithContextAsync(
+ ExtractionWindow window,
+ CancellationToken cancellationToken = default)
{
- if (messages.Count == 0)
+ // Judged on the targets: a window carrying only background has nothing to extract from, and
+ // calling out would spend a completion on turns the prompt forbids extracting from.
+ if (window.Targets.Count == 0)
return new UnifiedExtractionResult();
using var activity = AgentMemoryDiagnostics.Source.StartActivity("memory.extract.unified");
var results = await _runner.RunAsync(
BuildSystemPrompt(
_options.AssistantContent, _options.EntityTypes, _options.TemporalValidity,
- _options.Provenance),
+ _options.Provenance)
+ // Appended only when context is actually present, so a context-free prompt stays
+ // byte-for-byte what every sealed measurement was taken under (E2).
+ + (window.HasContext ? ExtractionPromptSemantics.ExtractionContextInstruction : string.Empty),
"Extract all supported memory from this conversation:",
- _options.Provenance == ExtractionProvenanceMode.PerItem
- ? ConversationTextBuilder.BuildNumbered(messages)
- : ConversationTextBuilder.Build(messages),
+ ConversationTextBuilder.BuildWindow(
+ window, numbered: _options.Provenance == ExtractionProvenanceMode.PerItem),
response => new[] { Project(response) },
cancellationToken,
failOnParseExhaustion: true).ConfigureAwait(false);
diff --git a/src/AgentMemory.Neo4j/Infrastructure/ServiceCollectionExtensions.cs b/src/AgentMemory.Neo4j/Infrastructure/ServiceCollectionExtensions.cs
index 5408555fe..c99638d03 100644
--- a/src/AgentMemory.Neo4j/Infrastructure/ServiceCollectionExtensions.cs
+++ b/src/AgentMemory.Neo4j/Infrastructure/ServiceCollectionExtensions.cs
@@ -72,6 +72,10 @@ public static IServiceCollection AddNeo4jAgentMemory(
services.TryAddTransient();
services.TryAddTransient();
services.TryAddTransient();
+ // S1. Registered beside the other repositories rather than behind a feature flag: an
+ // unregistered store would make EntitySummaryService unresolvable, so the option that
+ // enables summaries would fail at host start rather than simply doing nothing.
+ services.TryAddTransient();
services.TryAddTransient();
// Provenance
diff --git a/src/AgentMemory.Neo4j/Queries/EntitySummaryQueries.cs b/src/AgentMemory.Neo4j/Queries/EntitySummaryQueries.cs
new file mode 100644
index 000000000..6636f18e0
--- /dev/null
+++ b/src/AgentMemory.Neo4j/Queries/EntitySummaryQueries.cs
@@ -0,0 +1,76 @@
+namespace AgentMemory.Neo4j.Queries;
+
+///
+/// Cypher for synthesized entity summaries (S1).
+///
+///
+///
+/// One summary per entity, held on a :EntitySummary node joined to its entity by
+/// :SUMMARISES. A separate node rather than a property on :Entity because it carries
+/// its own provenance edges and its own fingerprint, and because a derived value living beside
+/// extracted ones invites exactly the confusion this design is trying to avoid.
+///
+///
+/// No history. A superseded summary is not a record of what was once believed — the facts it
+/// was built from carry their own bitemporal history already, and keeping stale derivations around
+/// would mean two answers to "what did we think about Alice in March", only one of them authoritative.
+///
+///
+internal static class EntitySummaryQueries
+{
+ ///
+ /// Writes the entity's summary, replacing whatever was there.
+ ///
+ ///
+ /// MERGE on entity_id + owner_key, so two tenants summarising the same shared entity
+ /// keep separate summaries — each was synthesised from the facts that tenant can see, and sharing
+ /// one node would leak one owner's knowledge into another's context.
+ ///
+ public const string Upsert = """
+ MERGE (s:EntitySummary {entity_id: $entityId, owner_key: $ownerKey})
+ SET s.id = $summaryId,
+ s.content = $content,
+ s.source_fact_ids = $sourceFactIds,
+ s.source_fingerprint = $sourceFingerprint,
+ s.owner_id = $ownerId,
+ s.generated_at = datetime($generatedAt)
+ WITH s
+ OPTIONAL MATCH (e:Entity {id: $entityId})
+ FOREACH (_ IN CASE WHEN e IS NULL THEN [] ELSE [1] END |
+ MERGE (s)-[:SUMMARISES]->(e))
+ WITH s
+ // Provenance to the facts the text was written from. Rebuilt wholesale rather than merged,
+ // because a summary regenerated from a smaller fact set must not keep edges to sources it no
+ // longer draws on -- that would claim provenance the content cannot support.
+ OPTIONAL MATCH (s)-[old:EXTRACTED_FROM]->(:Fact)
+ DELETE old
+ WITH s
+ UNWIND $sourceFactIds AS factId
+ MATCH (f:Fact {id: factId})
+ MERGE (s)-[:EXTRACTED_FROM]->(f)
+ RETURN s
+ """;
+
+ /// Reads an entity's summary, owner-confined (R1).
+ public static string GetByEntity(bool hasOwnerFilter, bool includeShared)
+ {
+ var owner = !hasOwnerFilter ? string.Empty
+ : includeShared ? " AND (s.owner_id = $ownerId OR s.owner_id IS NULL)"
+ : " AND s.owner_id = $ownerId";
+ return $"MATCH (s:EntitySummary) WHERE s.entity_id = $entityId{owner} RETURN s";
+ }
+
+ /// Removes an entity's summary and its edges.
+ public static string DeleteByEntity(bool hasOwnerFilter, bool includeShared)
+ {
+ var owner = !hasOwnerFilter ? string.Empty
+ : includeShared ? " AND (s.owner_id = $ownerId OR s.owner_id IS NULL)"
+ : " AND s.owner_id = $ownerId";
+ return $"""
+ MATCH (s:EntitySummary) WHERE s.entity_id = $entityId{owner}
+ WITH s, count(s) AS found
+ DETACH DELETE s
+ RETURN found
+ """;
+ }
+}
diff --git a/src/AgentMemory.Neo4j/Queries/FactQueries.cs b/src/AgentMemory.Neo4j/Queries/FactQueries.cs
index a9f9c7b92..6f635e322 100644
--- a/src/AgentMemory.Neo4j/Queries/FactQueries.cs
+++ b/src/AgentMemory.Neo4j/Queries/FactQueries.cs
@@ -109,16 +109,31 @@ ON CREATE SET
f.valid_until = CASE WHEN $validUntil IS NOT NULL THEN datetime($validUntil) ELSE null END,
f.source_message_ids = $sourceMessageIds,
f.created_at = datetime($createdAtUtc),
- f.metadata = $metadata
+ f.metadata = $metadata,
+ // R7 salience. Counts how often THE WORLD asserted this fact, incremented only here
+ // and in ON MATCH -- i.e. once per ingestion that re-states the same triple.
+ // Deliberately NOT the :MemoryReadAudit trail, which counts how often WE surfaced it:
+ // ranking on our own retrievals is a rich-get-richer loop that reinforces whatever
+ // already ranks highly and calls it learning.
+ f.mention_count = 1
ON MATCH SET
f.category = $category,
- f.confidence = $confidence,
+ // S2 corroboration. A re-asserted triple is the world saying it again, so confidence
+ // EARNS rather than being replaced by whatever the latest extraction happened to
+ // report. Gated by the parameter itself -- at alpha 0 this is the original assignment,
+ // byte for byte, so nothing recorded before S2 moves.
+ f.confidence = CASE WHEN $reinforceAlpha > 0
+ THEN CASE WHEN coalesce(f.confidence, $confidence) + $reinforceAlpha > 1.0
+ THEN 1.0
+ ELSE coalesce(f.confidence, $confidence) + $reinforceAlpha END
+ ELSE $confidence END,
f.valid_from = CASE WHEN $validFrom IS NOT NULL THEN datetime($validFrom) ELSE f.valid_from END,
f.valid_until = CASE WHEN $validUntil IS NOT NULL THEN datetime($validUntil) ELSE f.valid_until END,
f.source_message_ids = $sourceMessageIds,
f.updated_at = datetime($updatedAtUtc),
f.metadata = $metadata,
- f.invalidated_at = null
+ f.invalidated_at = null,
+ f.mention_count = coalesce(f.mention_count, 1) + 1
RETURN f";
// ── UpsertBatchAsync ───────────────────────────────────────────────
@@ -148,18 +163,54 @@ ON CREATE SET
f.valid_until = CASE WHEN item.valid_until IS NOT NULL THEN datetime(item.valid_until) ELSE null END,
f.source_message_ids = item.source_message_ids,
f.created_at = datetime(item.created_at),
- f.metadata = item.metadata
+ f.metadata = item.metadata,
+ f.mention_count = 1
ON MATCH SET
f.category = item.category,
- f.confidence = item.confidence,
+ // S2 corroboration, identical to the single-item path. A counter that depended on
+ // which write path ran would make reinforcement a property of batching rather than of
+ // the conversation.
+ f.confidence = CASE WHEN $reinforceAlpha > 0
+ THEN CASE WHEN coalesce(f.confidence, item.confidence) + $reinforceAlpha > 1.0
+ THEN 1.0
+ ELSE coalesce(f.confidence, item.confidence) + $reinforceAlpha END
+ ELSE item.confidence END,
f.valid_from = CASE WHEN item.valid_from IS NOT NULL THEN datetime(item.valid_from) ELSE f.valid_from END,
f.valid_until = CASE WHEN item.valid_until IS NOT NULL THEN datetime(item.valid_until) ELSE f.valid_until END,
f.source_message_ids = item.source_message_ids,
f.updated_at = datetime(item.updated_at),
f.metadata = item.metadata,
- f.invalidated_at = null
+ f.invalidated_at = null,
+ f.mention_count = coalesce(f.mention_count, 1) + 1
RETURN f";
+ // ── R7 mention frequency ───────────────────────────────────────────
+
+ ///
+ /// How often the world asserted each of these facts, for the whole candidate set at once.
+ ///
+ ///
+ ///
+ /// mention_count is incremented only by the upsert paths, i.e. once per ingestion that
+ /// re-states the same triple. It is a salience signal: a fact the conversation keeps
+ /// returning to matters more than one mentioned in passing.
+ ///
+ ///
+ /// Explicitly not the read audit. :MemoryReadAudit records how often we
+ /// surfaced a fact, and ranking on that is a rich-get-richer loop: whatever ranks highly gets
+ /// retrieved, which raises its count, which raises its rank. It would look like learning and be
+ /// self-reinforcement.
+ ///
+ ///
+ /// Facts written before this property existed report 1 via coalesce — asserted once,
+ /// which is what a single ingestion means and the only honest reading of an absent counter.
+ ///
+ ///
+ public const string MentionCounts = @"
+ MATCH (f:Fact)
+ WHERE f.id IN $candidateIds
+ RETURN f.id AS candidateId, coalesce(f.mention_count, 1) AS mentions";
+
// ── GetByIdAsync ───────────────────────────────────────────────────
/// Get a single fact by id.
@@ -406,7 +457,16 @@ WHERE true" + winnerOwner + @"
AND coalesce(loser.owner_id, '*') = coalesce(winner.owner_id, '*')
AND loser <> winner
SET loser.invalidated_at = coalesce(loser.invalidated_at, datetime($now)),
- loser.valid_until = coalesce(loser.valid_until, datetime($now))
+ loser.valid_until = coalesce(loser.valid_until, datetime($now)),
+ // S2 contradiction. Twice the corroboration step, and downward: being contradicted is
+ // stronger evidence against a fact than one more restatement is for it. Floored at 0
+ // rather than allowed negative -- confidence is a [0,1] quantity every ranking and
+ // dedup computation reads, and a negative would propagate somewhere it means nothing.
+ loser.confidence = CASE WHEN $reinforceAlpha > 0
+ THEN CASE WHEN coalesce(loser.confidence, 0.0) - (2 * $reinforceAlpha) < 0.0
+ THEN 0.0
+ ELSE coalesce(loser.confidence, 0.0) - (2 * $reinforceAlpha) END
+ ELSE loser.confidence END
MERGE (loser)-[:SUPERSEDED_BY]->(winner)
RETURN count(loser) > 0 AS superseded";
}
diff --git a/src/AgentMemory.Neo4j/Queries/FusedPersistenceQueries.cs b/src/AgentMemory.Neo4j/Queries/FusedPersistenceQueries.cs
index fa9622ca4..f937ff3e7 100644
--- a/src/AgentMemory.Neo4j/Queries/FusedPersistenceQueries.cs
+++ b/src/AgentMemory.Neo4j/Queries/FusedPersistenceQueries.cs
@@ -65,14 +65,23 @@ ON CREATE SET
f.confidence = item.confidence,
f.valid_from = CASE WHEN item.valid_from IS NOT NULL THEN datetime(item.valid_from) ELSE null END,
f.valid_until = CASE WHEN item.valid_until IS NOT NULL THEN datetime(item.valid_until) ELSE null END,
+ f.mention_count = 1,
f.source_message_ids = item.source_message_ids,
f.created_at = datetime(item.created_at),
f.metadata = item.metadata
ON MATCH SET
f.category = item.category,
- f.confidence = item.confidence,
+ // S2 corroboration, identical to the other two write paths. Reinforcement that
+ // depended on which path ran would be a property of batching rather than of the
+ // conversation.
+ f.confidence = CASE WHEN $reinforceAlpha > 0
+ THEN CASE WHEN coalesce(f.confidence, item.confidence) + $reinforceAlpha > 1.0
+ THEN 1.0
+ ELSE coalesce(f.confidence, item.confidence) + $reinforceAlpha END
+ ELSE item.confidence END,
f.valid_from = CASE WHEN item.valid_from IS NOT NULL THEN datetime(item.valid_from) ELSE f.valid_from END,
f.valid_until = CASE WHEN item.valid_until IS NOT NULL THEN datetime(item.valid_until) ELSE f.valid_until END,
+ f.mention_count = coalesce(f.mention_count, 1) + 1,
f.source_message_ids = item.source_message_ids,
f.updated_at = datetime(item.updated_at),
f.metadata = item.metadata,
diff --git a/src/AgentMemory.Neo4j/Queries/NodeDistanceQueries.cs b/src/AgentMemory.Neo4j/Queries/NodeDistanceQueries.cs
new file mode 100644
index 000000000..f131bc383
--- /dev/null
+++ b/src/AgentMemory.Neo4j/Queries/NodeDistanceQueries.cs
@@ -0,0 +1,68 @@
+namespace AgentMemory.Neo4j.Queries;
+
+///
+/// Graph distance from a query-matched centroid entity to a set of candidate facts (R6).
+///
+///
+///
+/// Vector similarity asks "does this row look like the query?"; graph distance asks "is this row
+/// about what the query is about?". They disagree usefully: a fact whose wording is unremarkable
+/// but which hangs directly off the entity the question names is often the answer, and a fact that
+/// merely paraphrases the query can be about someone else entirely.
+///
+///
+/// One bounded query for the whole candidate set, never one per candidate. A per-candidate
+/// traversal would multiply a recall's database round trips by the limit — and it runs on the blocking
+/// path, so a reranker that costs more than the retrieval it reorders is not an improvement.
+///
+///
+internal static class NodeDistanceQueries
+{
+ ///
+ /// The entity whose name or aliases best match the query, by vector similarity.
+ ///
+ ///
+ /// The centroid is chosen by the same embedding the retrieval used, so "near the centroid"
+ /// and "similar to the query" are commensurable rather than two unrelated notions of relevance.
+ /// Owner-scoped: a centroid drawn from another tenant's graph would silently reorder this tenant's
+ /// results around a node they cannot see.
+ ///
+ internal static string CentroidEntity(bool hasOwnerFilter, bool includeShared)
+ {
+ var owner = !hasOwnerFilter ? string.Empty
+ : includeShared ? " AND (node.owner_id = $ownerId OR node.owner_id IS NULL)"
+ : " AND node.owner_id = $ownerId";
+ return $@"
+ CALL db.index.vector.queryNodes('entity_embedding_idx', $topK, $embedding)
+ YIELD node, score
+ WHERE score >= $minScore{owner}
+ RETURN node.id AS entityId, score AS score
+ ORDER BY score DESC
+ LIMIT 1";
+ }
+
+ ///
+ /// Hop distance from the centroid entity to each candidate fact, for the whole set at once.
+ ///
+ ///
+ ///
+ /// Bounded three ways, because an unbounded traversal on a dense graph is how a reranker becomes
+ /// the slowest thing in a recall: the candidate list is the starting set (not the corpus), the
+ /// path length is capped at $maxHops, and only RELATED_TO/ABOUT edges are
+ /// followed — the two that carry meaning between an entity and a fact. EXTRACTED_FROM is
+ /// deliberately excluded: it links to source messages, so following it would make every fact from
+ /// a shared conversation look adjacent regardless of subject.
+ ///
+ ///
+ /// Candidates with no path within the cap are simply absent from the result, which the caller
+ /// reads as "no boost" — the alternative, returning a sentinel distance, invites arithmetic on a
+ /// number that means "unreachable".
+ ///
+ ///
+ internal static string DistanceToCandidates => @"
+ MATCH (centroid:Entity {id: $centroidId})
+ MATCH (f:Fact) WHERE f.id IN $candidateIds
+ MATCH path = shortestPath((centroid)-[:RELATED_TO|ABOUT*..4]-(f))
+ WHERE length(path) <= $maxHops
+ RETURN f.id AS candidateId, length(path) AS hops";
+}
diff --git a/src/AgentMemory.Neo4j/Repositories/Neo4jEntityRepository.cs b/src/AgentMemory.Neo4j/Repositories/Neo4jEntityRepository.cs
index b7618b2b2..afb62fabb 100644
--- a/src/AgentMemory.Neo4j/Repositories/Neo4jEntityRepository.cs
+++ b/src/AgentMemory.Neo4j/Repositories/Neo4jEntityRepository.cs
@@ -19,9 +19,42 @@ internal sealed partial class Neo4jEntityRepository : IEntityRepository, IUpsert
{
private readonly INeo4jTransactionRunner _tx;
+ private readonly bool _rescueShortOwnerResults;
private readonly ILogger _logger;
private readonly MemoryRankingOptions _ranking;
private readonly MemoryDecayOptions _decay;
+ /// Scores this owner's OWN entitys directly, bypassing the global vector index.
+ ///
+ /// Extracted because two conditions reach it -- an empty scoped result, and (opt-in) a short one
+ /// -- and two copies of a fallback drift.
+ ///
+ private async Task> OwnerScopedScanAsync(
+ float[] queryEmbedding,
+ int limit,
+ double minScore,
+ MemoryScope scope,
+ bool includeShared,
+ CancellationToken cancellationToken) =>
+ await _tx.ReadAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ EntityQueries.SearchByVectorOwnerScopedFallback(includeShared),
+ new Dictionary
+ {
+ ["embedding"] = queryEmbedding.ToList(),
+ ["limit"] = limit,
+ ["minScore"] = minScore,
+ ["ownerId"] = scope.OwnerId,
+ }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return records.Select(r =>
+ {
+ var node = r["node"].As();
+ var score = r["score"].As();
+ return (MapToEntity(node, ReadEmbedding(node)), score);
+ }).ToList();
+ }, cancellationToken).ConfigureAwait(false) ?? [];
+
private readonly IMemoryRankingContext? _rankingContext;
public Neo4jEntityRepository(
@@ -29,8 +62,10 @@ public Neo4jEntityRepository(
ILogger logger,
IOptions? ranking = null,
IOptions? decay = null,
- IMemoryRankingContext? rankingContext = null)
+ IMemoryRankingContext? rankingContext = null,
+ IOptions? memoryOptions = null)
{
+ _rescueShortOwnerResults = memoryOptions?.Value.RescueShortOwnerResults ?? false;
_tx = tx;
_logger = logger;
_ranking = ranking?.Value ?? MemoryRankingOptions.Default;
@@ -234,27 +269,25 @@ public async Task> GetByNameAsync(
_logger.LogDebug(
"Owner-scoped entity vector search still empty after widening; falling back to a "
+ "scoped similarity scan.");
- results = await _tx.ReadAsync(async runner =>
- {
- var cursor = await runner.RunAsync(
- EntityQueries.SearchByVectorOwnerScopedFallback(includeShared),
- new Dictionary
- {
- ["embedding"] = queryEmbedding.ToList(),
- ["limit"] = limit,
- ["minScore"] = minScore,
- ["ownerId"] = scope!.OwnerId,
- }).ConfigureAwait(false);
- var records = await cursor.ToListAsync().ConfigureAwait(false);
- return records.Select(r =>
- {
- var node = r["node"].As();
- var score = r["score"].As();
- return (MapToEntity(node, ReadEmbedding(node)), score);
- }).ToList();
- }, cancellationToken).ConfigureAwait(false) ?? [];
+ results = await OwnerScopedScanAsync(
+ queryEmbedding, limit, minScore, scope!, includeShared, cancellationToken)
+ .ConfigureAwait(false);
}
}
+ else if (_rescueShortOwnerResults
+ && OwnerVectorOverFetch.ShouldRescueShortResult(results.Count, limit, hasOwner))
+ {
+ // 2.12, the same rescue the fact path carries. Extended here because "a setting only some
+ // components respect" is the defect shape this project has found twice -- a host enabling
+ // RescueShortOwnerResults would otherwise get it on facts and silently not on entitys.
+ _logger.LogDebug(
+ "Owner-scoped entity vector search returned {Returned} of {Limit}; rescuing with a "
+ + "scoped similarity scan.", results.Count, limit);
+ var scanned = await OwnerScopedScanAsync(
+ queryEmbedding, limit, minScore, scope!, includeShared, cancellationToken)
+ .ConfigureAwait(false);
+ if (scanned.Count > results.Count) results = scanned;
+ }
EmitVectorYield(
activity, hasOwner, limit, escalatedTopK ?? topK, results.Count,
diff --git a/src/AgentMemory.Neo4j/Repositories/Neo4jEntitySummaryRepository.cs b/src/AgentMemory.Neo4j/Repositories/Neo4jEntitySummaryRepository.cs
new file mode 100644
index 000000000..8435d4846
--- /dev/null
+++ b/src/AgentMemory.Neo4j/Repositories/Neo4jEntitySummaryRepository.cs
@@ -0,0 +1,107 @@
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Options;
+using AgentMemory.Abstractions.Repositories;
+using AgentMemory.Neo4j.Infrastructure;
+using AgentMemory.Neo4j.Queries;
+using Microsoft.Extensions.Logging;
+using Neo4j.Driver;
+
+namespace AgentMemory.Neo4j.Repositories;
+
+///
+/// Neo4j persistence for synthesized entity summaries (S1).
+///
+///
+/// The summary node keeps its own :EXTRACTED_FROM edges to the facts it was written from. That
+/// is the part a summary column in a relational row cannot do, and it is what makes "which facts is
+/// this claim standing on?" a query rather than a comment.
+///
+internal sealed class Neo4jEntitySummaryRepository : IEntitySummaryRepository
+{
+ private readonly INeo4jTransactionRunner _tx;
+ private readonly ILogger _logger;
+
+ /// Public ctor: the type is internal, and DI can only activate it through one.
+ public Neo4jEntitySummaryRepository(
+ INeo4jTransactionRunner tx,
+ ILogger logger)
+ {
+ _tx = tx;
+ _logger = logger;
+ }
+
+ ///
+ public async Task UpsertAsync(
+ EntitySummary summary, CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(summary);
+
+ await _tx.WriteAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(EntitySummaryQueries.Upsert, new
+ {
+ summaryId = summary.SummaryId,
+ entityId = summary.EntityId,
+ content = summary.Content,
+ sourceFactIds = summary.SourceFactIds.ToArray(),
+ sourceFingerprint = summary.SourceFingerprint,
+ ownerId = summary.OwnerId,
+ ownerKey = summary.OwnerId ?? Neo4jFactRepository.OwnerKeyShared,
+ generatedAt = summary.GeneratedAtUtc.ToString("o"),
+ }).ConfigureAwait(false);
+ await cursor.ConsumeAsync().ConfigureAwait(false);
+ return true;
+ }, cancellationToken).ConfigureAwait(false);
+
+ _logger.LogDebug(
+ "Stored summary for entity {EntityId} over {SourceCount} fact(s).",
+ summary.EntityId, summary.SourceFactIds.Count);
+ return summary;
+ }
+
+ ///
+ public Task GetByEntityAsync(
+ string entityId, MemoryScope scope, CancellationToken cancellationToken = default)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(entityId);
+
+ return _tx.ReadAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ EntitySummaryQueries.GetByEntity(scope.OwnerId is not null, scope.IncludeShared),
+ new { entityId, ownerId = scope.OwnerId }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return records.Count == 0 ? null : Map(records[0]["s"].As());
+ }, cancellationToken);
+ }
+
+ ///
+ public Task DeleteByEntityAsync(
+ string entityId, MemoryScope scope, CancellationToken cancellationToken = default)
+ {
+ ArgumentException.ThrowIfNullOrWhiteSpace(entityId);
+
+ return _tx.WriteAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ EntitySummaryQueries.DeleteByEntity(scope.OwnerId is not null, scope.IncludeShared),
+ new { entityId, ownerId = scope.OwnerId }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return records.Count > 0;
+ }, cancellationToken);
+ }
+
+ private static EntitySummary Map(INode node) => new()
+ {
+ SummaryId = node.Properties.TryGetValue("id", out var id) ? id.As() : string.Empty,
+ EntityId = node["entity_id"].As(),
+ Content = node["content"].As(),
+ SourceFactIds = node.Properties.TryGetValue("source_fact_ids", out var ids)
+ ? ids.As>().Select(v => v.ToString()!).ToList()
+ : [],
+ SourceFingerprint = node["source_fingerprint"].As(),
+ OwnerId = node.Properties.TryGetValue("owner_id", out var owner) ? owner.As() : null,
+ GeneratedAtUtc = Neo4jDateTimeHelper.ReadNullableDateTimeOffset(node["generated_at"])
+ ?? DateTimeOffset.MinValue,
+ };
+}
diff --git a/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.Fused.cs b/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.Fused.cs
index b273e52b7..63bbe0c23 100644
--- a/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.Fused.cs
+++ b/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.Fused.cs
@@ -68,7 +68,9 @@ public async Task> UpsertFusedBatchAsync(
return await _tx.WriteAsync(async runner =>
{
- var cursor = await runner.RunAsync(FusedPersistenceQueries.FactUpsertBatch, new { items })
+ var cursor = await runner.RunAsync(
+ FusedPersistenceQueries.FactUpsertBatch,
+ new { items, reinforceAlpha = _reinforceAlpha })
.ConfigureAwait(false);
var records = await cursor.ToListAsync().ConfigureAwait(false);
var embeddingByTriple = deduped.ToDictionary(
diff --git a/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.cs b/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.cs
index 3b34245c8..7665d208c 100644
--- a/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.cs
+++ b/src/AgentMemory.Neo4j/Repositories/Neo4jFactRepository.cs
@@ -23,6 +23,8 @@ internal sealed partial class Neo4jFactRepository : IFactRepository, IUpsertPers
internal const string OwnerKeyShared = "*";
private readonly INeo4jTransactionRunner _tx;
+ private readonly bool _rescueShortOwnerResults;
+ private readonly double _reinforceAlpha;
private readonly ILogger _logger;
private readonly MemoryRankingOptions _ranking;
private readonly MemoryDecayOptions _decay;
@@ -33,8 +35,11 @@ public Neo4jFactRepository(
ILogger logger,
IOptions? ranking = null,
IOptions? decay = null,
- IMemoryRankingContext? rankingContext = null)
+ IMemoryRankingContext? rankingContext = null,
+ IOptions? memoryOptions = null)
{
+ _rescueShortOwnerResults = memoryOptions?.Value.RescueShortOwnerResults ?? false;
+ _reinforceAlpha = memoryOptions?.Value.ConfidenceReinforcementAlpha ?? 0.0;
_tx = tx;
_logger = logger;
_ranking = ranking?.Value ?? MemoryRankingOptions.Default;
@@ -78,6 +83,7 @@ public async Task UpsertAsync(Fact fact, CancellationToken cancellationTok
["ownerKey"] = fact.OwnerId ?? OwnerKeyShared,
["category"] = fact.Category,
["confidence"] = fact.Confidence,
+ ["reinforceAlpha"] = _reinforceAlpha,
["validFrom"] = (object?)(fact.ValidFrom?.ToString("O")),
["validUntil"] = (object?)(fact.ValidUntil?.ToString("O")),
["sourceMessageIds"] = fact.SourceMessageIds.ToList(),
@@ -174,7 +180,9 @@ public async Task> UpsertBatchAsync(IReadOnlyList fact
return await _tx.WriteAsync(async runner =>
{
- var cursor = await runner.RunAsync(FactQueries.UpsertBatch, new { items }).ConfigureAwait(false);
+ var cursor = await runner.RunAsync(
+ FactQueries.UpsertBatch,
+ new { items, reinforceAlpha = _reinforceAlpha }).ConfigureAwait(false);
var records = await cursor.ToListAsync().ConfigureAwait(false);
// The MERGE returns the SURVIVING node per triple; for a pre-existing triple that id is the
@@ -293,6 +301,43 @@ public async Task> GetBySubjectAsync(
}, cancellationToken).ConfigureAwait(false);
}
+ ///
+ /// Scores this owner's OWN facts directly, bypassing the global vector index.
+ ///
+ ///
+ /// Extracted because two different conditions now reach it — a totally empty scoped result, and
+ /// (opt-in) a short one — and two copies of a fallback drift. Bounded by one owner's rows rather
+ /// than by the corpus, which is what makes it affordable for the small tenant and effective for
+ /// the crowded one.
+ ///
+ private async Task> OwnerScopedScanAsync(
+ float[] queryEmbedding,
+ int limit,
+ double minScore,
+ MemoryScope scope,
+ bool includeShared,
+ bool currentValidTime,
+ CancellationToken cancellationToken) =>
+ await _tx.ReadAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ FactQueries.SearchByVectorOwnerScopedFallback(includeShared, currentValidTime),
+ new Dictionary
+ {
+ ["embedding"] = queryEmbedding.ToList(),
+ ["limit"] = limit,
+ ["minScore"] = minScore,
+ ["ownerId"] = scope.OwnerId,
+ }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return records.Select(r =>
+ {
+ var node = r["node"].As();
+ var score = r["score"].As();
+ return (MapToFact(node, ReadEmbedding(node)), score);
+ }).ToList();
+ }, cancellationToken).ConfigureAwait(false) ?? [];
+
public Task> SearchByVectorAsync(
float[] queryEmbedding,
int limit = 10,
@@ -387,27 +432,34 @@ public async Task> GetBySubjectAsync(
_logger.LogDebug(
"Owner-scoped fact vector search still empty after widening to {Widened}; "
+ "falling back to a scoped similarity scan.", escalatedTopK ?? topK);
- results = await _tx.ReadAsync(async runner =>
- {
- var cursor = await runner.RunAsync(
- FactQueries.SearchByVectorOwnerScopedFallback(includeShared, currentValidTime),
- new Dictionary
- {
- ["embedding"] = queryEmbedding.ToList(),
- ["limit"] = limit,
- ["minScore"] = minScore,
- ["ownerId"] = scope!.OwnerId,
- }).ConfigureAwait(false);
- var records = await cursor.ToListAsync().ConfigureAwait(false);
- return records.Select(r =>
- {
- var node = r["node"].As();
- var score = r["score"].As();
- return (MapToFact(node, ReadEmbedding(node)), score);
- }).ToList();
- }, cancellationToken).ConfigureAwait(false) ?? [];
+ results = await OwnerScopedScanAsync(
+ queryEmbedding, limit, minScore, scope!, includeShared, currentValidTime,
+ cancellationToken).ConfigureAwait(false);
}
}
+ else if (_rescueShortOwnerResults
+ && OwnerVectorOverFetch.ShouldRescueShortResult(results.Count, limit, hasOwner))
+ {
+ // 2.11. "Short still answers the question" is true for a small tenant and false for a
+ // crowded one, and the returned count cannot tell them apart: question 5d3d2817 returned
+ // 2 facts from a 710-fact graph with the answer present, and was answered wrongly.
+ //
+ // The rescue is the SCAN, not another widening. Widening is a second draw on the same
+ // global index, and a tenant losing to 50 neighbours at top-60 usually loses again at
+ // top-480. The scan is bounded by one owner's rows, so the small tenant this heuristic
+ // was protecting pays less than it would for a wider index query.
+ //
+ // Takes whichever result is larger rather than replacing outright: the scan applies the
+ // same minScore and orders by the same similarity, so a shorter scan result means the
+ // owner genuinely holds no more, and discarding indexed rows for it would be a loss.
+ _logger.LogDebug(
+ "Owner-scoped fact vector search returned {Returned} of {Limit}; rescuing with a "
+ + "scoped similarity scan.", results.Count, limit);
+ var scanned = await OwnerScopedScanAsync(
+ queryEmbedding, limit, minScore, scope!, includeShared, currentValidTime,
+ cancellationToken).ConfigureAwait(false);
+ if (scanned.Count > results.Count) results = scanned;
+ }
if (activity is not null)
{
@@ -542,6 +594,9 @@ private static Fact MapToFact(INode node, float[]? embedding) =>
ValidUntil = node.Properties.TryGetValue("valid_until", out var vu)
? Neo4jDateTimeHelper.ReadNullableDateTimeOffset(vu)
: null,
+ InvalidatedAtUtc = node.Properties.TryGetValue("invalidated_at", out var iat)
+ ? Neo4jDateTimeHelper.ReadNullableDateTimeOffset(iat)
+ : null,
Embedding = embedding,
SourceMessageIds = node.Properties.TryGetValue("source_message_ids", out var sm)
? sm.As>().Select(v => v.ToString()!).ToList()
@@ -643,7 +698,7 @@ public async Task SupersedeAsync(string loserFactId, string winnerFactId,
return await _tx.WriteAsync(async runner =>
{
- var parameters = new Dictionary { ["loserId"] = loserFactId, ["winnerId"] = winnerFactId, ["now"] = now };
+ var parameters = new Dictionary { ["loserId"] = loserFactId, ["winnerId"] = winnerFactId, ["now"] = now, ["reinforceAlpha"] = _reinforceAlpha };
if (hasOwner) parameters["ownerId"] = scope!.OwnerId;
var cursor = await runner.RunAsync(cypher, parameters).ConfigureAwait(false);
var records = await cursor.ToListAsync().ConfigureAwait(false);
diff --git a/src/AgentMemory.Neo4j/Repositories/Neo4jPreferenceRepository.cs b/src/AgentMemory.Neo4j/Repositories/Neo4jPreferenceRepository.cs
index 430e847c5..502dd0d26 100644
--- a/src/AgentMemory.Neo4j/Repositories/Neo4jPreferenceRepository.cs
+++ b/src/AgentMemory.Neo4j/Repositories/Neo4jPreferenceRepository.cs
@@ -19,9 +19,42 @@ internal sealed partial class Neo4jPreferenceRepository : IPreferenceRepository,
{
private readonly INeo4jTransactionRunner _tx;
+ private readonly bool _rescueShortOwnerResults;
private readonly ILogger _logger;
private readonly MemoryRankingOptions _ranking;
private readonly MemoryDecayOptions _decay;
+ /// Scores this owner's OWN preferences directly, bypassing the global vector index.
+ ///
+ /// Extracted because two conditions reach it -- an empty scoped result, and (opt-in) a short one
+ /// -- and two copies of a fallback drift.
+ ///
+ private async Task> OwnerScopedScanAsync(
+ float[] queryEmbedding,
+ int limit,
+ double minScore,
+ MemoryScope scope,
+ bool includeShared,
+ CancellationToken cancellationToken) =>
+ await _tx.ReadAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ PreferenceQueries.SearchByVectorOwnerScopedFallback(includeShared),
+ new Dictionary
+ {
+ ["embedding"] = queryEmbedding.ToList(),
+ ["limit"] = limit,
+ ["minScore"] = minScore,
+ ["ownerId"] = scope.OwnerId,
+ }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return records.Select(r =>
+ {
+ var node = r["node"].As();
+ var score = r["score"].As();
+ return (MapToPreference(node, ReadEmbedding(node)), score);
+ }).ToList();
+ }, cancellationToken).ConfigureAwait(false) ?? [];
+
private readonly IMemoryRankingContext? _rankingContext;
public Neo4jPreferenceRepository(
@@ -29,8 +62,10 @@ public Neo4jPreferenceRepository(
ILogger logger,
IOptions? ranking = null,
IOptions? decay = null,
- IMemoryRankingContext? rankingContext = null)
+ IMemoryRankingContext? rankingContext = null,
+ IOptions? memoryOptions = null)
{
+ _rescueShortOwnerResults = memoryOptions?.Value.RescueShortOwnerResults ?? false;
_tx = tx;
_logger = logger;
_ranking = ranking?.Value ?? MemoryRankingOptions.Default;
@@ -248,27 +283,25 @@ public async Task> GetByCategoryAsync(
_logger.LogDebug(
"Owner-scoped preference vector search still empty after widening; falling back to a "
+ "scoped similarity scan.");
- results = await _tx.ReadAsync(async runner =>
- {
- var cursor = await runner.RunAsync(
- PreferenceQueries.SearchByVectorOwnerScopedFallback(includeShared),
- new Dictionary
- {
- ["embedding"] = queryEmbedding.ToList(),
- ["limit"] = limit,
- ["minScore"] = minScore,
- ["ownerId"] = scope!.OwnerId,
- }).ConfigureAwait(false);
- var records = await cursor.ToListAsync().ConfigureAwait(false);
- return records.Select(r =>
- {
- var node = r["node"].As();
- var score = r["score"].As();
- return (MapToPreference(node, ReadEmbedding(node)), score);
- }).ToList();
- }, cancellationToken).ConfigureAwait(false) ?? [];
+ results = await OwnerScopedScanAsync(
+ queryEmbedding, limit, minScore, scope!, includeShared, cancellationToken)
+ .ConfigureAwait(false);
}
}
+ else if (_rescueShortOwnerResults
+ && OwnerVectorOverFetch.ShouldRescueShortResult(results.Count, limit, hasOwner))
+ {
+ // 2.12, the same rescue the fact path carries. A host enabling RescueShortOwnerResults
+ // would otherwise get it on facts and silently not on preferences -- the "setting only some
+ // components respect" shape this project has found twice.
+ _logger.LogDebug(
+ "Owner-scoped preference vector search returned {Returned} of {Limit}; rescuing with "
+ + "a scoped similarity scan.", results.Count, limit);
+ var scanned = await OwnerScopedScanAsync(
+ queryEmbedding, limit, minScore, scope!, includeShared, cancellationToken)
+ .ConfigureAwait(false);
+ if (scanned.Count > results.Count) results = scanned;
+ }
// Explicit null check rather than `activity?.SetTag(...)` per AgentMemoryDiagnostics' remarks: the
// tag block exists purely to produce telemetry, so it is skipped whole when nobody is listening.
diff --git a/src/AgentMemory.Neo4j/Repositories/Neo4jReasoningTraceRepository.cs b/src/AgentMemory.Neo4j/Repositories/Neo4jReasoningTraceRepository.cs
index b58d10136..dfe0475a6 100644
--- a/src/AgentMemory.Neo4j/Repositories/Neo4jReasoningTraceRepository.cs
+++ b/src/AgentMemory.Neo4j/Repositories/Neo4jReasoningTraceRepository.cs
@@ -1,5 +1,6 @@
using System.Diagnostics;
using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
using AgentMemory.Abstractions.Diagnostics;
using AgentMemory.Abstractions.Domain;
using AgentMemory.Abstractions.Options;
@@ -15,10 +16,50 @@ namespace AgentMemory.Neo4j.Repositories;
internal sealed class Neo4jReasoningTraceRepository : IReasoningTraceRepository
{
private readonly INeo4jTransactionRunner _tx;
+ private readonly bool _rescueShortOwnerResults;
+ /// Scores this owner's OWN traces directly, bypassing the global vector index.
+ ///
+ /// Extracted because two conditions reach it -- an empty scoped result, and (opt-in) a short one
+ /// -- and two copies of a fallback drift.
+ ///
+ private async Task> OwnerScopedScanAsync(
+ float[] queryEmbedding,
+ int limit,
+ double minScore,
+ MemoryScope scope,
+ bool includeShared,
+ bool? successFilter,
+ bool? proceduresOnly,
+ CancellationToken cancellationToken) =>
+ await _tx.ReadAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ ReasoningQueries.SearchByTaskVectorOwnerScopedFallback(
+ successFilter.HasValue, includeShared, proceduresOnly),
+ new Dictionary
+ {
+ ["embedding"] = queryEmbedding.ToList(),
+ ["limit"] = limit,
+ ["minScore"] = minScore,
+ ["ownerId"] = scope.OwnerId,
+ }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return records.Select(r =>
+ {
+ var node = r["node"].As();
+ var score = r["score"].As();
+ return (MapToTrace(node, ReadEmbedding(node)), score);
+ }).ToList();
+ }, cancellationToken).ConfigureAwait(false) ?? [];
+
private readonly ILogger _logger;
- public Neo4jReasoningTraceRepository(INeo4jTransactionRunner tx, ILogger logger)
+ public Neo4jReasoningTraceRepository(
+ INeo4jTransactionRunner tx,
+ ILogger logger,
+ IOptions? memoryOptions = null)
{
+ _rescueShortOwnerResults = memoryOptions?.Value.RescueShortOwnerResults ?? false;
_tx = tx;
_logger = logger;
}
@@ -243,23 +284,25 @@ public async Task> ListAllAsync(int limit = 50, int
["ownerId"] = scope!.OwnerId!,
};
if (successFilter.HasValue) fallbackParameters["successFilter"] = successFilter.Value;
-
- results = await _tx.ReadAsync(async runner =>
- {
- var cursor = await runner.RunAsync(
- ReasoningQueries.SearchByTaskVectorOwnerScopedFallback(
- successFilter.HasValue, includeShared, proceduresOnly),
- fallbackParameters).ConfigureAwait(false);
- var records = await cursor.ToListAsync().ConfigureAwait(false);
- return records.Select(r =>
- {
- var node = r["node"].As();
- var score = r["score"].As();
- return (MapToTrace(node, ReadEmbedding(node)), score);
- }).ToList();
- }, cancellationToken).ConfigureAwait(false) ?? [];
+ results = await OwnerScopedScanAsync(
+ taskEmbedding, limit, minScore, scope!, includeShared, successFilter,
+ proceduresOnly, cancellationToken).ConfigureAwait(false);
}
}
+ else if (_rescueShortOwnerResults
+ && OwnerVectorOverFetch.ShouldRescueShortResult(results.Count, limit, hasOwner))
+ {
+ // 2.12, the same rescue the fact path carries. A host enabling RescueShortOwnerResults
+ // would otherwise get it on facts and silently not on traces -- the "setting only some
+ // components respect" shape this project has found twice.
+ _logger.LogDebug(
+ "Owner-scoped trace vector search returned {Returned} of {Limit}; rescuing with "
+ + "a scoped similarity scan.", results.Count, limit);
+ var scanned = await OwnerScopedScanAsync(
+ taskEmbedding, limit, minScore, scope!, includeShared, successFilter,
+ proceduresOnly, cancellationToken).ConfigureAwait(false);
+ if (scanned.Count > results.Count) results = scanned;
+ }
// Explicit null check rather than `activity?.SetTag(...)` per AgentMemoryDiagnostics' remarks: the
// tag block exists purely to produce telemetry, so it is skipped whole when nobody is listening.
diff --git a/src/AgentMemory.Neo4j/Repositories/OwnerVectorOverFetch.cs b/src/AgentMemory.Neo4j/Repositories/OwnerVectorOverFetch.cs
index 63257a270..4cb419a52 100644
--- a/src/AgentMemory.Neo4j/Repositories/OwnerVectorOverFetch.cs
+++ b/src/AgentMemory.Neo4j/Repositories/OwnerVectorOverFetch.cs
@@ -27,6 +27,20 @@ namespace AgentMemory.Neo4j.Repositories;
/// with an extra query on every recall forever, because an owner holding three facts can never fill a
/// ten-row limit. So: one extra query, only when the first pass found nothing, and bounded.
///
+///
+/// That last argument has a measured counter-example. Question 5d3d2817 returned
+/// 2 facts from a 710-fact graph with the gold answer present at coverage 1.00, and both arms
+/// answered it wrongly. "Short still answers the question" is true for a small tenant and false for a
+/// crowded one, and the returned count alone cannot tell them apart.
+///
+///
+/// The rescue is therefore not more widening. Widening is another draw on the same global
+/// index, and a tenant losing to 50 neighbours at top-60 usually loses again at top-480. The
+/// owner-scoped similarity scan already used as the last resort is the right instrument: its cost
+/// scales with one owner's data rather than with the corpus, so the small tenant this argument
+/// was protecting pays almost nothing — scanning three facts is cheaper than a second index query —
+/// while the crowded tenant gets its true top-K instead of whatever survived the neighbours.
+///
///
internal static class OwnerVectorOverFetch
{
@@ -57,6 +71,30 @@ internal static int InitialTopK(int limit, bool hasOwner) =>
///
internal static bool ShouldEscalate(int returned, bool hasOwner) => hasOwner && returned == 0;
+ ///
+ /// Whether a scoped search that returned something, but less than asked for, should fall
+ /// back to the owner-bounded scan.
+ ///
+ ///
+ ///
+ /// Opt-in (MemoryOptions.RescueShortOwnerResults), because it trades latency for recall on
+ /// every short result and every recorded measurement was taken without it.
+ ///
+ ///
+ /// Deliberately not a fraction of the limit. A ratio invites a threshold nobody can
+ /// justify — is 4 of 10 starved? 6 of 10? — and the honest answer is that any shortfall might be
+ /// crowding, since the index gave the owner whatever the neighbours left. The scan is bounded by
+ /// the owner's own rows either way, so the gate is simply "short", and the cost question is
+ /// answered by the scan's shape rather than by guessing a cutoff.
+ ///
+ ///
+ /// Excludes the empty case, which already owns and which reaches the
+ /// same scan through a path that first tries one widened query.
+ ///
+ ///
+ internal static bool ShouldRescueShortResult(int returned, int limit, bool hasOwner) =>
+ hasOwner && returned > 0 && returned < limit;
+
/// The widened width, capped.
internal static int EscalatedTopK(int currentTopK)
{
diff --git a/src/AgentMemory.Neo4j/Services/MentionFrequencyReranker.cs b/src/AgentMemory.Neo4j/Services/MentionFrequencyReranker.cs
new file mode 100644
index 000000000..74dad34d8
--- /dev/null
+++ b/src/AgentMemory.Neo4j/Services/MentionFrequencyReranker.cs
@@ -0,0 +1,119 @@
+using AgentMemory.Abstractions.Domain;
+using AgentMemory.Abstractions.Options;
+using AgentMemory.Abstractions.Services;
+using AgentMemory.Neo4j.Infrastructure;
+using AgentMemory.Neo4j.Queries;
+using Microsoft.Extensions.Logging;
+using Microsoft.Extensions.Options;
+using Neo4j.Driver;
+
+namespace AgentMemory.Neo4j.Services;
+
+///
+/// Boosts facts the conversation keeps returning to (R7).
+///
+///
+///
+/// A fact the world asserted five times is usually more central than one mentioned once. Similarity
+/// cannot see that: two facts phrased alike score alike however often either was actually said.
+///
+///
+/// The signal is ingestion-side, and that distinction is the whole task. It counts how often
+/// the world re-asserted a fact — mention_count, incremented by the upsert paths when a
+/// new ingestion re-states an existing triple. The tempting substitute, :MemoryReadAudit,
+/// counts how often we surfaced it, and ranking on that is a rich-get-richer loop: whatever
+/// ranks highly gets retrieved, retrieval raises the count, the count raises the rank. It would look
+/// like learning and be self-reinforcement, so it is not used here and must not be.
+///
+///
+/// Logarithmic, not linear. The gap between one mention and three is real; the gap between
+/// thirty and thirty-two is noise, and a linear boost would let a chatty topic bury a precise answer.
+///
+///
+/// One bounded query for the whole candidate set. Off by default: it changes recall ordering and
+/// every recorded measurement was taken without it.
+///
+///
+internal sealed class MentionFrequencyReranker : IMemoryReranker
+{
+ private readonly INeo4jTransactionRunner _tx;
+ private readonly MemoryOptions _memory;
+ private readonly ILogger _logger;
+
+ public MentionFrequencyReranker(
+ INeo4jTransactionRunner tx,
+ ILogger logger,
+ IOptions? memory = null)
+ {
+ _tx = tx;
+ _logger = logger;
+ _memory = memory?.Value ?? new MemoryOptions();
+ }
+
+ ///
+ /// How much a well-attested fact may outrank a better-matching one.
+ ///
+ ///
+ /// At 0.15, a fact mentioned eight times gains ~1.31× while a once-mentioned one gains 1.0 — enough
+ /// to break a near-tie, not enough to promote a weak match over a strong one. Salience is a
+ /// tiebreaker among plausible answers, not a substitute for matching the question.
+ ///
+ private const double BoostWeight = 0.15;
+
+ ///
+ public bool IsEnabled => _memory.MentionFrequencyReranking;
+
+ ///
+ public async Task> RerankAsync(
+ IReadOnlyList candidates,
+ MemoryRerankContext context,
+ CancellationToken cancellationToken = default)
+ {
+ ArgumentNullException.ThrowIfNull(candidates);
+ ArgumentNullException.ThrowIfNull(context);
+
+ // mention_count is maintained on Fact only. Boosting another kind by a counter nothing
+ // increments would be a no-op dressed as a feature.
+ if (context.SectionKind != MemoryItemKind.Fact || candidates.Count < 2) return candidates;
+
+ var mentions = await MentionCountsAsync(candidates, cancellationToken).ConfigureAwait(false);
+ if (mentions.Count == 0) return candidates;
+
+ var reordered = candidates
+ .Select(item => new
+ {
+ Item = item,
+ Boosted = item.Score * (1.0 + (BoostWeight * Math.Log(
+ mentions.TryGetValue(item.ItemId, out var count) ? Math.Max(count, 1) : 1))),
+ })
+ .OrderByDescending(scored => scored.Boosted)
+ // Retrieval rank breaks ties, so equal salience leaves the provider's order intact rather
+ // than an arbitrary one.
+ .ThenBy(scored => scored.Item.RetrievalRank)
+ .Select((scored, index) => scored.Item with { ContextRank = index + 1 })
+ .ToList();
+
+ _logger.LogDebug(
+ "Mention-frequency rerank over {Count} candidates; most-mentioned {Max}.",
+ candidates.Count, mentions.Count == 0 ? 0 : mentions.Values.Max());
+
+ return reordered;
+ }
+
+ private async Task> MentionCountsAsync(
+ IReadOnlyList candidates, CancellationToken cancellationToken) =>
+ await _tx.ReadAsync(async runner =>
+ {
+ var cursor = await runner.RunAsync(
+ FactQueries.MentionCounts,
+ new Dictionary
+ {
+ ["candidateIds"] = candidates.Select(item => item.ItemId).ToList(),
+ }).ConfigureAwait(false);
+ var records = await cursor.ToListAsync().ConfigureAwait(false);
+ return (IReadOnlyDictionary)records.ToDictionary(
+ r => r["candidateId"].As(),
+ r => r["mentions"].As(),
+ StringComparer.Ordinal);
+ }, cancellationToken).ConfigureAwait(false) ?? new Dictionary