feat(memory): Refactor MemoryGraphRecallTool boundaries + temporal supersession with auto-retraction and fact history

[novaspectrayan]

Summary

Refactor MemoryGraphRecallTool to enforce proper module boundaries between the MCP layer (spector-mcp) and the memory module (spector-memory), then add temporal supersession and multi-evidence reconstruction capabilities.

Strategic rationale: The MCP tool currently has 570 lines of BFS traversal engine code that directly imports 7 internal memory classes (EntityDirectory, HyperEntityGraphMemory, TemporalKnowledgeGraph, TemporalFact, MemoryIndex, etc.) via memory.admin(). This logic belongs in CognitiveGraphFacade, which was designed to encapsulate all graph traversal. Fixing this boundary violation first enables temporal supersession to be built cleanly in the memory module without duplicating logic in the MCP layer.

Temporal supersession closes a gap: assertFact doesn't auto-detect supersession (callers must manually retract+assert), there's no public API for fact history chains, graph traversal ignores validity windows, and ContradictionResolver forces a single winner with no multi-evidence mode.

User Stories

Refactoring:
As a Spector developer, I want the MCP layer to use only SpectorMemory public API so that internal memory module changes don't break MCP tools and new memory features automatically surface through MCP.

Temporal Supersession:
As an AI agent, I want "What was the user's preferred model before the June change?" to return the correct historical fact without hallucinating the current one.

As an AI agent, when I assert ("Alice", "works_at", "Google") and a prior fact ("Alice", "works_at", "Meta") exists, I want the prior fact to be automatically superseded with a history link so I can query the complete employment timeline.

Acceptance Criteria

Workstream A: Refactor MemoryGraphRecallTool

• New GraphRecallOptions model class with builder pattern
• New GraphTraversalResult model class with structured entities, paths, grounding memories
• CognitiveGraphFacade.graphRecall() encapsulates BFS traversal (ported from MCP tool)
• SpectorMemory.graphRecall() default method delegates to facade
• MemoryGraphRecallTool reduced from 570 to ~120 LOC — zero imports from memory.graph.*, memory.temporal.*, memory.index.*
• ArchUnit boundary test prevents future MCP → memory internal coupling
• All existing memory_graph_recall MCP functionality preserved (no behavioral regression)

Workstream B: Temporal Supersession

• TemporalKnowledgeGraph.assertFactWithSupersession() auto-retracts prior active fact on same (subject, predicate)
• allowCoexisting=true flag for multi-valued predicates (e.g., speaks_language)
• Existing SpectorMemory.assertFact() defaults to auto-supersession
• New SpectorMemory.factHistory(subject, predicate) returns FactHistory (active + superseded chain)
• New FactHistory model with FactSnapshot records (factId, object, validFrom, validTo, txTime, confidence, supersededByFactId)
• New ConflictAwareResolver returns highest-confidence fact (multi-evidence via factHistory())
• CognitiveGraphFacade.graphRecall() respects asOf temporal parameter (validity window filtering)
• CognitiveGraphFacade.collectEntityEdges() filters expired facts by validity window
• MemoryGraphRecallTool adds as_of and include_superseded MCP parameters
• Zero extra latency on hot path (SIMD scoring unchanged)

Scope

IN scope (MVP):

• Graph recall refactoring with proper module boundaries
• Auto-supersession with retractsFactId linking
• factHistory() API for supersession chains
• Point-in-time asOf temporal queries in graph traversal
• Validity window filtering in collectEntityEdges()
• ArchUnit boundary test
• ConflictAwareResolver (highest-confidence selection)

OUT of scope (future):

• JPMS module-info.java (separate effort)
• Irreducible conflict recognition (TANGLE-style conflict-aware action policy)
• Multi-evidence reconstruction in MemoryRecallTool (only in graph recall for now)
• Migration tooling for existing shards

Getting Started

1. Build: mvn compile -pl memory/spector-memory,synapse/spector-mcp
2. Key files:
   • memory/spector-memory/src/main/java/com/spectrayan/spector/memory/graph/CognitiveGraphFacade.java
   • synapse/spector-mcp/src/main/java/com/spectrayan/spector/mcp/tools/memory/MemoryGraphRecallTool.java
   • memory/spector-memory/src/main/java/com/spectrayan/spector/memory/temporal/TemporalKnowledgeGraph.java
   • memory/spector-memory/src/main/java/com/spectrayan/spector/memory/SpectorMemory.java
3. Patterns to follow: RecallOptions (builder pattern), CognitiveGraphFacade.neighborhood() (facade traversal), ContradictionResolver interface

RICE-C Score

Factor	Score	Rationale
Reach	5/5	Affects every agent using graph recall; temporal queries benefit all enterprise users
Impact	3x	Closes #1 competitive gap (temporal), fixes architecture debt, enables future features cleanly
Confidence	80%	Infrastructure mostly exists (TKG, CognitiveGraphFacade, ContradictionResolver); scoped tightly
Effort	M	~2-3 weeks; refactoring is mechanical, temporal features build on existing infra
Cognitive Fit	5/5	Core to Spector's neuroscience identity — temporal memory is fundamental to cognition

