feat(agent): MRAgent reconstructive memory (Cue–Tag–Content graph + active reconstruction)

[danielsimonjr]

Implements "Memory is Reconstructed, Not Retrieved: Graph Memory for LLM
Agents" (Ji, Li & Hooi, ICML 2026) as a new src/agent/reconstruction/ module.

Replaces the static "retrieve-then-reason" paradigm with an associative
memory graph and an active, multi-step reconstruction loop that integrates
reasoning directly into memory access.

• CueTagContentGraph: heterogeneous M = (C, V, R) associative graph where
  associative tags bridge fine-grained cues to memory contents, organised into
  episodic / semantic / topic layers. O(1) mapping operators (paper Eq. 5/8/9):
  tagsForCue, contentsForCueTag, cueTagsForContent (reverse), episodesForTopic;
  snapshot round-trip.
• MemoryToolkit: the seven typed traversal operators from Table 4
  (query_tag_events, query_conversation_time, query_event_keywords,
  query_event_context, query_personal_information, query_personal_aspect,
  query_topic_events).
• MemoryDistiller: construction pipeline (§3.3 / App. B.1) — rewrite (pronoun
  resolution, temporal normalisation, episodic segmentation) → tag + cue
  extraction → semantic-fact extraction → topic abstraction. Optional
  LLMProvider with the paper's App. E prompts; deterministic heuristic fallback
  for zero-config use (mirrors LLMQueryPlanner).
• MemoryReconstructor: active reconstruction (Algorithm 1) — reconstruction
  state S(t) = (Z(t), H(t)), f_select action selection, controlled
  forward/reverse/topic traversal, f_route pruning, stopping. LLM answer
  synthesis with extractive fallback.
• ReconstructiveMemory facade + ctx.reconstructiveMemory() lazy getter.

Wired through agent + types barrels and the package root. Tagged @experimental.
28 unit tests; typecheck, lint, and full build clean.

Co-Authored-By: Claude Opus 4.8 noreply@anthropic.com
Claude-Session: https://claude.ai/code/session_01GZSDcmAkuVaQgb9gUyqinW

[Copilot]

Pull request overview

This PR adds a new reconstructive memory subsystem (MRAgent-style) to MemoryJS, shifting from one-shot “retrieve-then-reason” toward a Cue–Tag–Content (CTC) associative graph plus an active multi-step reconstruction loop, and wires it into ManagerContext with optional live-store persistence.

Changes:

• Introduces new reconstructive memory types (src/types/reconstruction.ts) and re-exports them through existing type/agent barrels.
• Adds the reconstructive memory implementation (distillation, graph traversal toolkit, active reconstructor, live-store bridge, facade API).
• Adds unit tests covering graph operators, toolkit operators, reconstruction behavior, snapshot round-trips, and live-store bridging.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/agent/reconstruction/ReconstructiveMemory.test.ts	Tests heuristic + LLM-assisted reconstruction, step budgeting, snapshot round-trip, and extractJson.
tests/unit/agent/reconstruction/MemoryToolkit.test.ts	Tests the 7 typed traversal operators against a small fixture graph.
tests/unit/agent/reconstruction/MemoryGraphBridge.test.ts	Tests persistence into fake backing + end-to-end persistence via ManagerContext backing.
tests/unit/agent/reconstruction/CueTagContentGraph.test.ts	Tests core CTC graph operators (forward/reverse/topic traversal) and snapshot round-trip.
src/types/reconstruction.ts	Adds the public type model for CTC nodes/edges, distillation output, and reconstruction trajectory/result shapes.
src/types/index.ts	Re-exports reconstructive memory types from the main types barrel.
src/core/ManagerContext.ts	Adds ctx.reconstructiveMemory() lazy getter and a default backing that bridges to live managers/storage.
src/agent/reconstruction/ReconstructiveMemory.ts	Facade API for ingest + reconstruct, plus snapshot, stats, and toolkit accessors.
src/agent/reconstruction/MemoryToolkit.ts	Implements the seven traversal operators over the CTC graph.
src/agent/reconstruction/MemoryReconstructor.ts	Implements the active multi-step reconstruction loop (action selection → traversal → routing → stopping → answer).
src/agent/reconstruction/MemoryGraphBridge.ts	Persists episodic/semantic/topic layers into the live store and annotates graph nodes with backing entity names.
src/agent/reconstruction/MemoryDistiller.ts	Distills dialogue into episodes/cues/tags/personal facts/topics with optional LLM path and heuristic fallback.
src/agent/reconstruction/index.ts	Barrel export for the reconstruction module.
src/agent/index.ts	Re-exports reconstructive memory API from the main agent barrel.
CLAUDE.md	Updates project documentation to mention the reconstructive memory module and ctx.reconstructiveMemory().

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.