collective-memory-mcp 0.5.0 → 0.6.0

package/README.md

@@ -1,16 +1,23 @@
 # Collective Memory MCP Server
 
-A persistent, graph-based memory system that enables AI agents to document their work and learn from each other's experiences. This system transforms ephemeral agent interactions into a searchable knowledge base of structural patterns, solutions, and methodologies.
+A persistent, graph-based memory system with **semantic search** that enables AI agents to document their work and learn from each other's experiences. This system transforms ephemeral agent interactions into a searchable knowledge base of structural patterns, solutions, and methodologies.
 
 ## Overview
 
 The Collective Memory System is designed for multi-agent environments where agents need to:
 
 - Document their completed work for future reference
-- Discover how similar tasks were solved previously
+- Discover how similar tasks were solved previously using **semantic understanding**
 - Learn from the structural patterns and approaches of other agents
 - Coordinate across parallel executions without duplicating effort
 
+## Key Features
+
+- **Semantic Search** - Finds conceptually similar content even when keywords differ
+- **Knowledge Graph** - Entities and relations capture complex relationships
+- **Ranked Results** - Similarity scores help identify the most relevant past work
+- **Auto-Embeddings** - New content automatically gets semantic embeddings
+
 ## Installation
 
 ```bash
@@ -42,8 +49,11 @@ Add this to your Claude system prompt to ensure agents know about the Collective
 You have access to a Collective Memory MCP Server that stores knowledge from previous tasks.
 
 BEFORE starting work, search for similar past tasks using:
-- search_collective_memory
-- find_similar_procedures
+- search_collective_memory (semantic search - understands meaning, not just keywords)
+- find_similar_procedures (finds similar tasks with full implementation details)
+
+The search uses semantic embeddings, so it finds relevant content even when different
+terminology is used. Results are ranked by similarity score.
 
 AFTER completing any task, document it using:
 - record_task_completion
@@ -52,6 +62,48 @@ When writing observations, be SPECIFIC and include facts like file paths, versio
 metrics, and error messages. Avoid vague statements like "works well" or "fixed bugs".
 ```
 
+## Setting Up Semantic Search
+
+For semantic search to work, you need to configure an embeddings provider:
+
+### Option 1: OpenAI (Recommended - Best Quality)
+
+```bash
+# Configure with your OpenAI API key
+# Use the manage_embeddings tool with:
+{
+  "action": "configure",
+  "provider": "openai",
+  "api_key": "sk-..."
+}
+```
+
+### Option 2: Ollama (Free - Local)
+
+```bash
+# Install Ollama first
+# Then pull the embedding model
+ollama pull nomic-embed-text
+
+# Configure the provider
+{
+  "action": "configure",
+  "provider": "ollama"
+}
+```
+
+### Generate Embeddings for Existing Data
+
+After configuring, generate embeddings for any existing entities:
+
+```json
+{
+  "action": "generate"
+}
+```
+
+**Note:** Without configuring embeddings, the system falls back to keyword-based search.
+
 ## Entity Types
 
 | Type | Description |
@@ -93,7 +145,7 @@ metrics, and error messages. Avoid vague statements like "works well" or "fixed
 ### Query & Search
 
 - **read_graph** - Read entire knowledge graph
-- **search_collective_memory** - Natural language search
+- **search_collective_memory** - Semantic search with ranked results
 - **open_nodes** - Retrieve specific nodes by name
 
 ### Agent Workflow
@@ -101,6 +153,10 @@ metrics, and error messages. Avoid vague statements like "works well" or "fixed
 - **record_task_completion** - Primary tool for documenting completed work
 - **find_similar_procedures** - Find similar tasks with full implementation details
 
+### Embeddings Management
+
+- **manage_embeddings** - Configure semantic search and generate embeddings
+
 ## Example Usage
 
 ### Recording a Task Completion
@@ -126,12 +182,38 @@ await session.callTool("record_task_completion", {
 });
 ```
 
-### Finding Similar Procedures
+### Finding Similar Procedures (Semantic Search)
 
 ```javascript
 const result = await session.callTool("find_similar_procedures", {
   query: "authentication implementation"
 });
