memo-grafter 0.2.2 → 0.2.4

package/USER_GUIDE.md

@@ -8,6 +8,8 @@ The project is intentionally focused. MemoGrafter is a chatbot memory framework,
 
 The most important idea is memory grafting. A chatbot can build useful memory during one conversation, and another chatbot can absorb only the relevant parts.
 
+MemoGrafter ingests conversation memory incrementally. New turns append topic nodes, memory nodes, and graph edges to the existing session graph instead of clearing and rebuilding the graph on every response. This keeps grafted memory and future external graph enrichment durable across normal chatbot turns.
+
 ## Requirements
 
 - Node.js 18 or newer.
@@ -85,6 +87,8 @@ Current v1 tables:
 - `mg_memory_edges`
 - `mg_fleets`
 - `mg_fleet_agents`
+- `mg_session_ingest_state`
+- `mg_graft_registry`
 
 ## Quick Start
 
@@ -140,7 +144,9 @@ export interface Message {
 }
 ```
 
-`MemoGrafterAgent` keeps an in-memory user/assistant history for the current session and stores messages in PostgreSQL during ingestion. System messages can be added to LLM calls internally when memory recall is pinned into an overflowing context window.
+`MemoGrafterAgent` keeps an in-memory user/assistant history for the current session and stores messages in PostgreSQL during ingestion. When a session already has memory graph content, `invoke()` can add a system message with recalled facts before the LLM call.
+
+Ingestion tracks the last message index that has been processed for each session. Re-running ingestion with the same history is a no-op for graph creation, while later turns append new graph state.
 
 ### Segments
 
@@ -191,10 +197,13 @@ Important fields:
 - `confidence`: confidence score from `0` to `1`.
 - `topicNodeId`: parent topic node ID.
 - `decayed`: whether the memory is stale.
+- `hasConflict`: whether crawler maintenance found a conflicting active fact.
 - `supersededBy`: newer memory ID when this memory has been replaced.
 
 Memory nodes are stored in `mg_memory_nodes`.
 
+`decayed`, `hasConflict`, and `supersededBy` are maintenance fields. Normal ingestion creates active memories. Optional crawler passes can later annotate existing memory rows, but they do not delete rows or rewrite topic summaries.
+
 ### Graph Edges
 
 Edges connect related topic nodes. They can represent temporal, semantic, grafted, or reentry relationships.
@@ -206,15 +215,32 @@ Edges connect related topic nodes. They can represent temporal, semantic, grafte
 
 Edges are stored in `mg_topic_edges`.
 
+Memory edges are stored separately in `mg_memory_edges`. They can represent:
+
+- `semantic`: two memory facts are similar.
+- `conflicts`: two active memory facts disagree.
+- `updates`: a newer memory supersedes an older memory.
+- `related`: reserved for broader memory relationships.
+
+For version edges, MemoGrafter uses this direction:
+
+```text
+newer_memory --updates--> older_memory
+```
+
 ### Grafting
 
-Grafting is the process of selecting memory nodes and turning them into useful context for another prompt or another chatbot.
+Grafting is the process of selecting topic nodes and turning them into useful context for another prompt or another chatbot.
 
 There are two common forms:
 
 - Preview memory with `graft()`.
 - Copy memory into another chatbot with `absorbFromAgent()` or `ingestGraftedNodes()`.
 
+When topic nodes are absorbed into another session, MemoGrafter also copies their active memory nodes so targeted recall can find the transferred facts. Copied memory rows get fresh IDs, keep their existing embeddings, and are copied as active memories only when the source row is not decayed or superseded.
+
+Absorbed topic nodes are also registered in `mg_graft_registry`. The registry records the destination session, copied node ID, source session ID, source node ID, and graft timestamp so applications can inspect provenance or remove a graft later.
+
 ## Using MemoGrafterAgent
 
 `MemoGrafterAgent` is the easiest API to start with.
@@ -251,17 +277,31 @@ await agent.close();
 
 On every call, `invoke()`:
 
-1. Adds the user message to local history.
-2. Builds the message list for the LLM.
-3. If history is under the configured budget, sends the raw local history.
-4. If history crosses the overflow threshold, calls targeted recall using recent conversation context, prepends the recall result as one pinned system message, and keeps only the recent raw message window.
-5. Adds the assistant response to history.
-6. Queues ingestion of the updated conversation into the memory graph.
+1. Checks whether the current session has topic nodes in the memory graph.
+2. If graph content exists, calls targeted recall using the current user message.
+3. Prepends the recalled memory prompt as a system message when recall returns matching facts.
+4. Builds the LLM message list from the optional memory system message, the recent raw history window, and the current user message.
+5. Adds the user message and assistant response to local history after the LLM response.
+6. Queues ingestion of only the newly added conversation turns into the memory graph.
+
+Recall is skipped entirely when the session has no topic nodes yet. This avoids an unnecessary embed and vector search on the first turn or while async ingestion has not produced graph content.
 
-The overflow threshold is 80% of `inject.tokenBudget`. Recall failures are logged as warnings and fall back to the recent raw message window, so a retrieval or embedder problem should not crash the foreground chatbot turn.
+Recall failures are logged as warnings and fall back to raw history only, so a retrieval or embedder problem should not crash the foreground chatbot turn.
 
 On the first turn there may be no memory to recall. Later turns can use memory created from earlier turns once ingestion has completed.
 
+Normal ingestion does not call `clearSession()`. Existing topic nodes, grafted nodes, memory rows, and graph edges are preserved unless you explicitly clear the session.
+
+### Clearing A Session
+
+Use `clearSession()` when you intentionally want to reset an agent:
+
+```ts
+await agent.clearSession();
+```
+
+This waits for pending ingestion, clears the agent's local in-memory history, removes stored messages, topic nodes, memory nodes, graph edges, segments, and resets the session ingest cursor. It is a destructive operation and is not part of normal `invoke()` processing.
+
 ### Targeted Recall
 
 Use `recall()` when you want to retrieve structured memory by meaning without asking the LLM to produce an answer.
@@ -298,38 +338,46 @@ Options:
 
 `recall()` is side-effect free. It does not call `invoke()`, does not trigger a new LLM completion, and does not mutate local history. Your application can call it directly to display memories, add `result.systemPrompt` to a model call, or ignore the result.
 
-`MemoGrafterAgent.invoke()` also calls `recall()` internally when local history overflows the configured history budget. In that automatic path, the returned `systemPrompt` is pinned as a single system message before the recent raw chat window.
-
-If you call `recall()` immediately after `invoke()`, it only sees memory that has already been ingested into storage. In queue mode, wait for your background worker to finish before expecting newly created memories to appear.
-
-## Inspecting Memory
-
-Read a complete session graph snapshot:
-
-```ts
-const snapshot = await agent.getGraphSnapshot();
-
-console.log(snapshot.sessionId);
-console.log(snapshot.nodes);
-console.log(snapshot.edges);
-console.log(snapshot.memories);
-console.log(snapshot.capturedAt);
-```
-
-`getGraphSnapshot()` returns a `GraphSnapshot`:
-
-- `sessionId`: current agent session ID.
-- `nodes`: active topic nodes for the session.
-- `edges`: topic edges where either endpoint belongs to a session topic node.
-- `memories`: all memory nodes for the session, including decayed or superseded rows.
-- `capturedAt`: ISO timestamp for when the snapshot was produced.
-
-This method is read-only. It does not include raw `mg_message_buffer` content and does not add rendering, layout, or color decisions. Like `getActiveNodes()` and `getActiveSegments()`, it waits for the agent's pending ingest work before reading. If called immediately after `invoke()` in queue mode, it waits for the current ingest job to settle before returning.
-
-Read active topic nodes:
-
-```ts
-const nodes = await agent.getActiveNodes();
+`MemoGrafterAgent.invoke()` also calls `recall()` internally before answering when the session has topic nodes. In that automatic path, the returned `systemPrompt` is pinned as a single system message before the recent raw chat window. Automatic recall uses `inject.recallLimit` and `inject.recallMinSimilarity`, defaulting to `6` and `0.55`.
+
+If you call `recall()` immediately after `invoke()`, it only sees memory that has already been ingested into storage. In queue mode, wait for your background worker to finish before expecting newly created memories to appear.
+
+## Inspecting Memory
+
+Read a complete session graph snapshot:
+
+```ts
+const snapshot = await agent.getGraphSnapshot();
+
+console.log(snapshot.sessionId);
+console.log(snapshot.nodes);
+console.log(snapshot.snapshotNodes);
+console.log(snapshot.edges);
+console.log(snapshot.memories);
+console.log(snapshot.memoryEdges);
+console.log(snapshot.capturedAt);
+```
+
+`getGraphSnapshot()` returns a `GraphSnapshot`:
+
+- `sessionId`: current agent session ID.
+- `nodes`: active topic nodes for the session.
+- `snapshotNodes`: active topic nodes wrapped with provenance metadata when a node came from a graft.
+- `edges`: topic edges where either endpoint belongs to a session topic node.
+- `memories`: all memory nodes for the session, including decayed or superseded rows.
+- `memoryEdges`: memory-level edges such as `semantic`, `conflicts`, `updates`, and `related`.
+- `capturedAt`: ISO timestamp for when the snapshot was produced.
+
+Each `snapshotNodes` entry contains the topic `node` and an optional `graftOrigin` with `sourceSessionId`, `sourceNodeId`, and `graftedAt`. The plain `nodes` array remains available for callers that only need the topic nodes.
+
+This method is read-only. It does not include raw `mg_message_buffer` content and does not add rendering, layout, or color decisions. Like `getActiveNodes()` and `getActiveSegments()`, it waits for the agent's pending ingest work before reading. If called immediately after `invoke()` in queue mode, it waits for the current ingest job to settle before returning.
+
+Graph snapshots intentionally include stale and maintenance metadata so visualizers can show memory lifecycle state. For example, a UI can fade `decayed` memories, show `hasConflict` badges, draw `conflicts` edges between contradictory facts, and draw `updates` edges from the current fact to the older fact it replaced.
+
+Read active topic nodes:
+
+```ts
+const nodes = await agent.getActiveNodes();
 
 for (const node of nodes) {
   console.log({
@@ -389,6 +437,112 @@ const graft = await agent.graft([nodes[0]!.id]);
 - `nodes`: selected topic nodes.
 - `tokenCount`: estimated token count.
 
+Graft prompts include topic summaries because they preserve useful conversation context. Topic summaries are historical: if an older topic summary says "the user lives in Delhi" and a later memory says "the user lives in Bangalore", MemoGrafter does not rewrite the old summary. Instead, when crawler maintenance has marked a contradiction or supersession, graft prompt assembly adds deterministic maintenance notes and active memory facts:
+
+```text
+Memory maintenance notes:
+- The fact "user location: Delhi" was superseded by "Bangalore".
+- Prefer active memory facts over contradictory historical summary details.
+Active memory facts:
+- user location: Bangalore
+```
+
+This keeps history intact while telling the downstream model which fact is current.
+
+## Maintaining Memory With The Crawler
+
+`MemoGrafterCrawler` is an optional graph maintenance worker. It can run once on demand or on a simple in-process interval. It does not use Redis, BullMQ, OpenAI, embeddings, or LLMs for the built-in conflict/versioning/decay passes.
+
+Typical usage with the real store:
+
+```ts
+import {
+  ConflictDetectionPass,
+  DecayScoringPass,
+  MemoGrafter,
+  MemoGrafterCrawler,
+  VersioningPass,
+} from "memo-grafter";
+
+const memo = new MemoGrafter(config);
+await memo.initialize();
+
+const crawler = new MemoGrafterCrawler({
+  store: memo.store,
+  intervalMs: 60_000,
+  passes: [
+    new ConflictDetectionPass(),
+    new VersioningPass(),
+    new DecayScoringPass({
+      halfLifeDays: 90,
+      minScore: 0.25,
+    }),
+  ],
+});
+
+const report = await crawler.runOnce();
+console.log(report);
+```
+
+`runOnce()` executes the configured passes exactly one time and returns a `CrawlerReport`. `intervalMs` does not affect `runOnce()`.
+
+To run the crawler in-process on a schedule:
+
+```ts
+crawler.start();
+
+// Later, during shutdown:
+crawler.stop();
+await memo.close();
+```
+
+`start()` is safe to call more than once; it does not create duplicate intervals. If a scheduled tick fires while the previous run is still executing, that tick is skipped.
+
+The built-in conflict/versioning passes use deterministic matching:
+
+- they group active memories by session, normalized `subject`, and normalized `predicate`;
+- a group conflicts when it has different normalized `value` strings;
+- decayed memories are skipped;
+- already superseded memories are skipped;
+- the newest conflicting fact wins by `createdAt`;
+- if timestamps tie, deterministic ID ordering is used.
+
+`DecayScoringPass` uses confidence-weighted exponential recency decay:
+
+```text
+recency_factor = exp(-(ln(2) / half_life_days) * age_days)
+decay_score = confidence * recency_factor
+```
+
+If `decay_score < minScore`, the memory is marked `decayed: true`. Superseded memories and already decayed memories are skipped. Conservative defaults are used when options are omitted:
+
+```ts
+new DecayScoringPass({
+  halfLifeDays: 90,
+  minScore: 0.25,
+});
+```
+
+By default the pass does not change stored `confidence`; confidence is treated as extraction confidence, while decay score is temporal freshness. If you explicitly want the score written back as confidence, pass `updateConfidence: true`.
+
+When conflicts are found:
+
+- both active facts get `hasConflict: true`;
+- a `conflicts` memory edge is created;
+- the older fact gets `supersededBy` pointing to the newer fact;
+- an `updates` edge is created as `newer_memory --updates--> older_memory`.
+- stale active memories can be marked `decayed: true` by the decay pass.
+
+Crawler maintenance is non-destructive. It annotates existing memory rows and creates memory edges. It does not delete nodes, does not rebuild topics, and does not rewrite topic summaries.
+
+Do not put crawler behavior inside `clearSession()`. `clearSession()` is a destructive reset. The crawler is a non-destructive maintenance worker. If you intentionally rebuild a session graph, use this order:
+
+```ts
+await agent.clearSession();
+await memo.ingestNow(messages, sessionId);
+await crawler.runOnce();
+```
+
 ## Absorbing Memory Into Another Chatbot
 
 Use `absorbFromAgent()` to copy selected memory from one chatbot into another.
@@ -419,6 +573,38 @@ const response = await writingBot.invoke(
 console.log(response);
 ```
 
