Merging entities rebuilds the working-memory block (30.4b, seam 1 of 5)

[joslat]

What this closes

The working-memory design named MergeEntitiesAsync in §5.2 and build step 6 as one of four direct rebuild seams. It was never built — and an independent review found it, not the green suite, because every working-memory test called RebuildAsync directly. Testing the thing rather than its trigger cannot detect a trigger wired to the wrong path.

This is 1 of the 5 seams that review found. Four remain open and are listed at the bottom.

Why a decorator rather than an epilogue

Every other rebuild seam hangs off a service. MergeEntitiesAsync has none — it is IEntityRepository-only, public, and TCK-Gold exposed, so calling the repository directly IS the usage pattern. A service-level hook would have been bypassed by every caller that exists.

So the seam goes on the interface: WorkingMemoryEntityRepositoryDecorator wraps whatever IEntityRepository is registered, rebuilds after a merge that actually matched, and forwards the other 21 members untouched.

Registered unconditionally and self-gated, following the reranker pattern in the same file. Gating the registration would freeze the tier at container-build time and break IOptions reconfiguration — the exact defect that comment warns about.

A defect this PR found in itself

The first draft got lifetime wrong. The decorator inherits the repository's Transient lifetime while IWorkingMemoryService is Scoped, and the DI factory resolved it eagerly — which made IEntityRepository unresolvable from the root container. A scoped-from-root violation, a regression in a surface that resolved fine before, and invisible to all fourteen tests because every one of them called CreateScope(). A host with ValidateScopes on would have failed at startup.

Now resolved through IServiceScopeFactory (a singleton, safe from root), lazily, and only once a merge has actually matched with the tier enabled; the rebuilder owns that scope and disposes it. A disabled tier never constructs a rebuilder or touches the container at all.

Bonus: one failure policy replaces three

The rebuild failure policy was already written out twice and had drifted — the identical clear-also-failed branch logged at Error in LongTermMemoryService ("because nothing else can notice it") and at Warning in PersistenceStage. This change needed a third copy. Instead there is now one shared WorkingMemoryRebuilder, and both existing sites delegate to it.

Two details worth their code

• A guarded / cross-owner / self-merge no-op changed nothing, so it rebuilds nothing and spends no read — rebuilding anyway would cost exactly the calls the isolation guard makes free.
• An unscoped admin merge names no owner, so the surviving target is read after the merge to find whose block changed. With no scope and an ownerless target there is nothing to rebuild — guard G3's near side.

Verification

Suite	Result
Release build	0 warnings / 0 errors
Unit	5054 (was 5039, + exactly these 15)
LongMemEval harness	676
SemanticKernel	54
Integration — full	479/479 (pre-fix build)
Integration — all repositories	204/204 (post-fix, live Neo4j)

15 tests, all driving MergeEntitiesAsync rather than RebuildAsync. The reachability guard was verified red-first by unwiring the registration (2 of 3 failed), because a decorator's unit tests construct it directly and stay green whether or not any container ever produces one. The captive-dependency guard was also watched failing with the real scoped-from-root exception before the fix.

Local full-integration runs were repeatedly killed by the environment mid-run, which is why the post-fix evidence is the 204-test repository layer — the entire surface this change touches — rather than the full 479. CI runs the complete suite.

Still open (30.4b seams 2–5)

AddEntityAsync + MCP memory_add_entity · the three Invalidate* paths + MCP memory_invalidate · DeletePreferenceAsync · RecordEntityFeedbackAsync (benign).

The Invalidate* group is the most important: supersede is hooked and its exact twin is not, and every block query filters invalidated_at IS NULL, so an invalidated item keeps asserting a retracted value until an unrelated write happens.

The tier ships off by default, so nothing in production is affected today.

🤖 Generated with Claude Code

https://claude.ai/code/session_01PgDgctPpbTziBNE2RT8VdE

[Copilot]

Pull request overview

