memo-grafter 0.2.7 → 0.3.0

package/README.md

@@ -38,10 +38,14 @@ MemoGrafter stores conversation turns, tracks which messages have already been i
 
 ```bash
 npm install memo-grafter
+npx memo-grafter init
+npx memo-grafter migrate
 ```
 
 MemoGrafter runs server-side on Node.js. The built-in storage backend uses PostgreSQL with `pgvector`.
 
+`init` creates local project files under `src/memo-grafter/` (`mg-schema.ts`, `schema.ts`, and `mg.config.ts`) without touching your database. `migrate` creates or updates MemoGrafter-owned `mg_*` tables. Application tables remain managed by your existing tool, such as Prisma, Drizzle, or SQL migrations.
+
 ## Minimal Example
 
 ```ts
@@ -68,12 +72,34 @@ await agent.ingestText("The product roadmap now prioritizes document imports.",
   source: "import",
 });
 
+await agent.remember("The user prefers concise TypeScript examples.");
+
 const recall = await agent.recall("travel preferences");
 console.log(recall.facts);
 
 await agent.close();
 ```
 
+## Shared Fleet Memory
+
+Fleets can store common knowledge once and make it available to workers without
+copying it into each worker session.
+
+```ts
+const fleet = new MemoGrafterFleet(config, {
+  id: "support-fleet",
+  defaultWorkerMemory: "both",
+});
+
+await fleet.initialize();
+await fleet.ingestToFleet("Refund policy: customers can request a refund within 30 days.");
+
+const support = await fleet.createWorker({ color: "support" });
+const recall = await support.recall("refund policy", { memory: "both" });
+
+console.log(recall.facts);
+```
+
 ## 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.

package/USER_GUIDE.md

@@ -69,13 +69,20 @@ REDIS_URL=redis://localhost:6379
 
 `REDIS_URL` is optional and only needed when you pass `queue` or `cache` config.
 
-Enable `pgvector` in PostgreSQL:
+Initialize MemoGrafter project files and migrate the MemoGrafter tables:
 
-```sql
-CREATE EXTENSION IF NOT EXISTS vector;
+```bash
+npx memo-grafter init
+npx memo-grafter migrate
 ```
 
-The built-in `PostgresGraphStore` creates its own tables during `initialize()`.
+`memo-grafter init` creates local project files only:
+
+- `src/memo-grafter/mg-schema.ts`: generated MemoGrafter schema reference for `mg_*` tables. This file is regenerated on every `init` run.
+- `src/memo-grafter/schema.ts`: user-owned schema composition file. It is created only if missing and is never overwritten.
+- `src/memo-grafter/mg.config.ts`: user-editable MemoGrafter CLI config.
+
+`memo-grafter migrate` creates `pgvector`, `pgcrypto`, and MemoGrafter-owned `mg_*` tables in the database. It does not migrate app tables from `schema.ts`; keep using Prisma, Drizzle, raw SQL, or another migration tool for application tables.
 
 Current v1 tables:
 
@@ -94,6 +101,13 @@ Current v1 tables:
 
 ## Quick Start
 
+Run the setup commands once for your app:
+
+```bash
+npx memo-grafter init
+npx memo-grafter migrate
+```
+
 Create `src/index.ts`:
 
 ```ts
@@ -185,6 +199,8 @@ Important fields:
 - `messageRange`: source message range.
 - `topicOrder`: chronological order.
 - `driftScore`: topic-change score.
+- `suppressed`: whether the topic is temporarily hidden from recall, grafting, crawler maintenance, and active topic reads.
+- `suppressedAt`: timestamp for the latest suppression, or `null` when active.
 - `agentColor`, `fleetId`, `agentId`: nullable fleet metadata.
 
 Topic nodes are stored in `mg_topic_nodes`.
@@ -201,12 +217,14 @@ Important fields:
 - `topicNodeId`: parent topic node ID.
 - `tags`: optional normalized tags copied from the session or ingest call.
 - `decayed`: whether the memory is stale.
+- `forgotten`: whether the memory has been explicitly hidden by an application.
+- `forgottenAt`: timestamp for the explicit forget action, or `null` when active.
 - `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.
+`decayed`, `hasConflict`, and `supersededBy` are maintenance fields. `forgotten` is an application-controlled lifecycle field. 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
 
@@ -241,7 +259,7 @@ 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.
+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, superseded, forgotten, or attached to a suppressed topic.
 
 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.
 
@@ -324,6 +342,19 @@ Without `replace`, each text call appends to the current session memory. Later `
 
 In queue mode, `await agent.ingestText()` confirms that the ingestion job was queued. Reads may need to wait for the worker to finish before the new graph content is visible.
 
