@199-bio/engram 0.2.0 → 0.3.1

package/dist/index.js

@@ -14,6 +14,7 @@ import { EngramDatabase } from "./storage/database.js";
 import { KnowledgeGraph } from "./graph/knowledge-graph.js";
 import { createRetriever } from "./retrieval/colbert.js";
 import { HybridSearch } from "./retrieval/hybrid.js";
+import { EngramWebServer } from "./web/server.js";
 // ============ Configuration ============
 const DB_PATH = process.env.ENGRAM_DB_PATH
     ? path.resolve(process.env.ENGRAM_DB_PATH.replace("~", os.homedir()))
@@ -23,6 +24,7 @@ const DB_FILE = path.join(DB_PATH, "engram.db");
 let db;
 let graph;
 let search;
+let webServer = null;
 async function initialize() {
     console.error(`[Engram] Initializing with database at ${DB_FILE}`);
     db = new EngramDatabase(DB_FILE);
@@ -40,23 +42,24 @@ async function initialize() {
 // ============ MCP Server ============
 const server = new Server({
     name: "engram",
-    version: "0.2.0",
+    version: "0.3.1",
 }, {
     capabilities: {
         tools: {},
     },
 });
 // Tool definitions with MCP 2025-06-18 annotations
+// Descriptions are carefully written to guide Claude on when to use each tool
 const TOOLS = [
     {
         name: "remember",
-        description: "Store a new memory. Automatically extracts entities and relationships for the knowledge graph.",
+        description: "PRIMARY STORAGE TOOL. Use this for ALL new information - conversations, facts, observations, notes. Automatically extracts people, organizations, and places as entities and creates relationships. Do NOT also call create_entity/observe/relate - remember handles entity extraction automatically. Only use remember once per piece of information.",
         inputSchema: {
             type: "object",
             properties: {
                 content: {
                     type: "string",
-                    description: "The memory content to store",
+                    description: "The information to store - can be a conversation snippet, fact, observation, or note",
                 },
                 source: {
                     type: "string",
@@ -65,7 +68,7 @@ const TOOLS = [
                 },
                 importance: {
                     type: "number",
-                    description: "Importance score from 0 to 1 (higher = more important)",
+                    description: "Importance score from 0 to 1 (higher = more important). Use 0.7+ for key facts, 0.3- for casual mentions",
                     minimum: 0,
                     maximum: 1,
                     default: 0.5,
@@ -83,7 +86,7 @@ const TOOLS = [
     },
     {
         name: "recall",
-        description: "Retrieve relevant memories using hybrid search (BM25 keywords + semantic + knowledge graph). Returns the most relevant memories for a query.",
+        description: "PRIMARY SEARCH TOOL. Use this FIRST when answering any question about stored information. Searches across all memories using semantic understanding, keywords, and knowledge graph connections. Returns relevant memories with context.",
         inputSchema: {
             type: "object",
             properties: {
@@ -114,7 +117,7 @@ const TOOLS = [
     },
     {
         name: "forget",
-        description: "Remove a specific memory by its ID",
+        description: "Delete a specific memory by its ID. Use only when explicitly asked to remove information.",
         inputSchema: {
             type: "object",
             properties: {
@@ -135,13 +138,13 @@ const TOOLS = [
     },
     {
         name: "create_entity",
-        description: "Create a new entity in the knowledge graph (person, place, concept, etc.)",
+        description: "ADVANCED: Manually create an entity. Rarely needed - remember auto-extracts entities. Only use when: (1) creating an entity that won't appear in any memory content, or (2) correcting entity type after auto-extraction.",
         inputSchema: {
             type: "object",
             properties: {
                 name: {
                     type: "string",
-                    description: "Entity name (e.g., 'John', 'Paris', 'Machine Learning')",
+                    description: "Entity name (e.g., 'John Smith', 'Paris', 'Machine Learning')",
                 },
                 type: {
                     type: "string",
@@ -161,13 +164,13 @@ const TOOLS = [
     },
     {
         name: "observe",
-        description: "Add an observation or fact about an entity",
+        description: "ADVANCED: Add a fact to an EXISTING entity without creating a memory. Rarely needed - use remember instead, which stores the content AND links it to entities. Only use observe for adding metadata or corrections to entities.",
         inputSchema: {
             type: "object",
             properties: {
                 entity: {
                     type: "string",
-                    description: "Entity name to add observation to",
+                    description: "Entity name to add observation to (must already exist)",
                 },
                 observation: {
                     type: "string",
@@ -191,7 +194,7 @@ const TOOLS = [
     },
     {
         name: "relate",
-        description: "Create a relationship between two entities in the knowledge graph",
+        description: "ADVANCED: Manually create a relationship between two entities. Rarely needed - remember auto-extracts relationships from text. Only use when: (1) the relationship wasn't captured by auto-extraction, or (2) you need to add a relationship not mentioned in any memory.",
         inputSchema: {
             type: "object",
             properties: {
@@ -220,7 +223,7 @@ const TOOLS = [
     },
     {
         name: "query_entity",
-        description: "Get detailed information about an entity including all observations and relationships",
+        description: "Get all stored information about a specific person, place, or organization. Use after recall to get deeper details about an entity mentioned in search results.",
         inputSchema: {
             type: "object",
             properties: {
@@ -241,7 +244,7 @@ const TOOLS = [
     },
     {
         name: "list_entities",
-        description: "List all entities, optionally filtered by type",
+        description: "List all known entities (people, places, organizations, etc.). Use to browse the knowledge graph or find entity names for query_entity.",
         inputSchema: {
             type: "object",
             properties: {
@@ -280,6 +283,27 @@ const TOOLS = [
             openWorldHint: false,
         },
     },
+    {
+        name: "engram_web",
+        description: "Launch the Engram web interface for browsing, searching, and editing memories visually. Returns a URL to open in your browser.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                port: {
+                    type: "number",
+                    description: "Port to run the web server on (default: 3847)",
+                    default: 3847,
+                },
+            },
+        },
+        annotations: {
+            title: "Launch Web Interface",
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    },
 ];
 // List available tools
 server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -505,6 +529,26 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
+            case "engram_web": {
+                const { port = 3847 } = args;
+                // Create or reuse web server
+                if (!webServer) {
+                    webServer = new EngramWebServer({ db, graph, search, port });
+                }
+                const url = await webServer.start();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                success: true,
+                                url,
+                                message: `Web interface running at ${url}`,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/dist/storage/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/storage/database.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/storage/database.ts"],"names":[],"mappings":"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"}

package/dist/web/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/web/server.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAiBtD,UAAU,gBAAgB;IACxB,EAAE,EAAE,cAAc,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;IACtB,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,eAAe;IAC1B,OAAO,CAAC,MAAM,CAA4B;IAC1C,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,KAAK,CAAiB;IAC9B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,IAAI,CAAS;gBAET,OAAO,EAAE,gBAAgB;IAO/B,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAkB9B,IAAI,IAAI,IAAI;YAOE,aAAa;YA+Bb,SAAS;YAgIT,WAAW;IAgCzB,OAAO,CAAC,SAAS;CAclB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@199-bio/engram",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Give Claude a perfect memory. Local-first MCP server with hybrid search.",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -19,6 +19,7 @@ import { EngramDatabase } from "./storage/database.js";
 import { KnowledgeGraph } from "./graph/knowledge-graph.js";
 import { createRetriever } from "./retrieval/colbert.js";
 import { HybridSearch } from "./retrieval/hybrid.js";
+import { EngramWebServer } from "./web/server.js";
 
 // ============ Configuration ============
 
@@ -33,6 +34,7 @@ const DB_FILE = path.join(DB_PATH, "engram.db");
 let db: EngramDatabase;
 let graph: KnowledgeGraph;
 let search: HybridSearch;
+let webServer: EngramWebServer | null = null;
 
 async function initialize(): Promise<void> {
   console.error(`[Engram] Initializing with database at ${DB_FILE}`);
@@ -58,7 +60,7 @@ async function initialize(): Promise<void> {
 const server = new Server(
   {
     name: "engram",
-    version: "0.2.0",
+    version: "0.3.1",
   },
   {
     capabilities: {
@@ -68,17 +70,18 @@ const server = new Server(
 );
 
 // Tool definitions with MCP 2025-06-18 annotations
+// Descriptions are carefully written to guide Claude on when to use each tool
 const TOOLS = [
   {
     name: "remember",
     description:
-      "Store a new memory. Automatically extracts entities and relationships for the knowledge graph.",
+      "PRIMARY STORAGE TOOL. Use this for ALL new information - conversations, facts, observations, notes. Automatically extracts people, organizations, and places as entities and creates relationships. Do NOT also call create_entity/observe/relate - remember handles entity extraction automatically. Only use remember once per piece of information.",
     inputSchema: {
       type: "object" as const,
       properties: {
         content: {
           type: "string",
-          description: "The memory content to store",
+          description: "The information to store - can be a conversation snippet, fact, observation, or note",
         },
         source: {
           type: "string",
@@ -87,7 +90,7 @@ const TOOLS = [
         },
         importance: {
           type: "number",
-          description: "Importance score from 0 to 1 (higher = more important)",
+          description: "Importance score from 0 to 1 (higher = more important). Use 0.7+ for key facts, 0.3- for casual mentions",
           minimum: 0,
           maximum: 1,
           default: 0.5,
@@ -106,7 +109,7 @@ const TOOLS = [
   {
     name: "recall",
     description:
-      "Retrieve relevant memories using hybrid search (BM25 keywords + semantic + knowledge graph). Returns the most relevant memories for a query.",
+      "PRIMARY SEARCH TOOL. Use this FIRST when answering any question about stored information. Searches across all memories using semantic understanding, keywords, and knowledge graph connections. Returns relevant memories with context.",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -137,7 +140,7 @@ const TOOLS = [
   },
   {
     name: "forget",
-    description: "Remove a specific memory by its ID",
+    description: "Delete a specific memory by its ID. Use only when explicitly asked to remove information.",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -158,13 +161,13 @@ const TOOLS = [
   },
   {
     name: "create_entity",
-    description: "Create a new entity in the knowledge graph (person, place, concept, etc.)",
+    description: "ADVANCED: Manually create an entity. Rarely needed - remember auto-extracts entities. Only use when: (1) creating an entity that won't appear in any memory content, or (2) correcting entity type after auto-extraction.",
     inputSchema: {
       type: "object" as const,
       properties: {
         name: {
           type: "string",
-          description: "Entity name (e.g., 'John', 'Paris', 'Machine Learning')",
+          description: "Entity name (e.g., 'John Smith', 'Paris', 'Machine Learning')",
         },
         type: {
           type: "string",
@@ -184,13 +187,13 @@ const TOOLS = [
   },
   {
     name: "observe",
-    description: "Add an observation or fact about an entity",
+    description: "ADVANCED: Add a fact to an EXISTING entity without creating a memory. Rarely needed - use remember instead, which stores the content AND links it to entities. Only use observe for adding metadata or corrections to entities.",
     inputSchema: {
       type: "object" as const,
       properties: {
         entity: {
           type: "string",
-          description: "Entity name to add observation to",
+          description: "Entity name to add observation to (must already exist)",
         },
         observation: {
           type: "string",
@@ -214,7 +217,7 @@ const TOOLS = [
   },
   {
     name: "relate",
-    description: "Create a relationship between two entities in the knowledge graph",
+    description: "ADVANCED: Manually create a relationship between two entities. Rarely needed - remember auto-extracts relationships from text. Only use when: (1) the relationship wasn't captured by auto-extraction, or (2) you need to add a relationship not mentioned in any memory.",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -243,7 +246,7 @@ const TOOLS = [
   },
   {
     name: "query_entity",
-    description: "Get detailed information about an entity including all observations and relationships",
+    description: "Get all stored information about a specific person, place, or organization. Use after recall to get deeper details about an entity mentioned in search results.",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -264,7 +267,7 @@ const TOOLS = [
   },
   {
     name: "list_entities",
-    description: "List all entities, optionally filtered by type",
+    description: "List all known entities (people, places, organizations, etc.). Use to browse the knowledge graph or find entity names for query_entity.",
     inputSchema: {
       type: "object" as const,
       properties: {
@@ -303,6 +306,27 @@ const TOOLS = [
       openWorldHint: false,
     },
   },
+  {
+    name: "engram_web",
+    description: "Launch the Engram web interface for browsing, searching, and editing memories visually. Returns a URL to open in your browser.",
+    inputSchema: {
+      type: "object" as const,
+      properties: {
+        port: {
+          type: "number",
+          description: "Port to run the web server on (default: 3847)",
+          default: 3847,
+        },
+      },
+    },
+    annotations: {
+      title: "Launch Web Interface",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
 ];
 
 // List available tools
@@ -587,6 +611,30 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
+      case "engram_web": {
+        const { port = 3847 } = args as { port?: number };
+
+        // Create or reuse web server
+        if (!webServer) {
+          webServer = new EngramWebServer({ db, graph, search, port });
+        }
+
+        const url = await webServer.start();
+
+        return {
+          content: [
+            {
+              type: "text" as const,
+              text: JSON.stringify({
+                success: true,
+                url,
+                message: `Web interface running at ${url}`,
+              }, null, 2),
+            },
+          ],
+        };
+      }
+
       default:
         throw new Error(`Unknown tool: ${name}`);
     }

package/src/storage/database.ts

@@ -266,12 +266,140 @@ export class EngramDatabase {
   }
 
   findEntityByName(name: string): Entity | null {
+    // First try exact match (case-insensitive)
     const row = this.stmt("SELECT * FROM entities WHERE LOWER(name) = LOWER(?)").get(name) as Record<string, unknown> | undefined;
-    return row ? this.rowToEntity(row) : null;
+    if (row) return this.rowToEntity(row);
+
+    // If no exact match, try fuzzy match for potential duplicates
+    const fuzzyMatch = this.findSimilarEntity(name);
+    return fuzzyMatch;
+  }
+
+  /**
+   * Find a similar entity using fuzzy matching
+   * Catches "Boris D" matching "Boris Djordjevic", "John" matching "John Smith"
+   */
+  findSimilarEntity(name: string, threshold: number = 0.8): Entity | null {
+    const normalizedName = name.toLowerCase().trim();
+    const nameWords = normalizedName.split(/\s+/);
+
+    // Get candidates: entities that share at least one word with the query
+    const candidates = this.stmt(`
+      SELECT * FROM entities
+      WHERE LOWER(name) LIKE ?
+      LIMIT 100
+    `).all(`%${nameWords[0]}%`) as Record<string, unknown>[];
+
+    let bestMatch: Entity | null = null;
+    let bestScore = 0;
+
+    for (const row of candidates) {
+      const entity = this.rowToEntity(row);
+      const entityName = entity.name.toLowerCase();
+      const entityWords = entityName.split(/\s+/);
+
+      // Calculate similarity score
+      const score = this.calculateNameSimilarity(nameWords, entityWords, normalizedName, entityName);
+
+      if (score >= threshold && score > bestScore) {
+        bestScore = score;
+        bestMatch = entity;
+      }
+    }
+
+    return bestMatch;
+  }
+
+  /**
+   * Calculate similarity between two names
+   * Returns 0-1 score (1 = identical)
+   */
+  private calculateNameSimilarity(
+    words1: string[],
+    words2: string[],
+    full1: string,
+    full2: string
+  ): number {
+    // Exact match
+    if (full1 === full2) return 1.0;
+
+    // One is prefix of the other (e.g., "Boris" vs "Boris Djordjevic")
+    if (full1.startsWith(full2 + " ") || full2.startsWith(full1 + " ")) {
+      return 0.9;
+    }
+
+    // First word matches (e.g., "John" vs "John Smith")
+    if (words1[0] === words2[0]) {
+      // Same first word, different lengths
+      const longer = Math.max(words1.length, words2.length);
+      const shorter = Math.min(words1.length, words2.length);
+      return 0.7 + (0.2 * shorter / longer);
+    }
+
+    // Check for abbreviated names (e.g., "Boris D" vs "Boris Djordjevic")
+    if (words1.length >= 2 && words2.length >= 2) {
+      const last1 = words1[words1.length - 1];
+      const last2 = words2[words2.length - 1];
+
+      // Check if one is abbreviation of the other
+      if (last1.length === 1 && last2.startsWith(last1)) {
+        return 0.85;
+      }
+      if (last2.length === 1 && last1.startsWith(last2)) {
+        return 0.85;
+      }
+    }
+
+    // Count shared words
+    const set1 = new Set(words1);
+    const shared = words2.filter(w => set1.has(w)).length;
+    const total = Math.max(words1.length, words2.length);
+
+    return shared / total * 0.7;
+  }
+
+  /**
+   * Find all potential duplicate entities
+   */
+  findDuplicateEntities(): Array<{ entity: Entity; potentialDuplicates: Entity[] }> {
+    const entities = this.listEntities(undefined, 1000);
+    const duplicates: Array<{ entity: Entity; potentialDuplicates: Entity[] }> = [];
+    const processed = new Set<string>();
+
+    for (const entity of entities) {
+      if (processed.has(entity.id)) continue;
+
+      const potentialDupes: Entity[] = [];
+      const words = entity.name.toLowerCase().split(/\s+/);
+
+      for (const other of entities) {
+        if (other.id === entity.id || processed.has(other.id)) continue;
+
+        const otherWords = other.name.toLowerCase().split(/\s+/);
+        const score = this.calculateNameSimilarity(
+          words, otherWords,
+          entity.name.toLowerCase(),
+          other.name.toLowerCase()
+        );
+
+        if (score >= 0.8) {
+          potentialDupes.push(other);
+          processed.add(other.id);
+        }
+      }
+
+      if (potentialDupes.length > 0) {
+        duplicates.push({ entity, potentialDuplicates: potentialDupes });
+        processed.add(entity.id);
+      }
+    }
+
+    return duplicates;
   }
 
   searchEntities(query: string, type?: Entity["type"]): Entity[] {
-    let sql = "SELECT * FROM entities WHERE name LIKE ?";
+    // Case-insensitive search
+    let sql = "SELECT * FROM entities WHERE LOWER(name) LIKE LOWER(?)";
     const params: unknown[] = [`%${query}%`];
 
     if (type) {