@jcyamacho/agent-memory 0.0.13 → 0.0.15

package/README.md

@@ -62,16 +62,34 @@ With a custom database path:
 }
 ```
 
+With a custom model cache path:
+
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@jcyamacho/agent-memory"
+      ],
+      "env": {
+        "AGENT_MEMORY_MODELS_CACHE_PATH": "/absolute/path/to/models"
+      }
+    }
+  }
+}
+```
+
 Optional LLM instructions to reinforce the MCP's built-in guidance:
 
 ```text
-Use `recall` at the start of every conversation and again mid-task before
-making design choices or picking conventions. Use `remember` when the user
-corrects your approach, a key decision is established, or you learn project
-context not obvious from the code. Before saving, recall to check whether a
-memory about the same fact already exists -- if so, use `revise` to update
-it instead of creating a duplicate. Use `forget` to remove memories that
-are wrong or no longer relevant. Always pass workspace.
+Use `recall` at conversation start and before design choices, conventions, or
+edge cases. Query with 2-5 short anchor-heavy terms or exact phrases, not
+questions or sentences. `recall` is lexical-first; if it misses, retry once
+with overlapping alternate terms. Use `remember` for one durable fact, then
+use `revise` instead of duplicates and `forget` for wrong or obsolete
+memories. Always pass workspace unless the memory is truly global.
 ```
 
 ## What It Stores
@@ -101,60 +119,10 @@ The web UI uses the same database as the MCP server.
 
 ## Tools
 
-### `remember`
-
-Save durable context for later recall.
-
-Inputs:
-
-- `content` -> fact, preference, decision, or context to store
-- `workspace` -> repository or workspace path
-
-Output:
-
-- `id`
-
-### `recall`
-
-Retrieve relevant memories for the current task.
-
-Inputs:
-
-- `terms` -> 2-5 distinctive terms or short phrases that should appear in the
-  memory content; avoid full natural-language questions
-- `limit` -> maximum results to return
-- `workspace` -> workspace or repo path; biases ranking toward this workspace
-- `updated_after` -> ISO 8601 lower bound
-- `updated_before` -> ISO 8601 upper bound
-
-Output:
-
-- `results[]` with `id`, `content`, `score`, `workspace`, and `updated_at`
-
-### `revise`
-
-Update the content of an existing memory.
-
-Inputs:
-
-- `id` -> the memory id from a previous recall result
-- `content` -> replacement content for the memory
-
-Output:
-
-- `id`, `updated_at`
-
-### `forget`
-
-Permanently delete a memory.
-
-Inputs:
-
-- `id` -> the memory id from a previous recall result
-
-Output:
-
-- `id`, `deleted`
+- `remember` saves durable facts, preferences, decisions, and project context.
+- `recall` retrieves the most relevant saved memories.
+- `revise` updates an existing memory when it becomes outdated.
+- `forget` deletes a memory that is no longer relevant.
 
 ## How Ranking Works
 
@@ -163,18 +131,21 @@ memories:
 
 1. **Text relevance** is the primary signal -- memories whose content best
    matches your search terms rank highest.
-2. **Workspace match** is a strong secondary signal. When you pass
+2. **Embedding similarity** is the next strongest signal. Recall builds an
+   embedding from your normalized search terms and boosts memories whose stored
+   embeddings are most semantically similar.
+3. **Workspace match** is a strong secondary signal. When you pass
    `workspace`, exact matches rank highest, sibling repositories get a small
    boost, and unrelated workspaces rank lowest.
-3. **Global memories** (saved without a workspace) are treated as relevant
+4. **Global memories** (saved without a workspace) are treated as relevant
    everywhere. When you pass `workspace`, they rank below exact workspace
    matches and above sibling or unrelated repositories.
-4. **Recency** is a minor tiebreaker -- newer memories rank slightly above older
+5. **Recency** is a minor tiebreaker -- newer memories rank slightly above older
    ones when other signals are equal.
 
-If you omit `workspace`, recall falls back to text relevance and recency only.
-For best results, pass `workspace` whenever you have one. Save memories without
-a workspace only when they apply across all projects.
+If you omit `workspace`, recall still uses text relevance, embedding similarity,
+and recency. For best results, pass `workspace` whenever you have one. Save
+memories without a workspace only when they apply across all projects.
 
 ## Database location
 
@@ -196,6 +167,26 @@ Set `AGENT_MEMORY_DB_PATH` when you want to:
 - share a memory DB across multiple clients
 - store the DB somewhere easier to back up or inspect
 
+## Model cache location
+
+By default, downloaded embedding model files are cached at:
+
+```text
+~/.config/agent-memory/models
+```
+
+Override it with:
+
+```bash
+AGENT_MEMORY_MODELS_CACHE_PATH=/absolute/path/to/models
+```
+
+Set `AGENT_MEMORY_MODELS_CACHE_PATH` when you want to:
+
+- keep model artifacts out of `node_modules`
+- share the model cache across reinstalls or multiple clients
+- store model downloads somewhere easier to inspect or manage
+
 Beta note: schema changes are not migrated. If you are upgrading from an older
 beta, delete the existing memory DB and let the server create a new one.
 

package/dist/index.js

