Skip to content

What an agent sees, and whether it is still true: dates, changes of mind, shared knowledge, relationships - #230

Merged
joslat merged 21 commits into
mainfrom
phase36/memory-quality
Sep 28, 2026
Merged

joslat merged 21 commits into
mainfrom
phase36/memory-quality

Conversation

@joslat

@joslat joslat commented Sep 28, 2026

Copy link
Copy Markdown
Owner

What an agent sees, and whether it is still true

Simulated conversations showed recalled memory that was stale, undated or not about the user: a changed city left both homes live, "When did I move to Lyon?" was answered without the date that was stored, shared reference knowledge was presented as the user's, and relationships never reached the prompt. This branch fixes the memory layer underneath those answers. Every behaviour change is off by default; the switches are listed below.

Recall

  • Shared knowledge has its own budget and label (MemoryOptions.SharedRecallBudget): an owner's search returns its own top-k plus a separate shared top-n, rendered as "shared knowledge, not about the user", on live, as-of and fan-out recall. One similarity scale, stated on every option that takes a threshold.
  • Dates reach the prompt at the precision they were stated (DatePrecision, stored as valid_from_precision / valid_until_precision): "since 2024-03", never a day nobody said. One rule (FactDates) for both renderers, the profile block, recalled turns from other sessions and the conflict/supersession blocks (IncludeDates on Agent Framework, Core/Semantic Kernel and working memory). Extractors now receive each turn's timestamp, so relative dates resolve against the turn, not the machine clock.
  • An event carries the day it happened (Fact.OccurredOn, stored as occurred_on): "(on 2026-09-26)" instead of "since", and it no longer drops out of the profile block the day after. Read by as-of recall, derivation, the conflict block, the MCP projection and memory history.
  • Relationships reach recall (RecallOptions.MaxRelationships): "Rosa — best friend → Carmen". A restated relationship is the stored edge (sources merged), not a second one.
  • A month named without a year that is still ahead is read as last year's only when the question is about the past ("what did I do in October?"), not for "what do I have coming up in October?".