+### Remembering Explicit Facts
+
+Use `remember()` when your application already knows a fact, preference, or note and wants to store it without running an assistant turn:
+
+```ts
+await agent.remember("The user prefers concise TypeScript examples.", {
+  label: "User preference",
+  source: "profile-settings",
+});
+```
+
+`remember()` is a convenience wrapper around `ingestText()`. It uses the same extraction pipeline, applies the current session tags automatically, does not change `getHistory()`, and defaults `source` to `"remember"` when you do not provide one. The extraction LLM still decides which structured memories to create, so this API is best for natural-language facts and preferences rather than exact row-level inserts.
+
 ### Clearing A Session
 
 Use `clearSession()` when you intentionally want to reset an agent:
@@ -334,6 +365,117 @@ 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.
 
+### Memory Lifecycle Controls
+
+Use lifecycle controls when your application needs user-controlled memory management without physically deleting graph rows by default.
+
+Forget a single memory node:
+
+```ts
+const recall = await agent.recall("food preferences");
+const memoryId = recall.facts[0]!.id;
+
+const changed = await agent.forget(memoryId);
+console.log(changed); // true when the memory was newly marked forgotten
+```
+
+Forget several memory nodes at once:
+
+```ts
+const changedCount = await agent.forgetMany([
+  "memory-id-a",
+  "memory-id-b",
+]);
+```
+
+Suppress a topic temporarily:
+
+```ts
+const nodes = await agent.getActiveNodes();
+const topicId = nodes[0]!.id;
+
+await agent.suppressTopic(topicId);
+```
+
+Restore a suppressed topic:
+
+```ts
+await agent.restoreTopic(topicId);
+```
+
+Forgotten memories stay in `mg_memory_nodes` with `forgotten = TRUE` and `forgotten_at` set. Suppressed topics stay in `mg_topic_nodes` with `suppressed = TRUE` and `suppressed_at` set. These rows are excluded from targeted recall, invoke-time recall, graft prompt assembly, semantic graft seed selection, absorption, active topic listing, and crawler maintenance until restored where applicable.
+
+`forget()` and `forgetMany()` are one-way soft lifecycle operations. There is no built-in `restoreMemory()` API because user-requested memory deletion and privacy flows usually need conservative behavior. Applications that require undo or hard deletion can implement that policy at the storage layer.
+
+`getGraphSnapshot()` remains useful for audit and visualization. Snapshot memory reads include forgotten, decayed, conflicted, and superseded rows, and snapshot topic reads include suppressed topics, so UIs can display lifecycle state explicitly.
+
+The lower-level `MemoGrafter` class exposes the same methods when you manage sessions yourself:
+
+```ts
+await memo.forget(memoryId);
+await memo.forgetMany(memoryIds);
+await memo.suppressTopic(topicId);
+await memo.restoreTopic(topicId);
+```
+
+### Memory History And Diff
+
+Use memory history APIs when your application needs audit trails, explainability, or debugging for facts that changed over time.
+
+Look up history from a specific memory node:
+
+```ts
+const history = await agent.getMemoryHistory(memoryId);
+
+for (const entry of history.entries) {
+  console.log(entry.versionIndex);
+  console.log(entry.status);
+  console.log(entry.memory.value);
+  console.log(entry.supersededBy);
+  console.log(entry.supersedes);
+  console.log(entry.conflictsWith);
+}
+
+console.log(history.currentMemory);
+```
+
+Look up history by fact key:
+
+```ts
+const history = await agent.getMemoryHistory("user", "location");
+```
+
+`MemoGrafterAgent` scopes history lookups to the current session. If you manage sessions yourself with `MemoGrafter`, pass the session explicitly:
+
+```ts
+const history = await memo.getMemoryHistory("user", "location", {
+  sessionId,
+});
+```
+
+Compare two memory versions:
+
+```ts
+const diff = await agent.getMemoryDiff(oldMemoryId, newMemoryId);
+
+console.log(diff.changedFields);
+console.log(diff.relationship.supersededBy);
+console.log(diff.relationship.updateEdges);
+console.log(diff.relationship.conflictEdges);
+```
+
+History results are read-only and derived from existing memory rows plus `supersededBy`, `updates`, and `conflicts` metadata. They intentionally include superseded, decayed, forgotten, and suppressed-topic memories, even though those rows are excluded from normal recall and grafting.
+
+`MemoryHistoryEntry.status` is one of:
+
+- `"active"`: not superseded, decayed, forgotten, or conflicting.
+- `"superseded"`: the memory has `supersededBy` set.
+- `"conflicting"`: the memory has `hasConflict` or a `conflicts` edge.
+- `"decayed"`: crawler decay marked the memory stale.
+- `"forgotten"`: an application explicitly forgot the memory.
+
+`getMemoryDiff()` is structural. It compares stored fields such as `value`, `confidence`, lifecycle flags, tags, source metadata, and timestamps. It does not call an LLM or generate prose explanations.
+
 ### Session Tags
 
 Use session tags when you want to organize memory by project, planning area, week, domain, or worker route.
