@199-bio/engram 0.3.0 → 0.3.2

package/dist/index.js

@@ -42,23 +42,24 @@ async function initialize() {
 // ============ MCP Server ============
 const server = new Server({
     name: "engram",
-    version: "0.3.0",
+    version: "0.3.2",
 }, {
     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",
@@ -67,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,
@@ -85,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: {
@@ -116,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,94 +136,9 @@ const TOOLS = [
             openWorldHint: false,
         },
     },
-    {
-        name: "create_entity",
-        description: "Create a new entity in the knowledge graph (person, place, concept, etc.)",
-        inputSchema: {
-            type: "object",
-            properties: {
-                name: {
-                    type: "string",
-                    description: "Entity name (e.g., 'John', 'Paris', 'Machine Learning')",
-                },
-                type: {
-                    type: "string",
-                    enum: ["person", "place", "concept", "event", "organization"],
-                    description: "Type of entity",
-                },
-            },
-            required: ["name", "type"],
-        },
-        annotations: {
-            title: "Create Entity",
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "observe",
-        description: "Add an observation or fact about an entity",
-        inputSchema: {
-            type: "object",
-            properties: {
-                entity: {
-                    type: "string",
-                    description: "Entity name to add observation to",
-                },
-                observation: {
-                    type: "string",
-                    description: "The fact or observation to record",
-                },
-                confidence: {
-                    type: "number",
-                    description: "Confidence in this observation (0-1)",
-                    default: 1.0,
-                },
-            },
-            required: ["entity", "observation"],
-        },
-        annotations: {
-            title: "Add Observation",
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: false,
-            openWorldHint: false,
-        },
-    },
-    {
-        name: "relate",
-        description: "Create a relationship between two entities in the knowledge graph",
-        inputSchema: {
-            type: "object",
-            properties: {
-                from: {
-                    type: "string",
-                    description: "Source entity name",
-                },
-                to: {
-                    type: "string",
-                    description: "Target entity name",
-                },
-                relation: {
-                    type: "string",
-                    description: "Type of relationship (e.g., 'sibling', 'works_at', 'knows', 'located_in')",
-                },
-            },
-            required: ["from", "to", "relation"],
-        },
-        annotations: {
-            title: "Create Relationship",
-            readOnlyHint: false,
-            destructiveHint: false,
-            idempotentHint: true,
-            openWorldHint: false,
-        },
-    },
     {
         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: {
@@ -243,7 +159,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: {
@@ -391,68 +307,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     ],
                 };
             }
-            case "create_entity": {
-                const { name: entityName, type } = args;
-                const entity = graph.getOrCreateEntity(entityName, type);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                entity: {
-                                    id: entity.id,
-                                    name: entity.name,
-                                    type: entity.type,
-                                },
-                            }, null, 2),
-                        },
-                    ],
-                };
-            }
-            case "observe": {
-                const { entity: entityName, observation, confidence = 1.0 } = args;
-                // Ensure entity exists
-                const entity = graph.getOrCreateEntity(entityName, "person");
-                // Add observation
-                const obs = graph.addObservation(entity.id, observation, undefined, confidence);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                entity: entity.name,
-                                observation_id: obs.id,
-                            }, null, 2),
-                        },
-                    ],
-                };
-            }
-            case "relate": {
-                const { from, to, relation } = args;
-                // Ensure both entities exist
-                const fromEntity = graph.getOrCreateEntity(from, "person");
-                const toEntity = graph.getOrCreateEntity(to, "person");
-                // Create relation
-                const rel = graph.relate(fromEntity.id, toEntity.id, relation);
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                success: true,
-                                relation: {
-                                    id: rel.id,
-                                    from: fromEntity.name,
-                                    to: toEntity.name,
-                                    type: rel.type,
-                                },
-                            }, null, 2),
-                        },
-                    ],
-                };
-            }
             case "query_entity": {
                 const { entity: entityName } = args;
                 const details = graph.getEntityDetails(entityName);

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/package.json

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

package/src/index.ts

@@ -60,7 +60,7 @@ async function initialize(): Promise<void> {
 const server = new Server(
   {
     name: "engram",
-    version: "0.3.0",
+    version: "0.3.2",
   },
   {
     capabilities: {
@@ -70,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",
@@ -89,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,
@@ -108,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: {
@@ -139,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,94 +159,9 @@ const TOOLS = [
       openWorldHint: false,
     },
   },
-  {
-    name: "create_entity",
-    description: "Create a new entity in the knowledge graph (person, place, concept, etc.)",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        name: {
-          type: "string",
-          description: "Entity name (e.g., 'John', 'Paris', 'Machine Learning')",
-        },
-        type: {
-          type: "string",
-          enum: ["person", "place", "concept", "event", "organization"],
-          description: "Type of entity",
-        },
-      },
-      required: ["name", "type"],
-    },
-    annotations: {
-      title: "Create Entity",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-    },
-  },
-  {
-    name: "observe",
-    description: "Add an observation or fact about an entity",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        entity: {
-          type: "string",
-          description: "Entity name to add observation to",
-        },
-        observation: {
-          type: "string",
-          description: "The fact or observation to record",
-        },
-        confidence: {
-          type: "number",
-          description: "Confidence in this observation (0-1)",
-          default: 1.0,
-        },
-      },
-      required: ["entity", "observation"],
-    },
-    annotations: {
-      title: "Add Observation",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: false,
-      openWorldHint: false,
-    },
-  },
-  {
-    name: "relate",
-    description: "Create a relationship between two entities in the knowledge graph",
-    inputSchema: {
-      type: "object" as const,
-      properties: {
-        from: {
-          type: "string",
-          description: "Source entity name",
-        },
-        to: {
-          type: "string",
-          description: "Target entity name",
-        },
-        relation: {
-          type: "string",
-          description: "Type of relationship (e.g., 'sibling', 'works_at', 'knows', 'located_in')",
-        },
-      },
-      required: ["from", "to", "relation"],
-    },
-    annotations: {
-      title: "Create Relationship",
-      readOnlyHint: false,
-      destructiveHint: false,
-      idempotentHint: true,
-      openWorldHint: false,
-    },
-  },
   {
     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: {
@@ -266,7 +182,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: {
@@ -439,90 +355,6 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         };
       }
 
-      case "create_entity": {
-        const { name: entityName, type } = args as {
-          name: string;
-          type: "person" | "place" | "concept" | "event" | "organization";
-        };
-
-        const entity = graph.getOrCreateEntity(entityName, type);
-
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify({
-                success: true,
-                entity: {
-                  id: entity.id,
-                  name: entity.name,
-                  type: entity.type,
-                },
-              }, null, 2),
-            },
-          ],
-        };
-      }
-
-      case "observe": {
-        const { entity: entityName, observation, confidence = 1.0 } = args as {
-          entity: string;
-          observation: string;
-          confidence?: number;
-        };
-
-        // Ensure entity exists
-        const entity = graph.getOrCreateEntity(entityName, "person");
-
-        // Add observation
-        const obs = graph.addObservation(entity.id, observation, undefined, confidence);
-
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify({
-                success: true,
-                entity: entity.name,
-                observation_id: obs.id,
-              }, null, 2),
-            },
-          ],
-        };
-      }
-
-      case "relate": {
-        const { from, to, relation } = args as {
-          from: string;
-          to: string;
-          relation: string;
-        };
-
-        // Ensure both entities exist
-        const fromEntity = graph.getOrCreateEntity(from, "person");
-        const toEntity = graph.getOrCreateEntity(to, "person");
-
-        // Create relation
-        const rel = graph.relate(fromEntity.id, toEntity.id, relation);
-
-        return {
-          content: [
-            {
-              type: "text" as const,
-              text: JSON.stringify({
-                success: true,
-                relation: {
-                  id: rel.id,
-                  from: fromEntity.name,
-                  to: toEntity.name,
-                  type: rel.type,
-                },
-              }, null, 2),
-            },
-          ],
-        };
-      }
-
       case "query_entity": {
         const { entity: entityName } = args as { entity: string };
 

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) {