feat(agent): bridge CTC layers to live MemoryJS modules (MRAgent §3.2)#84
Merged
Merged
Conversation
…ctive reconstruction) 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
Wires the Cue–Tag–Content multi-granular layers to the existing memory
modules they correspond to, so reconstructed memory is durable and visible
to the rest of the stack rather than an in-memory island.
- MemoryGraphBridge persists each layer into its module:
* episodic → memoryType:'episodic' entities stamped with the conversation
timestamp (land on the EpisodicMemoryManager timeline, temporally linked
precedes/follows)
* semantic → memoryType:'semantic' fact entities anchored to their person
entity via a has_<aspect> relation, indexed for SemanticSearch
* topic → topic entities linked to constituent episodes via `summarizes`
Driven through the structural ReconstructiveBacking interface (real managers
or test fakes).
- MemoryReconstructor routing/answer reuse SemanticSearch.calculateSimilarity
when the backing provides it (embedding similarity captures paraphrase),
with lexical overlap as fallback.
- ReconstructiveMemory.ingest persists via the bridge when a backing is set;
exposes lastPersistResult. ctx.reconstructiveMemory() defaults the backing
to the context's entityManager/relationManager/semanticSearch (agent
entities appended via storage to bypass the plain-Entity schema, with
name-dedup); pass backing:undefined to opt out.
- ContentNode gains entityName, set when bridged.
5 new bridge/integration tests (incl. end-to-end via ManagerContext verifying
entities, relations, and timeline ordering). Full suite green; typecheck,
lint, build clean.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GZSDcmAkuVaQgb9gUyqinW
There was a problem hiding this comment.
Pull request overview
This PR introduces an experimental MRAgent-style “reconstructive memory” subsystem to MemoryJS: it distills dialogue into a Cue–Tag–Content (CTC) graph, performs active multi-step reconstruction over that graph, and (optionally) bridges the resulting episodic/semantic/topic layers into the existing live entity/relation/semantic-search modules via ManagerContext.
Changes:
- Adds reconstructive memory implementation (
MemoryDistiller,MemoryReconstructor,MemoryToolkit,MemoryGraphBridge,ReconstructiveMemory) and wires it intoManagerContext. - Exposes the new APIs/types through the agent and types barrels.
- Adds unit tests covering graph operators, toolkit traversal operators, reconstruction behavior, and live-store bridging.
Reviewed changes
Copilot reviewed 15 out of 16 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/unit/agent/reconstruction/ReconstructiveMemory.test.ts | Adds unit tests for heuristic distillation, active reconstruction, snapshot round-trip, and LLM-assisted answer synthesis. |
| tests/unit/agent/reconstruction/MemoryToolkit.test.ts | Adds unit tests for the 7 traversal operators over a fixture CTC graph. |
| tests/unit/agent/reconstruction/MemoryGraphBridge.test.ts | Adds tests for persisting CTC layers into a fake backing and end-to-end ManagerContext bridging into the real store. |
| tests/unit/agent/reconstruction/CueTagContentGraph.test.ts | Adds tests for key graph mapping operators, idempotency, timeline ordering, and snapshot round-trip. |
| src/types/reconstruction.ts | Introduces public types for CTC nodes/snapshots, distillation outputs, and reconstruction trajectory/result structures. |
| src/types/index.ts | Re-exports reconstructive memory types from the main types barrel (with a DistillationResult alias). |
| src/core/ManagerContext.ts | Adds ctx.reconstructiveMemory() and a default live-store backing that persists entities/relations and reuses SemanticSearch similarity/indexing. |
| src/agent/reconstruction/ReconstructiveMemory.ts | Adds the facade that composes distillation, graph build/merge, optional persistence bridge, and reconstruction. |
| src/agent/reconstruction/MemoryToolkit.ts | Adds typed traversal operator helpers over the CTC graph. |
| src/agent/reconstruction/MemoryReconstructor.ts | Adds the active multi-step reconstruction loop with heuristic routing and optional LLM answer synthesis. |
| src/agent/reconstruction/MemoryGraphBridge.ts | Adds persistence bridge mapping episodic/semantic/topic layers into MemoryJS’s live modules and relations. |
| src/agent/reconstruction/MemoryDistiller.ts | Adds LLM + heuristic distillation pipeline and graph construction routine. |
| src/agent/reconstruction/index.ts | Adds reconstruction module barrel exports. |
| src/agent/index.ts | Re-exports reconstructive memory APIs from the agent barrel. |
| CLAUDE.md | Documents the new reconstructive memory subsystem and ctx.reconstructiveMemory() in the repo guide. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+88
to
+91
| // Topic abstraction layer — create topic content nodes first so episodes can link. | ||
| for (const [topicId, description] of Object.entries(result.topics)) { | ||
| graph.addContent({ id: topicId, layer: 'topic', text: description }); | ||
| } |
Comment on lines
+1110
to
+1118
| createEntities: async entities => { | ||
| const graph = await this.storage.loadGraph(); | ||
| const existing = new Set(graph.entities.map(e => e.name)); | ||
| for (const entity of entities) { | ||
| if (existing.has(entity.name)) continue; | ||
| existing.add(entity.name); | ||
| await this.storage.appendEntity(entity); | ||
| } | ||
| }, |
Comment on lines
+100
to
+103
| // f_select — line 7. | ||
| const actions = this.selectActions(active); | ||
| if (actions.length === 0) break; | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Server Details
Motivation and Context
How Has This Been Tested?
Breaking Changes
Types of changes
Checklist
Additional context