Implements the missing working-memory rebuild seam for IEntityRepository.MergeEntitiesAsync by decorating the repository so successful merges trigger a working-memory block rebuild, and centralizes the rebuild failure policy to avoid drift across call sites.

Changes:

• Add WorkingMemoryEntityRepositoryDecorator to rebuild working memory after successful entity merges, including owner resolution for unscoped merges.
• Extract rebuild-and-failure-policy logic into a shared WorkingMemoryRebuilder and route existing rebuild seams through it.
• Add unit tests to ensure the decorator is actually reachable via DI and that merge-triggered rebuild behavior is exercised; update docs/changelog with Neo4j 2026.02 / Cypher 25 verification notes.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/AgentMemory.Tests.Unit/Services/WorkingMemoryMergeReachabilityTests.cs	Adds DI reachability + captive-dependency guard tests for the merge decorator registration.
tests/AgentMemory.Tests.Unit/Services/WorkingMemoryMergeEntitiesTests.cs	Adds unit tests that drive MergeEntitiesAsync and assert rebuild/no-rebuild behavior.
src/AgentMemory.Neo4j/Infrastructure/ServiceCollectionExtensions.cs	Registers the merge rebuild seam by decorating IEntityRepository and creating the rebuilder lazily via IServiceScopeFactory.
src/AgentMemory.Core/Services/WorkingMemoryRebuilder.cs	Introduces a single shared implementation of rebuild + clear-on-failure policy.
src/AgentMemory.Core/Services/WorkingMemoryEntityRepositoryDecorator.cs	Implements the repository decorator that triggers rebuild after merge and forwards all other members.
src/AgentMemory.Core/Services/LongTermMemoryService.cs	Replaces inlined rebuild failure policy with WorkingMemoryRebuilder.
src/AgentMemory.Core/Extraction/PersistenceStage.cs	Replaces inlined rebuild failure policy with WorkingMemoryRebuilder and reuses its disabled gating.
docs/agent-framework.md	Documents Neo4j 5.x/2026.x prerequisites and Cypher 25 default-language behavior in Neo4j 2026.02.
CHANGELOG.md	Adds an Unreleased note documenting verified Neo4j 2026.02 / Cypher 25 compatibility.

Suppressed comments (3)

tests/AgentMemory.Tests.Unit/Services/WorkingMemoryMergeReachabilityTests.cs:48

• This test creates a ServiceProvider via Build() but never disposes it (only the scope). With ServiceProvider being IAsyncDisposable (and sync disposal potentially throwing due to Neo4j registrations), the provider should be disposed via DisposeAsync to avoid leaking resources across the unit test run.

    [Fact]
    public void TheResolvedEntityRepositoryIsTheMergeRebuildDecorator()
    {
        using var scope = Build(workingMemoryEnabled: true).CreateScope();

        var repository = scope.ServiceProvider.GetRequiredService<IEntityRepository>();

tests/AgentMemory.Tests.Unit/Services/WorkingMemoryMergeReachabilityTests.cs:67

• Like the previous test, this one creates a root ServiceProvider and only disposes the scope. The root provider should be disposed via DisposeAsync to avoid leaking any IAsyncDisposable registrations.

    [Fact]
    public void TheDecoratorIsRegisteredEvenWhenTheTierIsDisabled()
    {
        using var scope = Build(workingMemoryEnabled: false).CreateScope();

        var repository = scope.ServiceProvider.GetRequiredService<IEntityRepository>();

tests/AgentMemory.Tests.Unit/Services/WorkingMemoryMergeReachabilityTests.cs:83

• This test also builds a root ServiceProvider and never disposes it (only the scope). Dispose the provider with await using to avoid retaining IAsyncDisposable resources after the test completes.

    [Fact]
    public void TheDecoratedRegistrationStillResolvesRepeatedly()
    {
        using var scope = Build(workingMemoryEnabled: true).CreateScope();

        var first = scope.ServiceProvider.GetRequiredService<IEntityRepository>();
        var second = scope.ServiceProvider.GetRequiredService<IEntityRepository>();

---

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