@hasna/mementos 0.10.10 → 0.10.11

package/dist/cli/index.js

@@ -2584,6 +2584,17 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
 CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id);
 CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at);
 INSERT OR IGNORE INTO _migrations (id) VALUES (14);
+`,
+    `
+CREATE TABLE IF NOT EXISTS memory_embeddings (
+  memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  embedding TEXT NOT NULL,
+  model TEXT NOT NULL DEFAULT 'tfidf-512',
+  dimensions INTEGER NOT NULL DEFAULT 512,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_memory_embeddings_model ON memory_embeddings(model);
+INSERT OR IGNORE INTO _migrations (id) VALUES (15);
 `
   ];
 });
@@ -2645,6 +2656,78 @@ var init_types = __esm(() => {
   };
 });
 
+// src/lib/embeddings.ts
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length || a.length === 0)
+    return 0;
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0;i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+async function openAIEmbed(text, apiKey) {
+  const res = await fetch(OPENAI_EMBED_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model: EMBED_MODEL,
+      input: text.slice(0, 8192)
+    }),
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!res.ok) {
+    throw new Error(`OpenAI embedding API ${res.status}: ${await res.text()}`);
+  }
+  const data = await res.json();
+  return data.data[0].embedding;
+}
+function tfidfVector(text) {
+  const DIMS = 512;
+  const vec = new Float32Array(DIMS);
+  const tokens = text.toLowerCase().match(/\b\w+\b/g) ?? [];
+  for (const token of tokens) {
+    let hash = 2166136261;
+    for (let i = 0;i < token.length; i++) {
+      hash ^= token.charCodeAt(i);
+      hash = hash * 16777619 >>> 0;
+    }
+    vec[hash % DIMS] += 1;
+  }
+  let norm = 0;
+  for (let i = 0;i < DIMS; i++)
+    norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0)
+    for (let i = 0;i < DIMS; i++)
+      vec[i] /= norm;
+  return Array.from(vec);
+}
+async function generateEmbedding(text) {
+  const apiKey = process.env["OPENAI_API_KEY"];
+  if (apiKey) {
+    try {
+      const embedding2 = await openAIEmbed(text, apiKey);
+      return { embedding: embedding2, model: EMBED_MODEL, dimensions: EMBED_DIMENSIONS };
+    } catch {}
+  }
+  const embedding = tfidfVector(text);
+  return { embedding, model: "tfidf-512", dimensions: 512 };
+}
+function serializeEmbedding(embedding) {
+  return JSON.stringify(embedding);
+}
+function deserializeEmbedding(raw) {
+  return JSON.parse(raw);
+}
+var OPENAI_EMBED_URL = "https://api.openai.com/v1/embeddings", EMBED_MODEL = "text-embedding-3-small", EMBED_DIMENSIONS = 1536;
+
 // src/lib/redact.ts
 function redactSecrets(text) {
   let result = text;
@@ -2821,8 +2904,10 @@ var exports_memories = {};
 __export(exports_memories, {
   updateMemory: () => updateMemory,
   touchMemory: () => touchMemory,
+  semanticSearch: () => semanticSearch,
   parseMemoryRow: () => parseMemoryRow,
   listMemories: () => listMemories,
+  indexMemoryEmbedding: () => indexMemoryEmbedding,
   incrementRecallCount: () => incrementRecallCount,
   getMemoryVersions: () => getMemoryVersions,
   getMemoryByKey: () => getMemoryByKey,
@@ -3273,6 +3358,52 @@ function getMemoryVersions(memoryId, db) {
     return [];
   }
 }
+async function indexMemoryEmbedding(memoryId, text, db) {
+  try {
+    const d = db || getDatabase();
+    const { embedding, model, dimensions } = await generateEmbedding(text);
+    const serialized = serializeEmbedding(embedding);
+    d.run(`INSERT INTO memory_embeddings (memory_id, embedding, model, dimensions)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(memory_id) DO UPDATE SET embedding=excluded.embedding, model=excluded.model, dimensions=excluded.dimensions, created_at=datetime('now')`, [memoryId, serialized, model, dimensions]);
+  } catch {}
+}
+async function semanticSearch(queryText, options = {}, db) {
+  const d = db || getDatabase();
+  const { threshold = 0.5, limit = 10, scope, agent_id, project_id } = options;
+  const { embedding: queryEmbedding } = await generateEmbedding(queryText);
+  const conditions = ["m.status = 'active'", "e.embedding IS NOT NULL"];
+  const params = [];
+  if (scope) {
+    conditions.push("m.scope = ?");
+    params.push(scope);
+  }
+  if (agent_id) {
+    conditions.push("m.agent_id = ?");
+    params.push(agent_id);
+  }
+  if (project_id) {
+    conditions.push("m.project_id = ?");
+    params.push(project_id);
+  }
+  const where = conditions.join(" AND ");
+  const rows = d.prepare(`SELECT m.*, e.embedding FROM memories m
+     JOIN memory_embeddings e ON e.memory_id = m.id
+     WHERE ${where}`).all(...params);
+  const scored = [];
+  for (const row of rows) {
+    try {
+      const docEmbedding = deserializeEmbedding(row.embedding);
+      const score = cosineSimilarity(queryEmbedding, docEmbedding);
+      if (score >= threshold) {
+        const { embedding: _, ...memRow } = row;
+        scored.push({ memory: parseMemoryRow(memRow), score: Math.round(score * 1000) / 1000 });
+      }
+    } catch {}
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
 var RECALL_PROMOTE_THRESHOLD = 3;
 var init_memories = __esm(() => {
   init_types();
@@ -5494,6 +5625,18 @@ var init_built_in_hooks = __esm(() => {
       });
     }
   });
+  hookRegistry.register({
+    type: "PostMemorySave",
+    blocking: false,
+    builtin: true,
+    priority: 300,
+    description: "Generate and store vector embedding for semantic memory search",
+    handler: async (ctx) => {
+      const { indexMemoryEmbedding: indexMemoryEmbedding2 } = await Promise.resolve().then(() => (init_memories(), exports_memories));
+      const text = [ctx.memory.value, ctx.memory.summary].filter(Boolean).join(" ");
+      indexMemoryEmbedding2(ctx.memory.id, text);
+    }
+  });
   hookRegistry.register({
     type: "PostMemoryInject",
     blocking: false,

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

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmCtC,wBAAgB,SAAS,IAAI,MAAM,CAkBlC;AA6ZD,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAerD;AA+BD,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAef"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/db/database.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmCtC,wBAAgB,SAAS,IAAI,MAAM,CAkBlC;AA0aD,wBAAgB,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,QAAQ,CAerD;AA+BD,wBAAgB,aAAa,IAAI,IAAI,CAKpC;AAED,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAED,wBAAgB,GAAG,IAAI,MAAM,CAE5B;AAED,wBAAgB,IAAI,IAAI,MAAM,CAE7B;AAED,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED,wBAAgB,gBAAgB,CAC9B,EAAE,EAAE,QAAQ,EACZ,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,MAAM,GAChB,MAAM,GAAG,IAAI,CAef"}

package/dist/db/memories.d.ts

@@ -17,4 +17,24 @@ export declare function touchMemory(id: string, db?: Database): void;
 export declare function incrementRecallCount(id: string, db?: Database): void;
 export declare function cleanExpiredMemories(db?: Database): number;
 export declare function getMemoryVersions(memoryId: string, db?: Database): MemoryVersion[];
+export interface SemanticSearchResult {
+    memory: Memory;
+    score: number;
+}
+/**
+ * Store or update the embedding for a memory. Called asynchronously after saves.
+ * Non-blocking: failures are silently ignored.
+ */
+export declare function indexMemoryEmbedding(memoryId: string, text: string, db?: Database): Promise<void>;
+/**
+ * Semantic search across memories using cosine similarity.
+ * Falls back gracefully if no embeddings exist yet.
+ */
+export declare function semanticSearch(queryText: string, options?: {
+    threshold?: number;
+    limit?: number;
+    scope?: string;
+    agent_id?: string;
+    project_id?: string;
+}, db?: Database): Promise<SemanticSearchResult[]>;
 //# sourceMappingURL=memories.d.ts.map

package/dist/db/memories.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memories.d.ts","sourceRoot":"","sources":["../../src/db/memories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAyB,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,MAAM,EACN,YAAY,EACZ,aAAa,EACb,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AA8B3B,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAwBnE;AAMD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,UAAU,GAAE,UAAoB,EAChC,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,CAqKR;AAMD,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAOlE;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,GAAG,IAAI,CA4Bf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,EAAE,CAuBV;AAMD,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,EAAE,CA4G3E;AAMD,wBAAgB,YAAY,CAC1B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,iBAAiB,EACxB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,CAiHR;AAMD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAW/D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAmBvE;AAMD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAM3D;AAUD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAsBpE;AAMD,wBAAgB,oBAAoB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAiB1D;AAMD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,aAAa,EAAE,CAwBlF"}
+{"version":3,"file":"memories.d.ts","sourceRoot":"","sources":["../../src/db/memories.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAyB,MAAM,YAAY,CAAC;AAC7D,OAAO,KAAK,EACV,iBAAiB,EACjB,UAAU,EACV,MAAM,EACN,YAAY,EACZ,aAAa,EACb,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AA+B3B,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAwBnE;AAMD,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,UAAU,GAAE,UAAoB,EAChC,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,CAqKR;AAMD,wBAAgB,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI,CAOlE;AAED,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,GAAG,IAAI,CA4Bf;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,MAAM,EACX,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,EAClB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,EAAE,CAuBV;AAMD,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,YAAY,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,EAAE,CA4G3E;AAMD,wBAAgB,YAAY,CAC1B,EAAE,EAAE,MAAM,EACV,KAAK,EAAE,iBAAiB,EACxB,EAAE,CAAC,EAAE,QAAQ,GACZ,MAAM,CAiHR;AAMD,wBAAgB,YAAY,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAW/D;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAmBvE;AAMD,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAM3D;AAUD,wBAAgB,oBAAoB,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,IAAI,CAsBpE;AAMD,wBAAgB,oBAAoB,CAAC,EAAE,CAAC,EAAE,QAAQ,GAAG,MAAM,CAiB1D;AAMD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,aAAa,EAAE,CAwBlF;AAMD,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAsB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAcvG;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CAChB,EACN,EAAE,CAAC,EAAE,QAAQ,GACZ,OAAO,CAAC,oBAAoB,EAAE,CAAC,CAuCjC"}

package/dist/index.js

@@ -490,6 +490,17 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
 CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id);
 CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at);
 INSERT OR IGNORE INTO _migrations (id) VALUES (14);
+`,
+  `
+CREATE TABLE IF NOT EXISTS memory_embeddings (
+  memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  embedding TEXT NOT NULL,
+  model TEXT NOT NULL DEFAULT 'tfidf-512',
+  dimensions INTEGER NOT NULL DEFAULT 512,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_memory_embeddings_model ON memory_embeddings(model);
+INSERT OR IGNORE INTO _migrations (id) VALUES (15);
 `
 ];
 var _db = null;

