@jcyamacho/agent-memory 0.0.18 → 0.0.20

package/README.md

@@ -6,10 +6,11 @@ Persistent memory for MCP-powered coding agents.
 by SQLite. It helps your agent remember preferences, project context, and prior
 decisions across sessions.
 
-It exposes four tools:
+It exposes five tools:
 
 - `remember` -> save facts, decisions, preferences, and project context
 - `recall` -> retrieve the most relevant memories later
+- `review` -> browse all memories for a workspace
 - `revise` -> update an existing memory when it becomes outdated
 - `forget` -> delete a memory that is no longer relevant
 
@@ -49,10 +50,13 @@ Optional LLM instructions to reinforce the MCP's built-in guidance:
 ## Agent Memory
 
 - Use `memory_recall` at conversation start and before design choices,
-  conventions, or edge cases.
+  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 truly global memories.
+- Use `memory_review` to browse all memories for a workspace before bulk review
+  or cleanup.
+- 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.
@@ -83,15 +87,15 @@ memories:
 
 1. **Text relevance** is the primary signal -- memories whose content best
    matches your search terms rank highest.
-2. **Embedding similarity** is the next strongest signal. Recall builds an
-   embedding from your normalized search terms and boosts memories whose stored
+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.
-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.
 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.
+   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.
 
@@ -102,6 +106,8 @@ memories without a workspace only when they apply across all projects.
 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
 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
 

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.18";
+var version2 = "0.0.20";
 
 // src/config.ts
 import { homedir } from "node:os";
