@brainbank/memory 0.1.0

package/README.md

@@ -0,0 +1,189 @@
+# @brainbank/memory
+
+Deterministic memory extraction and deduplication for LLM conversations. Inspired by [mem0](https://github.com/mem0ai/mem0)'s pipeline.
+
+After every conversation turn, automatically:
+
+1. **Extract** atomic facts via LLM call
+2. **Search** existing memories for duplicates
+3. **Decide** ADD / UPDATE / NONE per fact
+4. **Execute** the operations
+
+No function calling. No relying on the model to "remember" to save.
+
+## Install
+
+```bash
+npm install @brainbank/memory
+```
+
+## Quick Start
+
+```typescript
+import { BrainBank } from 'brainbank';
+import { Memory, OpenAIProvider } from '@brainbank/memory';
+
+const brain = new BrainBank({ dbPath: './memory.db' });
+await brain.initialize();
+
+const memory = new Memory(brain.collection('memories'), {
+  llm: new OpenAIProvider({ model: 'gpt-4.1-nano' }),
+});
+
+// After every conversation turn — deterministic, automatic
+const ops = await memory.process(
+  'My name is Berna, I prefer TypeScript',
+  'Nice to meet you Berna!'
+);
+// ops → [
+//   { fact: "User's name is Berna", action: "ADD", reason: "no similar memories" },
+//   { fact: "User prefers TypeScript", action: "ADD", reason: "no similar memories" }
+// ]
+
+// Next turn — dedup kicks in
+await memory.process(
+  'I like TypeScript a lot',
+  'TypeScript is great!'
+);
+// → [{ fact: "User likes TypeScript", action: "NONE", reason: "already captured" }]
+
+// Build system prompt context
+const context = memory.buildContext();
+// → "## Memories\n- User's name is Berna\n- User prefers TypeScript"
+
+// Semantic search
+const results = await memory.search('what language does user prefer');
+```
+
+## Framework Integration
+
+The `LLMProvider` interface is framework-agnostic. Bring your own LLM:
+
+### LangChain
+
+```typescript
+import { ChatOpenAI } from '@langchain/openai';
+import { Memory } from '@brainbank/memory';
+import type { LLMProvider } from '@brainbank/memory';
+
+const model = new ChatOpenAI({ model: 'gpt-4.1-nano' });
+
+const llm: LLMProvider = {
+  generate: async (messages, opts) => {
+    const res = await model.invoke(messages);
+    return res.content as string;
+  }
+};
+
+const memory = new Memory(store, { llm });
+```
+
+### Vercel AI SDK
+
+```typescript
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { Memory } from '@brainbank/memory';
+import type { LLMProvider } from '@brainbank/memory';
+
+const llm: LLMProvider = {
+  generate: async (messages) => {
+    const { text } = await generateText({
+      model: openai('gpt-4.1-nano'),
+      messages,
+    });
+    return text;
+  }
+};
+
+const memory = new Memory(store, { llm });
+```
+
+### Anthropic / Other Providers
+
+```typescript
+const llm: LLMProvider = {
+  generate: async (messages) => {
+    // Call any LLM API that takes messages and returns a string
+    const response = await yourLLMClient.chat(messages);
+    return response.text;
+  }
+};
+```
+
+## Custom Storage
+
+The `MemoryStore` interface matches BrainBank collections, but you can implement your own:
+
+```typescript
+import type { MemoryStore } from '@brainbank/memory';
+
+const store: MemoryStore = {
+  add: async (content, opts) => { /* store in your DB */ },
+  search: async (query, opts) => { /* semantic search */ },
+  list: (opts) => { /* return recent items */ },
+  remove: async (id) => { /* delete by ID */ },
+  count: () => { /* return total */ },
+};
+
+const memory = new Memory(store, { llm });
+```
+
+## Options
+
+```typescript
+new Memory(store, {
+  llm: provider,            // required — LLM provider
+  maxFacts: 5,              // max facts to extract per turn (default: 5)
+  maxMemories: 50,          // max existing memories to load for dedup (default: 50)
+  dedupTopK: 3,             // similar memories to compare against (default: 3)
+  extractPrompt: '...',     // custom extraction prompt
+  dedupPrompt: '...',       // custom dedup prompt
+  onOperation: (op) => {    // callback for each operation
+    console.log(`${op.action}: ${op.fact}`);
+  },
+});
+```
+
+## API
+
+| Method | Description |
+|--------|-------------|
+| `process(userMsg, assistantMsg)` | Run the full pipeline: extract → dedup → execute. Returns `MemoryOperation[]` |
+| `search(query, k?)` | Semantic search across memories |
+| `recall(limit?)` | Get all memories (for system prompt injection) |
+| `count()` | Total stored memories |
+| `buildContext(limit?)` | Build a markdown section for system prompt injection |
+
+## How it works
+
+```
+User message + Assistant response
+          │
+          ▼
+  ┌─── Extract (LLM) ───┐
+  │ "User's name is X"   │
+  │ "Prefers TypeScript"  │
+  └──────────┬───────────┘
+             │ for each fact:
+             ▼
+  ┌─── Search (semantic) ─┐
+  │ Find similar existing  │
+  │ memories (top-K)       │
+  └──────────┬────────────┘
+             │
+             ▼
+  ┌─── Dedup (LLM) ──────┐
+  │ Compare new vs existing│
+  │ → ADD / UPDATE / NONE  │
+  └──────────┬────────────┘
+             │
+     ┌───────┼───────┐
+     ▼       ▼       ▼
+    ADD   UPDATE   NONE
+  (store) (replace) (skip)
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * @brainbank/memory — LLM Provider Interface
+ *
+ * Framework-agnostic interface for LLM calls.
+ * Implement this to use any LLM: OpenAI, Anthropic, LangChain, Vercel AI SDK, etc.
+ */
+interface ChatMessage {
+    role: 'system' | 'user' | 'assistant';
+    content: string;
+}
+interface GenerateOptions {
+    /** Request JSON output */
+    json?: boolean;
+    /** Max tokens for response */
+    maxTokens?: number;
+}
+/**
+ * LLM provider interface. Implement this to bring your own model.
+ *
+ * @example OpenAI
+ * ```typescript
+ * const llm = new OpenAIProvider({ apiKey: 'sk-...', model: 'gpt-4.1-nano' });
+ * ```
+ *
+ * @example LangChain
+ * ```typescript
+ * import { ChatOpenAI } from '@langchain/openai';
+ * const model = new ChatOpenAI({ model: 'gpt-4.1-nano' });
+ * const llm: LLMProvider = {
+ *   generate: async (messages, opts) => {
+ *     const res = await model.invoke(messages);
+ *     return res.content as string;
+ *   }
+ * };
+ * ```
+ *
+ * @example Vercel AI SDK
+ * ```typescript
+ * import { generateText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ * const llm: LLMProvider = {
+ *   generate: async (messages) => {
+ *     const { text } = await generateText({ model: openai('gpt-4.1-nano'), messages });
+ *     return text;
+ *   }
+ * };
+ * ```
+ */
+interface LLMProvider {
+    generate(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+}
+interface OpenAIProviderOptions {
+    /** OpenAI API key. Defaults to OPENAI_API_KEY env var. */
+    apiKey?: string;
+    /** Model name. Default: gpt-4.1-nano */
+    model?: string;
+    /** Base URL for API. Default: https://api.openai.com/v1 */
+    baseUrl?: string;
+}
+declare class OpenAIProvider implements LLMProvider {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    constructor(options?: OpenAIProviderOptions);
+    generate(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
+}
+
+/**
+ * @brainbank/memory — Deterministic Memory Pipeline
+ *
+ * Automatic fact extraction and deduplication for LLM conversations.
+ * Runs after every turn: extract → search → dedup → ADD/UPDATE/NONE.
+ */
+
+interface MemoryItem {
+    id?: string | number;
+    content: string;
+    score?: number;
+    metadata?: Record<string, any>;
+}
+type MemoryAction = 'ADD' | 'UPDATE' | 'NONE';
+interface MemoryOperation {
+    fact: string;
+    action: MemoryAction;
+    reason: string;
+}
+/**
+ * Collection interface — matches BrainBank's collection API.
+ * Implement this to use a different storage backend.
+ */
+interface MemoryStore {
+    add(content: string, options?: {
+        tags?: string[];
+        metadata?: Record<string, any>;
+    }): Promise<any>;
+    search(query: string, options?: {
+        k?: number;
+    }): Promise<MemoryItem[]>;
+    list(options?: {
+        limit?: number;
+    }): MemoryItem[];
+    remove(id: string | number): void | Promise<void>;
+    count(): number;
+}
+interface MemoryOptions {
+    /** LLM provider for extraction and dedup */
+    llm: LLMProvider;
+    /** Max facts to extract per turn. Default: 5 */
+    maxFacts?: number;
+    /** Max existing memories to compare against for dedup. Default: 50 */
+    maxMemories?: number;
+    /** Number of similar memories to check for dedup. Default: 3 */
+    dedupTopK?: number;
+    /** Custom extraction prompt (replaces default) */
+    extractPrompt?: string;
+    /** Custom dedup prompt (replaces default) */
+    dedupPrompt?: string;
+    /** Called for each memory operation */
+    onOperation?: (op: MemoryOperation) => void;
+}
+declare class Memory {
+    private readonly store;
+    private readonly llm;
+    private readonly maxFacts;
+    private readonly maxMemories;
+    private readonly dedupTopK;
+    private readonly extractPrompt;
+    private readonly dedupPrompt;
+    private readonly onOperation?;
+    constructor(store: MemoryStore, options: MemoryOptions);
+    /**
+     * Process a conversation turn — extract facts and store/update memories.
+     * This is the main entry point. Call after every user↔assistant exchange.
+     */
+    process(userMessage: string, assistantMessage: string): Promise<MemoryOperation[]>;
+    /**
+     * Search memories semantically.
+     */
+    search(query: string, k?: number): Promise<MemoryItem[]>;
+    /**
+     * Get all memories (for system prompt injection).
+     */
+    recall(limit?: number): MemoryItem[];
+    /**
+     * Get memory count.
+     */
+    count(): number;
+    /**
+     * Build a system prompt section with all memories.
+     * Drop this into your system prompt.
+     */
+    buildContext(limit?: number): string;
+    private extract;
+    private dedup;
+}
+
+export { type ChatMessage, type GenerateOptions, type LLMProvider, Memory, type MemoryAction, type MemoryItem, type MemoryOperation, type MemoryOptions, type MemoryStore, OpenAIProvider, type OpenAIProviderOptions };

package/dist/index.js

@@ -0,0 +1,186 @@
+// src/prompts.ts
+var EXTRACT_PROMPT = `You are a memory extraction engine. Given a conversation turn between a user and an assistant, extract distinct atomic facts worth remembering for future conversations.
+
+Focus on:
+- User preferences (language, tools, patterns, style)
+- User personal info (name, role, projects)
+- Decisions made (architecture, design, technology choices)
+- Important context (deadlines, constraints, goals)
+
+Respond with JSON: { "facts": ["fact1", "fact2", ...] }
+If nothing is worth remembering, return: { "facts": [] }
+
+Rules:
+- Each fact must be a single, self-contained sentence
+- Be specific ("prefers TypeScript" not "has programming preferences")
+- Skip trivial info ("said hello", "asked a question")
+- Max 5 facts per turn`;
+var DEDUP_PROMPT = `You are a memory deduplication engine. Given a NEW fact and a list of EXISTING memories, decide what action to take.
+
+Respond with JSON: { "action": "ADD" | "UPDATE" | "NONE", "reason": "brief reason" }
+
+- ADD: the fact is genuinely new information not covered by any existing memory
+- UPDATE: the fact updates, corrects, or expands an existing memory (include "update_index" field: 0-based index)
+- NONE: the fact is already well-captured by existing memories
+
+Be conservative \u2014 if in doubt, say NONE.`;
+
+// src/memory.ts
+var Memory = class {
+  store;
+  llm;
+  maxFacts;
+  maxMemories;
+  dedupTopK;
+  extractPrompt;
+  dedupPrompt;
+  onOperation;
+  constructor(store, options) {
+    this.store = store;
+    this.llm = options.llm;
+    this.maxFacts = options.maxFacts ?? 5;
+    this.maxMemories = options.maxMemories ?? 50;
+    this.dedupTopK = options.dedupTopK ?? 3;
+    this.extractPrompt = options.extractPrompt ?? EXTRACT_PROMPT;
+    this.dedupPrompt = options.dedupPrompt ?? DEDUP_PROMPT;
+    this.onOperation = options.onOperation;
+  }
+  /**
+   * Process a conversation turn — extract facts and store/update memories.
+   * This is the main entry point. Call after every user↔assistant exchange.
+   */
+  async process(userMessage, assistantMessage) {
+    const facts = await this.extract(userMessage, assistantMessage);
+    if (facts.length === 0) return [];
+    const existing = this.store.list({ limit: this.maxMemories });
+    const operations = [];
+    for (const fact of facts) {
+      const op = await this.dedup(fact, existing);
+      operations.push(op);
+      this.onOperation?.(op);
+      switch (op.action) {
+        case "ADD":
+          await this.store.add(fact);
+          break;
+        case "UPDATE": {
+          const similar = await this.store.search(fact, { k: this.dedupTopK });
+          const target = similar[0];
+          if (target?.id) {
+            await this.store.remove(target.id);
+            await this.store.add(fact);
+          }
+          break;
+        }
+        case "NONE":
+          break;
+      }
+    }
+    return operations;
+  }
+  /**
+   * Search memories semantically.
+   */
+  async search(query, k = 5) {
+    return this.store.search(query, { k });
+  }
+  /**
+   * Get all memories (for system prompt injection).
+   */
+  recall(limit = 20) {
+    return this.store.list({ limit });
+  }
+  /**
+   * Get memory count.
+   */
+  count() {
+    return this.store.count();
+  }
+  /**
+   * Build a system prompt section with all memories.
+   * Drop this into your system prompt.
+   */
+  buildContext(limit = 20) {
+    const items = this.store.list({ limit });
+    if (items.length === 0) return "";
+    return "## Memories\n" + items.map((m) => `- ${m.content}`).join("\n");
+  }
+  // ─── Internal ───────────────────────────────────
+  async extract(userMsg, assistantMsg) {
+    const response = await this.llm.generate([
+      { role: "system", content: this.extractPrompt },
+      { role: "user", content: `User: ${userMsg}
+
+Assistant: ${assistantMsg}` }
+    ], { json: true, maxTokens: 300 });
+    try {
+      const parsed = JSON.parse(response);
+      const facts = parsed.facts ?? [];
+      return facts.slice(0, this.maxFacts);
+    } catch {
+      return [];
+    }
+  }
+  async dedup(fact, _existing) {
+    const similar = await this.store.search(fact, { k: this.dedupTopK });
+    if (similar.length === 0) {
+      return { fact, action: "ADD", reason: "no similar memories found" };
+    }
+    const context = similar.map((m, i) => `[${i}] ${m.content}`).join("\n");
+    const response = await this.llm.generate([
+      { role: "system", content: this.dedupPrompt },
+      { role: "user", content: `NEW FACT: "${fact}"
+
+EXISTING MEMORIES:
+${context}` }
+    ], { json: true, maxTokens: 150 });
+    try {
+      const parsed = JSON.parse(response);
+      return {
+        fact,
+        action: parsed.action ?? "ADD",
+        reason: parsed.reason ?? ""
+      };
+    } catch {
+      return { fact, action: "ADD", reason: "parse error, defaulting to ADD" };
+    }
+  }
+};
+
+// src/llm.ts
+var OpenAIProvider = class {
+  apiKey;
+  model;
+  baseUrl;
+  constructor(options = {}) {
+    this.apiKey = options.apiKey ?? process.env.OPENAI_API_KEY ?? "";
+    this.model = options.model ?? "gpt-4.1-nano";
+    this.baseUrl = options.baseUrl ?? "https://api.openai.com/v1";
+    if (!this.apiKey) {
+      throw new Error("@brainbank/memory: OPENAI_API_KEY is required for OpenAIProvider");
+    }
+  }
+  async generate(messages, options) {
+    const res = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.apiKey}`
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages,
+        max_tokens: options?.maxTokens ?? 500,
+        ...options?.json ? { response_format: { type: "json_object" } } : {}
+      })
+    });
+    if (!res.ok) {
+      throw new Error(`OpenAI error ${res.status}: ${await res.text()}`);
+    }
+    const data = await res.json();
+    return data.choices?.[0]?.message?.content ?? "";
+  }
+};
+export {
+  Memory,
+  OpenAIProvider
+};

package/package.json

@@ -0,0 +1,32 @@
+{
+    "name": "@brainbank/memory",
+    "version": "0.1.0",
+    "description": "Deterministic memory extraction and deduplication for LLM conversations — extract, dedup, ADD/UPDATE/NONE",
+    "type": "module",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "exports": {
+        ".": { "import": "./dist/index.js", "types": "./dist/index.d.ts" }
+    },
+    "files": ["dist/"],
+    "scripts": {
+        "build": "tsup"
+    },
+    "peerDependencies": {
+        "brainbank": ">=0.2.0"
+    },
+    "peerDependenciesMeta": {
+        "brainbank": { "optional": true }
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/pinecall/brainbank.git",
+        "directory": "packages/memory"
+    },
+    "keywords": [
+        "memory", "llm", "ai", "agent", "langchain", "deduplication",
+        "fact-extraction", "conversation-memory", "rag", "brainbank"
+    ],
+    "author": "Bernardo Castro <bernardo@pinecall.io>",
+    "license": "MIT"
+}