package/dist/lib/built-in-hooks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"built-in-hooks.d.ts","sourceRoot":"","sources":["../../src/lib/built-in-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAwHlD,wBAAgB,kBAAkB,IAAI,IAAI,CAyBzC;AAuBD,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AAGD,YAAY,EAAE,QAAQ,EAAE,CAAC"}
+{"version":3,"file":"built-in-hooks.d.ts","sourceRoot":"","sources":["../../src/lib/built-in-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAyIlD,wBAAgB,kBAAkB,IAAI,IAAI,CAyBzC;AAuBD,wBAAgB,cAAc,IAAI,IAAI,CAGrC;AAGD,YAAY,EAAE,QAAQ,EAAE,CAAC"}

package/dist/lib/embeddings.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Embedding generation and cosine similarity for semantic memory search.
+ *
+ * Uses OpenAI text-embedding-3-small if OPENAI_API_KEY is set,
+ * falls back to a simple TF-IDF term frequency vector otherwise.
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+export interface EmbeddingResult {
+    embedding: number[];
+    model: string;
+    dimensions: number;
+}
+/**
+ * Generate an embedding for a text string.
+ * Uses OpenAI if OPENAI_API_KEY is available, otherwise uses TF-IDF hash trick.
+ */
+export declare function generateEmbedding(text: string): Promise<EmbeddingResult>;
+export declare function serializeEmbedding(embedding: number[]): string;
+export declare function deserializeEmbedding(raw: string): number[];
+//# sourceMappingURL=embeddings.d.ts.map

package/dist/lib/embeddings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddings.d.ts","sourceRoot":"","sources":["../../src/lib/embeddings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,MAAM,CAUjE;AAwDD,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAY9E;AAED,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,MAAM,CAE9D;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAE1D"}

package/dist/mcp/index.js

@@ -550,10 +550,93 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
 CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id);
 CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at);
 INSERT OR IGNORE INTO _migrations (id) VALUES (14);
