@jcyamacho/agent-memory 0.0.19 → 0.1.0

package/README.md

@@ -9,7 +9,7 @@ decisions across sessions.
 It exposes four tools:
 
 - `remember` -> save facts, decisions, preferences, and project context
-- `recall` -> retrieve the most relevant memories later
+- `review` -> load workspace and global memories sorted by most recently updated
 - `revise` -> update an existing memory when it becomes outdated
 - `forget` -> delete a memory that is no longer relevant
 
@@ -43,22 +43,20 @@ OpenCode:
 
 ## Optional LLM Instructions
 
-Optional LLM instructions to reinforce the MCP's built-in guidance:
+Optional LLM instructions to reinforce the MCP's built-in guidance. The server
+instructions and tool descriptions already cover most behavior -- this prompt
+targets the habits models most commonly miss:
 
 ```md
 ## Agent Memory
 
-- Use `memory_recall` at conversation start and before design choices,
-  conventions, edge cases, or saving memory.
-- Query `memory_recall` with 2-5 short anchor-heavy terms or exact phrases,
-  not full questions or sentences.
-- Pass `workspace` for project-scoped memory. Omit it only for facts that
-  apply across projects.
-- Use `memory_remember` to save one durable fact when the user states a stable
-  preference, correction, or reusable project decision.
-- If the fact already exists, use `memory_revise` instead of creating a duplicate.
-- Use `memory_forget` to remove a wrong or obsolete memory.
-- Do not store secrets or temporary task state in memory.
+- Use `memory_review` at conversation start to load workspace memories into
+  context. During the session, use `memory_remember`, `memory_revise`, and
+  `memory_forget` to keep memories accurate.
+- Pass `workspace` on `memory_remember` for project-scoped memory. Omit it
+  only for facts that apply across projects.
+- Do not store secrets, temporary task state, or facts obvious from current
+  code or git history.
 ```
 
 ## Web UI
@@ -77,34 +75,15 @@ npx -y @jcyamacho/agent-memory@latest --ui --port 9090
 
 The web UI uses the same database as the MCP server.
 
-## How Recall Finds Memories
-
-`recall` uses a multi-signal ranking system to surface the most relevant
-memories:
-
-1. **Text relevance** is the primary signal -- memories whose content best
-   matches your search terms rank highest.
-2. **Workspace match** is the next strongest signal. When you pass
-   `workspace`, exact matches rank highest and all other scoped workspaces rank
-   below exact matches.
-3. **Embedding similarity** is a secondary signal. Recall builds an embedding
-   from your normalized search terms and boosts memories whose stored
-   embeddings are most semantically similar.
-4. **Global memories** (saved without a workspace) are treated as relevant
-   everywhere. When you pass `workspace`, they rank below exact workspace
-   matches and above memories from other workspaces.
-5. **Recency** is a minor tiebreaker -- newer memories rank slightly above older
-   ones when other signals are equal.
-
-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.
+## How Review Works
+
+`review` requires a `workspace` and returns memories saved in that workspace
+plus global memories (saved without a workspace), sorted by most recently
+updated. Results are paginated -- pass `page` to load older memories.
 
 When you save a memory from a git worktree, `agent-memory` stores the main repo
-root as the workspace. `recall` applies the same normalization to incoming
+root as the workspace. `review` applies the same normalization to incoming
 workspace queries so linked worktrees still match repo-scoped memories exactly.
-When that happens, recall returns the queried workspace value so callers can
-treat the match as belonging to their current worktree context.
 
 ## Configuration
 
@@ -128,26 +107,6 @@ 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
-
 Schema changes are migrated automatically, including workspace normalization for
 existing git worktree memories when the original path can still be resolved.
 

package/dist/index.js