@@ -12533,14 +12533,20 @@ class PersistenceError extends MemoryError {
 
 // src/embedding/service.ts
 var DEFAULT_EMBEDDING_MODEL = "Xenova/all-MiniLM-L6-v2";
+function configureModelsCache(modelsCachePath) {
+  mkdirSync(modelsCachePath, { recursive: true });
+  transformersEnv.useFSCache = true;
+  transformersEnv.cacheDir = modelsCachePath;
+}
 
 class EmbeddingService {
   options;
   extractorPromise;
-  modelsCachePath;
   constructor(options = {}) {
     this.options = options;
-    this.modelsCachePath = options.modelsCachePath ?? resolveModelsCachePath();
+  }
+  async warmup() {
+    await this.getExtractor();
   }
   async createVector(text) {
     const normalizedText = text.trim();
@@ -12553,17 +12559,11 @@ class EmbeddingService {
   }
   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, {
@@ -20086,15 +20086,14 @@ function registerForgetTool(server, memory) {
 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 = 2;
+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;
-var SIBLING_WORKSPACE_SCORE = 0.25;
 function rerankSearchResults(results, workspace, queryEmbedding) {
-  if (results.length <= 1) {
+  if (results.length === 0) {
     return results;
   }
   const normalizedQueryWs = workspace ? normalizeWorkspacePath(workspace) : undefined;
@@ -20132,14 +20131,7 @@ function computeWorkspaceScore(memoryWs, queryWs) {
   if (normalizedMemoryWs === queryWs) {
     return 1;
   }
-  const queryLastSlashIndex = queryWs.lastIndexOf("/");
-  const memoryLastSlashIndex = normalizedMemoryWs.lastIndexOf("/");
-  if (queryLastSlashIndex <= 0 || memoryLastSlashIndex <= 0) {
-    return 0;
-  }
-  const queryParent = queryWs.slice(0, queryLastSlashIndex);
-  const memoryParent = normalizedMemoryWs.slice(0, memoryLastSlashIndex);
-  return memoryParent === queryParent ? SIBLING_WORKSPACE_SCORE : 0;
+  return 0;
 }
 
 // src/memory-service.ts
@@ -20193,6 +20185,7 @@ class MemoryService {
     return memory ? toPublicMemoryRecord(memory) : undefined;
   }
   async list(input) {
+    const queryWorkspace = normalizeOptionalString(input.workspace);
     const workspace = await this.workspaceResolver.resolve(input.workspace);
     const page = await this.repository.list({
       workspace,
@@ -20200,7 +20193,10 @@ class MemoryService {
       offset: normalizeOffset(input.offset),
       limit: normalizeListLimit(input.limit)
     });
-    return toPublicMemoryPage(page);
+    return {
+      items: page.items.map((item) => toPublicMemoryRecord(remapWorkspace(item, workspace, queryWorkspace))),
+      hasMore: page.hasMore
+    };
   }
   async listWorkspaces() {
     return this.repository.listWorkspaces();
@@ -20211,6 +20207,7 @@ class MemoryService {
       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,
@@ -20222,7 +20219,7 @@ class MemoryService {
       this.repository.search(normalizedQuery),
       this.embeddingService.createVector(terms.join(" "))
     ]);
-    return rerankSearchResults(results, workspace, queryEmbedding).slice(0, requestedLimit).map(toPublicSearchResult);
+    return rerankSearchResults(results, workspace, queryEmbedding).slice(0, requestedLimit).map((result) => toPublicSearchResult(remapWorkspace(result, workspace, queryWorkspace)));
   }
 }
 function toPublicMemoryRecord(memory) {
@@ -20244,12 +20241,6 @@ function toPublicSearchResult(result) {
     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;
@@ -20272,12 +20263,22 @@ 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 remapWorkspace(record3, canonicalWorkspace, queryWorkspace) {
+  if (record3.workspace !== canonicalWorkspace) {
+    return record3;
+  }
+  return { ...record3, workspace: queryWorkspace };
+}
 
 // src/mcp/tools/recall.ts
 var recallInputSchema = {
-  terms: array(string2()).min(1).describe("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. Avoid vague words, full questions, and repeating the workspace name."),
+  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("Pass the current working directory to prefer memories from the active project. Git worktree paths are normalized to the main repo root for matching."),
+  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.")
 };
@@ -20296,7 +20297,7 @@ function registerRecallTool(server, memory) {
       readOnlyHint: true,
       openWorldHint: false
     },
-    description: "Find 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. Returns `<memories>...</memories>` or a no-match hint.",
+    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 {
@@ -20323,7 +20324,7 @@ ${results.map(toMemoryXml).join(`
 // src/mcp/tools/remember.ts
 var rememberInputSchema = {
   content: string2().describe("One new durable fact to save. Use a self-contained sentence or short note."),
-  workspace: string2().optional().describe("Pass the current working directory for project-scoped memory. Git worktree paths are saved as the main repo root. Omit for truly global memory.")
+  workspace: string2().optional().describe("Current working directory for project-scoped memory. Omit for facts that apply across projects.")
 };
 function registerRememberTool(server, memory) {
   server.registerTool("remember", {
@@ -20333,7 +20334,7 @@ function registerRememberTool(server, memory) {
       idempotentHint: false,
       openWorldHint: false
     },
-    description: 'Save one new durable fact for later recall. Use for stable preferences, corrections, reusable decisions, and project context not obvious from code or git history. Save exactly one fact. If the memory already exists, use `revise` instead. Do not store secrets, temporary task state, or facts obvious from code or git history. Returns `<memory id="..." />`.',
+    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="..." />`.',
     inputSchema: rememberInputSchema
   }, async ({ content, workspace }) => {
     try {
@@ -20350,10 +20351,57 @@ function registerRememberTool(server, memory) {
   });
 }
 
+// src/mcp/tools/review.ts
+var REVIEW_PAGE_SIZE = 25;
+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 toMemoryXml2(record3) {
+  const content = escapeXml(record3.content);
+  return `<memory id="${record3.id}" updated_at="${record3.updatedAt.toISOString()}">
+${content}
+</memory>`;
+}
+function registerReviewTool(server, memory) {
+  server.registerTool("review", {
+    annotations: {
+      title: "Review",
+      readOnlyHint: true,
+      openWorldHint: false
+    },
+    description: 'Browse all memories for a workspace in creation order. Use before bulk review, cleanup, or when you need to scan memories without specific search terms. For targeted retrieval by topic, use `recall` instead. Returns `<memories workspace="..." has_more="true|false">...</memories>` with pagination support.',
+    inputSchema: reviewInputSchema
+  }, async ({ workspace, page }) => {
+    try {
+      const pageIndex = page ?? 0;
+      const result = await memory.list({
+        workspace,
+        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 text = `<memories workspace="${escapeXml(workspace)}" has_more="${result.hasMore}">
+${result.items.map(toMemoryXml2).join(`
+`)}
+</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`."),
-  content: string2().describe("Corrected replacement text for that memory. Keep it to one durable fact.")
+  content: string2().describe("Corrected replacement text for that memory.")
 };
 function registerReviseTool(server, memory) {
   server.registerTool("revise", {
@@ -20363,7 +20411,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. Keep it to one fact and do not merge unrelated facts. Returns `<memory id="..." updated_at="..." />`.',
+    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="..." />`.',
     inputSchema: reviseInputSchema
   }, async ({ id, content }) => {
     try {
@@ -20385,11 +20433,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 memory.",
-  "Use `remember` only for a new durable fact. Use `revise` when the fact already exists but needs correction.",
-  "Use `forget` only when a memory is wrong or no longer relevant.",
-  "Pass workspace for project-scoped memory. Omit it only for truly global memory.",
-  "Do not store secrets or temporary task state in memory."
+  "Use `recall` at conversation start, before design choices, and before saving or revising memory.",
+  "Use `review` to browse all memories for a workspace before bulk review or cleanup.",
+  "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."
 ].join(" ");
 function createMcpServer(memory, version3) {
   const server = new McpServer({
@@ -20402,6 +20451,7 @@ function createMcpServer(memory, version3) {
   registerRecallTool(server, memory);
   registerReviseTool(server, memory);
   registerForgetTool(server, memory);
+  registerReviewTool(server, memory);
   return server;
 }
 
@@ -24244,7 +24294,7 @@ function createGitWorkspaceResolver(options = {}) {
   const cache = new Map;
   return {
     async resolve(workspace) {
-      const trimmed = normalizeOptionalString(workspace);
+      const trimmed = normalizeOptionalString2(workspace);
       if (!trimmed) {
         return;
       }
@@ -24275,18 +24325,20 @@ async function defaultGetGitCommonDir(cwd) {
   });
   return stdout.trim();
 }
-function normalizeOptionalString(value) {
+function normalizeOptionalString2(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : undefined;
 }
 
 // src/index.ts
 var config2 = resolveConfig();
-var embeddingService = new EmbeddingService({ modelsCachePath: config2.modelsCachePath });
+configureModelsCache(config2.modelsCachePath);
+var embeddingService = new EmbeddingService;
 var workspaceResolver = createGitWorkspaceResolver();
 var database = await openMemoryDatabase(config2.databasePath, { embeddingService, workspaceResolver });
 var repository2 = new SqliteMemoryRepository(database);
 var memoryService = new MemoryService(repository2, embeddingService, workspaceResolver);
+embeddingService.warmup();
 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.18",
+  "version": "0.0.20",
   "bin": {
     "agent-memory": "dist/index.js"
   },