@brainbank/memory 0.1.0 → 0.2.0

package/README.md

@@ -1,13 +1,14 @@
 # @brainbank/memory
 
-Deterministic memory extraction and deduplication for LLM conversations. Inspired by [mem0](https://github.com/mem0ai/mem0)'s pipeline.
+Deterministic memory extraction, deduplication, and entity graph for LLM conversations. Framework-agnostic — works with any LLM provider.
 
 After every conversation turn, automatically:
 
-1. **Extract** atomic facts via LLM call
+1. **Extract** atomic facts + entities + relationships via LLM call
 2. **Search** existing memories for duplicates
 3. **Decide** ADD / UPDATE / NONE per fact
-4. **Execute** the operations
+4. **Upsert** entities and relationships into the knowledge graph
+5. **Execute** the operations
 
 No function calling. No relying on the model to "remember" to save.
 
@@ -31,11 +32,11 @@ const memory = new Memory(brain.collection('memories'), {
 });
 
 // After every conversation turn — deterministic, automatic
-const ops = await memory.process(
+const result = await memory.process(
   'My name is Berna, I prefer TypeScript',
   'Nice to meet you Berna!'
 );
-// ops → [
+// result.operations → [
 //   { fact: "User's name is Berna", action: "ADD", reason: "no similar memories" },
 //   { fact: "User prefers TypeScript", action: "ADD", reason: "no similar memories" }
 // ]
@@ -45,7 +46,7 @@ await memory.process(
   'I like TypeScript a lot',
   'TypeScript is great!'
 );
-// → [{ fact: "User likes TypeScript", action: "NONE", reason: "already captured" }]
+// → operations: [{ fact: "User likes TypeScript", action: "NONE", reason: "already captured" }]
 
 // Build system prompt context
 const context = memory.buildContext();
@@ -55,6 +56,72 @@ const context = memory.buildContext();
 const results = await memory.search('what language does user prefer');
 ```
 
+## Entity Extraction (Knowledge Graph)
+
+Opt-in entity and relationship extraction from the same LLM call — zero extra cost:
+
+```typescript
+import { Memory, EntityStore, OpenAIProvider } from '@brainbank/memory';
+
+const entityStore = new EntityStore({
+  entityCollection: brain.collection('entities'),
+  relationCollection: brain.collection('relationships'),
+});
+
+const memory = new Memory(brain.collection('memories'), {
+  llm: new OpenAIProvider({ model: 'gpt-4.1-nano' }),
+  entityStore,  // opt-in — omit for facts-only mode
+});
+
+// Process extracts facts + entities + relationships in one LLM call
+const result = await memory.process(
+  'Tell Juan to migrate payments to Stripe before Friday',
+  "I'll let Juan know about the Stripe migration deadline."
+);
+// result.operations → [{ fact: "deadline for Stripe migration is Friday", action: "ADD" }]
+// result.entities   → { entitiesProcessed: 2, relationshipsProcessed: 1 }
+
+// Query entities
+const related = await entityStore.getRelated('Juan');
+// → [{ source: "Juan", target: "Stripe", relation: "migrating_to" }]
+
+// Build context includes entities
+const context = memory.buildContext();
+// → "## Memories\n- ...\n\n## Known Entities\n- Juan (person, 2x)\n- Stripe (service, 1x)\n\n## Relationships\n- Juan → migrating_to → Stripe"
+```
+
+### EntityStore API
+
+| Method | Description |
+|--------|-------------|
+| `upsert(entity)` | Add or update entity (increments mention count) |
+| `relate(source, target, relation, context?)` | Add a relationship |
+| `findEntity(name)` | Search entities by name (semantic) |
+| `getRelated(entityName)` | Get all relationships for an entity |
+| `relationsOf(entityName)` | Shorthand for `getRelated()` |
+| `listEntities({ type?, limit? })` | List entities, optionally filtered by type |
+| `listRelationships()` | List all relationships |
+| `traverse(entity, maxDepth?)` | Multi-hop BFS graph traversal (default: 2 hops) |
+| `entityCount()` | Total entity count |
+| `relationCount()` | Total relationship count |
+| `buildContext(entityName?)` | Build markdown context (all or specific entity) |
+| `processExtraction(entities, relationships)` | Batch process from LLM response |
+
+#### Graph Traversal
+
+```typescript
+// Explore the entity graph from a starting point
+const graph = await entityStore.traverse('Juan', 2);
+// graph.nodes → [
+//   { entity: "Stripe", relation: "migrating_to", depth: 1, path: ["Juan", "Stripe"] },
+//   { entity: "Payments", relation: "uses", depth: 2, path: ["Juan", "Stripe", "Payments"] }
+// ]
+
+// Filter entities by type
+const people = entityStore.listEntities({ type: 'person' });
+const services = entityStore.listEntities({ type: 'service' });
+```
+
 ## Framework Integration
 
 The `LLMProvider` interface is framework-agnostic. Bring your own LLM:
@@ -134,6 +201,7 @@ const memory = new Memory(store, { llm });
 ```typescript
 new Memory(store, {
   llm: provider,            // required — LLM provider
+  entityStore: entityStore,  // optional — enables entity extraction
   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)
@@ -149,11 +217,12 @@ new Memory(store, {
 
 | Method | Description |
 |--------|-------------|
-| `process(userMsg, assistantMsg)` | Run the full pipeline: extract → dedup → execute. Returns `MemoryOperation[]` |
+| `process(userMsg, assistantMsg)` | Full pipeline: extract → dedup → execute. Returns `ProcessResult` |
 | `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 |
+| `buildContext(limit?)` | Build markdown context (memories + entities if enabled) |
+| `getEntityStore()` | Get the entity store instance (if enabled) |
 
 ## How it works
 
@@ -161,27 +230,27 @@ new Memory(store, {
 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  │
-  └──────────┬────────────┘
+  ┌─── Extract (LLM) ──────────┐
+  │ Facts:                      │
+  │  "User's name is X"         │
+  │  "Prefers TypeScript"       │
+  │ Entities:                   │
+  │  X (person), TypeScript     │
+  │ Relationships:              │
+  │  X → prefers → TypeScript   │
+  └──────────┬──────────────────┘
              │
-     ┌───────┼───────┐
-     ▼       ▼       ▼
-    ADD   UPDATE   NONE
-  (store) (replace) (skip)
+     ┌───────┴───────┐
+     ▼               ▼
+  Facts           Entities
+     │               │
+     ▼               ▼
+  ┌─ Dedup ──┐   ┌─ Upsert ─┐
+  │ ADD      │   │ name     │
+  │ UPDATE   │   │ type     │
+  │ NONE     │   │ mentions │
+  └──────────┘   │ relate   │
+                 └──────────┘
 ```
 
 ## License

package/dist/index.d.ts

@@ -13,6 +13,8 @@ interface GenerateOptions {
     json?: boolean;
     /** Max tokens for response */
     maxTokens?: number;
+    /** Temperature for response (0 = deterministic) */
+    temperature?: number;
 }
 /**
  * LLM provider interface. Implement this to bring your own model.
@@ -65,10 +67,183 @@ declare class OpenAIProvider implements LLMProvider {
     generate(messages: ChatMessage[], options?: GenerateOptions): Promise<string>;
 }
 
+/**
+ * @brainbank/memory — Entity Store
+ *
+ * Manages entities and relationships extracted from conversations.
+ * Uses BrainBank collections (SQLite) — no Neo4j or external graph DB needed.
+ * Optional LLM for intelligent entity resolution (e.g. merging "TS" with "TypeScript").
+ */
+
+interface Entity {
+    name: string;
+    type: 'person' | 'service' | 'project' | 'organization' | 'concept' | string;
+    attributes?: Record<string, any>;
+    firstSeen?: number;
+    lastSeen?: number;
+    mentionCount?: number;
+}
+interface Relationship {
+    source: string;
+    target: string;
+    relation: string;
+    context?: string;
+    timestamp?: number;
+}
+interface TraversalNode {
+    entity: string;
+    relation: string;
+    depth: number;
+    path: string[];
+}
+interface TraversalResult {
+    start: string;
+    maxDepth: number;
+    nodes: TraversalNode[];
+}
+/** Object with a .collection() method — satisfied by BrainBank */
+interface CollectionProvider {
+    collection(name: string): MemoryStore;
+}
+interface EntityStoreConfig {
+    /** Optional LLM for intelligent entity resolution */
+    llm?: LLMProvider;
+    /** Callback fired for each entity operation */
+    onEntity?: (op: {
+        action: 'NEW' | 'UPDATED' | 'RELATED';
+        name: string;
+        type?: string;
+        detail?: string;
+    }) => void;
+    /** Custom entity collection name. Default: 'entities' */
+    entityCollectionName?: string;
+    /** Custom relationship collection name. Default: 'relationships' */
+    relationCollectionName?: string;
+}
+/**
+ * @deprecated Use `new EntityStore(brain, config?)` instead.
+ */
+interface EntityStoreOptions {
+    /** Collection for entities */
+    entityCollection: MemoryStore;
+    /** Collection for relationships */
+    relationCollection: MemoryStore;
+    /** Optional LLM for intelligent entity resolution */
+    llm?: LLMProvider;
+    /** Callback fired for each entity operation */
+    onEntity?: (op: {
+        action: 'NEW' | 'UPDATED' | 'RELATED';
+        name: string;
+        type?: string;
+        detail?: string;
+    }) => void;
+}
+declare class EntityStore {
+    private readonly entities;
+    private readonly relations;
+    private llm?;
+    private readonly onEntity?;
+    /**
+     * Create an EntityStore.
+     *
+     * @example Simple (recommended)
+     * ```typescript
+     * const entityStore = new EntityStore(brain);
+     * ```
+     *
+     * @example With config
+     * ```typescript
+     * const entityStore = new EntityStore(brain, {
+     *   onEntity: (op) => console.log(op),
+     * });
+     * ```
+     */
+    constructor(provider: CollectionProvider, config?: EntityStoreConfig);
+    /** @deprecated Pass a CollectionProvider (brain) instead */
+    constructor(options: EntityStoreOptions);
+    /** @internal — used by Memory to share its LLM if EntityStore doesn't have one */
+    setLLM(llm: LLMProvider): void;
+    /**
+     * Upsert an entity — create if new, update mention count if exists.
+     */
+    upsert(entity: Entity): Promise<void>;
+    /**
+     * Add a relationship between two entities.
+     */
+    relate(source: string, target: string, relation: string, context?: string): Promise<void>;
+    /**
+     * Find an entity by name.
+     * 1. Exact name match (case-insensitive)
+     * 2. LLM resolution if available (e.g. "TS" → "TypeScript")
+     */
+    findEntity(name: string): Promise<(MemoryItem & {
+        metadata?: Record<string, any>;
+    }) | null>;
+    /**
+     * Ask LLM if a new entity matches any existing entity.
+     * Returns the matching entity name or null.
+     */
+    private resolveEntity;
+    /**
+     * Get all relationships for an entity (as source or target).
+     */
+    getRelated(entityName: string): Promise<Relationship[]>;
+    /**
+     * Get all relationships for an entity (shorthand for getRelated).
+     */
+    relationsOf(entityName: string): Promise<Relationship[]>;
+    /**
+     * List all entities, optionally filtered by type.
+     */
+    listEntities(options?: {
+        type?: string;
+        limit?: number;
+    }): MemoryItem[];
+    /**
+     * List all relationships.
+     */
+    listRelationships(): MemoryItem[];
+    /**
+     * Get entity count.
+     */
+    entityCount(): number;
+    /**
+     * Get relationship count.
+     */
+    relationCount(): number;
+    /**
+     * Traverse the entity graph — multi-hop BFS from a starting entity.
+     * Returns all reachable entities within the given depth.
+     */
+    traverse(startEntity: string, maxDepth?: number): Promise<TraversalResult>;
+    /**
+     * Build markdown context for system prompt injection.
+     */
+    buildContext(entityName?: string): string;
+    /**
+     * Process raw entities and relationships from LLM extraction.
+     */
+    processExtraction(entities: Array<{
+        name: string;
+        type: string;
+        attributes?: Record<string, any>;
+    }>, relationships: Array<{
+        source: string;
+        target: string;
+        relation: string;
+    }>, context?: string): Promise<{
+        entitiesProcessed: number;
+        relationshipsProcessed: number;
+    }>;
+    private serializeEntity;
+    private extractName;
+}
+
 /**
  * @brainbank/memory — Deterministic Memory Pipeline
  *
  * Automatic fact extraction and deduplication for LLM conversations.
+ * Optionally extracts entities and relationships (knowledge graph).
  * Runs after every turn: extract → search → dedup → ADD/UPDATE/NONE.
  */
 
@@ -84,6 +259,14 @@ interface MemoryOperation {
     action: MemoryAction;
     reason: string;
 }
+interface EntityOperation {
+    entitiesProcessed: number;
+    relationshipsProcessed: number;
+}
+interface ProcessResult {
+    operations: MemoryOperation[];
+    entities?: EntityOperation;
+}
 /**
  * Collection interface — matches BrainBank's collection API.
  * Implement this to use a different storage backend.
@@ -105,6 +288,8 @@ interface MemoryStore {
 interface MemoryOptions {
     /** LLM provider for extraction and dedup */
     llm: LLMProvider;
+    /** Entity store for knowledge graph (opt-in) */
+    entityStore?: EntityStore;
     /** Max facts to extract per turn. Default: 5 */
     maxFacts?: number;
     /** Max existing memories to compare against for dedup. Default: 50 */
@@ -117,22 +302,39 @@ interface MemoryOptions {
     dedupPrompt?: string;
     /** Called for each memory operation */
     onOperation?: (op: MemoryOperation) => void;
+    /** Custom collection name for memories. Default: 'memories' */
+    collectionName?: string;
 }
 declare class Memory {
     private readonly store;
     private readonly llm;
+    private readonly entityStore?;
     private readonly maxFacts;
     private readonly maxMemories;
     private readonly dedupTopK;
     private readonly extractPrompt;
     private readonly dedupPrompt;
     private readonly onOperation?;
+    /**
+     * Create a Memory instance.
+     *
+     * @example Recommended (pass brain directly)
+     * ```typescript
+     * const memory = new Memory(brain, { llm });
+     * ```
+     *
+     * @example Legacy (pass collection directly)
+     * ```typescript
+     * const memory = new Memory(brain.collection('memories'), { llm });
+     * ```
+     */
+    constructor(provider: CollectionProvider, options: MemoryOptions);
     constructor(store: MemoryStore, options: MemoryOptions);
     /**
-     * Process a conversation turn — extract facts and store/update memories.
+     * Process a conversation turn — extract facts (and optionally entities) and store/update memories.
      * This is the main entry point. Call after every user↔assistant exchange.
      */
-    process(userMessage: string, assistantMessage: string): Promise<MemoryOperation[]>;
+    process(userMessage: string, assistantMessage: string): Promise<ProcessResult>;
     /**
      * Search memories semantically.
      */
@@ -146,12 +348,16 @@ declare class Memory {
      */
     count(): number;
     /**
-     * Build a system prompt section with all memories.
+     * Build a system prompt section with all memories (and entities if enabled).
      * Drop this into your system prompt.
      */
     buildContext(limit?: number): string;
+    /**
+     * Get entity store (if enabled).
+     */
+    getEntityStore(): EntityStore | undefined;
     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 };
+export { type ChatMessage, type CollectionProvider, type Entity, type EntityOperation, EntityStore, type EntityStoreConfig, type EntityStoreOptions, type GenerateOptions, type LLMProvider, Memory, type MemoryAction, type MemoryItem, type MemoryOperation, type MemoryOptions, type MemoryStore, OpenAIProvider, type OpenAIProviderOptions, type ProcessResult, type Relationship, type TraversalNode, type TraversalResult };

package/dist/index.js

@@ -15,6 +15,29 @@ Rules:
 - Be specific ("prefers TypeScript" not "has programming preferences")
 - Skip trivial info ("said hello", "asked a question")
 - Max 5 facts per turn`;
+var EXTRACT_WITH_ENTITIES_PROMPT = `You are a memory extraction engine. Given a conversation turn, extract:
+1. Atomic facts worth remembering
+2. Named entities (people, services, projects, organizations, concepts)
+3. Relationships between entities
+
+Respond with JSON:
+{
+  "facts": ["fact1", "fact2"],
+  "entities": [
+    { "name": "EntityName", "type": "person|service|project|organization|concept", "attributes": {} }
+  ],
+  "relationships": [
+    { "source": "EntityA", "target": "EntityB", "relation": "verb_phrase" }
+  ]
+}
+
+Rules:
+- Facts: single self-contained sentences, be specific, max 5 per turn
+- Entities: only extract clearly named entities, not generic nouns
+- Relationships: use lowercase verb phrases ("works_on", "prefers", "depends_on", "migrating_to")
+- Entity types: person, service, project, organization, concept (or custom)
+- If nothing found, return empty arrays
+- Skip trivial info`;
 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" }
@@ -29,32 +52,41 @@ Be conservative \u2014 if in doubt, say NONE.`;
 var Memory = class {
   store;
   llm;
+  entityStore;
   maxFacts;
   maxMemories;
   dedupTopK;
   extractPrompt;
   dedupPrompt;
   onOperation;
-  constructor(store, options) {
-    this.store = store;
+  constructor(providerOrStore, options) {
+    if ("collection" in providerOrStore && typeof providerOrStore.collection === "function") {
+      this.store = providerOrStore.collection(options.collectionName ?? "memories");
+    } else {
+      this.store = providerOrStore;
+    }
     this.llm = options.llm;
+    this.entityStore = options.entityStore;
     this.maxFacts = options.maxFacts ?? 5;
     this.maxMemories = options.maxMemories ?? 50;
     this.dedupTopK = options.dedupTopK ?? 3;
-    this.extractPrompt = options.extractPrompt ?? EXTRACT_PROMPT;
+    this.extractPrompt = options.extractPrompt ?? (options.entityStore ? EXTRACT_WITH_ENTITIES_PROMPT : EXTRACT_PROMPT);
     this.dedupPrompt = options.dedupPrompt ?? DEDUP_PROMPT;
     this.onOperation = options.onOperation;
+    if (this.entityStore) this.entityStore.setLLM(this.llm);
   }
   /**
-   * Process a conversation turn — extract facts and store/update memories.
+   * Process a conversation turn — extract facts (and optionally entities) 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 extraction = await this.extract(userMessage, assistantMessage);
+    if (extraction.facts.length === 0 && extraction.entities.length === 0) {
+      return { operations: [] };
+    }
     const existing = this.store.list({ limit: this.maxMemories });
     const operations = [];
-    for (const fact of facts) {
+    for (const fact of extraction.facts) {
       const op = await this.dedup(fact, existing);
       operations.push(op);
       this.onOperation?.(op);
@@ -75,7 +107,16 @@ var Memory = class {
           break;
       }
     }
-    return operations;
+    let entityOps;
+    if (this.entityStore && (extraction.entities.length > 0 || extraction.relationships.length > 0)) {
+      const context = `${userMessage} \u2014 ${assistantMessage}`.slice(0, 200);
+      entityOps = await this.entityStore.processExtraction(
+        extraction.entities,
+        extraction.relationships,
+        context
+      );
+    }
+    return { operations, entities: entityOps };
   }
   /**
    * Search memories semantically.
@@ -96,13 +137,26 @@ var Memory = class {
     return this.store.count();
   }
   /**
-   * Build a system prompt section with all memories.
+   * Build a system prompt section with all memories (and entities if enabled).
    * Drop this into your system prompt.
    */
   buildContext(limit = 20) {
+    const parts = [];
     const items = this.store.list({ limit });
-    if (items.length === 0) return "";
-    return "## Memories\n" + items.map((m) => `- ${m.content}`).join("\n");
+    if (items.length > 0) {
+      parts.push("## Memories\n" + items.map((m) => `- ${m.content}`).join("\n"));
+    }
+    if (this.entityStore) {
+      const entityCtx = this.entityStore.buildContext();
+      if (entityCtx) parts.push(entityCtx);
+    }
+    return parts.join("\n\n");
+  }
+  /**
+   * Get entity store (if enabled).
+   */
+  getEntityStore() {
+    return this.entityStore;
   }
   // ─── Internal ───────────────────────────────────
   async extract(userMsg, assistantMsg) {
@@ -111,13 +165,16 @@ var Memory = class {
       { role: "user", content: `User: ${userMsg}
 
 Assistant: ${assistantMsg}` }
-    ], { json: true, maxTokens: 300 });
+    ], { json: true, maxTokens: 500 });
     try {
       const parsed = JSON.parse(response);
-      const facts = parsed.facts ?? [];
-      return facts.slice(0, this.maxFacts);
+      return {
+        facts: (parsed.facts ?? []).slice(0, this.maxFacts),
+        entities: parsed.entities ?? [],
+        relationships: parsed.relationships ?? []
+      };
     } catch {
-      return [];
+      return { facts: [], entities: [], relationships: [] };
     }
   }
   async dedup(fact, _existing) {
@@ -146,6 +203,287 @@ ${context}` }
   }
 };
 
+// src/entities.ts
+var ENTITY_RESOLVE_PROMPT = `You are an entity resolution engine. Given a NEW entity and a list of EXISTING entities, determine if the new entity refers to the same real-world thing as any existing one.
+
+Consider aliases, abbreviations, alternate names, and typos:
+- "TS" = "TypeScript"
+- "JS" = "JavaScript"
+- "berna" = "Berna"
+- "GCP" = "Google Cloud Platform"
+- "React.js" = "React"
+
+Respond with ONLY the matching entity name (exactly as listed) or "NONE" if no match.
+
+Existing entities:
+{entities}
+
+New entity: {newEntity}
+
+Match:`;
+var EntityStore = class {
+  entities;
+  relations;
+  llm;
+  onEntity;
+  constructor(providerOrOptions, config) {
+    if ("collection" in providerOrOptions && typeof providerOrOptions.collection === "function") {
+      const c = config ?? {};
+      this.entities = providerOrOptions.collection(c.entityCollectionName ?? "entities");
+      this.relations = providerOrOptions.collection(c.relationCollectionName ?? "relationships");
+      this.llm = c.llm;
+      this.onEntity = c.onEntity;
+    } else {
+      const opts = providerOrOptions;
+      this.entities = opts.entityCollection;
+      this.relations = opts.relationCollection;
+      this.llm = opts.llm;
+      this.onEntity = opts.onEntity;
+    }
+  }
+  /** @internal — used by Memory to share its LLM if EntityStore doesn't have one */
+  setLLM(llm) {
+    if (!this.llm) this.llm = llm;
+  }
+  /**
+   * Upsert an entity — create if new, update mention count if exists.
+   */
+  async upsert(entity) {
+    const now = Date.now();
+    const existing = await this.findEntity(entity.name);
+    if (existing) {
+      if (existing.id != null) await this.entities.remove(existing.id);
+      await this.entities.add(this.serializeEntity(entity), {
+        metadata: {
+          type: entity.type,
+          attributes: { ...existing.metadata?.attributes ?? {}, ...entity.attributes ?? {} },
+          firstSeen: existing.metadata?.firstSeen ?? now,
+          lastSeen: now,
+          mentionCount: (existing.metadata?.mentionCount ?? 1) + 1
+        }
+      });
+      this.onEntity?.({ action: "UPDATED", name: entity.name, type: entity.type, detail: `${(existing.metadata?.mentionCount ?? 1) + 1}x` });
+    } else {
+      await this.entities.add(this.serializeEntity(entity), {
+        metadata: {
+          type: entity.type,
+          attributes: entity.attributes ?? {},
+          firstSeen: now,
+          lastSeen: now,
+          mentionCount: 1
+        }
+      });
+      this.onEntity?.({ action: "NEW", name: entity.name, type: entity.type });
+    }
+  }
+  /**
+   * Add a relationship between two entities.
+   */
+  async relate(source, target, relation, context) {
+    const now = Date.now();
+    const content = `${source} \u2192 ${relation} \u2192 ${target}`;
+    await this.relations.add(content, {
+      metadata: { source, target, relation, context, timestamp: now }
+    });
+    this.onEntity?.({ action: "RELATED", name: source, detail: `${source} \u2192 ${relation} \u2192 ${target}` });
+  }
+  /**
+   * Find an entity by name.
+   * 1. Exact name match (case-insensitive)
+   * 2. LLM resolution if available (e.g. "TS" → "TypeScript")
+   */
+  async findEntity(name) {
+    const results = await this.entities.search(name, { k: 5 });
+    for (const r of results) {
+      if (this.extractName(r.content).toLowerCase() === name.toLowerCase()) {
+        return r;
+      }
+    }
+    if (this.llm && results.length > 0) {
+      const candidateNames = results.map((r) => this.extractName(r.content));
+      const resolved = await this.resolveEntity(name, candidateNames);
+      if (resolved) {
+        return results.find((r) => this.extractName(r.content) === resolved) ?? null;
+      }
+    }
+    return null;
+  }
+  /**
+   * Ask LLM if a new entity matches any existing entity.
+   * Returns the matching entity name or null.
+   */
+  async resolveEntity(newEntity, existing) {
+    if (!this.llm || existing.length === 0) return null;
+    const prompt = ENTITY_RESOLVE_PROMPT.replace("{entities}", existing.map((e) => `- ${e}`).join("\n")).replace("{newEntity}", newEntity);
+    try {
+      const response = await this.llm.generate(
+        [{ role: "user", content: prompt }],
+        { maxTokens: 50, temperature: 0 }
+      );
+      const match = response.trim();
+      if (match === "NONE" || match === "none") return null;
+      const found = existing.find((e) => e.toLowerCase() === match.toLowerCase());
+      return found ?? null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get all relationships for an entity (as source or target).
+   */
+  async getRelated(entityName) {
+    const results = await this.relations.search(entityName, { k: 20 });
+    return results.filter((r) => r.metadata?.source === entityName || r.metadata?.target === entityName).map((r) => ({
+      source: r.metadata?.source ?? "",
+      target: r.metadata?.target ?? "",
+      relation: r.metadata?.relation ?? "",
+      context: r.metadata?.context,
+      timestamp: r.metadata?.timestamp
+    }));
+  }
+  /**
+   * Get all relationships for an entity (shorthand for getRelated).
+   */
+  async relationsOf(entityName) {
+    return this.getRelated(entityName);
+  }
+  /**
+   * List all entities, optionally filtered by type.
+   */
+  listEntities(options) {
+    const all = this.entities.list({ limit: options?.limit ?? 100 });
+    if (options?.type) {
+      return all.filter((e) => e.metadata?.type === options.type);
+    }
+    return all;
+  }
+  /**
+   * List all relationships.
+   */
+  listRelationships() {
+    return this.relations.list({ limit: 200 });
+  }
+  /**
+   * Get entity count.
+   */
+  entityCount() {
+    return this.entities.count();
+  }
+  /**
+   * Get relationship count.
+   */
+  relationCount() {
+    return this.relations.count();
+  }
+  /**
+   * Traverse the entity graph — multi-hop BFS from a starting entity.
+   * Returns all reachable entities within the given depth.
+   */
+  async traverse(startEntity, maxDepth = 2) {
+    const visited = /* @__PURE__ */ new Set();
+    const queue = [
+      { entity: startEntity, depth: 0, path: [startEntity], relation: "" }
+    ];
+    const nodes = [];
+    while (queue.length > 0) {
+      const current = queue.shift();
+      if (current.depth > maxDepth || visited.has(current.entity)) continue;
+      visited.add(current.entity);
+      const rels = await this.getRelated(current.entity);
+      for (const rel of rels) {
+        const next = rel.source === current.entity ? rel.target : rel.source;
+        const nextPath = [...current.path, next];
+        if (!visited.has(next)) {
+          nodes.push({
+            entity: next,
+            relation: rel.relation,
+            depth: current.depth + 1,
+            path: nextPath
+          });
+          queue.push({
+            entity: next,
+            depth: current.depth + 1,
+            path: nextPath,
+            relation: rel.relation
+          });
+        }
+      }
+    }
+    return { start: startEntity, maxDepth, nodes };
+  }
+  /**
+   * Build markdown context for system prompt injection.
+   */
+  buildContext(entityName) {
+    const parts = [];
+    if (entityName) {
+      const entities = this.entities.list({ limit: 100 });
+      const match = entities.find((e) => this.extractName(e.content).toLowerCase() === entityName.toLowerCase());
+      if (match) {
+        parts.push(`## Entity: ${this.extractName(match.content)}`);
+        if (match.metadata?.type) parts.push(`Type: ${match.metadata.type}`);
+        if (match.metadata?.mentionCount) parts.push(`Mentions: ${match.metadata.mentionCount}`);
+      }
+      const rels = this.relations.list({ limit: 200 });
+      const related = rels.filter(
+        (r) => r.metadata?.source === entityName || r.metadata?.target === entityName
+      );
+      if (related.length > 0) {
+        parts.push("### Relationships");
+        for (const r of related) {
+          parts.push(`- ${r.metadata?.source} \u2192 ${r.metadata?.relation} \u2192 ${r.metadata?.target}`);
+        }
+      }
+    } else {
+      const entities = this.entities.list({ limit: 50 });
+      if (entities.length === 0) return "";
+      parts.push("## Known Entities");
+      for (const e of entities) {
+        const name = this.extractName(e.content);
+        const type = e.metadata?.type ?? "unknown";
+        const mentions = e.metadata?.mentionCount ?? 1;
+        parts.push(`- ${name} (${type}, ${mentions}x)`);
+      }
+      const rels = this.relations.list({ limit: 50 });
+      if (rels.length > 0) {
+        parts.push("\n## Relationships");
+        for (const r of rels) {
+          parts.push(`- ${r.metadata?.source} \u2192 ${r.metadata?.relation} \u2192 ${r.metadata?.target}`);
+        }
+      }
+    }
+    return parts.join("\n");
+  }
+  /**
+   * Process raw entities and relationships from LLM extraction.
+   */
+  async processExtraction(entities, relationships, context) {
+    let entitiesProcessed = 0;
+    let relationshipsProcessed = 0;
+    for (const entity of entities) {
+      await this.upsert(entity);
+      entitiesProcessed++;
+    }
+    for (const rel of relationships) {
+      await this.relate(rel.source, rel.target, rel.relation, context);
+      relationshipsProcessed++;
+    }
+    return { entitiesProcessed, relationshipsProcessed };
+  }
+  // ─── Internal ───────────────────────────────────
+  serializeEntity(entity) {
+    const parts = [entity.name];
+    if (entity.type) parts.push(`(${entity.type})`);
+    if (entity.attributes && Object.keys(entity.attributes).length > 0) {
+      parts.push(JSON.stringify(entity.attributes));
+    }
+    return parts.join(" ");
+  }
+  extractName(content) {
+    return content.split(/\s*\(/)[0].trim();
+  }
+};
+
 // src/llm.ts
 var OpenAIProvider = class {
   apiKey;
@@ -170,6 +508,7 @@ var OpenAIProvider = class {
         model: this.model,
         messages,
         max_tokens: options?.maxTokens ?? 500,
+        ...options?.temperature != null ? { temperature: options.temperature } : {},
         ...options?.json ? { response_format: { type: "json_object" } } : {}
       })
     });
@@ -181,6 +520,7 @@ var OpenAIProvider = class {
   }
 };
 export {
+  EntityStore,
   Memory,
   OpenAIProvider
 };