@@ -2431,9 +2431,9 @@ var require_validate = __commonJS((exports) => {
     }
   }
   function returnResults(it) {
-    const { gen, schemaEnv, validateName, ValidationError: ValidationError2, opts } = it;
+    const { gen, schemaEnv, validateName, ValidationError, 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 ${ValidationError2}(${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 ${ValidationError}(${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 ValidationError2 extends Error {
+  class ValidationError extends Error {
     constructor(errors3) {
       super("validation failed");
       this.errors = errors3;
       this.ajv = this.validation = true;
     }
   }
-  exports.default = ValidationError2;
+  exports.default = ValidationError;
 });
 
 // node_modules/ajv/dist/compile/ref_error.js
@@ -12464,14 +12464,13 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.19";
+var version2 = "0.1.0";
 
 // 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({
@@ -12484,7 +12483,6 @@ function resolveConfig(environment = process.env, argv = process.argv.slice(2))
   });
   return {
     databasePath: resolveDatabasePath(environment),
-    modelsCachePath: resolveModelsCachePath(environment),
     uiMode: Boolean(values.ui),
     uiPort: Number(values.port) || DEFAULT_UI_PORT
   };
@@ -12492,137 +12490,7 @@ function resolveConfig(environment = process.env, argv = process.argv.slice(2))
 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) {
@@ -20030,6 +19898,37 @@ 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) {
@@ -20045,20 +19944,10 @@ function toMcpError(error2) {
   return new McpError(ErrorCode.InternalError, message);
 }
 var escapeXml = (value) => value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-function parseOptionalDate(value, fieldName) {
-  if (!value) {
-    return;
-  }
-  const date4 = new Date(value);
-  if (Number.isNaN(date4.getTime())) {
-    throw new MemoryError("VALIDATION_ERROR", `${fieldName} must be a valid ISO 8601 datetime.`);
-  }
-  return date4;
-}
 
 // src/mcp/tools/forget.ts
 var forgetInputSchema = {
-  id: string2().describe("Memory id to delete. Use an id returned by `recall`.")
+  id: string2().describe("Memory id to delete. Use an id returned by `review`.")
 };
 function registerForgetTool(server, memory) {
   server.registerTool("forget", {
@@ -20068,7 +19957,7 @@ function registerForgetTool(server, memory) {
       idempotentHint: true,
       openWorldHint: false
     },
-    description: 'Delete a memory that is wrong or obsolete. Use after `recall` when you have the memory id. Use `revise` instead if the fact should remain with corrected wording. Returns `<memory id="..." deleted="true" />`.',
+    description: 'Delete a memory that is wrong or obsolete. Use after `review` when you have the memory id. Use `revise` instead if the fact should remain with corrected wording. Returns `<memory id="..." deleted="true" />`.',
     inputSchema: forgetInputSchema
   }, async ({ id }) => {
     try {
@@ -20082,250 +19971,6 @@ function registerForgetTool(server, memory) {
   });
 }
 
-// src/memory.ts
-var toNormalizedScore = (value) => value;
-
-// src/ranking.ts
-var RETRIEVAL_SCORE_WEIGHT = 9;
-var EMBEDDING_SIMILARITY_WEIGHT = 4;
-var WORKSPACE_MATCH_WEIGHT = 5;
-var RECENCY_WEIGHT = 1;
-var MAX_COMPOSITE_SCORE = RETRIEVAL_SCORE_WEIGHT + EMBEDDING_SIMILARITY_WEIGHT + WORKSPACE_MATCH_WEIGHT + RECENCY_WEIGHT;
-var GLOBAL_WORKSPACE_SCORE = 0.5;
-function rerankSearchResults(results, workspace, queryEmbedding) {
-  if (results.length === 0) {
-    return results;
-  }
-  const normalizedQueryWs = workspace ? normalizeWorkspacePath(workspace) : undefined;
-  const updatedAtTimes = results.map((result) => result.updatedAt.getTime());
-  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 + 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;
-  }
-  if (!memoryWs) {
-    return GLOBAL_WORKSPACE_SCORE;
-  }
-  const normalizedMemoryWs = normalizeWorkspacePath(memoryWs);
-  if (normalizedMemoryWs === queryWs) {
-    return 1;
-  }
-  return 0;
-}
-
-// src/memory-service.ts
-var DEFAULT_RECALL_LIMIT = 15;
-var MAX_RECALL_LIMIT = 50;
-var RECALL_CANDIDATE_LIMIT_MULTIPLIER = 3;
-var DEFAULT_LIST_LIMIT = 15;
-var MAX_LIST_LIMIT = 100;
-
-class MemoryService {
-  repository;
-  embeddingService;
-  workspaceResolver;
-  constructor(repository, embeddingService, workspaceResolver) {
-    this.repository = repository;
-    this.embeddingService = embeddingService;
-    this.workspaceResolver = workspaceResolver;
-  }
-  async create(input) {
-    const content = input.content.trim();
-    if (!content) {
-      throw new ValidationError("Memory content is required.");
-    }
-    const workspace = await this.workspaceResolver.resolve(input.workspace);
-    const memory = await this.repository.create({
-      content,
-      embedding: await this.embeddingService.createVector(content),
-      workspace
-    });
-    return toPublicMemoryRecord(memory);
-  }
-  async update(input) {
-    const content = input.content.trim();
-    if (!content)
-      throw new ValidationError("Memory content is required.");
-    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();
-    if (!id)
-      throw new ValidationError("Memory id is required.");
-    return this.repository.delete({ id });
-  }
-  async get(id) {
-    const memory = await this.repository.get(id);
-    return memory ? toPublicMemoryRecord(memory) : undefined;
-  }
-  async list(input) {
-    const workspace = await this.workspaceResolver.resolve(input.workspace);
-    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();
-  }
-  async search(input) {
-    const terms = normalizeTerms(input.terms);
-    if (terms.length === 0) {
-      throw new ValidationError("At least one search term is required.");
-    }
-    const requestedLimit = normalizeLimit(input.limit);
-    const queryWorkspace = normalizeOptionalString(input.workspace);
-    const workspace = await this.workspaceResolver.resolve(input.workspace);
-    const normalizedQuery = {
-      terms,
-      limit: requestedLimit * RECALL_CANDIDATE_LIMIT_MULTIPLIER,
-      updatedAfter: input.updatedAfter,
-      updatedBefore: input.updatedBefore
-    };
-    const [results, queryEmbedding] = await Promise.all([
-      this.repository.search(normalizedQuery),
-      this.embeddingService.createVector(terms.join(" "))
-    ]);
-    return rerankSearchResults(results, workspace, queryEmbedding).slice(0, requestedLimit).map((result) => toPublicSearchResult(remapSearchResultWorkspace(result, workspace, queryWorkspace)));
-  }
-}
-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;
-  }
-  if (!Number.isInteger(value) || value < 1 || value > MAX_RECALL_LIMIT) {
-    throw new ValidationError(`Limit must be an integer between 1 and ${MAX_RECALL_LIMIT}.`);
-  }
-  return value;
-}
-function normalizeOffset(value) {
-  return Number.isInteger(value) && value && value > 0 ? value : 0;
-}
-function normalizeListLimit(value) {
-  if (!Number.isInteger(value) || value === undefined) {
-    return DEFAULT_LIST_LIMIT;
-  }
-  return Math.min(Math.max(value, 1), MAX_LIST_LIMIT);
-}
-function normalizeTerms(terms) {
-  const normalizedTerms = terms.map((term) => term.trim()).filter(Boolean);
-  return [...new Set(normalizedTerms)];
-}
-function normalizeOptionalString(value) {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : undefined;
-}
-function remapSearchResultWorkspace(result, canonicalWorkspace, queryWorkspace) {
-  if (!queryWorkspace || !canonicalWorkspace || result.workspace !== canonicalWorkspace) {
-    return result;
-  }
-  return {
-    ...result,
-    workspace: queryWorkspace
-  };
-}
-
-// src/mcp/tools/recall.ts
-var recallInputSchema = {
-  terms: array(string2()).min(1).describe("2-5 short anchor-heavy terms or exact phrases. Prefer identifiers, commands, file paths, and exact wording likely to appear in the memory."),
-  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("Current working directory for project-scoped recall. Omit for cross-project recall."),
-  updated_after: string2().optional().describe("Only return memories updated on or after this ISO 8601 timestamp."),
-  updated_before: string2().optional().describe("Only return memories updated on or before this ISO 8601 timestamp.")
-};
-function toMemoryXml(r) {
-  const workspace = r.workspace ? ` workspace="${escapeXml(r.workspace)}"` : "";
-  const content = escapeXml(r.content);
-  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", {
-    annotations: {
-      title: "Recall",
-      readOnlyHint: true,
-      openWorldHint: false
-    },
-    description: "Retrieve memories relevant to the current task or check whether a fact already exists before saving. Use at conversation start and before design choices. Pass short anchor-heavy `terms` and `workspace` when available. Results reflect the queried workspace context when applicable. Returns `<memories>...</memories>` or a no-match hint.",
-    inputSchema: recallInputSchema
-  }, async ({ terms, limit, workspace, updated_after, updated_before }) => {
-    try {
-      const results = await memory.search({
-        terms,
-        limit,
-        workspace,
-        updatedAfter: parseOptionalDate(updated_after, "updated_after"),
-        updatedBefore: parseOptionalDate(updated_before, "updated_before")
-      });
-      const text = results.length === 0 ? "No matching memories found. Retry once with 1-3 overlapping alternate terms or an exact identifier, command, file path, or phrase likely to appear in the memory." : `<memories>
-${results.map(toMemoryXml).join(`
-`)}
-</memories>`;
-      return {
-        content: [{ type: "text", text }]
-      };
-    } catch (error2) {
-      throw toMcpError(error2);
-    }
-  });
-}
-
 // src/mcp/tools/remember.ts
 var rememberInputSchema = {
   content: string2().describe("One new durable fact to save. Use a self-contained sentence or short note."),
@@ -20339,7 +19984,7 @@ function registerRememberTool(server, memory) {
       idempotentHint: false,
       openWorldHint: false
     },
-    description: 'Save one new durable fact for later recall. Use for stable preferences, reusable decisions, and project context not obvious from code or git history. If the fact already exists, use `revise` instead. Returns `<memory id="..." />`.',
+    description: 'Save one new durable fact. Use for stable preferences, reusable decisions, and project context not obvious from code or git history. If the fact already exists, use `revise` instead. Returns `<memory id="..." />`.',
     inputSchema: rememberInputSchema
   }, async ({ content, workspace }) => {
     try {
@@ -20356,9 +20001,60 @@ function registerRememberTool(server, memory) {
   });
 }
 
