memo-grafter 0.2.3 → 0.2.5

package/USER_GUIDE.md

@@ -84,11 +84,13 @@ Current v1 tables:
 - `mg_topic_nodes`
 - `mg_topic_edges`
 - `mg_memory_nodes`
-- `mg_memory_edges`
-- `mg_fleets`
-- `mg_fleet_agents`
-- `mg_session_ingest_state`
-- `mg_graft_registry`
+- `mg_memory_edges`
+- `mg_fleets`
+- `mg_fleet_agents`
+- `mg_session_ingest_state`
+- `mg_graft_registry`
+
+`mg_topic_nodes` and `mg_memory_nodes` include optional `tags TEXT[]` columns. Tags default to an empty array, so existing untagged sessions continue to work normally.
 
 ## Quick Start
 
@@ -179,6 +181,7 @@ Important fields:
 - `label`: short label.
 - `summary`: structured summary of the segment.
 - `embedding`: vector used for semantic search.
+- `tags`: optional normalized tags such as `"project:memo-grafter"` or `"planning"`.
 - `messageRange`: source message range.
 - `topicOrder`: chronological order.
 - `driftScore`: topic-change score.
@@ -196,11 +199,15 @@ Important fields:
 - `subject`, `predicate`, `value`: the structured memory triple.
 - `confidence`: confidence score from `0` to `1`.
 - `topicNodeId`: parent topic node ID.
+- `tags`: optional normalized tags copied from the session or ingest call.
 - `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.
@@ -212,6 +219,19 @@ 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 topic nodes and turning them into useful context for another prompt or another chatbot.
@@ -221,9 +241,9 @@ 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.
+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
 
@@ -286,6 +306,32 @@ 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.
 
+### Session Tags
+
+Use session tags when you want to organize memory by project, planning area, week, domain, or worker route.
+
+```ts
+await agent.setSessionTags([
+  "project:memo-grafter",
+  "planning",
+  "week:2026-05-25",
+]);
+
+console.log(agent.getSessionTags());
+```
+
+Tags are optional. They are normalized by trimming whitespace, lowercasing, deduplicating, and sorting. Calling `setSessionTags()` waits for pending ingestion, updates existing topic and memory rows for the current session, and applies the same tags to future memories created by `invoke()`.
+
+You can also tag direct ingestion:
+
+```ts
+await memo.ingest(messages, sessionId, {
+  tags: ["project:memo-grafter", "planning"],
+});
+```
+
+Tags do not replace `sessionId`. By default, MemoGrafter still reads from the current session. Tag filters are opt-in.
+
 ### Targeted Recall
 
 Use `recall()` when you want to retrieve structured memory by meaning without asking the LLM to produce an answer.
@@ -295,6 +341,13 @@ const result = await agent.recall("deployment config", {
   limit: 8,
   minSimilarity: 0.55,
   tokenBudget: 1000,
+  tags: ["project:memo-grafter"],
+  tagMode: "all",
+  scope: "session-and-tags",
+  scoring: {
+    similarityWeight: 0.7,
+    confidenceWeight: 0.3,
+  },
   cache: {
     ttlSeconds: 90,
   },
@@ -318,9 +371,26 @@ Options:
 - `limit`: max memory nodes to fetch before filtering. Defaults to `10`.
 - `minSimilarity`: cosine similarity floor. Defaults to `0.6`.
 - `tokenBudget`: max approximate tokens for included fact blocks. Defaults to `1200`.
+- `tags`: optional normalized tag filter.
+- `tagMode`: `"all"` requires every requested tag, `"any"` accepts at least one requested tag. Defaults to `"all"`.
+- `scope`: `"session"` keeps normal current-session recall, `"session-and-tags"` filters current-session recall by tags, and `"tagged"` searches across sessions matching the tags.
+- `scoring.similarityWeight`: weight applied to semantic similarity when ranking retrieved facts. Defaults to `0.7`.
+- `scoring.confidenceWeight`: weight applied to memory confidence when ranking retrieved facts. Defaults to `0.3`.
 - `cache.ttlSeconds`: per-call recall cache TTL override when `MemoGrafterConfig.cache` is enabled. Values are clamped to 60-120 seconds.
 
-`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.
+`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. Retrieval still uses `minSimilarity` for the vector search floor, then ranks returned active facts with `similarity * similarityWeight + confidence * confidenceWeight`.
+
+Cross-session tagged recall is explicit:
+
+```ts
+const projectMemory = await agent.recall("deployment decisions", {
+  tags: ["project:memo-grafter"],
+  scope: "tagged",
+  minSimilarity: 0.3,
+});
+```
+
+This can return matching active memories from older or different sessions with the same tag. If your development database contains repeated smoke-test runs, you may see more than one matching fact because the older tagged rows are still present.
 
 `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`.
 
@@ -334,25 +404,29 @@ Read a complete session graph snapshot:
 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);
+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.
-- `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.
+- `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:
 
@@ -371,6 +445,15 @@ for (const node of nodes) {
 }
 ```
 
+Filter active topic nodes by tag:
+
+```ts
+const planningNodes = await agent.getActiveNodes({
+  tags: ["planning"],
+  tagMode: "all",
+});
+```
+
 Read active segments:
 
 ```ts
@@ -417,6 +500,117 @@ 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;
+- broad topic memories with generic subject/predicate pairs are skipped unless they match a recognized competing trip-plan pattern;
+- the newest conflicting fact wins by `createdAt`;
+- if timestamps tie, deterministic ID ordering is used.
+
+Conflict detection is meant for mutually exclusive fact slots such as `user location Delhi` versus `user location Bangalore`. For generic "things discussed" memories, MemoGrafter only recognizes a narrow travel destination plan pattern by default. That means `Goa trip plan` and `Vietnam trip plan` can conflict, while `how to cook rajma chawal`, `food in Vietnam`, and `places to visit Vietnam` do not all conflict just because extraction used a generic subject and predicate.
+
+`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.
+
+Existing incorrect conflict edges are not automatically deleted. If an older crawler run created a false-positive edge, handle cleanup with a future explicit pruning pass or filter displayed memory edges to active memories in your app.
+
+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.
@@ -447,37 +641,37 @@ 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.
+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
 
@@ -527,6 +721,9 @@ const agent = new MemoGrafterAgent({
     mode: "intent",
     windowSize: 5,
     driftSensitivity: "medium",
+    adaptiveSensitivity: {
+      enabled: false,
+    },
     minSegmentMessages: 3,
     llmAmbiguityDetection: false,
     reentryDetection: true,
@@ -575,13 +772,15 @@ const store: GraphStore = new PostgresGraphStore(process.env.DATABASE_URL!);
 
 Useful store inspection methods include:
 
-- `getNodesBySession(sessionId)`: read topic nodes for a session.
+- `getNodesBySession(sessionId, options?)`: read topic nodes for a session, optionally filtered by tags.
 - `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.
+- `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.
+- `setSessionTags(sessionId, tags)`: replace the normalized tag set on existing topic and memory rows for a session.
 
 ### `llm`
 
@@ -628,6 +827,9 @@ drift: {
   mode: "intent",
   windowSize: 5,
   driftSensitivity: "medium",
+  adaptiveSensitivity: {
+    enabled: false,
+  },
   minSegmentMessages: 3,
   llmAmbiguityDetection: false,
   reentryDetection: true,
@@ -640,6 +842,7 @@ Controls topic boundary detection.
 - `mode`: `"intent"` or `"window"`.
 - `windowSize`: message window size for window mode.
 - `driftSensitivity`: preferred sensitivity preset, one of `"low"`, `"medium"`, or `"high"`.
+- `adaptiveSensitivity`: optional session-history based threshold tuning. Disabled by default.
 - `threshold`: deprecated numeric threshold. It still works when `driftSensitivity` is not set, but MemoGrafter logs a one-time warning.
 - `minSegmentMessages`: minimum messages before a boundary.
 - `llmAmbiguityDetection`: optional LLM check for borderline topic shifts. Defaults to `false`.
@@ -658,6 +861,30 @@ Use `"medium"` first. Boundaries are cut when a drift score exceeds the resolved
 
 If both `driftSensitivity` and `threshold` are provided, `driftSensitivity` wins.
 
+#### Adaptive Sensitivity
+
+Adaptive sensitivity is opt-in and keeps the configured `driftSensitivity` as its baseline. When enabled, MemoGrafter looks at recent saved segments for the session and nudges the resolved threshold by a small bounded step:
+
+```ts
+drift: {
+  mode: "intent",
+  driftSensitivity: "medium",
+  adaptiveSensitivity: {
+    enabled: true,
+    minSegments: 4,
+    lookbackSegments: 8,
+    targetSegmentMessages: {
+      min: 3,
+      max: 8,
+    },
+    adjustmentStep: 0.05,
+    maxAdjustment: 0.1,
+  },
+}
+```
+
+If recent segments are consistently short, MemoGrafter raises the threshold slightly to reduce fragmentation. If recent segments are consistently long, it lowers the threshold slightly to split more readily. It does not adapt until enough segment history exists, and it skips adjustment when recent segment lengths are too erratic.
+
 #### Reentry Detection
 
 Reentry detection handles conversations that leave a topic and later return to it:
@@ -724,6 +951,20 @@ Enables an opt-in Redis cache for targeted recall. MemoGrafter creates one share
 
 Recall cache keys include the session ID, `limit`, `minSimilarity`, and a deterministic hash of the query embedding. Redis failures are logged as warnings and recall falls back to PostgreSQL search. The cache is disabled unless this section is present.
 
+When tag-aware recall is used, cache keys also include recall `scope`, `tagMode`, and the normalized tag list. This prevents untagged, session-filtered, and cross-session tagged recall from sharing cached search results.
+
+## Manual Smoke Tests
+
+From this repository, run the session-tagging smoke with a real PostgreSQL database:
+
+```powershell
+npx tsx --env-file=.env ./tests/manual/graft/session-tags-smoke.ts
+```
+
+Use the forward-slash path in PowerShell. An unquoted backslash path can be collapsed before `tsx` receives it.
+
+The smoke creates two tagged sessions, writes one memory into each, verifies current-session tag filtering with `getActiveNodes()`, and verifies cross-session project recall with `recall(..., { scope: "tagged" })`. If you run it repeatedly against the same database, tagged recall can return rows from previous smoke runs because those historical sessions are still present.
+
 ## Queue Mode
 
 Without queue config, ingestion runs synchronously after `invoke()`.
@@ -856,6 +1097,10 @@ const retriever = new RetrieverPipeline(store, embedder, {
   limit: 8,
   minSimilarity: 0.55,
   tokenBudget: 1000,
+  scoring: {
+    similarityWeight: 0.7,
+    confidenceWeight: 0.3,
+  },
 });
 
 const result = await retriever.run(
@@ -1112,6 +1357,10 @@ Main exports:
 - `OpenAILLMAdapter`
 - `OpenAIEmbedAdapter`
 - `PostgresGraphStore`
+- `MemoGrafterCrawler`
+- `ConflictDetectionPass`
+- `DecayScoringPass`
+- `VersioningPass`
 - `GrafterPipeline`
 - `IngestPipeline`
 - `RetrieverPipeline`
@@ -1119,16 +1368,19 @@ Main exports:
 - `FleetAgentRecord`
 - `RetrievalResult`
 - `RetrieverConfig`
+- `TagFilterOptions`
+- `IngestOptions`
 - public shared and fleet types
 
 Useful `GraphStore` inspection methods:
 
 - `getTopicNode(topicNodeId, sessionId?)`
-- `getNodesBySession(sessionId)`
+- `getNodesBySession(sessionId, options?)`
 - `getSegmentsBySession(sessionId)`
 - `getEdgesByType(sessionId, type)`
 - `getEdgesBySession(sessionId)`
 - `getMemoriesBySession(sessionId)`
+- `getMemoryEdgesBySession(sessionId)`
 - `getSessionNodeCount(sessionId)`
 - `getSessionIngestState(sessionId)`
 
@@ -1138,14 +1390,16 @@ Common `MemoGrafterAgent` methods:
 - `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.
-- `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.
+- `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(options?)`: inspect topic nodes, optionally filtered by tags.
+- `getActiveSegments()`: inspect topic segments.
+- `setSessionTags(tags)`: replace tags on the current session and apply them to future ingested memories.
+- `getSessionTags()`: read the current agent's normalized session tags.
+- `clearSession()`: explicitly clear local history and stored session memory.
+- `recall(query, options?)`: retrieve structured memory by semantic query, optionally filtered by tags.
+- `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/MemoGrafter.d.ts

@@ -2,7 +2,7 @@ import { Redis } from "ioredis";
 import { MemoGrafterFleet } from "./fleet/MemoGrafterFleet.js";
 import type { MemoGrafterFleetOptions } from "./fleet/types.js";
 import type { GraphStore } from "./store/index.js";
-import type { AbsorbFromAgentOptions, EmbedAdapter, InjectionResult, LLMAdapter, MemoGrafterConfig, Message, TopicNode, TopicSegment } from "./types.js";
+import type { AbsorbFromAgentOptions, EmbedAdapter, IngestOptions, InjectionResult, LLMAdapter, MemoGrafterConfig, Message, TopicNode, TopicSegment } from "./types.js";
 export declare class MemoGrafter {
     readonly llm: LLMAdapter;
     readonly embedder: EmbedAdapter;
@@ -13,10 +13,13 @@ export declare class MemoGrafter {
     private readonly ingestQueue;
     constructor(config: MemoGrafterConfig);
     initialize(): Promise<void>;
-    ingest(messages: Message[], sessionId: string): Promise<TopicNode[]>;
-    ingestNow(messages: Message[], sessionId: string): Promise<TopicNode[]>;
-    enqueueIngest(messages: Message[], sessionId: string): Promise<void>;
-    getTopics(sessionId: string): Promise<{
+    ingest(messages: Message[], sessionId: string, options?: IngestOptions): Promise<TopicNode[]>;
+    ingestNow(messages: Message[], sessionId: string, options?: IngestOptions): Promise<TopicNode[]>;
+    enqueueIngest(messages: Message[], sessionId: string, options?: IngestOptions): Promise<void>;
+    getTopics(sessionId: string, options?: {
+        tags?: string[];
+        tagMode?: "all" | "any";
+    }): Promise<{
         nodes: TopicNode[];
         segments: TopicSegment[];
     }>;

package/dist/MemoGrafter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoGrafter.d.ts","sourceRoot":"","sources":["../src/MemoGrafter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAKhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EACV,sBAAsB,EACtB,YAAY,EACZ,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,OAAO,EACP,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAW;IACtB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,MAAM,EAAE,iBAAiB;IAmDrC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQpE,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAIjE,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASpE,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IAM7F,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMrF,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBpG,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMpF,WAAW,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB;IAI9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,uBAAuB;CAUhC"}
+{"version":3,"file":"MemoGrafter.d.ts","sourceRoot":"","sources":["../src/MemoGrafter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAKhC,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EACV,sBAAsB,EACtB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,OAAO,EACP,SAAS,EACT,YAAY,EACb,MAAM,YAAY,CAAC;AAEpB,qBAAa,WAAW;IACtB,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,KAAK,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,MAAM,EAAE,iBAAiB;IAqDrC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAI3B,MAAM,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAQjG,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAI9F,aAAa,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IASjG,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,GAAG,KAAK,CAAA;KAAO,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IAMzJ,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMrF,oBAAoB,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAmBpG,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAMpF,WAAW,CAAC,OAAO,GAAE,uBAA4B,GAAG,gBAAgB;IAI9D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,uBAAuB;CAUhC"}

package/dist/MemoGrafter.js

@@ -22,6 +22,7 @@ export class MemoGrafter {
         const llmAmbiguityDetection = config.drift?.llmAmbiguityDetection;
         const reentryDetection = config.drift?.reentryDetection;
         const reentryThreshold = config.drift?.reentryThreshold;
+        const adaptiveSensitivity = config.drift?.adaptiveSensitivity;
         const topK = config.graph?.topK ?? 5;
         const hopDepth = config.graph?.hopDepth ?? 1;
         const bufferSize = config.inject?.bufferSize ?? 1;
@@ -51,6 +52,7 @@ export class MemoGrafter {
             ...(llmAmbiguityDetection !== undefined ? { llmAmbiguityDetection } : {}),
             ...(reentryDetection !== undefined ? { reentryDetection } : {}),
             ...(reentryThreshold !== undefined ? { reentryThreshold } : {}),
+            ...(adaptiveSensitivity !== undefined ? { adaptiveSensitivity } : {}),
         });
         this.grafterPipeline = new GrafterPipeline(this.store, {
             hopDepth,
@@ -62,24 +64,24 @@ export class MemoGrafter {
     initialize() {
         return this.store.initialize();
     }
-    ingest(messages, sessionId) {
+    ingest(messages, sessionId, options = {}) {
         if (this.ingestQueue) {
-            return this.enqueueIngest(messages, sessionId).then(() => []);
+            return this.enqueueIngest(messages, sessionId, options).then(() => []);
         }
-        return this.ingestPipeline.run(messages, sessionId);
+        return this.ingestPipeline.run(messages, sessionId, options);
     }
-    ingestNow(messages, sessionId) {
-        return this.ingestPipeline.run(messages, sessionId);
+    ingestNow(messages, sessionId, options = {}) {
+        return this.ingestPipeline.run(messages, sessionId, options);
     }
-    async enqueueIngest(messages, sessionId) {
+    async enqueueIngest(messages, sessionId, options = {}) {
         if (this.ingestQueue) {
-            await this.ingestQueue.enqueue(messages, sessionId);
+            await this.ingestQueue.enqueue(messages, sessionId, options);
             return;
         }
-        await this.ingestPipeline.run(messages, sessionId);
+        await this.ingestPipeline.run(messages, sessionId, options);
     }
-    async getTopics(sessionId) {
-        const nodes = await this.store.getNodesBySession(sessionId);
+    async getTopics(sessionId, options = {}) {
+        const nodes = await this.store.getNodesBySession(sessionId, options);
         const segments = await this.store.getSegmentsBySession(sessionId);
         return { nodes, segments };
     }