+
+// Returns ranked results with similarity scores:
+// {
+//   "similar_tasks": [
+//     { "task": {...}, "score": 0.89, "artifacts": [...], "structures": [...] },
+//     { "task": {...}, "score": 0.82, "artifacts": [...], "structures": [...] }
+//   ],
+//   "search_method": "semantic"
+// }
+```
+
+### Configuring Embeddings
+
+```javascript
+// Check status
+await session.callTool("manage_embeddings", { "action": "status" });
+
+// Configure OpenAI
+await session.callTool("manage_embeddings", {
+  "action": "configure",
+  "provider": "openai",
+  "api_key": "sk-..."
+});
+
+// Generate embeddings for existing data
+await session.callTool("manage_embeddings", { "action": "generate" });
 ```
 
 ## Database
@@ -139,9 +221,19 @@ const result = await session.callTool("find_similar_procedures", {
 The server uses JSON file storage for persistence. Data is stored at:
 
 ```
-~/.collective-memory/memory.json
+~/.collective-memory/memory.json      # Knowledge graph data
+~/.collective-memory/config.json      # Embeddings provider configuration
 ```
 
+## Semantic Search Benefits
+
+| Before (Keyword Search) | After (Semantic Search) |
+|------------------------|------------------------|
+| Query "login" misses "authentication" | Query "login" finds "authentication", "JWT", "OAuth" |
+| No relevance ranking | Results ranked by similarity score (0-1) |
+| Exact word matching required | Understands meaning and intent |
+| High false-positive rate | More precise, relevant results |
+
 ## Requirements
 
 - Node.js 18+

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "collective-memory-mcp",
-  "version": "0.5.0",
-  "description": "A persistent, graph-based memory system for AI agents (MCP Server)",
+  "version": "0.6.0",
+  "description": "A persistent, graph-based memory system for AI agents with semantic search (MCP Server)",
   "type": "module",
   "main": "src/server.js",
   "bin": {

package/src/embeddings.js

@@ -0,0 +1,318 @@
+/**
+ * Embeddings module for semantic search in the Collective Memory System.
+ * Supports multiple embedding providers with cosine similarity.
+ */
+
+import fs from "fs";
+import path from "path";
+import os from "os";
+
+const CONFIG_DIR = path.join(os.homedir(), ".collective-memory");
+const CONFIG_PATH = path.join(CONFIG_DIR, "config.json");
+
+/**
+ * Default configuration
+ */
+const DEFAULT_CONFIG = {
+  embedding_provider: "openai", // 'openai' or 'ollama'
+  openai_api_key: null,
+  openai_model: "text-embedding-3-small",
+  ollama_base_url: "http://localhost:11434",
+  ollama_model: "nomic-embed-text",
+  embedding_dimension: 1536,
+};
+
+/**
+ * Load configuration from file
+ */
+function loadConfig() {
+  try {
+    if (fs.existsSync(CONFIG_PATH)) {
+      const content = fs.readFileSync(CONFIG_PATH, "utf-8");
+      return { ...DEFAULT_CONFIG, ...JSON.parse(content) };
+    }
+  } catch (error) {
+    console.error("Failed to load config:", error.message);
+  }
+  return { ...DEFAULT_CONFIG };
+}
+
+/**
+ * Save configuration to file
+ */
+function saveConfig(config) {
+  try {
+    if (!fs.existsSync(CONFIG_DIR)) {
+      fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2));
+  } catch (error) {
+    console.error("Failed to save config:", error.message);
+  }
+}
+
+/**
+ * Calculate cosine similarity between two vectors
+ */
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length) {
+    throw new Error("Vector dimensions must match");
+  }
+
+  let dotProduct = 0;
+  let normA = 0;
+  let normB = 0;
+
+  for (let i = 0; i < a.length; i++) {
+    dotProduct += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+
+  normA = Math.sqrt(normA);
+  normB = Math.sqrt(normB);
+
+  if (normA === 0 || normB === 0) {
+    return 0;
+  }
+
+  return dotProduct / (normA * normB);
+}
+
+/**
+ * OpenAI embeddings provider
+ */
+class OpenAIEmbeddings {
+  constructor(config) {
+    this.apiKey = config.openai_api_key || process.env.OPENAI_API_KEY;
+    this.model = config.openai_model || "text-embedding-3-small";
+    this.dimension = config.embedding_dimension || 1536;
+  }
+
+  isAvailable() {
+    return !!this.apiKey;
+  }
+
+  async embed(text) {
+    if (!this.isAvailable()) {
+      throw new Error("OpenAI API key not configured");
+    }
+
+    const response = await fetch("https://api.openai.com/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: text,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OpenAI API error: ${error}`);
+    }
+
+    const data = await response.json();
+    return data.data[0].embedding;
+  }
+
+  async embedBatch(texts) {
+    if (!this.isAvailable()) {
+      throw new Error("OpenAI API key not configured");
+    }
+
+    const response = await fetch("https://api.openai.com/v1/embeddings", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: texts,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`OpenAI API error: ${error}`);
+    }
+
+    const data = await response.json();
+    return data.data.map((item) => item.embedding);
+  }
+}
+
+/**
+ * Ollama embeddings provider (local, free)
+ */
+class OllamaEmbeddings {
+  constructor(config) {
+    this.baseUrl = config.ollama_base_url || "http://localhost:11434";
+    this.model = config.ollama_model || "nomic-embed-text";
+    this.dimension = 768; // Default for nomic-embed-text
+  }
+
+  isAvailable() {
+    // Check if Ollama is running
+    return fetch(`${this.baseUrl}/api/tags`)
+      .then((res) => res.ok)
+      .catch(() => false);
+  }
+
+  async embed(text) {
+    const response = await fetch(`${this.baseUrl}/api/embeddings`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: this.model,
+        prompt: text,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response.text();
+      throw new Error(`Ollama API error: ${error}`);
+    }
+
+    const data = await response.json();
+    return data.embedding;
+  }
+
+  async embedBatch(texts) {
+    // Ollama doesn't support batch embeddings, so we do them sequentially
+    const embeddings = [];
+    for (const text of texts) {
+      embeddings.push(await this.embed(text));
+    }
+    return embeddings;
+  }
+}
+
+/**
+ * Main embeddings class that manages providers
+ */
+class Embeddings {
+  constructor(config) {
+    this.config = config || loadConfig();
+    this.providers = {
+      openai: new OpenAIEmbeddings(this.config),
+      ollama: new OllamaEmbeddings(this.config),
+    };
+    this.activeProvider = this.config.embedding_provider || "openai";
+  }
+
+  /**
+   * Get the active provider
+   */
+  getProvider() {
+    return this.providers[this.activeProvider];
+  }
+
+  /**
+   * Check if the active provider is available
+   */
+  async isAvailable() {
+    const provider = this.getProvider();
+
+    if (this.activeProvider === "ollama") {
+      return await provider.isAvailable();
+    }
+
+    return provider.isAvailable();
+  }
+
+  /**
+   * Generate embedding for a single text
+   */
+  async embed(text) {
+    const provider = this.getProvider();
+    return await provider.embed(text);
+  }
+
+  /**
+   * Generate embeddings for multiple texts
+   */
+  async embedBatch(texts) {
+    const provider = this.getProvider();
+    return await provider.embedBatch(texts);
+  }
+
+  /**
+   * Find most similar items using cosine similarity
+   */
+  findMostSimilar(queryEmbedding, items, topK = 10, threshold = 0.7) {
+    const results = items.map((item) => {
+      if (!item.embedding) {
+        return { ...item, score: 0 };
+      }
+      const score = cosineSimilarity(queryEmbedding, item.embedding);
+      return { ...item, score };
+    });
+
+    // Sort by score descending and filter by threshold
+    return results
+      .filter((r) => r.score >= threshold)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, topK);
+  }
+
+  /**
+   * Create text representation for entity embedding
+   */
+  createEntityText(entity) {
+    const parts = [];
+
+    // Name carries important semantic weight
+    parts.push(`Name: ${entity.name}`);
+
+    // Entity type provides context
+    parts.push(`Type: ${entity.entityType}`);
+
+    // Observations contain the detailed information
+    if (entity.observations && entity.observations.length > 0) {
+      parts.push(`Observations:\n${entity.observations.join("\n")}`);
+    }
+
+    // Metadata if present
+    if (entity.metadata) {
+      parts.push(`Metadata: ${JSON.stringify(entity.metadata)}`);
+    }
+
+    return parts.join("\n\n");
+  }
+}
+
+/**
+ * Singleton instance
+ */
+let embeddingsInstance = null;
+
+/**
+ * Get or create embeddings instance
+ */
+export function getEmbeddings(config) {
+  if (!embeddingsInstance) {
+    embeddingsInstance = new Embeddings(config);
+  }
+  return embeddingsInstance;
+}
+
+/**
+ * Export utilities
+ */
+export {
+  cosineSimilarity,
+  loadConfig,
+  saveConfig,
+  Embeddings,
+  OpenAIEmbeddings,
+  OllamaEmbeddings,
+};
+
+export default { getEmbeddings, cosineSimilarity, loadConfig, saveConfig };