@@ -418,7 +560,7 @@ const projectMemory = await agent.recall("deployment decisions", {
 });
 ```
 
-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.
+This can return matching active memories from older or different sessions with the same tag. Active recall excludes decayed, superseded, forgotten, and suppressed-topic memories. 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`.
 
@@ -436,6 +578,7 @@ console.log(snapshot.nodes);
 console.log(snapshot.snapshotNodes);
 console.log(snapshot.edges);
 console.log(snapshot.memories);
+console.log(snapshot.snapshotMemories);
 console.log(snapshot.memoryEdges);
 console.log(snapshot.capturedAt);
 ```
@@ -443,18 +586,30 @@ 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.
+- `nodes`: topic nodes for the session, including suppressed nodes for audit views.
+- `snapshotNodes`: topic nodes wrapped with lifecycle metadata and optional graft provenance.
 - `edges`: topic edges where either endpoint belongs to a session topic node.
-- `memories`: all memory nodes for the session, including decayed or superseded rows.
+- `memories`: all memory nodes for the session, including forgotten, decayed, conflicted, or superseded rows.
+- `snapshotMemories`: memory nodes wrapped with lifecycle metadata.
 - `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.
+Each `snapshotNodes` entry contains:
+
+- `node`: the topic node.
+- `lifecycle`: `{ suppressed, suppressedAt }`.
+- `graftOrigin`: optional `{ sourceSessionId, sourceNodeId, graftedAt }` when the node came from a graft.
+
+Each `snapshotMemories` entry contains:
+
+- `memory`: the memory node.
+- `lifecycle`: `{ forgotten, forgottenAt, decayed, supersededBy, hasConflict }`.
+
+The `nodes`, `edges`, `memories`, and `memoryEdges` arrays remain available for backward-compatible callers that already read the raw graph rows directly. Snapshot arrays are sorted deterministically so graph UIs can use them as a stable primary data source.
 
 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.
+Graph snapshots intentionally include stale and maintenance metadata so visualizers can show memory lifecycle state. For example, a UI can hide or label `forgotten` memories, fade `decayed` memories, show `hasConflict` badges, draw `conflicts` edges between contradictory facts, draw `updates` edges from the current fact to the older fact it replaced, and show suppressed topics separately from active topics.
 
 Read active topic nodes:
 
@@ -553,6 +708,8 @@ Active memory facts:
 
 This keeps history intact while telling the downstream model which fact is current.
 
+Suppressed topics are not included in graft prompts, even if their IDs are passed explicitly. Forgotten memories are not included as active facts or as replacement details in maintenance notes.
+
 ## 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.
@@ -608,6 +765,7 @@ The built-in conflict and versioning passes use separate deterministic classifie
 - a group conflicts when it has different normalized `value` strings and the newest value does not contain an explicit update cue;
 - a group versions only when its newest value contains an explicit replacement or update cue such as `actually`, `now`, `changed to`, or `instead`;
 - decayed memories are skipped;
+- forgotten memories and memories attached to suppressed topics 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;
 - version replacement candidates are selected by `createdAt`;
@@ -624,7 +782,7 @@ 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:
+If `decay_score < minScore`, the memory is marked `decayed: true`. Superseded memories, forgotten memories, and already decayed memories are skipped. Conservative defaults are used when options are omitted:
 
 ```ts
 new DecayScoringPass({
@@ -647,7 +805,7 @@ When explicit replacements are found:
 - 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.
+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. Forgotten memories and memories attached to suppressed topics are ignored by maintenance scans.
 
 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.
 
@@ -689,7 +847,7 @@ 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.
+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, superseded, forgotten, or suppressed-topic 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.
 
@@ -1030,6 +1188,18 @@ Run the semantic grafting smoke with a real PostgreSQL database:
 npx tsx --env-file=.env ./tests/manual/graft/graft-by-relevance-smoke.ts
 ```
 