[titanspectrayan]

🏗️ Architectural Decision Record — @titan

Status: Approved
Personas: @titan (Solutions Architect), @jarvis (CTO)

Context

MemoryGraphRecallTool (570 LOC in spector-mcp) implements a full BFS traversal engine that directly imports 7 internal spector-memory classes: EntityDirectory, HyperEntityGraphMemory, HyperEdge, HyperEdgeVertex, TemporalKnowledgeGraph, TemporalFact, MemoryIndex. This violates the module boundary between the MCP layer and memory internals.

Meanwhile, CognitiveGraphFacade (799 LOC in spector-memory) was designed exactly for this purpose — it already encapsulates neighborhood(), traceWhy(), traceEffects(), and all graph subsystem access. The BFS traversal in the MCP tool is a duplicated concern.

Additionally, the temporal subsystem has infrastructure gaps: assertFact() doesn't auto-detect supersession, factsAbout() returns only active facts (no history), and collectEntityEdges() ignores validity windows.

Decision

1. Move BFS traversal into CognitiveGraphFacade.graphRecall()

The ~380 lines of traversal logic (entity resolution, BFS across TKG + HyperEntityGraph, filtering, ranking) moves into a new graphRecall() method on CognitiveGraphFacade. This follows the established pattern of neighborhood() and traceWhy().

2. New model classes in memory.model

• GraphRecallOptions (builder pattern, consistent with RecallOptions)
• GraphTraversalResult (structured entities, paths, grounding memories)
• FactHistory (supersession chain with FactSnapshot records)

3. Thin delegation on SpectorMemory

SpectorMemory.graphRecall(options) as a default method delegating to admin().graph().graphRecall(options, this::inspect). Same pattern as other facade-backed methods.

4. Auto-supersession in TemporalKnowledgeGraph

New assertFactWithSupersession() method that auto-retracts prior active facts with same (subject, predicate) and links via retractsFactId. Opt-out via allowCoexisting=true for multi-valued predicates.

5. Temporal-aware graph traversal

graphRecall() accepts asOf (Instant) and includeSuperseded parameters. collectEntityEdges() fixed to respect validTo expiration.

Consequences

Positive:

• MCP tool drops from 570 → ~120 LOC
• Zero internal memory imports in MCP layer
• Temporal features land once in the memory module, automatically surfaced via MCP
• ArchUnit test prevents regression
• CognitiveGraphFacade gains caching for graph recall (free from existing SpectorCache integration)

Negative:

• SpectorMemory API surface grows (+3 methods: graphRecall, factHistory, assertFact overload)
• Existing assertFact() behavior changes to default auto-supersession (breaking if any caller relied on coexisting facts)

Risks & Mitigations:

• Breaking change on assertFact: Mitigated by allowCoexisting=true overload. Existing callers using the 6-arg assertFact() will get auto-supersession — but this is actually the correct default behavior.
• Output format regression: formatResult() stays in MCP layer (presentation logic), producing identical output from GraphTraversalResult instead of raw graph data.

Alternatives Considered

Alternative	Rejected Because
Keep traversal in MCP, add temporal there too	Perpetuates boundary violation; duplicates logic
Create a new GraphQueryService class	Unnecessary indirection; CognitiveGraphFacade already owns this concern
Change ContradictionResolver interface to return List<TemporalFact>	Breaking change to established interface; factHistory() provides multi-evidence without modifying resolvers

Component Design

MCP Layer (spector-mcp)                    Memory Module (spector-memory)
┌─────────────────────────┐                ┌──────────────────────────────┐
│ MemoryGraphRecallTool   │                │ SpectorMemory (interface)    │
│  - parse MCP args       │──graphRecall──▶│  - graphRecall(options)      │
│  - format output        │                │  - factHistory(s, p)         │
│  - ~120 LOC             │                │  - assertFact(..., coexist)  │
└─────────────────────────┘                └──────────┬───────────────────┘
                                                      │ delegates via admin().graph()
                                           ┌──────────▼───────────────────┐
                                           │ CognitiveGraphFacade         │
                                           │  - graphRecall() ← NEW      │
                                           │  - neighborhood()            │
                                           │  - traceWhy()                │
                                           │  - traceEffects()            │
                                           │  - collectEntityEdges() ← FIX│
                                           └──────────┬───────────────────┘
                                                      │ uses
                                    ┌─────────────────┼──────────────────┐
                                    ▼                 ▼                  ▼
                             EntityDirectory   TemporalKnowledge   HyperEntityGraph
                                               Graph (+ supersession)

Commit sequence: 10 dependency-ordered commits (models → temporal → facade → API → MCP → tests → ArchUnit)

Approved for implementation.
— @titan, Solutions Architect