+Absorbing copies selected topic nodes into the target session and creates `grafted` edges back to their source nodes. It also copies active memory facts attached to those topic nodes into the target session so future `recall()` and `invoke()` calls can surface the transferred context. Decayed or superseded source memories are not copied.
+
+Each copied topic node is recorded in the graft registry. Registry entries let you answer where a graft came from and which copied destination node owns it.
+
+Known limitation: if a source topic node has no associated memory rows in `mg_memory_nodes`, there are no facts to copy. The topic node can still be grafted, but targeted recall will not return facts for that node unless memory extraction produced them.
+
+### Inspect Graft Registry
+
+```ts
+const registry = await writingBot.getGraftRegistry();
+
+for (const entry of registry) {
+  console.log({
+    nodeId: entry.nodeId,
+    sourceSessionId: entry.sourceSessionId,
+    sourceNodeId: entry.sourceNodeId,
+    graftedAt: entry.graftedAt,
+  });
+}
+```
+
+Use this when your app needs to display transferred memory provenance or decide which graft to remove.
+
+### Remove A Graft
+
+```ts
+const registry = await writingBot.getGraftRegistry();
+await writingBot.removeGraft(registry[0]!.nodeId);
+```
+
+`removeGraft()` removes the copied graft node from the current session. The registry row is removed with it. The method is scoped to the current agent session and throws if the node is not a registered graft for that session.
+
 ### Absorb By Semantic Prompt
 
 ```ts
@@ -480,6 +666,8 @@ const agent = new MemoGrafterAgent({
     bufferSize: 4,
     tokenBudget: 1500,
     recentWindowSize: 20,
+    recallLimit: 6,
+    recallMinSimilarity: 0.55,
   },
   cache: {
     connectionString: process.env.REDIS_URL!,
@@ -511,14 +699,16 @@ const store: GraphStore = new PostgresGraphStore(process.env.DATABASE_URL!);
 
 `GraphStore` is the public storage interface. `PostgresGraphStore` is the default PostgreSQL and pgvector implementation.
 
-Useful store inspection methods include:
-
-- `getNodesBySession(sessionId)`: read topic nodes for a session.
-- `getTopicNode(topicNodeId, sessionId?)`: read one topic node by ID.
-- `getSegmentsBySession(sessionId)`: read topic segments for a session.
-- `getEdgesByType(sessionId, type)`: inspect graph edges such as `"reentry"`, `"semantic"`, `"temporal"`, or `"grafted"`.
-- `getEdgesBySession(sessionId)`: read all topic edges where either endpoint belongs to the session's topic nodes.
-- `getMemoriesBySession(sessionId)`: read all memory nodes for a session, including decayed and superseded rows.
+Useful store inspection methods include:
+
+- `getNodesBySession(sessionId)`: read topic nodes for a session.
+- `getTopicNode(topicNodeId, sessionId?)`: read one topic node by ID.
+- `getSegmentsBySession(sessionId)`: read topic segments for a session.
+- `getEdgesByType(sessionId, type)`: inspect graph edges such as `"reentry"`, `"semantic"`, `"temporal"`, or `"grafted"`.
+- `getEdgesBySession(sessionId)`: read all topic edges where either endpoint belongs to the session's topic nodes.
+- `getMemoriesBySession(sessionId)`: read all memory nodes for a session, including decayed and superseded rows.
+- `getMemoryEdgesBySession(sessionId)`: read memory-level edges such as `conflicts` and `updates`.
+- `getGraftRegistry(sessionId)`: read graft provenance entries for a session.
 
 ### `llm`
 
@@ -607,7 +797,7 @@ Without reentry detection, the later database discussion is just another topic n
 
 This helps graph traversal and memory injection recover earlier related context. A later question about connection pooling can still be connected to the original PostgreSQL/ACID discussion.
 
-Reentry edges are written between the current rebuilt topic nodes. They do not point at deleted nodes from previous ingestion passes.
+Reentry edges are written between newly ingested topic nodes, and can also point from a new node back to an existing durable topic node when the detector recognizes a return to earlier context.
 
 ### `graph`
 
@@ -630,16 +820,20 @@ inject: {
   bufferSize: 4,
   tokenBudget: 1500,
   recentWindowSize: 20,
+  recallLimit: 6,
+  recallMinSimilarity: 0.55,
 }
 ```
 
