memo-grafter 0.2.2 → 0.2.3

package/README.md

@@ -1,73 +1,81 @@
-# MemoGrafter
-[![npm version](https://img.shields.io/npm/v/memo-grafter.svg)](https://www.npmjs.com/package/memo-grafter)
-
-Structured memory for TypeScript chatbots.
-
-MemoGrafter helps chatbot applications remember conversations without stuffing every old message back into the prompt. It turns conversation history into topic-based memory, recalls relevant details later, and can copy useful memory from one chatbot or session into another.
-
-It is a memory framework, not an autonomous agent runtime. It does not run tools, schedule work, or decide goals for an agent.
-
-## What It Is For
-
-- Chatbots that need long-running memory.
-- Assistants that should recall user preferences, prior context, and open questions.
-- Multi-chatbot or multi-session flows where selected memory can be grafted into another conversation.
-- TypeScript apps that need reusable memory, retrieval, and graph-backed conversation primitives.
-
-## How It Works
-
-```text
-chat messages
-  -> topic-based memory
-  -> graph links
-  -> relevant recall
-  -> optional memory grafting
-```
-
-MemoGrafter stores conversation turns, detects topic changes, summarizes useful context, links related memories, and retrieves or grafts memory when needed.
-
-## Install
-
-```bash
-npm install memo-grafter
-```
-
-MemoGrafter runs server-side on Node.js. The built-in storage backend uses PostgreSQL with `pgvector`.
-
-## Minimal Example
-
-```ts
-import "dotenv/config";
-
-import {
-  MemoGrafterAgent,
-  OpenAIEmbedAdapter,
-  OpenAILLMAdapter,
-} from "memo-grafter";
-
-const agent = new MemoGrafterAgent({
-  db: { connectionString: process.env.DATABASE_URL! },
-  llm: new OpenAILLMAdapter("gpt-4o"),
-  embedder: new OpenAIEmbedAdapter("text-embedding-3-small"),
-});
-
-await agent.initialize();
-
-await agent.invoke("I am planning a Japan trip.");
-await agent.invoke("I like quiet towns, bookstores, and local cafes.");
-
-const recall = await agent.recall("travel preferences");
-console.log(recall.facts);
-
-await agent.close();
-```
-
-## Learn More
-
-- [USER_GUIDE.md](https://github.com/mayhemking007/memo-grafter/blob/main/USER_GUIDE.md) covers setup, configuration, adapters, queue mode, fleet APIs, examples, and troubleshooting.
-- [ARCHITECTURE.md](https://github.com/mayhemking007/memo-grafter/blob/main/ARCHITECTURE.md) explains the current high-level implementation.
-- `examples` contains runnable demo.
-
-## License
-
-MIT
+# MemoGrafter
+[![npm version](https://img.shields.io/npm/v/memo-grafter.svg)](https://www.npmjs.com/package/memo-grafter)
+
+Structured memory for TypeScript chatbots.
+
+MemoGrafter helps chatbot applications remember conversations without stuffing every old message back into the prompt. It turns conversation history into topic-based memory, recalls relevant details later, and can copy useful memory from one chatbot or session into another.
+
+It is a memory framework, not an autonomous agent runtime. It does not run tools, schedule work, or decide goals for an agent.
+
+MemoGrafter builds the memory graph incrementally. New chatbot turns append topic and memory nodes to the existing graph instead of clearing and rebuilding the session on every response, so grafted and externally enriched memory can survive later conversation turns. Use `clearSession()` explicitly when you want to reset an agent's local history and stored session memory.
+
+## Playground
+
+- Try the [MemoGrafter Playground](https://mgplayground-green.vercel.app/).
+- View the playground demo repo at [mayhemking007/mg-demo](https://github.com/mayhemking007/mg-demo).
+
+## What It Is For
+
+- Chatbots that need long-running memory.
+- Assistants that should recall user preferences, prior context, and open questions.
+- Multi-chatbot or multi-session flows where selected memory can be grafted into another conversation.
+- TypeScript apps that need reusable memory, retrieval, and graph-backed conversation primitives.
+
+## How It Works
+
+```text
+chat messages
+  -> topic-based memory
+  -> graph links
+  -> relevant recall
+  -> optional memory grafting
+```
+
+MemoGrafter stores conversation turns, tracks which messages have already been ingested, detects topic changes for new turns with recent context, summarizes useful context, links related memories, and retrieves or grafts memory when needed.
+
+## Install
+
+```bash
+npm install memo-grafter
+```
+
+MemoGrafter runs server-side on Node.js. The built-in storage backend uses PostgreSQL with `pgvector`.
+
+## Minimal Example
+
+```ts
+import "dotenv/config";
+
+import {
+  MemoGrafterAgent,
+  OpenAIEmbedAdapter,
+  OpenAILLMAdapter,
+} from "memo-grafter";
+
+const agent = new MemoGrafterAgent({
+  db: { connectionString: process.env.DATABASE_URL! },
+  llm: new OpenAILLMAdapter("gpt-4o"),
+  embedder: new OpenAIEmbedAdapter("text-embedding-3-small"),
+});
+
+await agent.initialize();
+
+await agent.invoke("I am planning a Japan trip.");
+await agent.invoke("I like quiet towns, bookstores, and local cafes.");
+
+const recall = await agent.recall("travel preferences");
+console.log(recall.facts);
+
+await agent.close();
+```
+
+## Learn More
+
+- [USER_GUIDE.md](https://github.com/mayhemking007/memo-grafter/blob/main/USER_GUIDE.md) covers setup, configuration, adapters, queue mode, fleet APIs, examples, and troubleshooting.
+- [ARCHITECTURE.md](https://github.com/mayhemking007/memo-grafter/blob/main/ARCHITECTURE.md) explains the current high-level implementation.
+- `examples/basic-chat-memory` is the simplest runnable single-agent memory demo.
+- `examples/chatbot-memory-demo` shows the larger two-agent grafting workflow.
+
+## License
+
+MIT

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.
@@ -82,9 +84,11 @@ Current v1 tables:
 - `mg_topic_nodes`
 - `mg_topic_edges`
 - `mg_memory_nodes`
-- `mg_memory_edges`
-- `mg_fleets`
-- `mg_fleet_agents`
+- `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
 
@@ -208,13 +214,17 @@ Edges are stored in `mg_topic_edges`.
 
 ### 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 +261,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 +322,42 @@ 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.
+`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);
+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.capturedAt);
-```
-
-`getGraphSnapshot()` returns a `GraphSnapshot`:
-
+```
+
+`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.
 - `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:
+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.
 
-```ts
-const nodes = await agent.getActiveNodes();
+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();
 
 for (const node of nodes) {
   console.log({
@@ -419,6 +447,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 +540,8 @@ const agent = new MemoGrafterAgent({
     bufferSize: 4,
     tokenBudget: 1500,
     recentWindowSize: 20,
+    recallLimit: 6,
+    recallMinSimilarity: 0.55,
   },
   cache: {
     connectionString: process.env.REDIS_URL!,
@@ -511,14 +573,15 @@ 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"`.
+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.
+- `getGraftRegistry(sessionId)`: read graft provenance entries for a session.
 
 ### `llm`
 
@@ -607,7 +670,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 +693,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 +747,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 +834,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 +929,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 +1060,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 +1090,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.
@@ -1025,26 +1121,31 @@ 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)`
+- `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.
+- `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.
-- `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.
-- `close()`: close database and queue resources.
+- `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;IAiC1C,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"}