+Run the memory lifecycle smoke with a real PostgreSQL database and `OPENAI_API_KEY`:
+
+```powershell
+npx tsx --env-file=.env ./tests/manual/graft/memory-lifecycle-smoke.ts
+```
+
+Run the memory history smoke with a real PostgreSQL database:
+
+```powershell
+npx tsx --env-file=.env ./tests/manual/graft/memory-history-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.
@@ -1158,6 +1328,7 @@ import {
 } from "memo-grafter";
 
 const store = new PostgresGraphStore(process.env.DATABASE_URL!);
+await store.migrate(); // Or run `npx memo-grafter migrate` before app startup.
 await store.initialize();
 
 const embedder = new OpenAIEmbedAdapter("text-embedding-3-small");
@@ -1234,6 +1405,63 @@ await fleet.close();
 
 The worker color `conductor` is reserved.
 
+### Shared fleet memory
+
+Fleet memory is a shared parent scope for every worker in a fleet. Use it for
+common knowledge such as product docs, company policies, operating procedures,
+or global application context.
+
+```ts
+await fleet.ingestToFleet(
+  "Refund policy: customers can request a refund within 30 days.",
+  {
+    tags: ["policy"],
+    source: "support-handbook",
+  }
+);
+
+const shared = await fleet.getSharedMemory();
+console.log(shared.memories);
+
+const recall = await fleet.recallFromFleet("refund policy");
+console.log(recall.facts);
+```
+
+Workers keep their own session memory. When a worker should also inherit fleet
+knowledge, configure its memory mode:
+
+```ts
+const support = await fleet.createWorker({
+  color: "support",
+  memory: "both",
+});
+
+await support.invoke("What is the refund window?");
+```
+
+Worker retrieval and relevance grafting can also choose the scope per call:
+
+```ts
+await support.recall("refund policy", {
+  memory: "fleet",
+});
+
+await support.graftByRelevance("refund policy", {
+  memory: "both",
+  minSimilarity: 0.55,
+});
+```
+
+Memory modes:
+
+- `"local"`: only the worker session memory.
+- `"fleet"`: only the shared fleet memory.
+- `"both"`: worker session memory plus shared fleet memory.
+
+The default worker mode is `"local"` for compatibility. You can set
+`defaultWorkerMemory: "both"` when creating the fleet if all workers should
+inherit shared fleet memory unless overridden.
+
 Prompt-guided fleet grafting:
 
 ```ts
@@ -1405,6 +1633,7 @@ Practical notes:
 - Tune `tokenBudget` to control prompt size and cost.
 - Use queue mode if ingestion becomes slow.
 - Use `clearSession()` only for intentional resets; normal ingestion preserves the graph incrementally.
+- Use `forget()`, `forgetMany()`, `suppressTopic()`, and `restoreTopic()` for user-controlled memory lifecycle flows.
 - 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.
@@ -1440,6 +1669,7 @@ Main exports:
 - `TagFilterOptions`
 - `IngestOptions`
 - `IngestTextOptions`
+- `RememberOptions`
 - public shared and fleet types
 
 Useful `GraphStore` inspection methods:
@@ -1453,21 +1683,36 @@ Useful `GraphStore` inspection methods:
 - `getMemoryEdgesBySession(sessionId)`
 - `getSessionNodeCount(sessionId)`
 - `getSessionIngestState(sessionId)`
+- `forgetMemory(memoryId)`
+- `forgetMemories(memoryIds)`
+- `suppressTopic(topicId)`
+- `restoreTopic(topicId)`
+- `getMemoryHistoryById(memoryId, options?)`
+- `getMemoryHistoryByFact(subject, predicate, options?)`
+- `getMemoryDiff(fromMemoryId, toMemoryId)`
 
 Common `MemoGrafterAgent` methods:
 
-- `initialize()`: initialize storage.
+- `initialize()`: verify that MemoGrafter storage has already been migrated.
 - `invoke(message)`: send a user message and receive an assistant response.
 - `ingestText(text, options?)`: ingest raw text without generating an assistant response.
