memo-grafter 0.1.0 → 0.2.0

package/.env.example

@@ -1,3 +1,5 @@
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/memograffer
-OPENAI_API_KEY=
-REDIS_URL=redis://localhost:6379
+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

@@ -1,182 +1,187 @@
-# MemoGrafter
-
-Experimental structured memory for TypeScript chatbots.
-
-MemoGrafter turns chatbot conversations into topic segments, topic nodes, and graph edges, then injects relevant memory into future turns. Its core idea is memory grafting: copying useful conversational memory from one chatbot or session into another.
-
-MemoGrafter is a chatbot memory framework. It is not an autonomous agent runtime.
-
-## Why MemoGrafter?
-
-Most chatbots either forget old context or keep stuffing long chat history back into the prompt. MemoGrafter explores a different shape:
-
-- store conversations as structured memory
-- detect topic shifts
-- summarize topic segments into memory nodes
-- connect related nodes in a graph
-- inject only relevant memory into later calls
-- graft selected memory into another chatbot/session
-
-The project is early-stage and experimental, but it is useful for demos, prototypes, and exploring memory workflows beyond plain chat history.
-
-## How It Works
-
-```text
-chat messages
-  -> topic segments
-  -> topic nodes
-  -> graph edges
-  -> memory injection
-  -> selective grafting into another chatbot
-```
-
-On each chatbot call, MemoGrafter can retrieve existing topic memory and pass it to the LLM as a system prompt. After the response, it ingests the updated conversation so future turns have better memory.
-
-## Installation
-
-```bash
-npm install memo-grafter
-```
-
-For local development from this repository:
-
-```bash
-git clone <repo-url> project-memoGrafter
-cd project-memoGrafter
-npm install
-npm run build
-```
-
-Then install it from a local app:
-
-```bash
-npm install D:/cohort/projects/project-memoGrafter
-```
-
-## Environment
-
-```bash
-DATABASE_URL=postgres://postgres:postgres@localhost:5432/memo_grafter
-OPENAI_API_KEY=sk-...
-REDIS_URL=redis://localhost:6379
-```
-
-`DATABASE_URL` is required. PostgreSQL must have `pgvector` enabled.
-
-`OPENAI_API_KEY` is only needed when using the included OpenAI adapters.
-
-`REDIS_URL` is optional and only needed for queue mode.
-
-## Minimal Usage
-
-```ts
-import "dotenv/config";
-
-import {
-  MemoGrafterAgent,
-  OpenAIEmbedAdapter,
-  OpenAILLMAdapter,
-} from "memo-grafter";
-
-const agent = new MemoGrafterAgent({
-  db: {
-    connectionString: process.env.DATABASE_URL!,
-  },
-  llm: new OpenAILLMAdapter("gpt-4o"),
-  embedder: new OpenAIEmbedAdapter("text-embedding-3-small"),
-});
-
-await agent.initialize();
-
-console.log(await agent.invoke("I am planning a Japan trip."));
-console.log(await agent.invoke("I like quiet towns, bookstores, and local cafes."));
-
-const nodes = await agent.getActiveNodes();
-console.log(nodes.map((node) => ({ label: node.label, summary: node.summary })));
-
-await agent.close();
-```
-
-Run with:
-
-```bash
-npx tsx --env-file=.env src/index.ts
-```
-
-## Memory Grafting
-
-Memory grafting copies selected memory from one chatbot/session into another.
-
-```ts
-const travelBot = new MemoGrafterAgent(config);
-const writingBot = new MemoGrafterAgent(config);
-
-await travelBot.initialize();
-await writingBot.initialize();
-
-await travelBot.invoke("I am planning a Japan trip.");
-await travelBot.invoke("I like quiet towns, bookstores, and local cafes.");
-await travelBot.invoke("My budget is around 2500 dollars.");
-
-await writingBot.absorbFromAgent(travelBot, {
-  prompt: "Japan travel preferences",
-  minSimilarity: 0.6,
-  limit: 3,
-});
-
-const intro = await writingBot.invoke(
-  "Suggest a reflective blog intro for my Japan trip."
-);
-
-console.log(intro);
-
-await travelBot.close();
-await writingBot.close();
-```
-
-You can also preview a graft before copying it:
-
-```ts
-const graft = await travelBot.graft();
-
-console.log(graft.systemPrompt);
-console.log(graft.nodes);
-console.log(graft.tokenCount);
-```
-
-## Key Features
-
-- Structured chatbot memory over PostgreSQL and pgvector.
-- Topic drift detection for splitting conversations into segments.
-- Topic nodes with summaries, embeddings, message ranges, and graph edges.
-- Automatic memory injection during chatbot calls.
-- Selective memory grafting by topic ID or semantic prompt.
-- Optional BullMQ/Redis queue mode for background ingestion.
-- OpenAI adapters included.
-- Custom LLM and embedding adapters supported.
-- Minimal fleet API for color-scoped worker chatbots and conductor grafting.
-
-## Requirements
-
-- Node.js 18 or newer.
-- Server-side Node.js runtime.
-- PostgreSQL with `pgvector`.
-- An LLM adapter and embedding adapter.
-- OpenAI API key if using `OpenAILLMAdapter` or `OpenAIEmbedAdapter`.
-- Redis only if using queue mode.
-
-MemoGrafter does not run in browser code.
-
-## Learn More
-
-Read the full [USER_GUIDE.md](./USER_GUIDE.md) for setup, concepts, configuration, queue mode, custom adapters, fleet usage, examples, and troubleshooting.
-
-This repository also includes a runnable demo:
-
-```text
-examples/chatbot-memory-demo
-```
-
-## License
-
-MIT
+# MemoGrafter
+[![npm version](https://img.shields.io/npm/v/memo-grafter.svg)](https://www.npmjs.com/package/memo-grafter)
+
+Structured memory for TypeScript chatbots.
+
+MemoGrafter helps chatbot applications remember conversations without stuffing every old message back into the prompt. It turns conversations into topic-based memory, retrieves the relevant parts 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.
+
+## What You Can Build
+
+- 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.
+
+## How It Works
+
+At a high level:
+
+```text
+chat messages
+  -> topic segments
+  -> memory nodes
+  -> graph links
+  -> relevant memory injection
+  -> 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. Drift detection uses embedding distance, sharp message pivots, short-message dampening, and structural phrases like "by the way" or "going back to" to split conversations into useful topic segments. Memory grafting lets one chatbot or session copy selected memory from another.
+
+## Install
+
+```bash
+npm install memo-grafter
+```
+
+MemoGrafter runs server-side on Node.js. The built-in storage implementation is `PostgresGraphStore`, which requires PostgreSQL with `pgvector`. Included provider adapters require their matching API keys.
+
+```bash
+DATABASE_URL=postgres://postgres:postgres@localhost:5432/memo_grafter
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=...
+OPENAI_API_KEY=sk-...
+```
+
+## Minimal Example
+
+```ts
+import "dotenv/config";
+
+import {
+  MemoGrafterAgent,
+  OpenAIEmbedAdapter,
+  OpenAILLMAdapter,
+} from "memo-grafter";
+
+const agent = new MemoGrafterAgent({
+  db: { connectionString: process.env.DATABASE_URL! },
+  llm: new OpenAILLMAdapter("gpt-4o"),
+  embedder: new OpenAIEmbedAdapter("text-embedding-3-small"),
+});
+
+await agent.initialize();
+
+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?"));
+
+const recall = await agent.recall("travel preferences", {
+  limit: 5,
+  minSimilarity: 0.6,
+});
+
+console.log(recall.facts);
+console.log(recall.systemPrompt);
+
+await agent.close();
+```
+
+## Adapters
+
+MemoGrafter includes provider adapters such as `OpenAILLMAdapter`, `OpenAIEmbedAdapter`, `AnthropicLLMAdapter`, `GeminiLLMAdapter`, and `GeminiEmbedAdapter`. You can also bring any provider by implementing the public adapter interfaces:
+
+```ts
+import {
+  type EmbedAdapter,
+  type LLMAdapter,
+  type Message,
+} from "memo-grafter";
+
+class MyLLMAdapter implements LLMAdapter {
+  async complete(messages: Message[], system?: string): Promise<string> {
+    // Call your model provider here.
+    return "Assistant response";
+  }
+}
+
+class MyEmbedAdapter implements EmbedAdapter {
+  async embed(text: string): Promise<number[]> {
+    // Return an embedding vector matching your storage schema.
+    return [];
+  }
+}
+```
+
+## Storage
+
+MemoGrafter uses a public `GraphStore` interface internally. The default implementation is `PostgresGraphStore`, backed by PostgreSQL and `pgvector`, and this is what `MemoGrafter` and `MemoGrafterAgent` construct from the `db.connectionString` config today.
+
+```ts
+import {
+  PostgresGraphStore,
+  type GraphStore,
+} from "memo-grafter";
+
+const store: GraphStore = new PostgresGraphStore(process.env.DATABASE_URL!);
+```
+
+The interface boundary keeps the Postgres implementation isolated and gives future storage backends a clear contract to implement.
+
+## Targeted Recall
+
+Use `agent.recall()` when you want structured memory back without asking the LLM to answer yet. It searches atomic memory nodes by meaning, filters stale memories, groups them with their parent topic summaries, and returns a prompt block you can inspect or pass to your own model call.
+
+```ts
+const result = await agent.recall("deployment config", {
+  limit: 8,
+  minSimilarity: 0.55,
+  tokenBudget: 1000,
+});
+
+console.log(result.facts);
+console.log(result.nodes);
+console.log(result.systemPrompt);
+console.log(result.tokenCount);
+```
+
+`recall()` is side-effect free. It does not call `invoke()`, does not mutate chat history, and does not inject anything automatically.
+
+## Memory Grafting
+
+Memory grafting is the core idea behind the name: one chatbot can build memory, and another chatbot can absorb only the useful parts.
+
+```ts
+await writingBot.absorbFromAgent(travelBot, {
+  prompt: "Japan travel preferences",
+  limit: 3,
+});
+```
+
+## Drift And Reentry
+
+Use `driftSensitivity` for developer-friendly topic segmentation:
+
+```ts
+const agent = new MemoGrafterAgent({
+  db: { connectionString: process.env.DATABASE_URL! },
+  llm,
+  embedder,
+  drift: {
+    mode: "intent",
+    driftSensitivity: "medium",
+    minSegmentMessages: 3,
+    reentryDetection: true,
+  },
+});
+```
+
+Sensitivity presets are `"low"`, `"medium"`, and `"high"`. The older numeric `threshold` option is still accepted for compatibility, but `driftSensitivity` is preferred.
+
+When a conversation returns to an earlier topic, MemoGrafter can create a `reentry` edge between the new topic node and the earlier related topic node. For example, a chat can move from database decisions to authentication, then back to database pooling; the later database segment is linked back to the original database topic instead of becoming an isolated duplicate.
+
+## 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
+```
+
+## License
+
+MIT