@@ -2431,9 +2431,9 @@ var require_validate = __commonJS((exports) => {
     }
   }
   function returnResults(it) {
-    const { gen, schemaEnv, validateName, ValidationError, opts } = it;
+    const { gen, schemaEnv, validateName, ValidationError: ValidationError2, opts } = it;
     if (schemaEnv.$async) {
-      gen.if((0, codegen_1._)`${names_1.default.errors} === 0`, () => gen.return(names_1.default.data), () => gen.throw((0, codegen_1._)`new ${ValidationError}(${names_1.default.vErrors})`));
+      gen.if((0, codegen_1._)`${names_1.default.errors} === 0`, () => gen.return(names_1.default.data), () => gen.throw((0, codegen_1._)`new ${ValidationError2}(${names_1.default.vErrors})`));
     } else {
       gen.assign((0, codegen_1._)`${validateName}.errors`, names_1.default.vErrors);
       if (opts.unevaluated)
@@ -2783,14 +2783,14 @@ var require_validate = __commonJS((exports) => {
 var require_validation_error = __commonJS((exports) => {
   Object.defineProperty(exports, "__esModule", { value: true });
 
-  class ValidationError extends Error {
+  class ValidationError2 extends Error {
     constructor(errors3) {
       super("validation failed");
       this.errors = errors3;
       this.ajv = this.validation = true;
     }
   }
-  exports.default = ValidationError;
+  exports.default = ValidationError2;
 });
 
 // node_modules/ajv/dist/compile/ref_error.js
@@ -12464,13 +12464,14 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.13";
+var version2 = "0.0.15";
 
 // src/config.ts
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { parseArgs } from "node:util";
 var AGENT_MEMORY_DB_PATH_ENV = "AGENT_MEMORY_DB_PATH";
+var AGENT_MEMORY_MODELS_CACHE_PATH_ENV = "AGENT_MEMORY_MODELS_CACHE_PATH";
 var DEFAULT_UI_PORT = 6580;
 function resolveConfig(environment = process.env, argv = process.argv.slice(2)) {
   const { values } = parseArgs({
@@ -12482,12 +12483,146 @@ function resolveConfig(environment = process.env, argv = process.argv.slice(2))
     strict: false
   });
   return {
-    databasePath: environment[AGENT_MEMORY_DB_PATH_ENV] || join(homedir(), ".config", "agent-memory", "memory.db"),
+    databasePath: resolveDatabasePath(environment),
+    modelsCachePath: resolveModelsCachePath(environment),
     uiMode: Boolean(values.ui),
     uiPort: Number(values.port) || DEFAULT_UI_PORT
   };
 }
+function resolveDatabasePath(environment = process.env) {
+  return environment[AGENT_MEMORY_DB_PATH_ENV] || join(homedir(), ".config", "agent-memory", "memory.db");
+}
+function resolveModelsCachePath(environment = process.env) {
+  return environment[AGENT_MEMORY_MODELS_CACHE_PATH_ENV] || join(homedir(), ".config", "agent-memory", "models");
+}
+
+// src/embedding/service.ts
+import { mkdirSync } from "node:fs";
+import { pipeline, env as transformersEnv } from "@huggingface/transformers";
+
+// src/errors.ts
+class MemoryError extends Error {
+  code;
+  constructor(code, message, options) {
+    super(message, options);
+    this.name = "MemoryError";
+    this.code = code;
+  }
+}
+
+class ValidationError extends MemoryError {
+  constructor(message) {
+    super("VALIDATION_ERROR", message);
+    this.name = "ValidationError";
+  }
+}
 
+class NotFoundError extends MemoryError {
+  constructor(message) {
+    super("NOT_FOUND", message);
+    this.name = "NotFoundError";
+  }
+}
+
+class PersistenceError extends MemoryError {
+  constructor(message, options) {
+    super("PERSISTENCE_ERROR", message, options);
+    this.name = "PersistenceError";
+  }
+}
+
+// src/embedding/service.ts
+var DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
+
+class EmbeddingService {
+  options;
+  extractorPromise;
+  modelsCachePath;
+  constructor(options = {}) {
+    this.options = options;
+    this.modelsCachePath = options.modelsCachePath ?? resolveModelsCachePath();
+  }
+  async createVector(text) {
+    const normalizedText = text.trim();
+    if (!normalizedText) {
+      throw new ValidationError("Text is required.");
+    }
+    const extractor = await this.getExtractor();
+    const embedding = await extractor(normalizedText);
+    return normalizeVector(embedding.tolist());
+  }
+  getExtractor() {
+    if (!this.extractorPromise) {
+      configureModelsCache(this.modelsCachePath);
+      this.extractorPromise = (this.options.createExtractor ?? createDefaultExtractor)();
+    }
+    return this.extractorPromise;
+  }
+}
+function configureModelsCache(modelsCachePath) {
+  mkdirSync(modelsCachePath, { recursive: true });
+  transformersEnv.useFSCache = true;
+  transformersEnv.cacheDir = modelsCachePath;
+}
+async function createDefaultExtractor() {
+  const extractor = await pipeline("feature-extraction", DEFAULT_EMBEDDING_MODEL);
+  return (text) => extractor(text, {
+    pooling: "mean",
+    normalize: true
+  });
+}
+function normalizeVector(value) {
+  if (value.length === 0) {
+    throw new ValidationError("Embedding model returned an empty vector.");
+  }
+  const [firstItem] = value;
+  if (typeof firstItem === "number") {
+    return value.map((item) => {
+      if (typeof item !== "number" || !Number.isFinite(item)) {
+        throw new ValidationError("Embedding model returned a non-numeric vector.");
+      }
+      return item;
+    });
+  }
+  if (Array.isArray(firstItem)) {
+    return normalizeVector(firstItem);
+  }
+  throw new ValidationError("Embedding model returned an unexpected vector shape.");
+}
+// src/embedding/similarity.ts
+function compareVectors(left, right) {
+  validateVector(left, "Left vector");
+  validateVector(right, "Right vector");
+  if (left.length !== right.length) {
+    throw new ValidationError("Vectors must have the same length.");
+  }
+  let dotProduct = 0;
+  let leftMagnitude = 0;
+  let rightMagnitude = 0;
+  for (const [index, leftValue] of left.entries()) {
+    const rightValue = right[index];
+    if (rightValue === undefined) {
+      throw new ValidationError("Vectors must have the same length.");
+    }
+    dotProduct += leftValue * rightValue;
+    leftMagnitude += leftValue * leftValue;
+    rightMagnitude += rightValue * rightValue;
+  }
+  if (leftMagnitude === 0 || rightMagnitude === 0) {
+    throw new ValidationError("Vectors must not have zero magnitude.");
+  }
+  return dotProduct / (Math.sqrt(leftMagnitude) * Math.sqrt(rightMagnitude));
+}
+function validateVector(vector, label) {
+  if (vector.length === 0) {
+    throw new ValidationError(`${label} must not be empty.`);
+  }
+  for (const value of vector) {
+    if (!Number.isFinite(value)) {
+      throw new ValidationError(`${label} must contain only finite numbers.`);
+    }
+  }
+}
 // node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
@@ -19895,37 +20030,6 @@ var EMPTY_COMPLETION_RESULT = {
   }
 };
 
-// src/errors.ts
-class MemoryError extends Error {
-  code;
-  constructor(code, message, options) {
-    super(message, options);
-    this.name = "MemoryError";
-    this.code = code;
-  }
-}
-
-class ValidationError extends MemoryError {
-  constructor(message) {
-    super("VALIDATION_ERROR", message);
-    this.name = "ValidationError";
-  }
-}
-
-class NotFoundError extends MemoryError {
-  constructor(message) {
-    super("NOT_FOUND", message);
-    this.name = "NotFoundError";
-  }
-}
-
-class PersistenceError extends MemoryError {
-  constructor(message, options) {
-    super("PERSISTENCE_ERROR", message, options);
-    this.name = "PersistenceError";
-  }
-}
-
 // src/mcp/tools/shared.ts
 function toMcpError(error2) {
   if (error2 instanceof McpError) {
@@ -19954,11 +20058,11 @@ function parseOptionalDate(value, fieldName) {
 
 // src/mcp/tools/forget.ts
 var forgetInputSchema = {
-  id: string2().describe("The id of the memory to delete. Use the id returned by a previous recall result.")
+  id: string2().describe("The memory id to delete. Use an id returned by `recall`.")
 };
 function registerForgetTool(server, memory) {
   server.registerTool("forget", {
-    description: "Permanently delete a memory that is wrong, obsolete, or no longer relevant. Pass the memory id from a previous recall result.",
+    description: 'Permanently delete a wrong or obsolete memory. Use `revise` instead when the fact still exists and only needs correction. Returns `<memory id="..." deleted="true" />`.',
     inputSchema: forgetInputSchema
   }, async ({ id }) => {
     try {
@@ -19977,12 +20081,13 @@ var toNormalizedScore = (value) => value;
 
 // src/ranking.ts
 var RETRIEVAL_SCORE_WEIGHT = 8;
+var EMBEDDING_SIMILARITY_WEIGHT = 5;
 var WORKSPACE_MATCH_WEIGHT = 4;
-var RECENCY_WEIGHT = 1;
-var MAX_COMPOSITE_SCORE = RETRIEVAL_SCORE_WEIGHT + WORKSPACE_MATCH_WEIGHT + RECENCY_WEIGHT;
+var RECENCY_WEIGHT = 2;
+var MAX_COMPOSITE_SCORE = RETRIEVAL_SCORE_WEIGHT + EMBEDDING_SIMILARITY_WEIGHT + WORKSPACE_MATCH_WEIGHT + RECENCY_WEIGHT;
 var GLOBAL_WORKSPACE_SCORE = 0.5;
 var SIBLING_WORKSPACE_SCORE = 0.25;
-function rerankSearchResults(results, workspace) {
+function rerankSearchResults(results, workspace, queryEmbedding) {
   if (results.length <= 1) {
     return results;
   }
@@ -19991,18 +20096,25 @@ function rerankSearchResults(results, workspace) {
   const minUpdatedAt = Math.min(...updatedAtTimes);
   const maxUpdatedAt = Math.max(...updatedAtTimes);
   return results.map((result) => {
+    const embeddingSimilarityScore = computeEmbeddingSimilarityScore(result, queryEmbedding);
     const workspaceScore = computeWorkspaceScore(result.workspace, normalizedQueryWs);
     const recencyScore = maxUpdatedAt === minUpdatedAt ? 0 : (result.updatedAt.getTime() - minUpdatedAt) / (maxUpdatedAt - minUpdatedAt);
-    const combinedScore = (result.score * RETRIEVAL_SCORE_WEIGHT + workspaceScore * WORKSPACE_MATCH_WEIGHT + recencyScore * RECENCY_WEIGHT) / MAX_COMPOSITE_SCORE;
+    const combinedScore = (result.score * RETRIEVAL_SCORE_WEIGHT + embeddingSimilarityScore * EMBEDDING_SIMILARITY_WEIGHT + workspaceScore * WORKSPACE_MATCH_WEIGHT + recencyScore * RECENCY_WEIGHT) / MAX_COMPOSITE_SCORE;
     return {
       ...result,
       score: toNormalizedScore(combinedScore)
     };
   }).sort((a, b) => b.score - a.score);
 }
+function computeEmbeddingSimilarityScore(result, queryEmbedding) {
+  return normalizeCosineSimilarity(compareVectors(result.embedding, queryEmbedding));
+}
 function normalizeWorkspacePath(value) {
   return value.trim().replaceAll("\\", "/").replace(/\/+/g, "/").split("/").filter(Boolean).join("/");
 }
+function normalizeCosineSimilarity(value) {
+  return (value + 1) / 2;
+}
 function computeWorkspaceScore(memoryWs, queryWs) {
   if (!queryWs) {
     return 0;
@@ -20033,24 +20145,33 @@ var MAX_LIST_LIMIT = 100;
 
 class MemoryService {
   repository;
-  constructor(repository) {
+  embeddingService;
+  constructor(repository, embeddingService) {
     this.repository = repository;
+    this.embeddingService = embeddingService;
   }
   async create(input) {
     const content = input.content.trim();
     if (!content) {
       throw new ValidationError("Memory content is required.");
     }
-    return this.repository.create({
+    const memory = await this.repository.create({
       content,
+      embedding: await this.embeddingService.createVector(content),
       workspace: normalizeOptionalString(input.workspace)
     });
+    return toPublicMemoryRecord(memory);
   }
   async update(input) {
     const content = input.content.trim();
     if (!content)
       throw new ValidationError("Memory content is required.");
-    return this.repository.update({ id: input.id, content });
+    const memory = await this.repository.update({
+      id: input.id,
+      content,
+      embedding: await this.embeddingService.createVector(content)
+    });
+    return toPublicMemoryRecord(memory);
   }
   async delete(input) {
     const id = input.id.trim();
@@ -20059,16 +20180,18 @@ class MemoryService {
     return this.repository.delete({ id });
   }
   async get(id) {
-    return this.repository.get(id);
+    const memory = await this.repository.get(id);
+    return memory ? toPublicMemoryRecord(memory) : undefined;
   }
   async list(input) {
     const workspace = normalizeOptionalString(input.workspace);
-    return this.repository.list({
+    const page = await this.repository.list({
       workspace,
       workspaceIsNull: workspace ? false : Boolean(input.workspaceIsNull),
       offset: normalizeOffset(input.offset),
       limit: normalizeListLimit(input.limit)
     });
+    return toPublicMemoryPage(page);
   }
   async listWorkspaces() {
     return this.repository.listWorkspaces();
@@ -20086,10 +20209,38 @@ class MemoryService {
       updatedAfter: input.updatedAfter,
       updatedBefore: input.updatedBefore
     };
-    const results = await this.repository.search(normalizedQuery);
-    return rerankSearchResults(results, workspace).slice(0, requestedLimit);
+    const [results, queryEmbedding] = await Promise.all([
+      this.repository.search(normalizedQuery),
+      this.embeddingService.createVector(terms.join(" "))
+    ]);
+    return rerankSearchResults(results, workspace, queryEmbedding).slice(0, requestedLimit).map(toPublicSearchResult);
   }
 }
+function toPublicMemoryRecord(memory) {
+  return {
+    id: memory.id,
+    content: memory.content,
+    workspace: memory.workspace,
+    createdAt: memory.createdAt,
+    updatedAt: memory.updatedAt
+  };
+}
+function toPublicSearchResult(result) {
+  return {
+    id: result.id,
+    content: result.content,
+    score: result.score,
+    workspace: result.workspace,
+    createdAt: result.createdAt,
+    updatedAt: result.updatedAt
+  };
+}
+function toPublicMemoryPage(page) {
+  return {
+    items: page.items.map(toPublicMemoryRecord),
+    hasMore: page.hasMore
+  };
+}
 function normalizeLimit(value) {
   if (value === undefined) {
     return DEFAULT_RECALL_LIMIT;
@@ -20119,22 +20270,23 @@ function normalizeTerms(terms) {
 
 // src/mcp/tools/recall.ts
 var recallInputSchema = {
-  terms: array(string2()).min(1).describe("Search terms used to find relevant memories. Pass 2-5 short, distinctive items as separate array entries. Be specific: instead of 'preferences' or 'context', name the actual topic -- e.g. 'error handling', 'commit format', 'testing strategy'. Do not repeat the project or workspace name here -- use the workspace parameter for project scoping. Avoid full sentences."),
-  limit: number2().int().min(1).max(MAX_RECALL_LIMIT).optional().describe("Maximum number of matches to return. Keep this small when you only need the strongest hits."),
-  workspace: string2().optional().describe("Always pass the current working directory. Biases ranking toward the active project while still allowing cross-workspace matches. Memories saved without a workspace are treated as global and rank between matching and non-matching results."),
-  updated_after: string2().optional().describe("Only return memories updated at or after this ISO 8601 timestamp. Use it when you need to narrow recall to newer context."),
-  updated_before: string2().optional().describe("Only return memories updated at or before this ISO 8601 timestamp. Use it when you need to narrow recall to older context.")
+  terms: array(string2()).min(1).describe("Search terms for lexical memory lookup. Pass 2-5 short anchor-heavy terms or exact phrases as separate entries. Prefer identifiers, commands, file paths, package names, and conventions likely to appear verbatim in the memory. Avoid vague words, full sentences, and repeating the workspace name. If recall misses, retry once with overlapping alternate terms."),
+  limit: number2().int().min(1).max(MAX_RECALL_LIMIT).optional().describe("Maximum matches to return. Keep this small when you only need the strongest hits."),
+  workspace: string2().optional().describe("Pass the current working directory. This strongly boosts memories from the active project while still allowing global and cross-workspace matches."),
+  updated_after: string2().optional().describe("Only return memories updated at or after this ISO 8601 timestamp."),
+  updated_before: string2().optional().describe("Only return memories updated at or before this ISO 8601 timestamp.")
 };
 function toMemoryXml(r) {
   const workspace = r.workspace ? ` workspace="${escapeXml(r.workspace)}"` : "";
   const content = escapeXml(r.content);
-  return `<memory id="${r.id}" score="${r.score}"${workspace} updated_at="${r.updatedAt.toISOString()}">
+  const score = Number(r.score.toFixed(3)).toString();
+  return `<memory id="${r.id}" score="${score}"${workspace} updated_at="${r.updatedAt.toISOString()}">
 ${content}
 </memory>`;
 }
 function registerRecallTool(server, memory) {
   server.registerTool("recall", {
-    description: "Search memories for prior decisions, corrections, and context that cannot be derived from code or git history. Call at the start of every conversation and again mid-task when you are about to make a design choice, pick a convention, or handle an edge case that the user may have guided before. Always pass workspace.",
+    description: "Retrieve relevant memories for the current task. Use at conversation start and before design choices, conventions, or edge cases. Query with 2-5 short anchor-heavy terms or exact phrases, not questions or full sentences. `recall` is lexical-first; semantic reranking only reorders lexical matches. If it misses, retry once with overlapping alternate terms. Pass workspace. Returns `<memories>...</memories>` or a no-match hint.",
     inputSchema: recallInputSchema
   }, async ({ terms, limit, workspace, updated_after, updated_before }) => {
     try {
@@ -20145,7 +20297,7 @@ function registerRecallTool(server, memory) {
         updatedAfter: parseOptionalDate(updated_after, "updated_after"),
         updatedBefore: parseOptionalDate(updated_before, "updated_before")
       });
-      const text = results.length === 0 ? "No matching memories found." : `<memories>
+      const text = results.length === 0 ? "No matching memories found. Retry once with 1-3 alternate overlapping terms or an exact phrase likely to appear in the memory text. Recall is lexical-first, so semantic reranking cannot rescue a query with no wording overlap." : `<memories>
 ${results.map(toMemoryXml).join(`
 `)}
 </memories>`;
@@ -20160,12 +20312,12 @@ ${results.map(toMemoryXml).join(`
 
 // src/mcp/tools/remember.ts
 var rememberInputSchema = {
-  content: string2().describe("The fact, preference, decision, or context to remember. Use a single self-contained sentence or short note. One fact per memory."),
-  workspace: string2().optional().describe("Always pass the current working directory to scope this memory to a project. Omit only when the memory applies across all projects (global preference).")
+  content: string2().describe("One durable fact to save. Use a single self-contained sentence or short note with concrete nouns, identifiers, commands, file paths, or exact phrases the agent is likely to reuse."),
+  workspace: string2().optional().describe("Pass the current working directory for project-specific memories. Omit only for truly global memories.")
 };
 function registerRememberTool(server, memory) {
   server.registerTool("remember", {
-    description: "Save durable context for later recall. Use this when the user corrects your approach, states a preference, a key decision or convention is established, or you learn project context not obvious from the code. Store one concise fact per memory. Do not store secrets, ephemeral task state, or information already in the codebase.",
+    description: 'Save one durable memory for later recall. Use when the user states a stable preference, corrects you, or establishes reusable project context not obvious from code or git history. Save one fact per memory. Call `recall` first; use `revise` instead of creating duplicates. Do not store secrets, temporary task state, or codebase facts. Returns `<memory id="..." />`.',
     inputSchema: rememberInputSchema
   }, async ({ content, workspace }) => {
     try {
@@ -20184,12 +20336,12 @@ function registerRememberTool(server, memory) {
 
 // src/mcp/tools/revise.ts
 var reviseInputSchema = {
-  id: string2().describe("The id of the memory to update. Use the id returned by a previous recall result."),
-  content: string2().describe("The replacement content for the memory. Use a single self-contained sentence or short note. One fact per memory.")
+  id: string2().describe("The memory id to update. Use an id returned by `recall`."),
+  content: string2().describe("The corrected replacement for that same fact. Keep it to one durable fact.")
 };
 function registerReviseTool(server, memory) {
   server.registerTool("revise", {
-    description: "Update the content of an existing memory. Use when a previously saved memory is outdated or inaccurate and needs correction rather than deletion. Pass the memory id from a previous recall result.",
+    description: 'Replace one existing memory with corrected wording. Use after `recall` when the same fact still applies but details changed. Do not append unrelated facts or merge memories. Returns `<memory id="..." updated_at="..." />`.',
     inputSchema: reviseInputSchema
   }, async ({ id, content }) => {
     try {
@@ -20210,14 +20362,15 @@ function registerReviseTool(server, memory) {
 
 // src/mcp/server.ts
 var SERVER_INSTRUCTIONS = [
-  "Stores decisions, corrections, and context that cannot be derived from code or git history.",
-  "Use `recall` at the start of every conversation and again mid-task before making design choices or picking conventions the user may have guided before.",
-  "Use `remember` when the user corrects your approach, states a preference, a key decision is established, or you learn project context not obvious from the code.",
-  "Before saving a new memory, recall to check whether a memory about the same fact already exists. If so, use `revise` to update it instead of creating a duplicate.",
-  "Use `revise` when a previously saved memory is outdated or inaccurate and needs correction rather than deletion.",
-  "Use `forget` to remove memories that are wrong, obsolete, or no longer relevant.",
-  "Always pass workspace (the current working directory) to scope results to the active project.",
-  "Omit workspace only when saving a memory that applies across all projects."
+  "Use this server for durable memory: user preferences, corrections, decisions, and project context not obvious from code or git history.",
+  "Use `recall` at conversation start and before design choices, conventions, or edge cases.",
+  "Query `recall` with 2-5 short anchor-heavy terms or exact phrases likely to appear verbatim in memory text: identifiers, commands, file paths, and conventions.",
+  "`recall` is lexical-first; semantic reranking only reorders lexical matches.",
+  "If `recall` misses, retry once with overlapping alternate terms.",
+  "Use `remember` for one durable fact when the user states a preference, corrects you, or a reusable project decision becomes clear.",
+  "Call `recall` before `remember`; if the fact already exists, use `revise` instead of creating a duplicate.",
+  "Use `revise` to correct an existing memory and `forget` to remove a wrong or obsolete one.",
+  "Pass workspace for project-scoped calls. Omit it only for truly global memories."
 ].join(" ");
 function createMcpServer(memory, version3) {
   const server = new McpServer({
@@ -20233,72 +20386,242 @@ function createMcpServer(memory, version3) {
   return server;
 }
 
-// src/sqlite-db.ts
-import { mkdirSync } from "node:fs";
+// src/sqlite/db.ts
+import { mkdirSync as mkdirSync2 } from "node:fs";
 import { dirname } from "node:path";
 import Database from "better-sqlite3";
-var MEMORY_SCHEMA = `
-  CREATE TABLE IF NOT EXISTS memories (
-    id TEXT PRIMARY KEY,
-    content TEXT NOT NULL,
-    workspace TEXT,
-    created_at INTEGER NOT NULL,
-    updated_at INTEGER NOT NULL
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at);
-  CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace);
-
-  CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
-    content,
-    content = 'memories',
-    content_rowid = 'rowid',
-    tokenize = 'porter unicode61'
-  );
-
-  CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
-    INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
-  END;
-
-  CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
-    INSERT INTO memories_fts(memories_fts, rowid, content)
-    VALUES ('delete', old.rowid, old.content);
-  END;
-
-  CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
-    INSERT INTO memories_fts(memories_fts, rowid, content)
-    VALUES ('delete', old.rowid, old.content);
-    INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
-  END;
-`;
-function openMemoryDatabase(databasePath) {
+
+// src/sqlite/memory-schema.ts
+function createMemoriesTable(database, options) {
+  const embeddingColumn = getEmbeddingColumnSql(options.embeddingColumn);
+  database.exec(`
+    CREATE TABLE IF NOT EXISTS memories (
+      id TEXT PRIMARY KEY,
+      content TEXT NOT NULL,
+      workspace TEXT,
+      ${embeddingColumn}
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+  `);
+}
+function createMemoryIndexes(database) {
+  database.exec(`
+    CREATE INDEX IF NOT EXISTS idx_memories_created_at ON memories(created_at);
+    CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace);
+  `);
+}
+function createMemorySearchArtifacts(database, rebuild = false) {
+  database.exec(`
+    CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
+      content,
+      content = 'memories',
+      content_rowid = 'rowid',
+      tokenize = 'porter unicode61'
+    );
+
+    CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
+      INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content)
+      VALUES ('delete', old.rowid, old.content);
+    END;
+
+    CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
+      INSERT INTO memories_fts(memories_fts, rowid, content)
+      VALUES ('delete', old.rowid, old.content);
+      INSERT INTO memories_fts(rowid, content) VALUES (new.rowid, new.content);
+    END;
+  `);
+  if (rebuild) {
+    database.exec("INSERT INTO memories_fts(memories_fts) VALUES ('rebuild')");
+  }
+}
+function dropMemorySearchArtifacts(database) {
+  database.exec(`
+    DROP TRIGGER IF EXISTS memories_ai;
+    DROP TRIGGER IF EXISTS memories_ad;
+    DROP TRIGGER IF EXISTS memories_au;
+    DROP TABLE IF EXISTS memories_fts;
+  `);
+}
+function getEmbeddingColumnSql(mode) {
+  switch (mode) {
+    case "omit":
+      return "";
+    case "nullable":
+      return `embedding BLOB,
+      `;
+    case "required":
+      return `embedding BLOB NOT NULL,
+      `;
+  }
+}
+
+// src/sqlite/migrations/001-create-memory-schema.ts
+var createMemorySchemaMigration = {
+  version: 1,
+  async up(database) {
+    createMemoriesTable(database, { embeddingColumn: "omit" });
+    createMemoryIndexes(database);
+    createMemorySearchArtifacts(database);
+  }
+};
+
+// src/sqlite/embedding-codec.ts
+var FLOAT32_BYTE_WIDTH = 4;
+function encodeEmbedding(vector) {
+  const typedArray = Float32Array.from(vector);
+  return new Uint8Array(typedArray.buffer.slice(0));
+}
+function decodeEmbedding(value) {
+  const bytes = toUint8Array(value);
+  if (bytes.byteLength === 0) {
+    throw new Error("Embedding blob is empty.");
+  }
+  if (bytes.byteLength % FLOAT32_BYTE_WIDTH !== 0) {
+    throw new Error("Embedding blob length is not a multiple of 4.");
+  }
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  const vector = [];
+  for (let offset = 0;offset < bytes.byteLength; offset += FLOAT32_BYTE_WIDTH) {
+    vector.push(view.getFloat32(offset, true));
+  }
+  return vector;
+}
+function toUint8Array(value) {
+  if (value instanceof Uint8Array) {
+    return value;
+  }
+  if (value instanceof ArrayBuffer) {
+    return new Uint8Array(value);
+  }
+  throw new Error("Expected embedding blob as Uint8Array or ArrayBuffer.");
+}
+
+// src/sqlite/migrations/002-add-memory-embedding.ts
+function createAddMemoryEmbeddingMigration(embeddingService = new EmbeddingService) {
+  return {
+    version: 2,
+    async up(database) {
+      database.exec("ALTER TABLE memories ADD COLUMN embedding BLOB");
+      const rows = database.prepare("SELECT id, content FROM memories ORDER BY created_at ASC").all();
+      const updateStatement = database.prepare("UPDATE memories SET embedding = ? WHERE id = ?");
+      for (const row of rows) {
+        const embedding = await embeddingService.createVector(row.content);
+        updateStatement.run(encodeEmbedding(embedding), row.id);
+      }
+      const nullRows = database.prepare("SELECT COUNT(*) AS count FROM memories WHERE embedding IS NULL").all();
+      if ((nullRows[0]?.count ?? 0) > 0) {
+        throw new Error("Failed to backfill embeddings for all memories.");
+      }
+      dropMemorySearchArtifacts(database);
+      database.exec("ALTER TABLE memories RENAME TO memories_old");
+      createMemoriesTable(database, { embeddingColumn: "required" });
+      database.exec(`
+        INSERT INTO memories (id, content, workspace, embedding, created_at, updated_at)
+        SELECT id, content, workspace, embedding, created_at, updated_at
+        FROM memories_old
+      `);
+      database.exec("DROP TABLE memories_old");
+      createMemoryIndexes(database);
+      createMemorySearchArtifacts(database, true);
+    }
+  };
+}
+var addMemoryEmbeddingMigration = createAddMemoryEmbeddingMigration();
+
+// src/sqlite/migrations/index.ts
+function createMemoryMigrations(embeddingService = new EmbeddingService) {
+  return [createMemorySchemaMigration, createAddMemoryEmbeddingMigration(embeddingService)];
+}
+var MEMORY_MIGRATIONS = createMemoryMigrations();
+
+// src/sqlite/db.ts
+var PRAGMA_STATEMENTS = [
+  "journal_mode = WAL",
+  "synchronous = NORMAL",
+  "foreign_keys = ON",
+  "busy_timeout = 5000"
+];
+async function openMemoryDatabase(databasePath, options = {}) {
+  let database;
   try {
-    mkdirSync(dirname(databasePath), { recursive: true });
-    const database = new Database(databasePath);
-    initializeMemoryDatabase(database);
+    mkdirSync2(dirname(databasePath), { recursive: true });
+    database = new Database(databasePath);
+    await initializeMemoryDatabase(database, createMemoryMigrations(options.embeddingService));
     return database;
+  } catch (error2) {
+    database?.close();
+    if (error2 instanceof PersistenceError) {
+      throw error2;
+    }
+    throw new PersistenceError("Failed to initialize the SQLite database.", {
+      cause: error2
+    });
+  }
+}
+async function initializeMemoryDatabase(database, migrations = MEMORY_MIGRATIONS) {
+  try {
+    applyPragmas(database);
+    await runSqliteMigrations(database, migrations);
   } catch (error2) {
     throw new PersistenceError("Failed to initialize the SQLite database.", {
       cause: error2
     });
   }
 }
-function initializeMemoryDatabase(database) {
+async function runSqliteMigrations(database, migrations) {
+  validateMigrations(migrations);
+  let currentVersion = getUserVersion(database);
+  for (const migration of migrations) {
+    if (migration.version <= currentVersion) {
+      continue;
+    }
+    database.exec("BEGIN");
+    try {
+      await migration.up(database);
+      setUserVersion(database, migration.version);
+      database.exec("COMMIT");
+      currentVersion = migration.version;
+    } catch (error2) {
+      try {
+        database.exec("ROLLBACK");
+      } catch {}
+      throw error2;
+    }
+  }
+}
+function applyPragmas(database) {
   if (database.pragma) {
-    database.pragma("journal_mode = WAL");
-    database.pragma("synchronous = NORMAL");
-    database.pragma("foreign_keys = ON");
-    database.pragma("busy_timeout = 5000");
-  } else {
-    database.exec("PRAGMA journal_mode = WAL");
-    database.exec("PRAGMA synchronous = NORMAL");
-    database.exec("PRAGMA foreign_keys = ON");
-    database.exec("PRAGMA busy_timeout = 5000");
+    for (const statement of PRAGMA_STATEMENTS) {
+      database.pragma(statement);
+    }
+    return;
+  }
+  for (const statement of PRAGMA_STATEMENTS) {
+    database.exec(`PRAGMA ${statement}`);
   }
-  database.exec(MEMORY_SCHEMA);
 }
-
-// src/sqlite-memory-repository.ts
+function getUserVersion(database) {
+  const rows = database.prepare("PRAGMA user_version").all();
+  return rows[0]?.user_version ?? 0;
+}
+function setUserVersion(database, version3) {
+  database.exec(`PRAGMA user_version = ${version3}`);
+}
+function validateMigrations(migrations) {
+  let previousVersion = 0;
+  for (const migration of migrations) {
+    if (!Number.isInteger(migration.version) || migration.version <= previousVersion) {
+      throw new Error("SQLite migrations must use strictly increasing versions.");
+    }
+    previousVersion = migration.version;
+  }
+}
+// src/sqlite/repository.ts
 import { randomUUID } from "node:crypto";
 var DEFAULT_SEARCH_LIMIT = 15;
 var DEFAULT_LIST_LIMIT2 = 15;
@@ -20317,6 +20640,7 @@ class SqliteMemoryRepository {
         id,
         content,
         workspace,
+        embedding,
         created_at,
         updated_at
       ) VALUES (
@@ -20324,11 +20648,12 @@ class SqliteMemoryRepository {
         ?,
         ?,
         ?,
+        ?,
         ?
       )
     `);
-    this.getStatement = database.prepare("SELECT id, content, workspace, created_at, updated_at FROM memories WHERE id = ?");
-    this.updateStatement = database.prepare("UPDATE memories SET content = ?, updated_at = ? WHERE id = ?");
+    this.getStatement = database.prepare("SELECT id, content, workspace, embedding, created_at, updated_at FROM memories WHERE id = ?");
+    this.updateStatement = database.prepare("UPDATE memories SET content = ?, embedding = ?, updated_at = ? WHERE id = ?");
     this.deleteStatement = database.prepare("DELETE FROM memories WHERE id = ?");
     this.listWorkspacesStatement = database.prepare("SELECT DISTINCT workspace FROM memories WHERE workspace IS NOT NULL ORDER BY workspace");
   }
@@ -20338,11 +20663,12 @@ class SqliteMemoryRepository {
       const memory = {
         id: randomUUID(),
         content: input.content,
+        embedding: input.embedding,
         workspace: input.workspace,
         createdAt: now,
         updatedAt: now
       };
-      this.insertStatement.run(memory.id, memory.content, memory.workspace, memory.createdAt.getTime(), memory.updatedAt.getTime());
+      this.insertStatement.run(memory.id, memory.content, memory.workspace, encodeEmbedding(memory.embedding), memory.createdAt.getTime(), memory.updatedAt.getTime());
       return memory;
     } catch (error2) {
       throw new PersistenceError("Failed to save memory.", { cause: error2 });
@@ -20367,6 +20693,7 @@ class SqliteMemoryRepository {
           m.id,
           m.content,
           m.workspace,
+          m.embedding,
           m.created_at,
           m.updated_at,
           MAX(0, -bm25(memories_fts)) AS score
@@ -20379,7 +20706,7 @@ class SqliteMemoryRepository {
       const rows = statement.all(...params);
       const maxScore = Math.max(...rows.map((row) => row.score), 0);
       return rows.map((row) => ({
-        ...toMemoryRecord(row),
+        ...toMemoryEntity(row),
         score: toNormalizedScore(maxScore > 0 ? row.score / maxScore : 0)
       }));
     } catch (error2) {
@@ -20392,7 +20719,7 @@ class SqliteMemoryRepository {
     try {
       const rows = this.getStatement.all(id);
       const row = rows[0];
-      return row ? toMemoryRecord(row) : undefined;
+      return row ? toMemoryEntity(row) : undefined;
     } catch (error2) {
       throw new PersistenceError("Failed to find memory.", { cause: error2 });
     }
@@ -20413,7 +20740,7 @@ class SqliteMemoryRepository {
       const queryLimit = limit + 1;
       params.push(queryLimit, offset);
       const statement = this.database.prepare(`
-        SELECT id, content, workspace, created_at, updated_at
+        SELECT id, content, workspace, embedding, created_at, updated_at
         FROM memories
         ${whereClause}
         ORDER BY created_at DESC
@@ -20421,7 +20748,7 @@ class SqliteMemoryRepository {
       `);
       const rows = statement.all(...params);
       const hasMore = rows.length > limit;
-      const items = (hasMore ? rows.slice(0, limit) : rows).map(toMemoryRecord);
+      const items = (hasMore ? rows.slice(0, limit) : rows).map(toMemoryEntity);
       return { items, hasMore };
     } catch (error2) {
       throw new PersistenceError("Failed to list memories.", { cause: error2 });
@@ -20431,7 +20758,7 @@ class SqliteMemoryRepository {
     let result;
     try {
       const now = Date.now();
-      result = this.updateStatement.run(input.content, now, input.id);
+      result = this.updateStatement.run(input.content, encodeEmbedding(input.embedding), now, input.id);
     } catch (error2) {
       throw new PersistenceError("Failed to update memory.", { cause: error2 });
     }
@@ -20464,9 +20791,10 @@ class SqliteMemoryRepository {
     }
   }
 }
-var toMemoryRecord = (row) => ({
+var toMemoryEntity = (row) => ({
   id: row.id,
   content: row.content,
+  embedding: decodeEmbedding(row.embedding),
   workspace: row.workspace ?? undefined,
   createdAt: new Date(row.created_at),
   updatedAt: new Date(row.updated_at)
@@ -20479,7 +20807,6 @@ function toFtsTerm(term) {
   }
   return `"${escaped}"*`;
 }
-
 // node_modules/@hono/node-server/dist/index.mjs
 import { createServer as createServerHTTP } from "http";
 import { Http2ServerRequest as Http2ServerRequest2 } from "http2";
@@ -23870,9 +24197,10 @@ function startWebServer(memory, options) {
 
 // src/index.ts
 var config2 = resolveConfig();
-var database = openMemoryDatabase(config2.databasePath);
-var repository = new SqliteMemoryRepository(database);
-var memoryService = new MemoryService(repository);
+var embeddingService = new EmbeddingService({ modelsCachePath: config2.modelsCachePath });
+var database = await openMemoryDatabase(config2.databasePath, { embeddingService });
+var repository2 = new SqliteMemoryRepository(database);
+var memoryService = new MemoryService(repository2, embeddingService);
 if (config2.uiMode) {
   let shutdown = function() {
     server.close();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jcyamacho/agent-memory",
   "main": "dist/index.js",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "bin": {
     "agent-memory": "dist/index.js"
   },
@@ -20,7 +20,7 @@
     "url": "git+https://github.com/jcyamacho/agent-memory.git"
   },
   "scripts": {
-    "build": "bun build src/index.ts --target=node --external better-sqlite3 --outfile dist/index.js --banner \"#!/usr/bin/env node\"",
+    "build": "bun build src/index.ts --target=node --external better-sqlite3 --external @huggingface/transformers --outfile dist/index.js --banner \"#!/usr/bin/env node\"",
     "start": "node dist/index.js",
     "test": "bun test",
     "lint": "biome check --write && tsc --noEmit",
@@ -38,6 +38,7 @@
   },
   "dependencies": {
     "@hono/node-server": "^1.19.11",
+    "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "better-sqlite3": "^12.6.2",
     "hono": "^4.12.8",