+- `remember(text, options?)`: store explicit natural-language facts or preferences through the text ingestion path.
 - `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.
+- `getGraphSnapshot()`: read a stable graph snapshot with raw topic and memory rows, graph edges, lifecycle metadata, graft metadata, 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.
+- `forget(memoryId)`: soft-forget a memory node so it is excluded from future recall, grafting, absorption, and crawler maintenance.
+- `forgetMany(memoryIds)`: soft-forget several memory nodes and return the number changed.
+- `suppressTopic(topicId)`: hide a topic from active reads, recall, grafting, absorption, and crawler maintenance.
+- `restoreTopic(topicId)`: make a suppressed topic active again.
+- `getMemoryHistory(memoryId)`: inspect the current session lineage for a specific memory.
+- `getMemoryHistory(subject, predicate)`: inspect the current session lineage for a fact key.
+- `getMemoryDiff(fromMemoryId, toMemoryId)`: compare two memory versions and their maintenance relationship.
 - `recall(query, options?)`: retrieve structured memory by semantic query, optionally filtered by tags.
 - `graft(topicIds?)`: preview memory injection.
 - `graftByRelevance(query, options?)`: preview memory injection selected by semantic topic-node relevance.

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, GraftByRelevanceOptions, IngestOptions, IngestTextOptions, InjectionResult, LLMAdapter, MemoGrafterConfig, Message, TopicNode, TopicSegment } from "./types.js";
+import type { AbsorbFromAgentOptions, EmbedAdapter, GraftByRelevanceOptions, IngestOptions, IngestTextOptions, InjectionResult, LLMAdapter, MemoryDiff, MemoryHistoryOptions, MemoryHistoryResult, MemoGrafterConfig, Message, TagFilterOptions, TopicNode, TopicSegment } from "./types.js";
 export declare class MemoGrafter {
     readonly llm: LLMAdapter;
     readonly embedder: EmbedAdapter;
@@ -20,14 +20,18 @@ export declare class MemoGrafter {
     enqueueIngest(messages: Message[], sessionId: string, options?: IngestOptions): Promise<void>;
     ingestText(text: string, sessionId: string, options?: IngestTextOptions & IngestOptions): Promise<TopicNode[]>;
     enqueueTextIngest(text: string, sessionId: string, options?: IngestTextOptions & IngestOptions): Promise<void>;
-    getTopics(sessionId: string, options?: {
-        tags?: string[];
-        tagMode?: "all" | "any";
-    }): Promise<{
+    getTopics(sessionId: string, options?: TagFilterOptions): Promise<{
         nodes: TopicNode[];
         segments: TopicSegment[];
     }>;
     inject(sessionId: string, topicIds: string[]): Promise<InjectionResult>;
+    forget(memoryId: string): Promise<boolean>;
+    forgetMany(memoryIds: string[]): Promise<number>;
+    suppressTopic(topicId: string): Promise<boolean>;
+    restoreTopic(topicId: string): Promise<boolean>;
+    getMemoryHistory(memoryId: string, options?: MemoryHistoryOptions): Promise<MemoryHistoryResult>;
+    getMemoryHistory(subject: string, predicate: string, options?: MemoryHistoryOptions): Promise<MemoryHistoryResult>;
+    getMemoryDiff(fromMemoryId: string, toMemoryId: string): Promise<MemoryDiff>;
     graftByRelevance(sessionId: string, query: string, options?: GraftByRelevanceOptions): Promise<InjectionResult>;
     ingestGraftedNodes(nodes: TopicNode[], targetSessionId: string): Promise<TopicNode[]>;
     selectNodesForAbsorb(sourceSessionId: string, options: AbsorbFromAgentOptions): Promise<TopicNode[]>;
@@ -36,5 +40,7 @@ export declare class MemoGrafter {
     close(): Promise<void>;
     private assertServerEnvironment;
     private toTextPipelineOptions;
+    private clearRecallCache;
+    private resolveSessionIds;
 }
 //# sourceMappingURL=MemoGrafter.d.ts.map

package/dist/MemoGrafter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MemoGrafter.d.ts","sourceRoot":"","sources":["../src/MemoGrafter.ts"],"names":[],"mappings":"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"}
+{"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,uBAAuB,EACvB,aAAa,EAEb,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,UAAU,EACV,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,OAAO,EACP,gBAAgB,EAChB,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;IACjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,MAAM,EAAE,iBAAiB;IAuDrC,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;IASvG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAiB,GAAG,aAAkB,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IAS5G,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAiB,GAAG,aAAkB,GAAG,OAAO,CAAC,IAAI,CAAC;IAUlH,SAAS,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;KAAE,CAAC;IAM7H,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAIjE,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAM1C,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAMhD,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMhD,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAMrD,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAChG,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAalH,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAItE,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,eAAe,CAAC;IA+BrB,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;IAW/B,OAAO,CAAC,qBAAqB;YAUf,gBAAgB;IAa9B,OAAO,CAAC,iBAAiB;CAI1B"}

package/dist/MemoGrafter.js

@@ -107,18 +107,61 @@ export class MemoGrafter {
     inject(sessionId, topicIds) {
         return this.grafterPipeline.run(sessionId, topicIds);
     }
+    async forget(memoryId) {
+        const changed = await this.store.forgetMemory(memoryId);
+        if (changed)
+            await this.clearRecallCache();
+        return changed;
+    }
+    async forgetMany(memoryIds) {
+        const changed = await this.store.forgetMemories(memoryIds);
+        if (changed > 0)
+            await this.clearRecallCache();
+        return changed;
+    }
+    async suppressTopic(topicId) {
+        const changed = await this.store.suppressTopic(topicId);
+        if (changed)
+            await this.clearRecallCache();
+        return changed;
+    }
+    async restoreTopic(topicId) {
+        const changed = await this.store.restoreTopic(topicId);
+        if (changed)
+            await this.clearRecallCache();
+        return changed;
+    }
+    getMemoryHistory(memoryIdOrSubject, predicateOrOptions, options = {}) {
+        if (typeof predicateOrOptions === "string") {
+            return this.store.getMemoryHistoryByFact(memoryIdOrSubject, predicateOrOptions, options);
+        }
+        return this.store.getMemoryHistoryById(memoryIdOrSubject, predicateOrOptions ?? {});
+    }
+    getMemoryDiff(fromMemoryId, toMemoryId) {
+        return this.store.getMemoryDiff(fromMemoryId, toMemoryId);
+    }
     async graftByRelevance(sessionId, query, options = {}) {
         const embedding = await this.embedder.embed(query);
-        const seedNodes = await this.store.getSimilarNodes(embedding, sessionId, {
-            k: options.topK ?? this.graphTopK,
-            minSimilarity: options.minSimilarity ?? 0.6,
-        });
+        const configuredSessionIds = options.sessionIds?.filter(Boolean) ?? [];
+        const sessionIds = this.resolveSessionIds(sessionId, configuredSessionIds);
+        const useConfiguredSessions = configuredSessionIds.length > 0
+            && (sessionIds.length > 1 || sessionIds[0] !== sessionId);
+        const seedNodes = useConfiguredSessions
+            ? await this.store.getSimilarNodesAcrossSessions(embedding, sessionIds, {
+                k: options.topK ?? this.graphTopK,
+                minSimilarity: options.minSimilarity ?? 0.6,
+            })
+            : await this.store.getSimilarNodes(embedding, sessionId, {
+                k: options.topK ?? this.graphTopK,
+                minSimilarity: options.minSimilarity ?? 0.6,
+            });
         if (seedNodes.length === 0) {
             return { systemPrompt: "", nodes: [], tokenCount: 0 };
         }
         return this.grafterPipeline.run(sessionId, seedNodes.map((node) => node.id), {
             hopDepth: options.hopDepth ?? this.graphHopDepth,
             expansionStrategy: options.expansionStrategy ?? "graph",
+            ...(configuredSessionIds.length > 0 ? { sessionIds } : {}),
         });
     }
     async ingestGraftedNodes(nodes, targetSessionId) {
@@ -172,5 +215,22 @@ export class MemoGrafter {
             sourceType: "document",
         };
     }
+    async clearRecallCache() {
+        if (!this.recallCache)
+            return;
+        try {
+            const keys = await this.recallCache.keys("mg:recall:*");
+            if (keys.length > 0) {
+                await this.recallCache.del(...keys);
+            }
+        }
+        catch (error) {
+            console.warn("MemoGrafter recall cache invalidation warning:", error);
+        }
+    }
+    resolveSessionIds(sessionId, configured) {
+        const sessionIds = configured && configured.length > 0 ? configured : [sessionId];
+        return [...new Set(sessionIds)];
+    }
 }
 //# sourceMappingURL=MemoGrafter.js.map