-Controls memory prompt sizing and the raw history window kept when chat history overflows.
+Controls memory prompt sizing, invoke-time recall, and the raw history window sent to the LLM.
 
 - `bufferSize`: nearby raw messages to include.
-- `tokenBudget`: approximate token budget used for memory prompts and agent history overflow checks. `MemoGrafterAgent` starts overflow handling at 80% of this value.
-- `recentWindowSize`: number of newest raw chat messages to keep after the pinned recall block during overflow. Defaults to `20`.
+- `tokenBudget`: approximate token budget used for graft prompt assembly.
+- `recentWindowSize`: number of newest raw chat messages to send after the optional invoke-time memory system message. Defaults to `20`.
+- `recallLimit`: max memory facts to fetch for automatic invoke-time recall. Defaults to `6`.
+- `recallMinSimilarity`: similarity floor for automatic invoke-time recall. Defaults to `0.55`.
 
-When `MemoGrafterAgent` detects overflow, it builds a recall query from the last six message contents, calls recall with `{ limit: 5, minSimilarity: 0.65 }`, prepends the returned memory prompt as a system message, and keeps the last `recentWindowSize` raw messages. If recall fails, it uses only that recent raw window.
+When `MemoGrafterAgent.invoke()` sees existing topic nodes for the session, it calls recall with the current user message, prepends the returned memory prompt as a system message when facts are found, and keeps the last `recentWindowSize` raw messages. If recall fails or returns no facts, it uses only that recent raw window plus the current user message.
 
 ### `cache`
 