Changes of mind (ExtractionOptions.SupersedeReplacedFacts, LlmExtractionOptions.MarkCorrections)

  • Present-state forms per relation (lives in / resides in / …), age, favourite … for facts and preferences, and entailment ("moved to" a place entails "lives in" there, from the move's day).
  • A marked correction ("Arcade Fire, not Radiohead") closes what it replaces, conservatively, when it is said, even when the new value is dated ahead ("the full marathon in May instead of the half in April").
  • Which value one extraction leaves current is decided once, before anything is written (CurrentValues), and nothing is closed until every fact is written, so the batch and item write paths agree: the last value said that no correction names is current; dated values order by date; a value that has ended or not begun joins no group and supersedes nothing; supersession only replaces a value that holds now.
  • Single-valued relationship edges end (non-destructively) when replaced.

Identity and isolation

  • The speaker is the named person, written once under their name with their name's vector, never an entity called "user". A question's presupposition is not stored as a statement.
  • Entities carry owner_key (index, bootstrap backfill, healed on write), so the shared half of entity resolution is an index seek.
  • OwnPreferencesOnly; a shared (owner-less) write stores no preferences.

Switches (all default off)

MemoryOptions.SharedRecallBudget, ExtractionOptions.SupersedeReplacedFacts, LlmExtractionOptions.MarkCorrections / OwnPreferencesOnly, IncludeDates (MAF ContextFormatOptions, Core MemoryContextFormatterOptions, SK MemoryRecallSecurityOptions, WorkingMemoryOptions), RecallOptions.MaxRelationships, TemporalValidityMode.Extract for turn stamping and event dates.

Known limits, recorded for follow-up

  • One node per fact holds one validity window: a value said again after it was replaced ("I moved back") is live again in transaction time but keeps its earlier end (the existing bitemporal re-assertion rule). A second period needs its own design.
  • A plan that begins does not yet hand over from the value it replaces.
  • Relationships reach recall through recalled entities only; a relationship whose endpoints are named only by recalled facts is not yet included.

Verification

  • Unit: 5,895 (core) + 910 + 55 + 42 + 3, all green. Every fix has a test that fails when the fix is reverted (mutation-checked).
  • Integration (Neo4j via Testcontainers): 567 passed, 29 skipped, 0 failed.
  • Samples: all build (0 warnings); MinimalAgent and AgentWithMemory run end to end on a live Neo4j with a real model.
  • Perf gate (hermetic, zero and remote latency): pass, with the one counter change below.
  • Nine review rounds; the within-extraction supersession logic was redesigned after six rounds of point fixes kept regressing. Persistence tests share one in-memory store fake that behaves as the Cypher does.
  • Simulated conversations re-run on the branch: dated questions answered with the stored dates ("What do I have coming up in October?" now finds the appointment), changes of mind leave one current value.

Perf counter change justification: PERF-W-08 neo4j.queries 14 -> 15 is the restated-relationship read (one indexed read of the source entity's edges per extraction that has relationships), which stops a relationship said twice from being stored as two edges.

🤖 Generated with Claude Code

https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

joslat and others added 21 commits September 27, 2026 23:24
… stated

Measured on four embedding models: a shared corpus took 7-8 of 10 fact slots on
questions about the person and pushed out answers they had given. A relative
(z-score) cutoff was tried and rejected: against the store it keeps no answers
to questions about the shared topic itself; against a neutral reference set it
admits 16-45 irrelevant items per question. Separate budgets cut shared items
per question 7.6 -> 3.0 with answers equal or better on every model.

- MemoryOptions.SharedRecallBudget: own top k + shared top n, live, as-of and
  fan-out; MemoryContext.SeparatesSharedKnowledge; both renderers label shared
  items instead of "Known facts" / "User preferences"
- LlmExtractionOptions.OwnPreferencesOnly: someone else's taste is a fact about
  them, a request is not a preference (all extractors)
- shared writes store no preferences
- an owner's mention joins a shared entity by exact name/alias only
- entity prefilter converts SemanticMatchThreshold (cosine) to the index scale;
  every threshold documents its scale

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
A fact's validity dates keep how precisely they were written (year, month,
day, instant): the parser records it, every fact write path stores it
(single, batch, fused; a re-assertion without a date keeps both), and one
rule renders it on every surface: the MAF mapper, the Core formatter and the
profile block, behind IncludeDates (off by default). Recalled turns from
another session carry the day they were said. Due/expiring reminders print
their date at its precision.

Found in simulated conversations: the move date was stored and the agent
answered "I don't have the date"; printing the stored instant as a day would
have answered "on 1 March", a day nobody said.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
Found in simulated conversations, each with both values left live: "works
for" a new firm beside "works at" the old one, "moved to Copenhagen" beside
"lives in Hamburg", "Bruno is 7 years old" beside "6", "Arcade Fire, not
Radiohead" as two preferences, the full marathon beside the half.

- cardinality resolves stored predicates through their stored forms (the
  question-side resolver refused "works for", a stored form of "works at")
- a new value replaces every stored form of its relation
- age is a single-valued relation; "X is N years old" is written as age
- "favourite <thing>" is single-valued per thing (vocabulary prefix)
- events declare the state they entail, with the object type it needs
  ("moved to" a LOCATION entails "lives in")
- a value that has already ended does not replace the current one
- MarkCorrections: extractors mark what a correction replaces; the write
  closes the fact or preference that stated it (preferences had no
  supersession at all); Preference.InvalidatedAtUtc

All with SupersedeReplacedFacts (off by default); prompts unchanged off.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…statement

Found in simulated conversations: the model listed "user" among the people
(the prompt calls the speaker "the user"), so a "user" node stood beside the
person's own with relationships from it; and "When did I move to Lyon?" was
stored as a move. Self words are not resolved as entities (a relationship
from one lands on the person's entity when their name is known, else is
skipped), and the questions instruction says a presupposition states nothing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
… fixes

From the first rerun of the simulated conversations on this branch:
- the correction rule closed "left the shipping company" (a true event) and
  missed "is training for half marathon" (stored object shorter than the
  replaced value): mentions now match either way, the same relation is
  closed first, and a different relation only when it is the one mention
- "has favourite band" is the favourite-band relation too
- extracted dates came out a year off: only the multi-session extractor
  sent turn times; every dated extractor now stamps each turn (one helper)

36.7: RecallOptions.MaxRelationships renders the live relationships of the
recalled entities ("Rosa - best friend -> Carmen") in both renderers; one
query with both names. Extraction reuses the id of the live same edge
(the same relation said twice was two edges); with SupersedeReplacedFacts a
single-valued relation ends its previous edge (valid_until) through
IRelationshipRepository.EndAsync. Divergence recorded: live recall only.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…tated precision

Run 3 of the simulated conversations: "I moved to Lyon in March 2024" was
extracted as 2024-03-01, stored at day precision, and answered "on March
1st". The model invented the day; the parser keeps whatever precision it
is given.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
Two reviewers, 19 findings (5 HIGH), all fixed with a test that fails when
the fix is reverted (21 mutants, all killed):

- HIGH: history forms ("worked at", "lived in") replaced and were replaced by
  the current value; relations now declare their present-state forms
- HIGH: a correction's fallback closed an unrelated fact after supersession
  had closed the real one; corrections run first, and the fallback needs
  more than a one-word coincidence
- HIGH: an entailed state overrode a state the same turn stated, and
  "moving to" (not yet) closed the current home; completed, past, unstated
  only, inserted right after its event
- HIGH: "favourite bands are" was single-valued; plurals are not
- HIGH: restating an edge overwrote its sources and validity; the stored
  edge is restated with this statement's sources added
- corrections on a shared write matched nothing; the speaker entity is
  dropped only once the user's name is known (no relationship lost); edges
  end only after the replacement is stored; the subject's earlier wording is
  searched as supersession does
- off-state: the Core formatter repeated projection preambles in empty
  shared sections; the batch extraction path kept shared preferences;
  expansion/derived facts bypassed the shared budget; empty owner split
- dates: conflict/supersession blocks print at the stated precision
  (SupersededFact.ValidUntilPrecision); Semantic Kernel IncludeDates; free
  text without a time is unspecified; the fact extractor gets the
  own-preferences instruction

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
Review round 2 (on the round-1 fixes; 1 HIGH, 2 MEDIUM; 8 mutants killed):
- HIGH: a history form ("lived in Paris") blocked the entailed new home;
  only present, current states block an entailment now
- two moves in one turn kept the first; each states its home, in order
- the speaker's entity is written under the user's name (dropped only when
  that person is already an entity), so "I'm Rosa, my sister is Carmen"
  keeps user->Carmen; the name is also read for entity-only extractions
- self words are one subject for entailment
- shared items keep their projection annotations in the Core formatter
- present forms the vocabulary lists: "live", "is employed by the"

36.9 (G-17): entities carry owner_key on every write path (index, bootstrap
backfill, heal on match); resolution's shared half is an index seek instead
of a scan of every entity of the type (1,122 hits on 868 entities).

Run 4 finding: "Favourite band is Arcade Fire, not Radiohead" came without
a marked correction; a preference stating a single-valued relation now
replaces its previous value in the same category.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…with its own vector

Round 3 (on round 2; 1 HIGH, 2 MEDIUM; 6 mutants killed):
- HIGH: two values of one single-valued relation in the same extraction
  closed each other on the batch path (pre-existing, made reachable by the
  entailment and favourite rules): within one write only a later value
  closes an earlier one, for facts and preferences
- the speaker, written under the user's name, is embedded as that name
  (it kept the vector of "user"), and several self words are one entity
- "live" alone is not a residence ("live with my parents")
- the store branch of "the named person already exists" is tested

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
Round 4 (on round 3; 1 HIGH, 1 MEDIUM, 3 LOW; 5 mutants, 4 killed, the 5th
was redundant code, removed):
- HIGH: ordering on the item path let "Copenhagen, Oslo, Copenhagen" leave
  two live homes; order only the batch (the item path is sequential)
- a marked correction closes what it names regardless of order, and a
  value a correction names does not supersede it (facts and preferences)
- the speaker's name maps to the speaker, never to an earlier alias;
  FailFast honoured for its vector; "live" alone tested as not a residence

Run 5 regression, root-caused: "What do I have coming up in October?"
(asked in September) resolved to last October, and point-in-time recall
hid the appointment extraction now dates this October. TemporalQueryParser
reads a bare month still ahead this year as last year's only in a
past-tense question. The test that recorded this as an accepted limit is
updated: the limit was not tolerable once future facts carry dates.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…losed by its correction

The old value a correction names is matched in stored terms (the user's name,
not "I"), by relation, and never as the correction's own value. It supersedes
nothing, and its correction closes it after every fact is written, so the item
path and favourites hold too. A correction's other-relation fallback leaves
facts stated in the same extraction alone. FailFast reports the speaker's name
vector as an embedding failure. A past-tense month question that points ahead
("where did I say I'd be in October") stays at now.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
A one-off event is not a validity period: extracted as valid_from alone it read
"since", and as valid_from = valid_until it left the profile block the next day.
Under TemporalValidityMode.Extract the extractor gives it occurred_on at the
stated precision; it is stored on all three fact write paths (kept when told
again without a day), read back, rendered "(on X)" by FactDates everywhere
(profile block included), carried by within-extraction dedup, and a move's day
becomes the entailed home's valid_from.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…rent

Five rules (a batch order guard, a corrected-away set, a stated-now set, a
favourite order guard, the correction fallback) each fixed one sequence and
broke another, because the batch and item paths see an extraction's own
statements at different moments. CurrentValues decides it once, before any
write: a value a correction names is old; of one single-valued relation the
last said that is not old is current; the rest supersede nothing and are
closed by the current value after everything is written; a replaced
correction passes its old values on. Fixes chained corrections (no live home),
chained favourites, the fallback sparing a stored value merely restated, a
self-naming preference correction, a best-effort speaker-vector failure
reported as Failed, and look-ahead words that only look ahead.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
AgentFrameworkOptions.DeferQuestionTurns (off by default): a turn in which
every sentence the user said is a question or a request is held, per owner,
and extracted as part of the next turn that tells something, or once
MaxDeferredTurns are waiting. Asking to be reminded or to have something
remembered is never held. The held turns belong to the host's options
instance, which every Agent Framework entry point of one host shares, so no
public constructor changes.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
Deferring (36.5) uses a generous rule and skipping (H-2) a strict one, on
purpose: a deferred turn loses nothing, a skipped fact is never formed. They
are now one file apart instead of two assemblies apart, with the relation
between them tested: every plain question only asks.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…unds it

An ended value joins no group (one StillHolds rule for ReplacementShapes, the
grouping and the supersession guard); of dated values the later-dated is
current; no correction of the extraction closes its current value, on either
path; a current value that fails to write is stood in for by the last
replaced one; the current value supersedes what each replaced one would have
(another self word, another relation form); a correction's fallback spares
what the extraction created or said after it; a merged statement takes the
place of its latest telling; a name stated in the extraction folds into the
speaker for entailment. occurred_on is read by as-of recall, derivation, the
conflict block, the MCP projection and memory history (all three history
segments project the column, which the integration suite caught).

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…'s real semantics

On both write paths, corrections, supersession and the replaced values'
closing now run after every fact of the extraction is written (the item path
closed while writing, so a value not yet restated looked absent and the paths
disagreed). One supersession routine carries every guard, and the replaced
values' duty goes through it. Supersession replaces only values that hold
now: the query skips ended and not-yet-begun losers, and ended or planned
values join no group. An undated value began when said. A failed current
value is stood in for by the latest value not corrected away. A value said
again after it was replaced is current again (the supersession-stamped end is
cleared on revival, a stated end kept). occurred_on twins in live recall, the
alias as-of read and the profile block. The persistence tests share one fake
that behaves as the Cypher does; round 7's tests had passed against fakes
that did not.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
The round-8 revival (a restated superseded value cleared its stamped
valid_until) is reverted: a triple is one node with one validity window, and
clearing it corrupted as-of recall of the interim and moved ends to today; the
existing tests that re-assertion keeps valid_until encode that decision. A
second period for the same value ("moved back") needs its own design.
Also: a correction that failed to write withdraws the value this extraction
itself corrected away; a correction that is a plan closes nothing before it
begins; the profile rebuild boundary counts occurred_on; the candidate
contract documents the holds-now rule.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
…e new value's date

Round 9 had given corrections supersession's start guard. Rerun: "the full
marathon in May instead of the half in April" was extracted with the full
marathon dated May, so the half stayed live beside it. A correction is the
person withdrawing what they said, now; only cardinality supersession waits
for a value to hold.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9
Copilot AI lite review requested due to automatic review settings September 28, 2026 10:00
@joslat joslat added the perf-counter-change Intentional structural counter increase; PR-body justification is also required label Sep 28, 2026

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Several moderate correctness and projection gaps remain unresolved.

Review effort: Lite
Findings: 5 Medium severity

Open (5)
What changed in this PR

Adds opt-in temporal precision, event dates, shared-knowledge isolation, relationship recall, identity scoping, and correction-aware supersession across the memory pipeline.

Changes:

  • Extends extraction, persistence, recall, rendering, and projections with temporal metadata.
  • Adds shared recall budgets, owner-key indexing, relationship handling, and preference isolation.
  • Adds correction/supersession logic and broad unit/integration coverage.
File Description
tools/​AgentMemory.LongMemEval/​LongMemEvalRepresentationProgram.cs Exports event dates.
tests/​AgentMemory.Tests.Unit/​TestSupport/​StoreFakes.cs Adds persistence fakes.
tests/​AgentMemory.Tests.Unit/​Services/​SupersessionPredicateGateTests.cs Updates predicate coverage.
tests/​AgentMemory.Tests.Unit/​Services/​SharedKnowledgeExtractionTests.cs Tests shared preference filtering.
tests/​AgentMemory.Tests.Unit/​Services/​DerivationEvaluatorTests.cs Tests event-based duration derivation.
tests/​AgentMemory.Tests.Unit/​Resolution/​IndexedCandidatesTests.cs Updates similarity threshold expectations.
tests/​AgentMemory.Tests.Unit/​Queries/​ValidTimeGateQueryTests.cs Tests event validity gates.
tests/​AgentMemory.Tests.Unit/​Queries/​TemporalAndDecayQueryTests.cs Tests temporal query filtering.
tests/​AgentMemory.Tests.Unit/​Queries/​ScopedNonVectorReadQueryTests.cs Tests owner-key filtering.
tests/​AgentMemory.Tests.Unit/​Queries/​DerivedFactCypherGuardTests.cs Tests event ordering.
tests/​AgentMemory.Tests.Unit/​Queries/​CypherQuerySnapshotTests.cs Updates query inventory.
tests/​AgentMemory.Tests.Unit/​Memory/​TemporalQueryParserTests.cs Tests month interpretation.
tests/​AgentMemory.Tests.Unit/​Infrastructure/​SchemaBootstrapperTests.cs Updates schema coverage.
tests/​AgentMemory.Tests.Unit/​Infrastructure/​AbstractionsContractGuardTests.cs Updates public type coverage.
tests/​AgentMemory.Tests.Unit/​Extraction/​WithinExtractionDedupTests.cs Tests dates, corrections, and identity.
tests/​AgentMemory.Tests.Unit/​Extraction/​PeriodDateConverterTests.cs Tests date conversion.
tests/​AgentMemory.Tests.Unit/​Extraction/​OwnPreferencesInstructionTests.cs Tests preference prompts.
tests/​AgentMemory.Tests.Unit/​Extraction/​CurrentValuesTests.cs Tests current-value selection.
tests/​AgentMemory.Tests.Unit/​Configuration/​AsOfRecallDivergenceTests.cs Records as-of limitations.
tests/​AgentMemory.Tests.Unit.SemanticKernel/​Neo4jTextSearchTests.cs Tests date-option bridging.
tests/​AgentMemory.Tests.Integration/​Repositories/​RelationshipsInRecallIntegrationTests.cs Tests relationship recall.
tests/​AgentMemory.Tests.Integration/​Repositories/​EntityOwnerKeyIntegrationTests.cs Tests owner-key indexing and backfill.
tests/​AgentMemory.Tests.Integration/​Repositories/​DatePrecisionIntegrationTests.cs Tests date persistence and rendering.
tests/​AgentMemory.Tests.Integration/​Repositories/​ChangesOfMindIntegrationTests.cs Tests fact and preference supersession.
src/​AgentMemory.SemanticKernel/​MemoryRecallSecurityOptionsExtensions.cs Bridges date rendering options.
src/​AgentMemory.SemanticKernel/​MemoryRecallSecurityOptions.cs Adds date configuration.
src/​AgentMemory.Neo4j/​Services/​Neo4jWorkingMemoryService.cs Renders precise working-memory dates.
src/​AgentMemory.Neo4j/​Services/​Neo4jMemoryHistoryService.cs Maps event dates into history.
src/​AgentMemory.Neo4j/​Schema/​Parity/​SchemaParityPolicy.cs Registers new schema properties.
src/​AgentMemory.Neo4j/​Repositories/​Neo4jRelationshipRepository.cs Adds relationship recall and ending.
src/​AgentMemory.Neo4j/​Repositories/​Neo4jPreferenceRepository.cs Maps preference invalidation.
src/​AgentMemory.Neo4j/​Repositories/​Neo4jFactRepository.Fused.cs Persists date metadata in fused writes.
src/​AgentMemory.Neo4j/​Repositories/​Neo4jFactRepository.cs Persists and reads temporal metadata.
src/​AgentMemory.Neo4j/​Queries/​WorkingMemoryQueries.cs Applies event validity to working memory.
src/​AgentMemory.Neo4j/​Queries/​TemporalQueries.cs Applies event dates to temporal queries.
src/​AgentMemory.Neo4j/​Queries/​SchemaQueries.cs Adds the entity owner-key index.
src/​AgentMemory.Neo4j/​Queries/​RelationshipQueries.cs Adds relationship recall queries.
src/​AgentMemory.Neo4j/​Queries/​HistoryQueries.cs Returns event dates from history.
src/​AgentMemory.Neo4j/​Queries/​FusedPersistenceQueries.cs Persists temporal metadata and owner keys.
src/​AgentMemory.Neo4j/​Queries/​FactQueries.cs Updates fact persistence and filtering.
src/​AgentMemory.Neo4j/​Queries/​EntityQueries.cs Adds owner-key writes and filtering.
src/​AgentMemory.Neo4j/​Queries/​DerivedFactQueries.cs Orders derived inputs by event time.
src/​AgentMemory.Neo4j/​Infrastructure/​SchemaBootstrapper.cs Backfills entity owner keys.
src/​AgentMemory.Neo4j/​Infrastructure/​DatePrecisionProperty.cs Serializes date precision.
src/​AgentMemory.McpServer/​Tools/​McpMemoryProjection.cs Projects event dates through MCP.
src/​AgentMemory.Extraction.Llm/​LlmUnifiedMemoryExtractor.cs Extracts dates and corrections.
src/​AgentMemory.Extraction.Llm/​LlmPreferenceExtractor.cs Adds preference and correction guidance.
src/​AgentMemory.Extraction.Llm/​LlmMultiSessionUnifiedMemoryExtractor.cs Adds stamped multi-session extraction.
src/​AgentMemory.Extraction.Llm/​LlmFactExtractor.cs Extracts temporal metadata.
src/​AgentMemory.Extraction.Llm/​LlmExtractionOptions.cs Adds extraction switches.
src/​AgentMemory.Extraction.Llm/​Internal/​PeriodDateConverters.cs Preserves parsed precision.
src/​AgentMemory.Extraction.Llm/​Internal/​LlmResponseModels.cs Adds temporal and correction fields.
src/​AgentMemory.Extraction.Llm/​ExtractionPromptSemantics.cs Adds temporal and preference guidance.
src/​AgentMemory.Core/​Services/​SimilarityScale.cs Defines similarity-scale conversion.
src/​AgentMemory.Core/​Services/​SharedKnowledge.cs Splits and labels shared memory.
src/​AgentMemory.Core/​Services/​RecallFanOutMerge.cs Supports separate shared budgets.
src/​AgentMemory.Core/​Services/​Projection/​SupersessionProjectionFeature.cs Renders precise supersession dates.
src/​AgentMemory.Core/​Services/​Projection/​ConflictProjectionFeature.cs Renders precise conflict dates.
src/​AgentMemory.Core/​Services/​MemoryExtractionPipeline.cs Filters shared preferences.
src/​AgentMemory.Core/​Services/​MemoryExtractionPipeline.Batch.cs Applies shared filtering to batches.
src/​AgentMemory.Core/​Services/​MemoryContextFormatterOptions.cs Adds date formatting options.
src/​AgentMemory.Core/​Services/​MemoryContextFormatter.cs Renders dates, shared knowledge, and relationships.
src/​AgentMemory.Core/​Services/​MemoryContextAssembler.FanOut.cs Applies shared budgets during fan-out.
src/​AgentMemory.Core/​Services/​MemoryContextAssembler.cs Assembles relationships and shared metadata.
src/​AgentMemory.Core/​Services/​LongTermMemoryService.cs Implements shared-budget searches.
src/​AgentMemory.Core/​Services/​FactDates.cs Centralizes date rendering.
src/​AgentMemory.Core/​ServiceCollectionExtensions.cs Validates shared-budget configuration.
src/​AgentMemory.Core/​Resolution/​CompositeEntityResolver.cs Applies owner boundaries and score conversion.
src/​AgentMemory.Core/​Resolution/​CompositeEntityResolver.Batch.cs Applies owner boundaries in batches.
src/​AgentMemory.Core/​Memory/​TemporalQueryParser.cs Distinguishes past and future month queries.
src/​AgentMemory.Core/​Memory/​RelationVocabularyDocument.cs Adds relation metadata.
src/​AgentMemory.Core/​Memory/​relation-vocabulary.json Defines relation forms and entailments.
src/​AgentMemory.Core/​Memory/​MemoryRelationLexicon.cs Resolves stored relation forms.
src/​AgentMemory.Core/​Memory/​MemoryRelationCardinality.cs Handles single-valued relations.
src/​AgentMemory.Core/​Extraction/​ReplacementShapes.cs Shapes ages and entailed states.
src/​AgentMemory.Core/​Extraction/​Derivation/​IDerivationEvaluator.cs Uses event dates for derivation.
src/​AgentMemory.Core/​Extraction/​Derivation/​Evaluators.cs Calculates event durations.
src/​AgentMemory.Core/​Extraction/​CurrentValues.cs Chooses current extracted values.
src/​AgentMemory.Core/​Extraction/​Corrections.cs Resolves marked corrections.
src/​AgentMemory.Core/​Extraction/​ConversationTextBuilder.cs Stamps extraction turns.
src/​AgentMemory.AgentFramework/​ServiceCollectionExtensions.cs Bridges date options.
src/​AgentMemory.AgentFramework/​Mapping/​MafTypeMapper.cs Renders dates, sharing, and relationships.
src/​AgentMemory.AgentFramework/​ContextFormatOptions.cs Adds date formatting configuration.
src/​AgentMemory.Abstractions/​Services/​ILongTermMemoryService.cs Adds relationship recall API.
src/​AgentMemory.Abstractions/​Schema/​SchemaConstants.cs Defines temporal properties.
src/​AgentMemory.Abstractions/​Repositories/​IRelationshipRepository.cs Adds relationship recall and ending contracts.
src/​AgentMemory.Abstractions/​Repositories/​IFactRepository.cs Documents supersession candidate rules.
src/​AgentMemory.Abstractions/​Options/​WorkingMemoryOptions.cs Adds profile date rendering.
src/​AgentMemory.Abstractions/​Options/​RecallOptions.cs Adds relationship limits and score documentation.
src/​AgentMemory.Abstractions/​Options/​RecallFanOutOptions.cs Documents score scale.
src/​AgentMemory.Abstractions/​Options/​MemoryProjectionOptions.cs Documents projection score scale.
src/​AgentMemory.Abstractions/​Options/​MemoryOptions.cs Adds shared recall budgeting.
src/​AgentMemory.Abstractions/​Options/​LongTermMemoryOptions.cs Documents deduplication score scale.
src/​AgentMemory.Abstractions/​Options/​ExtractionOptions.cs Clarifies thresholds and switches.
src/​AgentMemory.Abstractions/​Domain/​LongTerm/​SupersededFact.cs Adds supersession date precision.
src/​AgentMemory.Abstractions/​Domain/​LongTerm/​RecalledRelationship.cs Defines recalled relationships.
src/​AgentMemory.Abstractions/​Domain/​LongTerm/​Preference.cs Adds preference invalidation state.
src/​AgentMemory.Abstractions/​Domain/​LongTerm/​Fact.cs Adds validity and event dates.
src/​AgentMemory.Abstractions/​Domain/​LongTerm/​DatePrecision.cs Defines date precision values.
src/​AgentMemory.Abstractions/​Domain/​History/​MemoryHistory.cs Adds event dates to history.
src/​AgentMemory.Abstractions/​Domain/​Extraction/​ExtractedPreference.cs Adds preference corrections.
src/​AgentMemory.Abstractions/​Domain/​Extraction/​ExtractedFact.cs Adds precise dates and corrections.
src/​AgentMemory.Abstractions/​Domain/​Context/​MemoryContext.cs Adds relationships and shared state.
docs/​architecture.md Updates public type counts.

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

Comment on lines +69 to +71
var statedStates = aged
.Where(fact => StillHolds(fact.ValidUntil, now))
.Select(fact => (Subject: SubjectKey(fact.Subject), Relation: MemoryRelationCardinality.Relation(fact.Predicate)))
Comment on lines +1036 to +1037
SeparatesSharedKnowledge = SharedBudgetFor(scope, _options.SharedRecallBudget) is not null,
RelevantRelationships = new MemoryContextSection<RecalledRelationship> { Items = relationships },
Comment on lines +100 to +102
WHERE (s.id IN $entityIds OR t.id IN $entityIds)
AND (r.valid_until IS NULL OR r.valid_until > datetime($now)){OwnerAnd(hasOwnerFilter, includeShared)}
RETURN r, s.name AS sourceName, t.name AS targetName
Comment on lines +98 to +104
public static string GetLiveAmong(bool hasOwnerFilter, bool includeShared) => $@"
MATCH (s:Entity)-[r:RELATED_TO]->(t:Entity)
WHERE (s.id IN $entityIds OR t.id IN $entityIds)
AND (r.valid_until IS NULL OR r.valid_until > datetime($now)){OwnerAnd(hasOwnerFilter, includeShared)}
RETURN r, s.name AS sourceName, t.name AS targetName
ORDER BY r.confidence DESC, r.created_at DESC
LIMIT $limit";
Comment on lines +32 to +38
store[i] = was with
{
InvalidatedAtUtc = null,
ValidUntil = fact.ValidUntil ?? was.ValidUntil,
ValidFrom = fact.ValidFrom ?? was.ValidFrom,
OccurredOn = fact.OccurredOn ?? was.OccurredOn,
};
@joslat
joslat merged commit 18818d1 into main Sep 28, 2026
8 of 9 checks passed
@joslat
joslat deleted the phase36/memory-quality branch September 28, 2026 10:15
joslat added a commit that referenced this pull request Sep 28, 2026
…tions, recent topics (#231)

* Dates and the shared-knowledge budget on by default (37.1)

IncludeDates defaults to true on the four renderers that print dates (one
guard test for the twins) and SharedRecallBudget to 3: in simulated
conversations both kept every answer and improved the dated ones. The
model-dependent extraction switches and supersession stay opt-in.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* An object the model wrote twice is stored once (37.2)

"Daniel | is a chef | chef" rendered "Daniel is a chef chef". A predicate that
ends with its own object's words, with or without a leading article, is
trimmed at write, for every fact on either write path; whole words only, and
never to an empty predicate.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* "Lately": what the person has talked about most recently (37.5)

WorkingMemoryOptions.RecentTopicsDays (off by default) ends the profile block
with one line naming the owner's entities that live facts extracted in the
window mention most, counted by distinct messages (EXTRACTED_FROM provenance
with the message time), never the person (self words, their stated name).
Only what the person said counts. One read per rebuild, only when enabled;
trimmed first when the block is over budget.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* A question-only turn waits, stored, for the next turn that tells something (37.4)

The durable redesign of the deferral pulled in review round 8. The memory
service decides (every entry point gets it); the host only consents
(AgentFrameworkOptions.DeferQuestionTurns sets ExtractionRequest.DeferIfOnlyAsking).
A waiting turn is marked on its stored message: it survives a restart, stays
in its store and session, is gone when forgotten, and the marks clear only
when the releasing extraction succeeds; at most MaxDeferredTurns wait. The
E2 context window reaches up to the last target, so the agent's reply between
a waiting question and its telling turn is context.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* Docs: every memory option in one table; dates, events, shared knowledge, relationships, changes of mind (37.3)

A new docs/configuration/memory-options.md lists each switch with its default;
getting-started, agent-framework, memory-map, schema and architecture say what
the memory now does and store (occurred_on, date precision, entity owner_key,
the predicate trim), with the known limits.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* Docs: the ships-dark section says which defaults were later turned on

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* Keep the shared-knowledge budget opt-in; record W-08's justified read in the baseline

The perf gate caught the cost of SharedRecallBudget on by default: an
owner-scoped recall searches twice per memory type (PERF-R-07: 9 -> 16
queries), in every store, shared knowledge or not. It stays opt-in (3 is the
measured value) until the shared search is skipped where there is nothing
shared. IncludeDates stays on. The baseline records PERF-W-08's 15th query,
the restated-relationship read justified in #230, so later changes are gated
against the current shape.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* Phase 37 review round 1: held turns belong to their owner; Lately counts what the person said

Deferral: a waiting turn is marked for its owner (the session when there is
none) and read by an index seek; the owner's next telling turn in any session
releases it (a session ending on a question no longer strands it; one agent's
shared session id never releases Alice's words into Bob's extraction); any
failure while deferring extracts the turn now; "please ..." and "help me ..."
are told, not held; waiting turns are counted as the user's messages.
Lately: distinct facts from live user messages (a released batch and the
agent's words no longer inflate it), the naming exclusion by the same keys as
the name lookup, case-blind entity match, rebuilt at least daily. The predicate
trim moves a dangling article to the object. A dated recalled turn is
deduplicated against the live thread by what was said.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* The shared budget no longer searches for shared rows that do not exist; on by default (37.1b)

With SharedRecallBudget set, every owner-scoped recall searched twice per
memory type, shared knowledge or not (the perf gate caught it: PERF-R-07 9 ->
16 queries). ISharedCorpusProbe answers whether the store holds shared memory
of a kind (Neo4j: one EXISTS per store and kind, a seek on owner_key for facts
and entities; "none" cached 30 s, "some" 10 min); without any, the shared
search is skipped, and a probe that cannot answer leaves it in place. With the
cost gone where nothing is shared, SharedRecallBudget defaults to 3 again. The
perf gate passes unchanged.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* Integration tests that read a turn's memory at once extract inline

Three tests read what a turn stored right after it returned; with
ExtractInBackground on by default (since #229) that was a race they lost when
run on their own (warm runs won it, so full-suite runs passed). They are about
owner stamping, provenance and trust, not background timing.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

* Shared knowledge written a moment ago is recalled at once

The shared-corpus check cached "none" for 30 seconds, so in a store without shared
knowledge, a book taught and then asked about straight away was not recalled until
the window expired. Every repository path that writes an owner-less fact, entity or
preference (single, batch, fused, derived) now tells the check before the write, and
it answers "some" at once; a "some" that turns out wrong only costs one empty search.
Only a write from another process still waits out the window.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0139u7CNFuidKuPJBRK7auC9

---------

Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

perf-counter-change Intentional structural counter increase; PR-body justification is also required

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants