memo-grafter 0.1.1 → 0.2.1

package/.env.example

@@ -1,4 +1,5 @@
 DATABASE_URL=postgres://postgres:postgres@localhost:5432/memograffer
 ANTHROPIC_API_KEY=
+GEMINI_API_KEY=
 OPENAI_API_KEY=
 REDIS_URL=redis://localhost:6379

package/README.md

@@ -3,32 +3,28 @@
 
 Structured memory for TypeScript chatbots.
 
-MemoGrafter helps chatbot applications remember conversations without stuffing every old message back into the prompt. It turns conversations into topic-based memory, retrieves the relevant parts later, and can copy useful memory from one chatbot or session into another.
+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 tasks, or decide goals for an agent.
+It is a memory framework, not an autonomous agent runtime. It does not run tools, schedule work, or decide goals for an agent.
 
-## What You Can Build
+## What It Is For
 
-- Chatbots that remember user preferences across long conversations.
-- Support or tutoring assistants that recall prior topics without replaying full history.
-- Multi-chatbot demos where one bot can absorb selected memory from another.
-- Prototypes for graph-based conversational memory, retrieval, and memory transfer.
-- Server-side TypeScript apps that need reusable LLM memory primitives.
+- 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
 
-At a high level:
-
 ```text
 chat messages
-  -> topic segments
-  -> memory nodes
+  -> topic-based memory
   -> graph links
-  -> relevant memory injection
+  -> relevant recall
   -> optional memory grafting
 ```
 
-MemoGrafter stores conversation turns, detects topic shifts, summarizes segments into memory nodes, links related nodes, and injects relevant memory into future LLM calls. Memory grafting lets one chatbot or session copy selected memory from another.
+MemoGrafter stores conversation turns, detects topic changes, summarizes useful context, links related memories, and retrieves or grafts memory when needed.
 
 ## Install
 
@@ -36,12 +32,7 @@ MemoGrafter stores conversation turns, detects topic shifts, summarizes segments
 npm install memo-grafter
 ```
 
-MemoGrafter runs server-side on Node.js and requires PostgreSQL with `pgvector`. The included OpenAI adapters also require `OPENAI_API_KEY`.
-
-```bash
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/memo_grafter
-OPENAI_API_KEY=sk-...
-```
+MemoGrafter runs server-side on Node.js. The built-in storage backend uses PostgreSQL with `pgvector`.
 
 ## Minimal Example
 
@@ -62,33 +53,20 @@ const agent = new MemoGrafterAgent({
 
 await agent.initialize();
 
-console.log(await agent.invoke("I am planning a Japan trip."));
-console.log(await agent.invoke("I like quiet towns, bookstores, and local cafes."));
-console.log(await agent.invoke("What do you remember about my travel preferences?"));
-
-await agent.close();
-```
-
-## Memory Grafting
+await agent.invoke("I am planning a Japan trip.");
+await agent.invoke("I like quiet towns, bookstores, and local cafes.");
 
-Memory grafting is the core idea behind the name: one chatbot can build memory, and another chatbot can absorb only the useful parts.
+const recall = await agent.recall("travel preferences");
+console.log(recall.facts);
 
-```ts
-await writingBot.absorbFromAgent(travelBot, {
-  prompt: "Japan travel preferences",
-  limit: 3,
-});
+await agent.close();
 ```
 
 ## Learn More
 
-Read [USER_GUIDE.md](https://github.com/mayhemking007/memo-grafter/blob/main/USER_GUIDE.md) for setup, configuration, queue mode, custom adapters, fleet APIs, examples, and troubleshooting.
-
-This repository also includes a runnable demo:
-
-```text
-examples/chatbot-memory-demo
-```
+- [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
 

package/USER_GUIDE.md

@@ -12,12 +12,13 @@ The most important idea is memory grafting. A chatbot can build useful memory du
 
 - Node.js 18 or newer.
 - TypeScript or modern JavaScript using ES modules.
-- PostgreSQL with the `pgvector` extension enabled.
+- PostgreSQL with the `pgvector` extension enabled for the built-in `PostgresGraphStore`.
 - An LLM adapter.
 - An embedding adapter.
 - An OpenAI API key only if using the included OpenAI adapters.
 - An Anthropic API key only if using the included Anthropic LLM adapter.
-- Redis only if enabling queue mode.
+- A Gemini API key only if using the included Gemini adapters.
+- Redis only if enabling queue mode or the optional recall cache.
 
 MemoGrafter is server-side only. Do not run it in browser code.
 
@@ -51,17 +52,20 @@ Create a `.env` file in your app:
 ```bash
 DATABASE_URL=postgres://postgres:postgres@localhost:5432/memo_grafter
 ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=...
 OPENAI_API_KEY=sk-...
 REDIS_URL=redis://localhost:6379
 ```
 
-`DATABASE_URL` is required.
+`DATABASE_URL` is required when using the built-in PostgreSQL storage.
 
 `OPENAI_API_KEY` is required only when using `OpenAILLMAdapter` or `OpenAIEmbedAdapter`.
 
 `ANTHROPIC_API_KEY` is required only when using `AnthropicLLMAdapter`.
 
-`REDIS_URL` is optional and only needed when you pass `queue` config.
+`GEMINI_API_KEY` is required only when using `GeminiLLMAdapter` or `GeminiEmbedAdapter`.
+
+`REDIS_URL` is optional and only needed when you pass `queue` or `cache` config.
 
 Enable `pgvector` in PostgreSQL:
 
@@ -69,7 +73,7 @@ Enable `pgvector` in PostgreSQL:
 CREATE EXTENSION IF NOT EXISTS vector;
 ```
 
-MemoGrafter creates its own tables during `initialize()`.
+The built-in `PostgresGraphStore` creates its own tables during `initialize()`.
 
 Current v1 tables:
 
@@ -77,6 +81,8 @@ Current v1 tables:
 - `mg_segments`
 - `mg_topic_nodes`
 - `mg_topic_edges`
+- `mg_memory_nodes`
+- `mg_memory_edges`
 - `mg_fleets`
 - `mg_fleet_agents`
 
@@ -129,17 +135,25 @@ A message is one user or assistant turn:
 
 ```ts
 export interface Message {
-  role: "user" | "assistant";
+  role: "system" | "user" | "assistant";
   content: string;
 }
 ```
 
-`MemoGrafterAgent` keeps an in-memory history for the current session and stores messages in PostgreSQL during ingestion.
+`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.
 
 ### Segments
 
 A segment is a range of messages that belong to the same topic. MemoGrafter uses drift detection to decide where topic boundaries are.
 
+Drift detection combines several signals:
+
+- how far the current message is from the current topic embedding,
+- whether the current message is a sharp pivot from the previous user message,
+- whether the message contains structural phrases such as "by the way", "different topic", or "going back to",
+- short-message dampening so filler like "okay" or "got it" is less likely to create false boundaries,
+- optional LLM classification for ambiguous topic-shift scores.
+
 Example:
 
 ```text
@@ -166,9 +180,29 @@ Important fields:
 
 Topic nodes are stored in `mg_topic_nodes`.
 
+### Memory Nodes
+
+Memory nodes are typed atomic memories attached to topic nodes. They are the units used by targeted recall.
+
+Important fields:
+
+- `memoryType`: `"fact"`, `"insight"`, `"question"`, `"task"`, or `"reference"`.
+- `subject`, `predicate`, `value`: the structured memory triple.
+- `confidence`: confidence score from `0` to `1`.
+- `topicNodeId`: parent topic node ID.
+- `decayed`: whether the memory is stale.
+- `supersededBy`: newer memory ID when this memory has been replaced.
+
+Memory nodes are stored in `mg_memory_nodes`.
+
 ### Graph Edges
 
-Edges connect related topic nodes. They can represent temporal, semantic, or grafted relationships.
+Edges connect related topic nodes. They can represent temporal, semantic, grafted, or reentry relationships.
+
+- `temporal`: one topic followed another in the conversation.
+- `semantic`: two topics are similar by embedding search.
+- `grafted`: a topic was copied from another session or chatbot.
+- `reentry`: the conversation returned to an earlier topic after discussing something else.
 
 Edges are stored in `mg_topic_edges`.
 
@@ -218,13 +252,55 @@ await agent.close();
 On every call, `invoke()`:
 
 1. Adds the user message to local history.
-2. Loads existing topic nodes for the session.
-3. Builds a memory injection prompt from those nodes.
-4. Sends history plus memory prompt to the LLM.
+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. Ingests the updated conversation into the memory graph.
+6. Queues ingestion of the updated conversation into the memory graph.
+
+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.
+
+On the first turn there may be no memory to recall. Later turns can use memory created from earlier turns once ingestion has completed.
+
+### Targeted Recall
+
+Use `recall()` when you want to retrieve structured memory by meaning without asking the LLM to produce an answer.
+
+```ts
+const result = await agent.recall("deployment config", {
+  limit: 8,
+  minSimilarity: 0.55,
+  tokenBudget: 1000,
+  cache: {
+    ttlSeconds: 90,
+  },
+});
+
+console.log(result.facts);
+console.log(result.nodes);
+console.log(result.systemPrompt);
+console.log(result.tokenCount);
+```
+
+`recall()` returns a `RetrievalResult`:
+
+- `facts`: matching memory nodes with a `similarity` score.
+- `nodes`: parent topic nodes for the included facts.
+- `systemPrompt`: a formatted memory block that can be passed to an LLM if you choose.
+- `tokenCount`: approximate token count for the included fact blocks.
+
+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`.
+- `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.
+
+`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.
 
-On the first turn there may be no memory to inject. Later turns can use memory created from earlier turns.
+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
 
@@ -368,8 +444,11 @@ const agent = new MemoGrafterAgent({
   drift: {
     mode: "intent",
     windowSize: 5,
-    threshold: 0.3,
+    driftSensitivity: "medium",
     minSegmentMessages: 3,
+    llmAmbiguityDetection: false,
+    reentryDetection: true,
+    reentryThreshold: 0.85,
   },
   graph: {
     topK: 5,
@@ -378,6 +457,11 @@ const agent = new MemoGrafterAgent({
   inject: {
     bufferSize: 4,
     tokenBudget: 1500,
+    recentWindowSize: 20,
+  },
+  cache: {
+    connectionString: process.env.REDIS_URL!,
+    ttlSeconds: 90,
   },
 });
 ```
@@ -390,7 +474,27 @@ db: {
 }
 ```
 
-PostgreSQL connection string.
+PostgreSQL connection string used by the built-in `PostgresGraphStore`.
+
+MemoGrafter currently constructs `PostgresGraphStore` from this config internally. Advanced users can also import the storage contract directly:
+
+```ts
+import {
+  PostgresGraphStore,
+  type GraphStore,
+} from "memo-grafter";
+
+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"`.
 
 ### `llm`
 
@@ -406,6 +510,12 @@ Anthropic models can be used with the included Anthropic adapter:
 llm: new AnthropicLLMAdapter("claude-sonnet-4-5")
 ```
 
+Gemini models can be used with the included Gemini adapter:
+
+```ts
+llm: new GeminiLLMAdapter("gemini-2.5-flash")
+```
+
 ### `embedder`
 
 ```ts
@@ -416,14 +526,25 @@ Adapter used to create vectors for semantic search.
 
 Anthropic does not provide a native embedding API. Pair `AnthropicLLMAdapter` with `OpenAIEmbedAdapter` or another custom `EmbedAdapter`.
 
+Gemini embeddings can be used with the included Gemini embedder:
+
+```ts
+embedder: new GeminiEmbedAdapter("gemini-embedding-001")
+```
+
+`GeminiEmbedAdapter` requests 1536-dimensional embeddings by default to match MemoGrafter's current `vector(1536)` database schema. If you change the schema dimension, pass the matching value as the second constructor argument.
+
 ### `drift`
 
 ```ts
 drift: {
   mode: "intent",
   windowSize: 5,
-  threshold: 0.3,
+  driftSensitivity: "medium",
   minSegmentMessages: 3,
+  llmAmbiguityDetection: false,
+  reentryDetection: true,
+  reentryThreshold: 0.85,
 }
 ```
 
@@ -431,11 +552,39 @@ Controls topic boundary detection.
 
 - `mode`: `"intent"` or `"window"`.
 - `windowSize`: message window size for window mode.
-- `threshold`: drift sensitivity.
+- `driftSensitivity`: preferred sensitivity preset, one of `"low"`, `"medium"`, or `"high"`.
+- `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`.
+- `reentryDetection`: whether to link later topic returns back to earlier topic nodes. Defaults to `true`.
+- `reentryThreshold`: embedding similarity threshold for reentry detection. Defaults to `0.85`.
 
 Use `"intent"` for most chatbot memory demos. In intent mode, user messages drive topic shifts.
 
+Sensitivity presets resolve internally to numeric thresholds:
+
+- `"low"`: `0.25`
+- `"medium"`: `0.35`
+- `"high"`: `0.50`
+
+Use `"medium"` first. Boundaries are cut when a drift score exceeds the resolved threshold, so lower numeric thresholds split more readily and higher numeric thresholds require stronger evidence.
+
+If both `driftSensitivity` and `threshold` are provided, `driftSensitivity` wins.
+
+#### Reentry Detection
+
+Reentry detection handles conversations that leave a topic and later return to it:
+
+```text
+database choice -> authentication flow -> database connection pooling
+```
+
+Without reentry detection, the later database discussion is just another topic node. With reentry detection, MemoGrafter creates a `reentry` edge from the later database node back to the earlier database node.
+
+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.
+
 ### `graph`
 
 ```ts
@@ -456,13 +605,33 @@ Controls graph retrieval and traversal.
 inject: {
   bufferSize: 4,
   tokenBudget: 1500,
+  recentWindowSize: 20,
 }
 ```
 
-Controls how much memory is inserted into the prompt.
+Controls memory prompt sizing and the raw history window kept when chat history overflows.
 
 - `bufferSize`: nearby raw messages to include.
-- `tokenBudget`: approximate memory prompt budget.
+- `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`.
+
+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.
+
+### `cache`
+
+```ts
+cache: {
+  connectionString: process.env.REDIS_URL!,
+  ttlSeconds: 90,
+}
+```
+
+Enables an opt-in Redis cache for targeted recall. MemoGrafter creates one shared Redis client and uses it to cache only the raw `searchMemories()` result. It does not cache final prompts, filtered blocks, or `RetrievalResult`, so different `tokenBudget` values still assemble fresh output.
+
+- `connectionString`: Redis URL.
+- `ttlSeconds`: cache TTL in seconds. Defaults to `90` and is clamped between `60` and `120`.
+
+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.
 
 ## Queue Mode
 
@@ -531,6 +700,88 @@ const agent = new MemoGrafterAgent({
 
 Your embedding vector dimension must match the vector dimension expected by the database schema.
 
+## Storage Backends
+
+MemoGrafter exposes storage through the `GraphStore` interface. The built-in implementation is `PostgresGraphStore`, which stores relational data, graph edges, and vector search data in PostgreSQL with `pgvector`.
+
+Most users do not need to instantiate a store directly. `MemoGrafter` and `MemoGrafterAgent` use `PostgresGraphStore` from the `db.connectionString` config:
+
+```ts
+const agent = new MemoGrafterAgent({
+  db: {
+    connectionString: process.env.DATABASE_URL!,
+  },
+  llm,
+  embedder,
+});
+```
+
+If you are extending MemoGrafter, use `GraphStore` as the contract and keep concrete storage details behind an implementation:
+
+```ts
+import type { GraphStore } from "memo-grafter";
+
+class MyGraphStore implements GraphStore {
+  // Implement the full GraphStore contract.
+}
+```
+
+Future storage implementations can use the same interface without changing pipeline or fleet code. For example, a SQLite plus vector-database implementation would implement `GraphStore` while preserving the same behavior expected by ingestion, grafting, and fleet APIs.
+
+## Using Pipelines Directly
+
+`MemoGrafterAgent` is the recommended starting point, but the underlying
+pipeline classes are also exported for developers who want to build custom
+agent loops or integrate MemoGrafter memory primitives into an existing
+orchestration framework.
+
+Pipeline classes are exported for composability. Their constructors and
+internal behavior are not covered by semver stability guarantees until v1.0.
+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.
+- `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.
+
+Example using `RetrieverPipeline` directly:
+
+```ts
+import {
+  PostgresGraphStore,
+  RetrieverPipeline,
+  OpenAIEmbedAdapter,
+} from "memo-grafter";
+
+const store = new PostgresGraphStore(process.env.DATABASE_URL!);
+await store.initialize();
+
+const embedder = new OpenAIEmbedAdapter("text-embedding-3-small");
+
+const retriever = new RetrieverPipeline(store, embedder, {
+  limit: 8,
+  minSimilarity: 0.55,
+  tokenBudget: 1000,
+});
+
+const result = await retriever.run(
+  "deployment config and Kubernetes namespace",
+  sessionId,
+);
+
+console.log(result.facts);
+console.log(result.systemPrompt);
+
+await store.close();
+```
+
+When using pipelines directly you are responsible for managing the store
+connection lifecycle. Call `store.close()` during graceful shutdown.
+
+`MemoGrafterAgent` remains the batteries-included default. Existing code
+that uses `MemoGrafterAgent` does not need to change.
+
 ## Fleet API
 
 Fleets let you group color-scoped worker chatbots and use a conductor to graft memory across workers.
@@ -641,11 +892,31 @@ For small demos, try:
 ```ts
 drift: {
   mode: "intent",
-  threshold: 0.3,
+  driftSensitivity: "medium",
   minSegmentMessages: 3,
 }
 ```
 
+If segments are too coarse, try a lower resolved threshold:
+
+```ts
+drift: {
+  mode: "intent",
+  driftSensitivity: "low",
+  minSegmentMessages: 2,
+}
+```
+
+If segments are too fragmented, try a higher resolved threshold:
+
+```ts
+drift: {
+  mode: "intent",
+  driftSensitivity: "high",
+  minSegmentMessages: 4,
+}
+```
+
 ### Absorb Copies Zero Nodes
 
 Inspect the source memory:
@@ -664,9 +935,27 @@ await targetAgent.absorbFromAgent(sourceAgent, {
 });
 ```
 
+### Recall Returns Zero Facts
+
+`recall()` searches atomic memory nodes, not raw chat messages. If it returns no facts:
+
+- Make sure ingestion has completed.
+- Confirm memory nodes exist for the session.
+- Try a lower `minSimilarity`.
+- Try a more specific query that uses the same vocabulary as the original conversation.
+
+Example:
+
+```ts
+const result = await agent.recall("Japan travel preferences", {
+  minSimilarity: 0.3,
+  limit: 5,
+});
+```
+
 ### Redis Warnings
 
-Redis is only required when you pass `queue` config. If you do not need background ingestion, remove the `queue` section.
+Redis is only required when you pass `queue` or `cache` config. If you do not need background ingestion or recall caching, remove those sections.
 
 ### Browser Runtime Error
 
@@ -682,6 +971,7 @@ 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.
 - Store your own user/session mapping outside MemoGrafter.
 - Call `close()` during graceful shutdown.
 - Do not expose database credentials or OpenAI keys to browser code.
@@ -697,10 +987,27 @@ Main exports:
 - `WorkerAgent`
 - `ConductorAgent`
 - `AnthropicLLMAdapter`
+- `GeminiLLMAdapter`
+- `GeminiEmbedAdapter`
 - `OpenAILLMAdapter`
 - `OpenAIEmbedAdapter`
+- `PostgresGraphStore`
+- `GrafterPipeline`
+- `IngestPipeline`
+- `RetrieverPipeline`
+- `GraphStore`
+- `FleetAgentRecord`
+- `RetrievalResult`
+- `RetrieverConfig`
 - public shared and fleet types
 
+Useful `GraphStore` inspection methods:
+
+- `getTopicNode(topicNodeId, sessionId?)`
+- `getNodesBySession(sessionId)`
+- `getSegmentsBySession(sessionId)`
+- `getEdgesByType(sessionId, type)`
+
 Common `MemoGrafterAgent` methods:
 
 - `initialize()`: initialize storage.
@@ -709,6 +1016,7 @@ Common `MemoGrafterAgent` methods:
 - `getSessionId()`: read the current session ID.
 - `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.

package/dist/MemoGrafter.d.ts

@@ -1,11 +1,13 @@
-import { GraphStore } from "./store/GraphStore.js";
+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";
 export declare class MemoGrafter {
     readonly llm: LLMAdapter;
     readonly embedder: EmbedAdapter;
     readonly store: GraphStore;
+    readonly recallCache: Redis | null;
     private readonly ingestPipeline;
     private readonly grafterPipeline;
     private readonly ingestQueue;

package/dist/MemoGrafter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoGrafter.d.ts","sourceRoot":"","sources":["../src/MemoGrafter.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,kBAAkB,CAAC;AAChE,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,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkB;IAClD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAqB;gBAErC,MAAM,EAAE,iBAAiB;IA8BrC,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;IAK5B,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,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"}