package/src/server.js

@@ -14,13 +14,17 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 import { getStorage } from "./storage.js";
 import { Entity, Relation, ENTITY_TYPES, RELATION_TYPES } from "./models.js";
+import { loadConfig } from "./embeddings.js";
 
 /**
  * Create and configure the MCP server
  */
-function createServer() {
+async function createServer() {
   const storage = getStorage();
 
+  // Initialize embeddings for semantic search
+  await storage.initEmbeddings();
+
   const server = new Server(
     {
       name: "collective-memory",
@@ -230,16 +234,17 @@ function createServer() {
         {
           name: "search_collective_memory",
           description:
-            "**Search all past work** - Use before starting a task to learn from previous solutions. " +
-            "Searches entity names, types, and all observation content. " +
-            "Returns matching entities with their relations. " +
+            "**Search all past work using semantic search** - Use before starting a task to learn from previous solutions. " +
+            "Uses semantic embeddings to find conceptually similar content, even with different keywords. " +
+            "Returns ranked results with similarity scores. " +
+            "Automatically falls back to keyword search if embeddings aren't available. " +
             "Use find_similar_procedures for more detailed results with artifacts.",
           inputSchema: {
             type: "object",
             properties: {
               query: {
                 type: "string",
-                description: "What are you looking for? (e.g., 'authentication', 'CORS fix', 'database')",
+                description: "What are you looking for? Semantic search understands meaning. (e.g., 'authentication', 'CORS fix', 'database')",
               },
             },
             required: ["query"],
@@ -350,8 +355,9 @@ function createServer() {
         {
           name: "find_similar_procedures",
           description:
-            "**Use BEFORE starting work** - Find how similar tasks were solved previously. " +
-            "Returns complete implementation details including artifacts and structures. " +
+            "**Use BEFORE starting work** - Find how similar tasks were solved previously using semantic search. " +
+            "Returns complete implementation details including artifacts and structures, ranked by similarity. " +
+            "Understands meaning and intent, not just keywords. " +
             "Learn from past solutions before implementing new features. " +
             "Query examples: 'authentication', 'database migration', 'API design', 'error handling'.",
           inputSchema: {
@@ -359,12 +365,39 @@ function createServer() {
             properties: {
               query: {
                 type: "string",
-                description: "What are you trying to do? (e.g., 'authentication implementation', 'database migration')",
+                description: "What are you trying to do? Semantic search finds conceptually similar work. (e.g., 'authentication implementation', 'database migration')",
               },
             },
             required: ["query"],
           },
         },
+        {
+          name: "manage_embeddings",
+          description:
+            "**Manage semantic search embeddings** - Generate embeddings for existing entities " +
+            "to enable semantic search. Run this once after setting up an embeddings provider. " +
+            "Embeddings enable finding similar content even when keywords don't match exactly.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              action: {
+                type: "string",
+                enum: ["generate", "status", "configure"],
+                description: "Action: 'generate' creates embeddings for entities missing them, 'status' shows current state, 'configure' updates settings",
+              },
+              provider: {
+                type: "string",
+                enum: ["openai", "ollama"],
+                description: "Provider to use (only for 'configure' action)",
+              },
+              api_key: {
+                type: "string",
+                description: "API key for OpenAI (only for 'configure' action with provider='openai')",
+              },
+            },
+            required: ["action"],
+          },
+        },
       ],
     };
   });
@@ -703,6 +736,9 @@ Future agents will read your observations to learn. Write for them, not for your
         case "find_similar_procedures":
           return { content: [{ type: "text", text: JSON.stringify(findSimilarProcedures(args), null, 2) }] };
 
+        case "manage_embeddings":
+          return { content: [{ type: "text", text: JSON.stringify(await manageEmbeddings(args), null, 2) }] };
+
         default:
           throw new Error(`Unknown tool: ${name}`);
       }
@@ -841,16 +877,19 @@ Future agents will read your observations to learn. Write for them, not for your
     };
   }
 