@@ -680,6 +874,8 @@ const agent = new MemoGrafterAgent({
 
 Queue mode is useful when ingestion becomes too slow to run inline. Redis connection problems are logged as warnings and should not throw from normal chatbot invocation.
 
+Whether ingestion runs inline or through the queue, MemoGrafter uses the stored ingest cursor to skip message ranges that have already been processed. Queue retries should therefore avoid creating duplicate topic nodes for the same message range.
+
 ## Custom Adapters
 
 You can use any model provider if you implement the public adapter interfaces.
@@ -765,7 +961,7 @@ Breaking changes to pipeline internals may occur in minor versions.
 
 Available pipeline exports:
 
-- `IngestPipeline`: segments messages, builds topic nodes, extracts memory nodes, and writes graph edges.
+- `IngestPipeline`: incrementally segments new messages, builds topic nodes, extracts memory nodes, and writes graph edges.
 - `RetrieverPipeline`: embeds a query, searches memory nodes, and returns a structured `RetrievalResult`.
 - `GrafterPipeline`: traverses the topic graph and assembles a token-budget-fitted system prompt.
 
@@ -860,15 +1056,29 @@ await conductor.graftByPrompt("invoice credit policy", technical, {
 });
 ```
 
-## Example Project
+## Example Projects
 
-This repository includes a runnable example:
+This repository includes two runnable examples:
 
 ```text
+examples/basic-chat-memory
 examples/chatbot-memory-demo
 ```
 
-Run it:
+Run the single-agent memory demo:
+
+```bash
+cd D:/cohort/projects/project-memoGrafter
+npm install
+npm run build
+
+cd examples/basic-chat-memory
+npm install
+cp .env.example .env
+npm run dev
+```
+
+Run the two-agent grafting demo:
 
 ```bash
 cd D:/cohort/projects/project-memoGrafter
@@ -977,6 +1187,18 @@ const result = await agent.recall("Japan travel preferences", {
 });
 ```
 
+For grafted sessions, also confirm that the source topic had active memory nodes before it was absorbed. Absorbing copies active memory rows, but it cannot create facts for a topic if extraction produced only a topic summary and no `mg_memory_nodes` rows.
+
+### Duplicate Or Unexpected Topic Nodes
+
+MemoGrafter processes only messages after the stored ingest cursor. If you see duplicate topic ranges:
+
+- Confirm your database has the `mg_session_ingest_state` table.
+- Confirm the same session ID is being reused for the same agent.
+- Check whether `clearSession()` was called, which resets the cursor and removes stored session data.
+
+Incremental ingest can still create semantically similar topic nodes over time. That is expected; node merge and graph compaction are separate maintenance features.
+
 ### Redis Warnings
 
 Redis is only required when you pass `queue` or `cache` config. If you do not need background ingestion or recall caching, remove those sections.
@@ -995,7 +1217,8 @@ Practical notes:
 - Use PostgreSQL with `pgvector` enabled.
 - Tune `tokenBudget` to control prompt size and cost.
 - Use queue mode if ingestion becomes slow.
-- Use the optional recall cache for long sessions with repeated or automatic overflow recall.
+- Use `clearSession()` only for intentional resets; normal ingestion preserves the graph incrementally.
+- Use the optional recall cache for long sessions with repeated direct or invoke-time recall.
 - Store your own user/session mapping outside MemoGrafter.
 - Call `close()` during graceful shutdown.
 - Do not expose database credentials or OpenAI keys to browser code.
@@ -1016,6 +1239,10 @@ Main exports:
 - `OpenAILLMAdapter`
 - `OpenAIEmbedAdapter`
 - `PostgresGraphStore`
+- `MemoGrafterCrawler`
+- `ConflictDetectionPass`
+- `DecayScoringPass`
+- `VersioningPass`
 - `GrafterPipeline`
 - `IngestPipeline`
 - `RetrieverPipeline`
@@ -1025,26 +1252,32 @@ Main exports:
 - `RetrieverConfig`
 - public shared and fleet types
 
-Useful `GraphStore` inspection methods:
-
-- `getTopicNode(topicNodeId, sessionId?)`
-- `getNodesBySession(sessionId)`
-- `getSegmentsBySession(sessionId)`
-- `getEdgesByType(sessionId, type)`
-- `getEdgesBySession(sessionId)`
-- `getMemoriesBySession(sessionId)`
-
-Common `MemoGrafterAgent` methods:
+Useful `GraphStore` inspection methods:
+
+- `getTopicNode(topicNodeId, sessionId?)`
+- `getNodesBySession(sessionId)`
+- `getSegmentsBySession(sessionId)`
+- `getEdgesByType(sessionId, type)`
+- `getEdgesBySession(sessionId)`
+- `getMemoriesBySession(sessionId)`
+- `getMemoryEdgesBySession(sessionId)`
+- `getSessionNodeCount(sessionId)`
+- `getSessionIngestState(sessionId)`
+
+Common `MemoGrafterAgent` methods:
 
 - `initialize()`: initialize storage.
 - `invoke(message)`: send a user message and receive an assistant response.
 - `getHistory()`: read local chat history.
-- `getSessionId()`: read the current session ID.
-- `getGraphSnapshot()`: read nodes, edges, memories, session ID, and capture timestamp for visualization or inspection.
-- `getActiveNodes()`: inspect topic nodes.
-- `getActiveSegments()`: inspect topic segments.
+- `getSessionId()`: read the current session ID.
+- `getGraphSnapshot()`: read nodes, edges, memories, session ID, and capture timestamp for visualization or inspection.
+- `getGraftRegistry()`: inspect provenance for grafted nodes in the current session.
+- `getActiveNodes()`: inspect topic nodes.
+- `getActiveSegments()`: inspect topic segments.
+- `clearSession()`: explicitly clear local history and stored session memory.
 - `recall(query, options?)`: retrieve structured memory by semantic query.
 - `graft(topicIds?)`: preview memory injection.
 - `ingestGraftedNodes(nodes)`: copy provided nodes into this agent.
 - `absorbFromAgent(sourceAgent, options)`: select and copy memory from another agent.
+- `removeGraft(nodeId)`: remove a registered graft node from the current session.
 - `close()`: close database and queue resources.

package/dist/MemoGrafterAgent.d.ts

@@ -1,11 +1,12 @@
-import type { AbsorbFromAgentOptions, GraphSnapshot, InjectionResult, MemoGrafterConfig, Message, RetrievalResult, RetrieverConfig, TopicNode, TopicSegment } from "./types.js";
+import type { AbsorbFromAgentOptions, GraftRegistryEntry, GraphSnapshot, InjectionResult, MemoGrafterConfig, Message, RetrievalResult, RetrieverConfig, TopicNode, TopicSegment } from "./types.js";
 export declare class MemoGrafterAgent {
     private readonly core;
     private readonly sessionId;
     private readonly history;
     private readonly baseSystemPrompt;
-    private readonly historyTokenBudget;
     private readonly recentWindowSize;
+    private readonly recallLimit;
+    private readonly recallMinSimilarity;
     private readonly cacheConfig;
     private pendingIngest;
     constructor(config: MemoGrafterConfig);
@@ -16,12 +17,15 @@ export declare class MemoGrafterAgent {
     getActiveNodes(): Promise<TopicNode[]>;
     getActiveSegments(): Promise<TopicSegment[]>;
     getGraphSnapshot(): Promise<GraphSnapshot>;
+    getGraftRegistry(): Promise<GraftRegistryEntry[]>;
+    removeGraft(nodeId: string): Promise<void>;
+    clearSession(): Promise<void>;
     graft(topicIds?: string[]): Promise<InjectionResult>;
     ingestGraftedNodes(nodes: TopicNode[]): Promise<TopicNode[]>;
     recall(query: string, options?: RetrieverConfig): Promise<RetrievalResult>;
     absorbFromAgent(sourceAgent: MemoGrafterAgent, options?: AbsorbFromAgentOptions): Promise<TopicNode[]>;
     private enqueueBackgroundIngest;
-    private buildHistory;
+    private _buildMemoryContext;
     close(): Promise<void>;
 }
 //# sourceMappingURL=MemoGrafterAgent.d.ts.map

package/dist/MemoGrafterAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoGrafterAgent.d.ts","sourceRoot":"","sources":["../src/MemoGrafterAgent.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,sBAAsB,EACtB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,eAAe,EACf,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,aAAa,CAAoC;gBAE7C,MAAM,EAAE,iBAAiB;IAQrC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYlD,UAAU,IAAI,OAAO,EAAE;IAIvB,YAAY,IAAI,MAAM;IAIhB,cAAc,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAMtC,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAM5C,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC;IAe1C,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAO1D,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAItD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkB9E,eAAe,CAAC,WAAW,EAAE,gBAAgB,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAKhH,OAAO,CAAC,uBAAuB;YAUjB,YAAY;IA4B1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}
+{"version":3,"file":"MemoGrafterAgent.d.ts","sourceRoot":"","sources":["../src/MemoGrafterAgent.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EACV,sBAAsB,EACtB,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,OAAO,EACP,eAAe,EACf,eAAe,EACf,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAc;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgB;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA6B;IACzD,OAAO,CAAC,aAAa,CAAoC;gBAE7C,MAAM,EAAE,iBAAiB;IASrC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIrB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAoBlD,UAAU,IAAI,OAAO,EAAE;IAIvB,YAAY,IAAI,MAAM;IAIhB,cAAc,IAAI,OAAO,CAAC,SAAS,EAAE,CAAC;IAMtC,iBAAiB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;IAM5C,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC;IAmC1C,gBAAgB,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAKjD,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1C,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B,KAAK,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAO1D,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAItD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,eAAoB,GAAG,OAAO,CAAC,eAAe,CAAC;IAkB9E,eAAe,CAAC,WAAW,EAAE,gBAAgB,EAAE,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAKhH,OAAO,CAAC,uBAAuB;YAUjB,mBAAmB;IAsBjC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}