package/package.json

@@ -1,22 +1,29 @@
 {
     "name": "@brainbank/memory",
-    "version": "0.1.0",
+    "version": "0.2.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" }
+        ".": {
+            "import": "./dist/index.js",
+            "types": "./dist/index.d.ts"
+        }
     },
-    "files": ["dist/"],
+    "files": [
+        "dist/"
+    ],
     "scripts": {
         "build": "tsup"
     },
     "peerDependencies": {
-        "brainbank": ">=0.2.0"
+        "brainbank": ">=0.1.0"
     },
     "peerDependenciesMeta": {
-        "brainbank": { "optional": true }
+        "brainbank": {
+            "optional": true
+        }
     },
     "repository": {
         "type": "git",
@@ -24,8 +31,16 @@
         "directory": "packages/memory"
     },
     "keywords": [
-        "memory", "llm", "ai", "agent", "langchain", "deduplication",
-        "fact-extraction", "conversation-memory", "rag", "brainbank"
+        "memory",
+        "llm",
+        "ai",
+        "agent",
+        "langchain",
+        "deduplication",
+        "fact-extraction",
+        "conversation-memory",
+        "rag",
+        "brainbank"
     ],
     "author": "Bernardo Castro <bernardo@pinecall.io>",
     "license": "MIT"