+`,
+    `
+CREATE TABLE IF NOT EXISTS memory_embeddings (
+  memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  embedding TEXT NOT NULL,
+  model TEXT NOT NULL DEFAULT 'tfidf-512',
+  dimensions INTEGER NOT NULL DEFAULT 512,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_memory_embeddings_model ON memory_embeddings(model);
+INSERT OR IGNORE INTO _migrations (id) VALUES (15);
 `
   ];
 });
 
+// src/lib/embeddings.ts
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length || a.length === 0)
+    return 0;
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0;i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+async function openAIEmbed(text, apiKey) {
+  const res = await fetch(OPENAI_EMBED_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model: EMBED_MODEL,
+      input: text.slice(0, 8192)
+    }),
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!res.ok) {
+    throw new Error(`OpenAI embedding API ${res.status}: ${await res.text()}`);
+  }
+  const data = await res.json();
+  return data.data[0].embedding;
+}
+function tfidfVector(text) {
+  const DIMS = 512;
+  const vec = new Float32Array(DIMS);
+  const tokens = text.toLowerCase().match(/\b\w+\b/g) ?? [];
+  for (const token of tokens) {
+    let hash = 2166136261;
+    for (let i = 0;i < token.length; i++) {
+      hash ^= token.charCodeAt(i);
+      hash = hash * 16777619 >>> 0;
+    }
+    vec[hash % DIMS] += 1;
+  }
+  let norm = 0;
+  for (let i = 0;i < DIMS; i++)
+    norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0)
+    for (let i = 0;i < DIMS; i++)
+      vec[i] /= norm;
+  return Array.from(vec);
+}
+async function generateEmbedding(text) {
+  const apiKey = process.env["OPENAI_API_KEY"];
+  if (apiKey) {
+    try {
+      const embedding2 = await openAIEmbed(text, apiKey);
+      return { embedding: embedding2, model: EMBED_MODEL, dimensions: EMBED_DIMENSIONS };
+    } catch {}
+  }
+  const embedding = tfidfVector(text);
+  return { embedding, model: "tfidf-512", dimensions: 512 };
+}
+function serializeEmbedding(embedding) {
+  return JSON.stringify(embedding);
+}
+function deserializeEmbedding(raw) {
+  return JSON.parse(raw);
+}
+var OPENAI_EMBED_URL = "https://api.openai.com/v1/embeddings", EMBED_MODEL = "text-embedding-3-small", EMBED_DIMENSIONS = 1536;
+
 // src/lib/redact.ts
 function redactSecrets(text) {
   let result = text;
@@ -726,8 +809,10 @@ var exports_memories = {};
 __export(exports_memories, {
   updateMemory: () => updateMemory,
   touchMemory: () => touchMemory,
+  semanticSearch: () => semanticSearch,
   parseMemoryRow: () => parseMemoryRow,
   listMemories: () => listMemories,
+  indexMemoryEmbedding: () => indexMemoryEmbedding,
   incrementRecallCount: () => incrementRecallCount,
   getMemoryVersions: () => getMemoryVersions,
   getMemoryByKey: () => getMemoryByKey,
@@ -1178,6 +1263,52 @@ function getMemoryVersions(memoryId, db) {
     return [];
   }
 }
+async function indexMemoryEmbedding(memoryId, text, db) {
+  try {
+    const d = db || getDatabase();
+    const { embedding, model, dimensions } = await generateEmbedding(text);
+    const serialized = serializeEmbedding(embedding);
+    d.run(`INSERT INTO memory_embeddings (memory_id, embedding, model, dimensions)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(memory_id) DO UPDATE SET embedding=excluded.embedding, model=excluded.model, dimensions=excluded.dimensions, created_at=datetime('now')`, [memoryId, serialized, model, dimensions]);
+  } catch {}
+}
+async function semanticSearch(queryText, options = {}, db) {
+  const d = db || getDatabase();
+  const { threshold = 0.5, limit = 10, scope, agent_id, project_id } = options;
+  const { embedding: queryEmbedding } = await generateEmbedding(queryText);
+  const conditions = ["m.status = 'active'", "e.embedding IS NOT NULL"];
+  const params = [];
+  if (scope) {
+    conditions.push("m.scope = ?");
+    params.push(scope);
+  }
+  if (agent_id) {
+    conditions.push("m.agent_id = ?");
+    params.push(agent_id);
+  }
+  if (project_id) {
+    conditions.push("m.project_id = ?");
+    params.push(project_id);
+  }
+  const where = conditions.join(" AND ");
+  const rows = d.prepare(`SELECT m.*, e.embedding FROM memories m
+     JOIN memory_embeddings e ON e.memory_id = m.id
+     WHERE ${where}`).all(...params);
+  const scored = [];
+  for (const row of rows) {
+    try {
+      const docEmbedding = deserializeEmbedding(row.embedding);
+      const score = cosineSimilarity(queryEmbedding, docEmbedding);
+      if (score >= threshold) {
+        const { embedding: _, ...memRow } = row;
+        scored.push({ memory: parseMemoryRow(memRow), score: Math.round(score * 1000) / 1000 });
+      }
+    } catch {}
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
 var RECALL_PROMOTE_THRESHOLD = 3;
 var init_memories = __esm(() => {
   init_types();
@@ -3265,6 +3396,18 @@ var init_built_in_hooks = __esm(() => {
       });
     }
   });
+  hookRegistry.register({
+    type: "PostMemorySave",
+    blocking: false,
+    builtin: true,
+    priority: 300,
+    description: "Generate and store vector embedding for semantic memory search",
+    handler: async (ctx) => {
+      const { indexMemoryEmbedding: indexMemoryEmbedding2 } = await Promise.resolve().then(() => (init_memories(), exports_memories));
+      const text = [ctx.memory.value, ctx.memory.summary].filter(Boolean).join(" ");
+      indexMemoryEmbedding2(ctx.memory.id, text);
+    }
+  });
   hookRegistry.register({
     type: "PostMemoryInject",
     blocking: false,
@@ -9550,6 +9693,46 @@ ${lines.join(`
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
+server.tool("memory_search_semantic", "Semantic (meaning-based) memory search using vector embeddings. Finds memories by conceptual similarity, not keyword match. Uses OpenAI embeddings if OPENAI_API_KEY is set, otherwise TF-IDF.", {
+  query: exports_external.string().describe("Natural language query"),
+  threshold: exports_external.coerce.number().min(0).max(1).optional().describe("Minimum cosine similarity score (default: 0.5)"),
+  limit: exports_external.coerce.number().optional().describe("Max results (default: 10)"),
+  scope: exports_external.enum(["global", "shared", "private"]).optional(),
+  agent_id: exports_external.string().optional(),
+  project_id: exports_external.string().optional(),
+  index_missing: exports_external.coerce.boolean().optional().describe("If true, index any memories that lack embeddings before searching")
+}, async (args) => {
+  try {
+    ensureAutoProject();
+    if (args.index_missing) {
+      const db = getDatabase();
+      const unindexed = db.prepare(`SELECT id, value, summary FROM memories
+           WHERE status = 'active' AND id NOT IN (SELECT memory_id FROM memory_embeddings)
+           LIMIT 100`).all();
+      await Promise.all(unindexed.map((m) => indexMemoryEmbedding(m.id, [m.value, m.summary].filter(Boolean).join(" "))));
+    }
+    let effectiveProjectId = args.project_id;
+    if (!args.project_id && args.agent_id) {
+      effectiveProjectId = resolveProjectId(args.agent_id, null) ?? undefined;
+    }
+    const results = await semanticSearch(args.query, {
+      threshold: args.threshold,
+      limit: args.limit,
+      scope: args.scope,
+      agent_id: args.agent_id,
+      project_id: effectiveProjectId
+    });
+    if (results.length === 0) {
+      return { content: [{ type: "text", text: `No semantically similar memories found for: "${args.query}". Try a lower threshold or call with index_missing:true to generate embeddings first.` }] };
+    }
+    const lines = results.map((r, i) => `${i + 1}. [score:${r.score}] [${r.memory.scope}/${r.memory.category}] ${r.memory.key} = ${r.memory.value.slice(0, 120)}${r.memory.value.length > 120 ? "..." : ""}`);
+    return { content: [{ type: "text", text: `${results.length} semantic result(s) for "${args.query}":
+${lines.join(`
+`)}` }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
 server.tool("memory_stats", "Get aggregate statistics about stored memories", {}, async () => {
   try {
     const db = getDatabase();

package/dist/server/index.js

@@ -545,10 +545,93 @@ CREATE UNIQUE INDEX IF NOT EXISTS idx_resource_locks_exclusive
 CREATE INDEX IF NOT EXISTS idx_resource_locks_agent ON resource_locks(agent_id);
 CREATE INDEX IF NOT EXISTS idx_resource_locks_expires ON resource_locks(expires_at);
 INSERT OR IGNORE INTO _migrations (id) VALUES (14);
+`,
+    `
+CREATE TABLE IF NOT EXISTS memory_embeddings (
+  memory_id TEXT PRIMARY KEY REFERENCES memories(id) ON DELETE CASCADE,
+  embedding TEXT NOT NULL,
+  model TEXT NOT NULL DEFAULT 'tfidf-512',
+  dimensions INTEGER NOT NULL DEFAULT 512,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+CREATE INDEX IF NOT EXISTS idx_memory_embeddings_model ON memory_embeddings(model);
+INSERT OR IGNORE INTO _migrations (id) VALUES (15);
 `
   ];
 });
 
+// src/lib/embeddings.ts
+function cosineSimilarity(a, b) {
+  if (a.length !== b.length || a.length === 0)
+    return 0;
+  let dot = 0, magA = 0, magB = 0;
+  for (let i = 0;i < a.length; i++) {
+    dot += a[i] * b[i];
+    magA += a[i] * a[i];
+    magB += b[i] * b[i];
+  }
+  const denom = Math.sqrt(magA) * Math.sqrt(magB);
+  return denom === 0 ? 0 : dot / denom;
+}
+async function openAIEmbed(text, apiKey) {
+  const res = await fetch(OPENAI_EMBED_URL, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`
+    },
+    body: JSON.stringify({
+      model: EMBED_MODEL,
+      input: text.slice(0, 8192)
+    }),
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!res.ok) {
+    throw new Error(`OpenAI embedding API ${res.status}: ${await res.text()}`);
+  }
+  const data = await res.json();
+  return data.data[0].embedding;
+}
+function tfidfVector(text) {
+  const DIMS = 512;
+  const vec = new Float32Array(DIMS);
+  const tokens = text.toLowerCase().match(/\b\w+\b/g) ?? [];
+  for (const token of tokens) {
+    let hash = 2166136261;
+    for (let i = 0;i < token.length; i++) {
+      hash ^= token.charCodeAt(i);
+      hash = hash * 16777619 >>> 0;
+    }
+    vec[hash % DIMS] += 1;
+  }
+  let norm = 0;
+  for (let i = 0;i < DIMS; i++)
+    norm += vec[i] * vec[i];
+  norm = Math.sqrt(norm);
+  if (norm > 0)
+    for (let i = 0;i < DIMS; i++)
+      vec[i] /= norm;
+  return Array.from(vec);
+}
+async function generateEmbedding(text) {
+  const apiKey = process.env["OPENAI_API_KEY"];
+  if (apiKey) {
+    try {
+      const embedding2 = await openAIEmbed(text, apiKey);
+      return { embedding: embedding2, model: EMBED_MODEL, dimensions: EMBED_DIMENSIONS };
+    } catch {}
+  }
+  const embedding = tfidfVector(text);
+  return { embedding, model: "tfidf-512", dimensions: 512 };
+}
+function serializeEmbedding(embedding) {
+  return JSON.stringify(embedding);
+}
+function deserializeEmbedding(raw) {
+  return JSON.parse(raw);
+}
+var OPENAI_EMBED_URL = "https://api.openai.com/v1/embeddings", EMBED_MODEL = "text-embedding-3-small", EMBED_DIMENSIONS = 1536;
+
 // src/lib/redact.ts
 function redactSecrets(text) {
   let result = text;
@@ -721,8 +804,10 @@ var exports_memories = {};
 __export(exports_memories, {
   updateMemory: () => updateMemory,
   touchMemory: () => touchMemory,
+  semanticSearch: () => semanticSearch,
   parseMemoryRow: () => parseMemoryRow,
   listMemories: () => listMemories,
+  indexMemoryEmbedding: () => indexMemoryEmbedding,
   incrementRecallCount: () => incrementRecallCount,
   getMemoryVersions: () => getMemoryVersions,
   getMemoryByKey: () => getMemoryByKey,
@@ -1173,6 +1258,52 @@ function getMemoryVersions(memoryId, db) {
     return [];
   }
 }
+async function indexMemoryEmbedding(memoryId, text, db) {
+  try {
+    const d = db || getDatabase();
+    const { embedding, model, dimensions } = await generateEmbedding(text);
+    const serialized = serializeEmbedding(embedding);
+    d.run(`INSERT INTO memory_embeddings (memory_id, embedding, model, dimensions)
+       VALUES (?, ?, ?, ?)
+       ON CONFLICT(memory_id) DO UPDATE SET embedding=excluded.embedding, model=excluded.model, dimensions=excluded.dimensions, created_at=datetime('now')`, [memoryId, serialized, model, dimensions]);
+  } catch {}
+}
+async function semanticSearch(queryText, options = {}, db) {
+  const d = db || getDatabase();
+  const { threshold = 0.5, limit = 10, scope, agent_id, project_id } = options;
+  const { embedding: queryEmbedding } = await generateEmbedding(queryText);
+  const conditions = ["m.status = 'active'", "e.embedding IS NOT NULL"];
+  const params = [];
+  if (scope) {
+    conditions.push("m.scope = ?");
+    params.push(scope);
+  }
+  if (agent_id) {
+    conditions.push("m.agent_id = ?");
+    params.push(agent_id);
+  }
+  if (project_id) {
+    conditions.push("m.project_id = ?");
+    params.push(project_id);
+  }
+  const where = conditions.join(" AND ");
+  const rows = d.prepare(`SELECT m.*, e.embedding FROM memories m
+     JOIN memory_embeddings e ON e.memory_id = m.id
+     WHERE ${where}`).all(...params);
+  const scored = [];
+  for (const row of rows) {
+    try {
+      const docEmbedding = deserializeEmbedding(row.embedding);
+      const score = cosineSimilarity(queryEmbedding, docEmbedding);
+      if (score >= threshold) {
+        const { embedding: _, ...memRow } = row;
+        scored.push({ memory: parseMemoryRow(memRow), score: Math.round(score * 1000) / 1000 });
+      }
+    } catch {}
+  }
+  scored.sort((a, b) => b.score - a.score);
+  return scored.slice(0, limit);
+}
 var RECALL_PROMOTE_THRESHOLD = 3;
 var init_memories = __esm(() => {
   init_types();
@@ -3620,6 +3751,18 @@ hookRegistry.register({
     });
   }
 });
+hookRegistry.register({
+  type: "PostMemorySave",
+  blocking: false,
+  builtin: true,
+  priority: 300,
+  description: "Generate and store vector embedding for semantic memory search",
+  handler: async (ctx) => {
+    const { indexMemoryEmbedding: indexMemoryEmbedding2 } = await Promise.resolve().then(() => (init_memories(), exports_memories));
+    const text = [ctx.memory.value, ctx.memory.summary].filter(Boolean).join(" ");
+    indexMemoryEmbedding2(ctx.memory.id, text);
+  }
+});
 hookRegistry.register({
   type: "PostMemoryInject",
   blocking: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.10.10",
+  "version": "0.10.11",
   "description": "Universal memory system for AI agents - CLI + MCP server + library API",
   "type": "module",
   "main": "dist/index.js",