+// src/mcp/tools/review.ts
+var REVIEW_PAGE_SIZE = 50;
+var reviewInputSchema = {
+  workspace: string2().describe("Current working directory for project-scoped listing."),
+  page: number2().int().min(0).optional().describe("Zero-based page number. Defaults to 0.")
+};
+function toMemoryXml(record3, workspace) {
+  const global2 = record3.workspace !== workspace ? ' global="true"' : "";
+  const content = escapeXml(record3.content);
+  return `<memory id="${record3.id}"${global2} updated_at="${record3.updatedAt.toISOString()}">
+${content}
+</memory>`;
+}
+function registerReviewTool(server, memory) {
+  server.registerTool("review", {
+    annotations: {
+      title: "Review",
+      readOnlyHint: true,
+      openWorldHint: false
+    },
+    description: 'Load workspace and global memories sorted by most recently updated. Use at the start of a task and before saving or revising memory. Returns `<memories workspace="..." has_more="true|false">...</memories>` with pagination support. Global memories are marked with `global="true"`.',
+    inputSchema: reviewInputSchema
+  }, async ({ workspace, page }) => {
+    try {
+      const pageIndex = page ?? 0;
+      const result = await memory.list({
+        workspace,
+        global: true,
+        offset: pageIndex * REVIEW_PAGE_SIZE,
+        limit: REVIEW_PAGE_SIZE
+      });
+      if (result.items.length === 0) {
+        return {
+          content: [{ type: "text", text: "No memories found for this workspace." }]
+        };
+      }
+      const escapedWorkspace = escapeXml(workspace);
+      const memories = result.items.map((item) => toMemoryXml(item, workspace)).join(`
+`);
+      const text = `<memories workspace="${escapedWorkspace}" has_more="${result.hasMore}">
+${memories}
+</memories>`;
+      return {
+        content: [{ type: "text", text }]
+      };
+    } catch (error2) {
+      throw toMcpError(error2);
+    }
+  });
+}
+
 // src/mcp/tools/revise.ts
 var reviseInputSchema = {
-  id: string2().describe("Memory id to update. Use an id returned by `recall`."),
+  id: string2().describe("Memory id to update. Use an id returned by `review`."),
   content: string2().describe("Corrected replacement text for that memory.")
 };
 function registerReviseTool(server, memory) {
@@ -20369,7 +20065,7 @@ function registerReviseTool(server, memory) {
       idempotentHint: false,
       openWorldHint: false
     },
-    description: 'Update one existing memory when the same fact still applies but its wording or details changed. Use after `recall` when you already have the memory id. Returns `<memory id="..." updated_at="..." />`.',
+    description: 'Update one existing memory when the same fact still applies but its wording or details changed. Use after `review` when you already have the memory id. Returns `<memory id="..." updated_at="..." />`.',
     inputSchema: reviseInputSchema
   }, async ({ id, content }) => {
     try {
@@ -20390,12 +20086,12 @@ function registerReviseTool(server, memory) {
 
 // src/mcp/server.ts
 var SERVER_INSTRUCTIONS = [
-  "Use this server only for durable memory that should survive across turns: stable preferences, corrections, reusable decisions, and project context not obvious from code or git history.",
-  "Use `recall` at conversation start, before design choices, and before saving or revising memory.",
-  "Use `remember` for one new durable fact. Use `revise` when the fact already exists but needs correction.",
-  "Use `forget` only when a memory is wrong or obsolete.",
-  "Pass workspace for project-scoped memory. Omit it only for facts that apply across projects.",
-  "Do not store secrets, temporary task state, or facts obvious from current code or git history."
+  "Durable memory for stable preferences, corrections, reusable decisions, and project context not obvious from code or git history.",
+  "Workflow: (1) Call `review` with the current workspace at conversation start -- this loads workspace and global memories into context.",
+  "(2) During the session, call `remember` to save a new fact, `revise` to correct an existing one, or `forget` to remove one that is wrong or obsolete.",
+  "Always check loaded memories before calling `remember` to avoid duplicates -- use `revise` instead when the fact already exists.",
+  "Pass workspace on `remember` for project-scoped memory. Omit it only for facts that apply across all projects.",
+  "Never store secrets, temporary task state, or facts obvious from current code or git history."
 ].join(" ");
 function createMcpServer(memory, version3) {
   const server = new McpServer({
@@ -20405,26 +20101,96 @@ function createMcpServer(memory, version3) {
     instructions: SERVER_INSTRUCTIONS
   });
   registerRememberTool(server, memory);
-  registerRecallTool(server, memory);
   registerReviseTool(server, memory);
   registerForgetTool(server, memory);
+  registerReviewTool(server, memory);
   return server;
 }
 
+// src/memory-service.ts
+var DEFAULT_LIST_LIMIT = 15;
+var MAX_LIST_LIMIT = 100;
+
+class MemoryService {
+  repository;
+  workspaceResolver;
+  constructor(repository, workspaceResolver) {
+    this.repository = repository;
+    this.workspaceResolver = workspaceResolver;
+  }
+  async create(input) {
+    const content = input.content.trim();
+    if (!content) {
+      throw new ValidationError("Memory content is required.");
+    }
+    const workspace = await this.workspaceResolver.resolve(input.workspace);
+    return this.repository.create({ content, workspace });
+  }
+  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 });
+  }
+  async delete(input) {
+    const id = input.id.trim();
+    if (!id)
+      throw new ValidationError("Memory id is required.");
+    return this.repository.delete({ id });
+  }
+  async get(id) {
+    return this.repository.get(id);
+  }
+  async list(input) {
+    const queryWorkspace = normalizeOptionalString(input.workspace);
+    const workspace = await this.workspaceResolver.resolve(input.workspace);
+    const page = await this.repository.list({
+      workspace,
+      global: input.global,
+      offset: normalizeOffset(input.offset),
+      limit: normalizeListLimit(input.limit)
+    });
+    return {
+      items: page.items.map((item) => remapWorkspace(item, workspace, queryWorkspace)),
+      hasMore: page.hasMore
+    };
+  }
+  async listWorkspaces() {
+    return this.repository.listWorkspaces();
+  }
+}
+function normalizeOffset(value) {
+  return Number.isInteger(value) && value && value > 0 ? value : 0;
+}
+function normalizeListLimit(value) {
+  if (!Number.isInteger(value) || value === undefined) {
+    return DEFAULT_LIST_LIMIT;
+  }
+  return Math.min(Math.max(value, 1), MAX_LIST_LIMIT);
+}
+function normalizeOptionalString(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+function remapWorkspace(record3, canonicalWorkspace, queryWorkspace) {
+  if (record3.workspace !== canonicalWorkspace) {
+    return record3;
+  }
+  return { ...record3, workspace: queryWorkspace };
+}
+
 // src/sqlite/db.ts
-import { mkdirSync as mkdirSync2 } from "node:fs";
+import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import Database from "better-sqlite3";
 
 // src/sqlite/memory-schema.ts
-function createMemoriesTable(database, options) {
-  const embeddingColumn = getEmbeddingColumnSql(options.embeddingColumn);
+function createMemoriesTable(database) {
   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
     );
@@ -20432,7 +20198,7 @@ function createMemoriesTable(database, options) {
 }
 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_updated_at ON memories(updated_at);
     CREATE INDEX IF NOT EXISTS idx_memories_workspace ON memories(workspace);
   `);
 }
@@ -20472,82 +20238,38 @@ function dropMemorySearchArtifacts(database) {
     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" });
+    createMemoriesTable(database);
     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) {
+function createAddMemoryEmbeddingMigration() {
   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(`
+        CREATE TABLE IF NOT EXISTS memories (
+          id TEXT PRIMARY KEY,
+          content TEXT NOT NULL,
+          workspace TEXT,
+          embedding BLOB NOT NULL,
+          created_at INTEGER NOT NULL,
+          updated_at INTEGER NOT NULL
+        );
+      `);
       database.exec(`
         INSERT INTO memories (id, content, workspace, embedding, created_at, updated_at)
-        SELECT id, content, workspace, embedding, created_at, updated_at
+        SELECT id, content, workspace, COALESCE(embedding, X'00000000'), created_at, updated_at
         FROM memories_old
       `);
       database.exec("DROP TABLE memories_old");
@@ -20575,12 +20297,31 @@ function createNormalizeWorkspaceMigration(workspaceResolver) {
   };
 }
 
+// src/sqlite/migrations/004-remove-memory-embedding.ts
+var removeMemoryEmbeddingMigration = {
+  version: 4,
+  async up(database) {
+    dropMemorySearchArtifacts(database);
+    database.exec("ALTER TABLE memories RENAME TO memories_old");
+    createMemoriesTable(database);
+    database.exec(`
+      INSERT INTO memories (id, content, workspace, created_at, updated_at)
+      SELECT id, content, workspace, created_at, updated_at
+      FROM memories_old
+    `);
+    database.exec("DROP TABLE memories_old");
+    createMemoryIndexes(database);
+    createMemorySearchArtifacts(database, true);
+  }
+};
+
 // src/sqlite/migrations/index.ts
 function createMemoryMigrations(options) {
   return [
     createMemorySchemaMigration,
-    createAddMemoryEmbeddingMigration(options.embeddingService),
-    createNormalizeWorkspaceMigration(options.workspaceResolver)
+    createAddMemoryEmbeddingMigration(),
+    createNormalizeWorkspaceMigration(options.workspaceResolver),
+    removeMemoryEmbeddingMigration
   ];
 }
 
@@ -20594,7 +20335,7 @@ var PRAGMA_STATEMENTS = [
 async function openMemoryDatabase(databasePath, options) {
   let database;
   try {
-    mkdirSync2(dirname(databasePath), { recursive: true });
+    mkdirSync(dirname(databasePath), { recursive: true });
     database = new Database(databasePath);
     await initializeMemoryDatabase(database, createMemoryMigrations(options));
     return database;
@@ -20668,7 +20409,6 @@ function validateMigrations(migrations) {
 }
 // src/sqlite/repository.ts
 import { randomUUID } from "node:crypto";
-var DEFAULT_SEARCH_LIMIT = 15;
 var DEFAULT_LIST_LIMIT2 = 15;
 
 class SqliteMemoryRepository {
@@ -20681,24 +20421,11 @@ class SqliteMemoryRepository {
   constructor(database) {
     this.database = database;
     this.insertStatement = database.prepare(`
-      INSERT INTO memories (
-        id,
-        content,
-        workspace,
-        embedding,
-        created_at,
-        updated_at
-      ) VALUES (
-        ?,
-        ?,
-        ?,
-        ?,
-        ?,
-        ?
-      )
+      INSERT INTO memories (id, content, workspace, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?)
     `);
-    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.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.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");
   }
@@ -20708,63 +20435,21 @@ 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, encodeEmbedding(memory.embedding), memory.createdAt.getTime(), memory.updatedAt.getTime());
+      this.insertStatement.run(memory.id, memory.content, memory.workspace, memory.createdAt.getTime(), memory.updatedAt.getTime());
       return memory;
     } catch (error2) {
       throw new PersistenceError("Failed to save memory.", { cause: error2 });
     }
   }
-  async search(query) {
-    try {
-      const whereParams = [toFtsQuery(query.terms)];
-      const limit = query.limit ?? DEFAULT_SEARCH_LIMIT;
-      const whereClauses = ["memories_fts MATCH ?"];
-      if (query.updatedAfter) {
-        whereClauses.push("m.updated_at >= ?");
-        whereParams.push(query.updatedAfter.getTime());
-      }
-      if (query.updatedBefore) {
-        whereClauses.push("m.updated_at <= ?");
-        whereParams.push(query.updatedBefore.getTime());
-      }
-      const params = [...whereParams, limit];
-      const statement = this.database.prepare(`
-        SELECT
-          m.id,
-          m.content,
-          m.workspace,
-          m.embedding,
-          m.created_at,
-          m.updated_at,
-          MAX(0, -bm25(memories_fts)) AS score
-        FROM memories_fts
-        INNER JOIN memories AS m ON m.rowid = memories_fts.rowid
-        WHERE ${whereClauses.join(" AND ")}
-        ORDER BY score DESC
-        LIMIT ?
-      `);
-      const rows = statement.all(...params);
-      const maxScore = Math.max(...rows.map((row) => row.score), 0);
-      return rows.map((row) => ({
-        ...toMemoryEntity(row),
-        score: toNormalizedScore(maxScore > 0 ? row.score / maxScore : 0)
-      }));
-    } catch (error2) {
-      throw new PersistenceError("Failed to search memories.", {
-        cause: error2
-      });
-    }
-  }
   async get(id) {
     try {
       const rows = this.getStatement.all(id);
       const row = rows[0];
-      return row ? toMemoryEntity(row) : undefined;
+      return row ? toMemoryRecord(row) : undefined;
     } catch (error2) {
       throw new PersistenceError("Failed to find memory.", { cause: error2 });
     }
@@ -20775,25 +20460,28 @@ class SqliteMemoryRepository {
       const params = [];
       const offset = options.offset ?? 0;
       const limit = options.limit ?? DEFAULT_LIST_LIMIT2;
-      if (options.workspace) {
+      if (options.workspace && options.global) {
+        whereClauses.push("(workspace = ? OR workspace IS NULL)");
+        params.push(options.workspace);
+      } else if (options.workspace) {
         whereClauses.push("workspace = ?");
         params.push(options.workspace);
-      } else if (options.workspaceIsNull) {
+      } else if (options.global) {
         whereClauses.push("workspace IS NULL");
       }
       const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(" AND ")}` : "";
       const queryLimit = limit + 1;
       params.push(queryLimit, offset);
       const statement = this.database.prepare(`
-        SELECT id, content, workspace, embedding, created_at, updated_at
+        SELECT id, content, workspace, created_at, updated_at
         FROM memories
         ${whereClause}
-        ORDER BY created_at DESC
+        ORDER BY updated_at DESC
         LIMIT ? OFFSET ?
       `);
       const rows = statement.all(...params);
       const hasMore = rows.length > limit;
-      const items = (hasMore ? rows.slice(0, limit) : rows).map(toMemoryEntity);
+      const items = (hasMore ? rows.slice(0, limit) : rows).map(toMemoryRecord);
       return { items, hasMore };
     } catch (error2) {
       throw new PersistenceError("Failed to list memories.", { cause: error2 });
@@ -20803,7 +20491,7 @@ class SqliteMemoryRepository {
     let result;
     try {
       const now = Date.now();
-      result = this.updateStatement.run(input.content, encodeEmbedding(input.embedding), now, input.id);
+      result = this.updateStatement.run(input.content, now, input.id);
     } catch (error2) {
       throw new PersistenceError("Failed to update memory.", { cause: error2 });
     }
@@ -20836,22 +20524,13 @@ class SqliteMemoryRepository {
     }
   }
 }
-var toMemoryEntity = (row) => ({
+var toMemoryRecord = (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)
 });
-var toFtsQuery = (terms) => terms.map(toFtsTerm).join(" OR ");
-function toFtsTerm(term) {
-  const escaped = term.replaceAll('"', '""');
-  if (term.includes(" ")) {
-    return `"${escaped}"`;
-  }
-  return `"${escaped}"*`;
-}
 // node_modules/@hono/node-server/dist/index.mjs
 import { createServer as createServerHTTP } from "http";
 import { Http2ServerRequest as Http2ServerRequest2 } from "http2";
@@ -24167,7 +23846,7 @@ function createPageRoutes(memory) {
     const wsFilter = workspace && !isNoWorkspace ? workspace : undefined;
     const page = await memory.list({
       workspace: wsFilter,
-      workspaceIsNull: isNoWorkspace,
+      global: isNoWorkspace,
       offset: (pageNum - 1) * DEFAULT_LIST_LIMIT3,
       limit: DEFAULT_LIST_LIMIT3
     });
@@ -24288,11 +23967,10 @@ function normalizeOptionalString2(value) {
 
 // src/index.ts
 var config2 = resolveConfig();
-var embeddingService = new EmbeddingService({ modelsCachePath: config2.modelsCachePath });
 var workspaceResolver = createGitWorkspaceResolver();
-var database = await openMemoryDatabase(config2.databasePath, { embeddingService, workspaceResolver });
+var database = await openMemoryDatabase(config2.databasePath, { workspaceResolver });
 var repository2 = new SqliteMemoryRepository(database);
-var memoryService = new MemoryService(repository2, embeddingService, workspaceResolver);
+var memoryService = new MemoryService(repository2, workspaceResolver);
 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.19",
+  "version": "0.1.0",
   "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 --external @huggingface/transformers --outfile dist/index.js --banner \"#!/usr/bin/env node\"",
+    "build": "bun build src/index.ts --target=node --external better-sqlite3 --outfile dist/index.js --banner \"#!/usr/bin/env node\"",
     "start": "node dist/index.js",
     "test": "bun test",
     "lint": "biome check --write && tsc --noEmit",
@@ -38,7 +38,6 @@
   },
   "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",