-  function searchCollectiveMemory({ query = "" }) {
-    const matchingEntities = storage.searchEntities(query);
+  async function searchCollectiveMemory({ query = "" }) {
+    // Use semantic search if available
+    const searchResult = await storage.semanticSearchEntities(query);
 
-    const results = matchingEntities.map((entity) => {
+    const results = searchResult.results.map((item) => {
+      const entity = item.entity;
       const related = storage.getRelatedEntities(entity.name);
       return {
         name: entity.name,
         entityType: entity.entityType,
         observations: entity.observations,
         createdAt: entity.createdAt,
+        score: item.score,
         related_entities: related.connected.map((e) => ({
           name: e.name,
           entityType: e.entityType,
@@ -858,7 +897,11 @@ Future agents will read your observations to learn. Write for them, not for your
       };
     });
 
-    return { matching_entities: results, count: results.length };
+    return {
+      matching_entities: results,
+      count: results.length,
+      search_method: searchResult.method,
+    };
   }
 
   function openNodes({ names = [] }) {
@@ -1032,20 +1075,13 @@ Future agents will read your observations to learn. Write for them, not for your
     };
   }
 
-  function findSimilarProcedures({ query = "" }) {
-    const searchQuery = query.toLowerCase();
-
-    // Search for matching task entities
-    const allEntities = storage.getAllEntities();
-    const matchingTasks = allEntities.filter(
-      (e) =>
-        e.entityType === "task" &&
-        (e.name.toLowerCase().includes(searchQuery) ||
-          e.observations.some((obs) => obs.toLowerCase().includes(searchQuery)))
-    );
+  async function findSimilarProcedures({ query = "" }) {
+    // Use semantic search for tasks, falling back to keyword search
+    const searchResult = await storage.semanticSearchEntities(query, { entityType: "task" });
 
     const results = [];
-    for (const task of matchingTasks) {
+    for (const item of searchResult.results) {
+      const task = item.entity;
       const taskRelations = storage.getRelations({ fromEntity: task.name });
 
       const artifacts = [];
@@ -1083,10 +1119,117 @@ Future agents will read your observations to learn. Write for them, not for your
         artifacts,
         structures,
         execution_context: executionContext,
+        score: item.score,
       });
     }
 
-    return { similar_tasks: results, count: results.length };
+    return { similar_tasks: results, count: results.length, search_method: searchResult.method };
+  }
+
+  async function manageEmbeddings({ action = "status", provider = null, api_key = null }) {
+    const { saveConfig } = await import("./embeddings.js");
+
+    switch (action) {
+      case "status": {
+        const allEntities = storage.getAllEntities();
+        const withEmbeddings = allEntities.filter(
+          (e) => storage.data.entities[e.name]?.embedding
+        ).length;
+
+        const config = loadConfig();
+        const isReady = storage.embeddingsReady;
+
+        return {
+          status: "success",
+          action: "status",
+          embeddings_ready: isReady,
+          provider: config.embedding_provider,
+          entities_with_embeddings: withEmbeddings,
+          total_entities: allEntities.length,
+          coverage_percent: allEntities.length > 0
+            ? Math.round((withEmbeddings / allEntities.length) * 100)
+            : 0,
+          message: isReady
+            ? `Embeddings enabled using ${config.embedding_provider}. ${withEmbeddings}/${allEntities.length} entities have embeddings.`
+            : "Embeddings not configured. Use 'configure' action to set up a provider.",
+        };
+      }
+
+      case "configure": {
+        if (!provider) {
+          return {
+            status: "error",
+            message: "Provider is required for configure action",
+          };
+        }
+
+        const config = loadConfig();
+        config.embedding_provider = provider;
+
+        if (provider === "openai" && api_key) {
+          config.openai_api_key = api_key;
+        }
+
+        saveConfig(config);
+
+        // Re-initialize embeddings with new config
+        storage.embeddingsReady = false;
+        await storage.initEmbeddings();
+
+        return {
+          status: "success",
+          action: "configure",
+          provider,
+          embeddings_ready: storage.embeddingsReady,
+          message: storage.embeddingsReady
+            ? `Successfully configured ${provider} for embeddings`
+            : `Configured ${provider} but provider is not available. Check API keys or provider status.`,
+        };
+      }
+
+      case "generate": {
+        // Generate embeddings for entities that don't have them
+        const allEntities = storage.getAllEntities();
+        const missing = allEntities.filter(
+          (e) => !storage.data.entities[e.name]?.embedding
+        );
+
+        if (missing.length === 0) {
+          return {
+            status: "success",
+            action: "generate",
+            message: "All entities already have embeddings",
+            processed: 0,
+          };
+        }
+
+        try {
+          const result = await storage.generateMissingEmbeddings((current, total, name) => {
+            // Optional: could emit progress events
+          });
+
+          return {
+            status: "success",
+            action: "generate",
+            processed: result.processed,
+            total_entities: result.total,
+            message: `Generated embeddings for ${result.processed} entities`,
+          };
+        } catch (error) {
+          return {
+            status: "error",
+            action: "generate",
+            message: error.message,
+          };
+        }
+      }
+
+      default:
+        return {
+          status: "error",
+          message: `Unknown action: ${action}`,
+        };
+    }
   }
 
   return server;
@@ -1096,7 +1239,7 @@ Future agents will read your observations to learn. Write for them, not for your
  * Main entry point
  */
 async function main() {
-  const server = createServer();
+  const server = await createServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/src/storage.js

@@ -8,6 +8,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import path from "path";
 import os from "os";
 import { Entity, Relation } from "./models.js";
+import { getEmbeddings } from "./embeddings.js";
 
 const DB_DIR = path.join(os.homedir(), ".collective-memory");
 const DB_PATH = path.join(DB_DIR, "memory.json");
@@ -16,9 +17,12 @@ const DB_PATH = path.join(DB_DIR, "memory.json");
  * Simple file-based storage
  */
 export class Storage {
-  constructor(dbPath = DB_PATH) {
+  constructor(dbPath = DB_PATH, embeddingsEnabled = true) {
     this.dbPath = dbPath;
     this.data = null;
+    this.embeddingsEnabled = embeddingsEnabled;
+    this.embeddings = null;
+    this.embeddingsReady = false;
     // Initialize synchronously
     this.init();
   }
@@ -41,7 +45,7 @@ export class Storage {
         this.data = {
           entities: {},
           relations: [],
-          version: "1.0",
+          version: "2.0", // Version bump for embeddings support
         };
         this.saveSync();
       }
@@ -50,11 +54,61 @@ export class Storage {
       this.data = {
         entities: {},
         relations: [],
-        version: "1.0",
+        version: "2.0",
       };
     }
   }
 
+  /**
+   * Initialize embeddings asynchronously
+   */
+  async initEmbeddings() {
+    if (!this.embeddingsEnabled || this.embeddingsReady) {
+      return this.embeddingsReady;
+    }
+
+    try {
+      this.embeddings = getEmbeddings();
+      this.embeddingsReady = await this.embeddings.isAvailable();
+    } catch (error) {
+      console.warn("Embeddings not available:", error.message);
+      this.embeddingsReady = false;
+    }
+
+    return this.embeddingsReady;
+  }
+
+  /**
+   * Generate embedding for an entity
+   */
+  async generateEmbedding(entity) {
+    if (!this.embeddingsReady || !this.embeddings) {
+      return null;
+    }
+
+    try {
+      const text = this.embeddings.createEntityText(entity);
+      return await this.embeddings.embed(text);
+    } catch (error) {
+      console.warn("Failed to generate embedding:", error.message);
+      return null;
+    }
+  }
+
+  /**
+   * Store embedding in entity data
+   */
+  async updateEntityEmbedding(entityName, entity) {
+    if (!this.embeddingsReady) {
+      return;
+    }
+
+    const embedding = await this.generateEmbedding(entity);
+    if (embedding) {
+      this.data.entities[entityName].embedding = embedding;
+    }
+  }
+
   /**
    * Save data synchronously
    */
@@ -90,7 +144,12 @@ export class Storage {
     if (this.data.entities[entity.name]) {
       return false;
     }
-    this.data.entities[entity.name] = entity.toJSON();
+    const entityData = entity.toJSON();
+    this.data.entities[entity.name] = entityData;
+
+    // Generate embedding if available
+    await this.updateEntityEmbedding(entity.name, entity);
+
     await this.save();
     return true;
   }
@@ -127,6 +186,7 @@ export class Storage {
     const entity = this.data.entities[name];
     if (!entity) return false;
 
+    const updated = false;
     if (observations !== undefined) {
       entity.observations = observations;
     }
@@ -134,6 +194,12 @@ export class Storage {
       entity.metadata = metadata;
     }
 
+    // Regenerate embedding if observations changed
+    if (observations !== undefined && this.embeddingsReady) {
+      const entityObj = new Entity(entity);
+      await this.updateEntityEmbedding(name, entityObj);
+    }
+
     await this.save();
     return true;
   }
@@ -257,17 +323,131 @@ export class Storage {
 
   /**
    * Search entities by name, type, or observations
+   * Uses word-based matching - any word in the query that matches returns the entity
    */
   searchEntities(query) {
-    const lowerQuery = query.toLowerCase();
+    // Split query into words, remove common stop words
+    const stopWords = new Set(["the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for", "of", "with", "by"]);
+    const words = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter(w => w.length > 2 && !stopWords.has(w));
+
+    if (words.length === 0) {
+      // Fallback to original query if all words were filtered
+      const lowerQuery = query.toLowerCase();
+      return this.getAllEntities().filter(e => {
+        if (e.name.toLowerCase().includes(lowerQuery)) return true;
+        if (e.entityType.toLowerCase().includes(lowerQuery)) return true;
+        if (e.observations.some(o => o.toLowerCase().includes(lowerQuery))) return true;
+        return false;
+      });
+    }
+
     return this.getAllEntities().filter(e => {
-      if (e.name.toLowerCase().includes(lowerQuery)) return true;
-      if (e.entityType.toLowerCase().includes(lowerQuery)) return true;
-      if (e.observations.some(o => o.toLowerCase().includes(lowerQuery))) return true;
+      // Check if ANY word matches in name, type, or observations
+      for (const word of words) {
+        if (e.name.toLowerCase().includes(word)) return true;
+        if (e.entityType.toLowerCase().includes(word)) return true;
+        if (e.observations.some(o => o.toLowerCase().includes(word))) return true;
+      }
       return false;
     });
   }
 
+  /**
+   * Semantic search using embeddings
+   * Returns entities ranked by similarity score
+   */
+  async semanticSearchEntities(query, options = {}) {
+    const {
+      topK = 10,
+      threshold = 0.65, // Lower threshold for more matches
+      entityType = null,
+    } = options;
+
+    // Initialize embeddings if not ready
+    if (!this.embeddingsReady) {
+      await this.initEmbeddings();
+    }
+
+    // Fall back to keyword search if embeddings not available
+    if (!this.embeddingsReady) {
+      const results = this.searchEntities(query);
+      return {
+        results: results.map(e => ({ entity: e, score: 0 })),
+        method: "keyword",
+        count: results.length,
+      };
+    }
+
+    try {
+      // Generate embedding for the query
+      const queryEmbedding = await this.embeddings.embed(query);
+
+      // Get all entities with their embeddings
+      const allEntities = this.getAllEntities();
+      const items = allEntities
+        .filter(e => !entityType || e.entityType === entityType)
+        .map(e => ({
+          entity: e,
+          embedding: this.data.entities[e.name]?.embedding || null,
+        }))
+        .filter(item => item.embedding !== null);
+
+      // Find most similar
+      const scoredResults = this.embeddings.findMostSimilar(
+        queryEmbedding,
+        items,
+        topK,
+        threshold
+      );
+
+      return {
+        results: scoredResults.map(r => ({ entity: r.entity, score: r.score })),
+        method: "semantic",
+        count: scoredResults.length,
+      };
+    } catch (error) {
+      console.warn("Semantic search failed, falling back to keyword:", error.message);
+      const results = this.searchEntities(query);
+      return {
+        results: results.map(e => ({ entity: e, score: 0 })),
+        method: "keyword",
+        count: results.length,
+      };
+    }
+  }
+
+  /**
+   * Generate embeddings for all entities that don't have them
+   * Useful for migrating existing data to semantic search
+   */
+  async generateMissingEmbeddings(progressCallback = null) {
+    // Initialize embeddings if not ready
+    if (!this.embeddingsReady) {
+      const ready = await this.initEmbeddings();
+      if (!ready) {
+        throw new Error("Embeddings provider not available");
+      }
+    }
+
+    const entities = this.getAllEntities();
+    const missing = entities.filter(e => !this.data.entities[e.name]?.embedding);
+
+    let processed = 0;
+    for (const entity of missing) {
+      await this.updateEntityEmbedding(entity.name, entity);
+      processed++;
+      if (progressCallback) {
+        progressCallback(processed, missing.length, entity.name);
+      }
+    }
+
+    await this.save();
+    return { processed, total: entities.length };
+  }
+
   /**
    * Get entities related to a given entity
    */