@jcyamacho/agent-memory 0.0.15 → 0.0.18

package/README.md

@@ -3,16 +3,16 @@
 Persistent memory for MCP-powered coding agents.
 
 `agent-memory` is a stdio MCP server that gives your LLM durable memory backed
-by SQLite. It exposes four tools:
+by SQLite. It helps your agent remember preferences, project context, and prior
+decisions across sessions.
+
+It exposes four tools:
 
 - `remember` -> save facts, decisions, preferences, and project context
 - `recall` -> retrieve the most relevant memories later
 - `revise` -> update an existing memory when it becomes outdated
 - `forget` -> delete a memory that is no longer relevant
 
-Use it when your agent should remember preferences, project facts, and prior
-decisions across sessions.
-
 ## Quick Start
 
 Claude CLI:
@@ -27,104 +27,56 @@ Codex CLI:
 codex mcp add memory -- npx -y @jcyamacho/agent-memory
 ```
 
-Example MCP server config:
-
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@jcyamacho/agent-memory"
-      ]
-    }
-  }
-}
-```
-
-With a custom database path:
+OpenCode:
 
-```json
+```jsonc
 {
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
     "memory": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@jcyamacho/agent-memory"
-      ],
-      "env": {
-        "AGENT_MEMORY_DB_PATH": "/absolute/path/to/memory.db"
-      }
+      "type": "local",
+      "command": ["npx", "-y", "@jcyamacho/agent-memory"]
     }
   }
 }
 ```
 
-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
 
 Optional LLM instructions to reinforce the MCP's built-in guidance:
 
-```text
-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.
+```md
+## Agent Memory
+
+- Use `memory_recall` at conversation start and before design choices,
+  conventions, or edge cases.
+- 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_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.
 ```
 
-## What It Stores
-
-This MCP is useful for context that should survive across turns and sessions:
-
-- User preferences like response style, formatting, and workflow habits
-- Project facts like paths, architecture choices, and conventions
-- Important decisions and constraints that should not be rediscovered
-- Project-scoped notes that still matter later
-
 ## Web UI
 
 Browse, edit, and delete memories in a local web interface:
 
 ```bash
-npx -y @jcyamacho/agent-memory --ui
+npx -y @jcyamacho/agent-memory@latest --ui
 ```
 
 Opens at `http://localhost:6580`. Use `--port` to change:
 
 ```bash
-npx -y @jcyamacho/agent-memory --ui --port 9090
+npx -y @jcyamacho/agent-memory@latest --ui --port 9090
 ```
 
 The web UI uses the same database as the MCP server.
 
-## Tools
-
-- `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
+## How Recall Finds Memories
 
 `recall` uses a multi-signal ranking system to surface the most relevant
 memories:
@@ -147,7 +99,13 @@ 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
+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.
+
+## Configuration
+
+### Database Location
 
 By default, the SQLite database is created at:
 
@@ -167,7 +125,7 @@ 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
+### Model Cache Location
 
 By default, downloaded embedding model files are cached at:
 
@@ -187,38 +145,8 @@ Set `AGENT_MEMORY_MODELS_CACHE_PATH` when you want to:
 - 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.
-
-## Development
-
-For working on the project itself or running from source. Requires Bun and
-Node.js.
-
-```bash
-bun install
-bun run build
-```
-
-To use a local build as your MCP server:
-
-```json
-{
-  "mcpServers": {
-    "memory": {
-      "command": "node",
-      "args": [
-        "/absolute/path/to/agent-memory/dist/index.js"
-      ]
-    }
-  }
-}
-```
-
-```bash
-bun lint
-bun test
-```
+Schema changes are migrated automatically, including workspace normalization for
+existing git worktree memories when the original path can still be resolved.
 
 ## License
 

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.15";
+var version2 = "0.0.18";
 
 // src/config.ts
 import { homedir } from "node:os";
@@ -20058,11 +20058,17 @@ function parseOptionalDate(value, fieldName) {
 
 // src/mcp/tools/forget.ts
 var forgetInputSchema = {
-  id: string2().describe("The memory id to delete. Use an id returned by `recall`.")
+  id: string2().describe("Memory id to delete. Use an id returned by `recall`.")
 };
 function registerForgetTool(server, memory) {
   server.registerTool("forget", {
-    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" />`.',
+    annotations: {
+      title: "Forget",
+      destructiveHint: true,
+      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" />`.',
     inputSchema: forgetInputSchema
   }, async ({ id }) => {
     try {
@@ -20146,19 +20152,22 @@ var MAX_LIST_LIMIT = 100;
 class MemoryService {
   repository;
   embeddingService;
-  constructor(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: normalizeOptionalString(input.workspace)
+      workspace
     });
     return toPublicMemoryRecord(memory);
   }
@@ -20184,7 +20193,7 @@ class MemoryService {
     return memory ? toPublicMemoryRecord(memory) : undefined;
   }
   async list(input) {
-    const workspace = normalizeOptionalString(input.workspace);
+    const workspace = await this.workspaceResolver.resolve(input.workspace);
     const page = await this.repository.list({
       workspace,
       workspaceIsNull: workspace ? false : Boolean(input.workspaceIsNull),
@@ -20202,7 +20211,7 @@ class MemoryService {
       throw new ValidationError("At least one search term is required.");
     }
     const requestedLimit = normalizeLimit(input.limit);
-    const workspace = normalizeOptionalString(input.workspace);
+    const workspace = await this.workspaceResolver.resolve(input.workspace);
     const normalizedQuery = {
       terms,
       limit: requestedLimit * RECALL_CANDIDATE_LIMIT_MULTIPLIER,
@@ -20259,10 +20268,6 @@ function normalizeListLimit(value) {
   }
   return Math.min(Math.max(value, 1), MAX_LIST_LIMIT);
 }
-function normalizeOptionalString(value) {
-  const trimmed = value?.trim();
-  return trimmed ? trimmed : undefined;
-}
 function normalizeTerms(terms) {
   const normalizedTerms = terms.map((term) => term.trim()).filter(Boolean);
   return [...new Set(normalizedTerms)];
@@ -20270,11 +20275,11 @@ function normalizeTerms(terms) {
 
 // src/mcp/tools/recall.ts
 var recallInputSchema = {
-  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."),
+  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."),
   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.")
+  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."),
+  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)}"` : "";
@@ -20286,7 +20291,12 @@ ${content}
 }
 function registerRecallTool(server, memory) {
   server.registerTool("recall", {
-    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.",
+    annotations: {
+      title: "Recall",
+      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.",
     inputSchema: recallInputSchema
   }, async ({ terms, limit, workspace, updated_after, updated_before }) => {
     try {
@@ -20297,7 +20307,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. 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>
+      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>`;
@@ -20312,12 +20322,18 @@ ${results.map(toMemoryXml).join(`
 
 // src/mcp/tools/remember.ts
 var rememberInputSchema = {
-  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.")
+  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.")
 };
 function registerRememberTool(server, memory) {
   server.registerTool("remember", {
-    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="..." />`.',
+    annotations: {
+      title: "Remember",
+      destructiveHint: false,
+      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="..." />`.',
     inputSchema: rememberInputSchema
   }, async ({ content, workspace }) => {
     try {
@@ -20336,12 +20352,18 @@ function registerRememberTool(server, memory) {
 
 // src/mcp/tools/revise.ts
 var reviseInputSchema = {
-  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.")
+  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.")
 };
 function registerReviseTool(server, memory) {
   server.registerTool("revise", {
-    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="..." />`.',
+    annotations: {
+      title: "Revise",
+      destructiveHint: false,
+      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="..." />`.',
     inputSchema: reviseInputSchema
   }, async ({ id, content }) => {
     try {
@@ -20362,15 +20384,12 @@ function registerReviseTool(server, memory) {
 
 // src/mcp/server.ts
 var SERVER_INSTRUCTIONS = [
-  "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."
+  "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."
 ].join(" ");
 function createMcpServer(memory, version3) {
   const server = new McpServer({
@@ -20502,7 +20521,7 @@ function toUint8Array(value) {
 }
 
 // src/sqlite/migrations/002-add-memory-embedding.ts
-function createAddMemoryEmbeddingMigration(embeddingService = new EmbeddingService) {
+function createAddMemoryEmbeddingMigration(embeddingService) {
   return {
     version: 2,
     async up(database) {
@@ -20531,13 +20550,33 @@ function createAddMemoryEmbeddingMigration(embeddingService = new EmbeddingServi
     }
   };
 }
-var addMemoryEmbeddingMigration = createAddMemoryEmbeddingMigration();
+
+// src/sqlite/migrations/003-normalize-workspaces.ts
+function createNormalizeWorkspaceMigration(workspaceResolver) {
+  return {
+    version: 3,
+    async up(database) {
+      const rows = database.prepare("SELECT DISTINCT workspace FROM memories WHERE workspace IS NOT NULL ORDER BY workspace").all();
+      const updateStatement = database.prepare("UPDATE memories SET workspace = ? WHERE workspace = ?");
+      for (const row of rows) {
+        const normalizedWorkspace = await workspaceResolver.resolve(row.workspace);
+        if (!normalizedWorkspace || normalizedWorkspace === row.workspace) {
+          continue;
+        }
+        updateStatement.run(normalizedWorkspace, row.workspace);
+      }
+    }
+  };
+}
 
 // src/sqlite/migrations/index.ts
-function createMemoryMigrations(embeddingService = new EmbeddingService) {
-  return [createMemorySchemaMigration, createAddMemoryEmbeddingMigration(embeddingService)];
+function createMemoryMigrations(options) {
+  return [
+    createMemorySchemaMigration,
+    createAddMemoryEmbeddingMigration(options.embeddingService),
+    createNormalizeWorkspaceMigration(options.workspaceResolver)
+  ];
 }
-var MEMORY_MIGRATIONS = createMemoryMigrations();
 
 // src/sqlite/db.ts
 var PRAGMA_STATEMENTS = [
@@ -20546,12 +20585,12 @@ var PRAGMA_STATEMENTS = [
   "foreign_keys = ON",
   "busy_timeout = 5000"
 ];
-async function openMemoryDatabase(databasePath, options = {}) {
+async function openMemoryDatabase(databasePath, options) {
   let database;
   try {
     mkdirSync2(dirname(databasePath), { recursive: true });
     database = new Database(databasePath);
-    await initializeMemoryDatabase(database, createMemoryMigrations(options.embeddingService));
+    await initializeMemoryDatabase(database, createMemoryMigrations(options));
     return database;
   } catch (error2) {
     database?.close();
@@ -20563,7 +20602,7 @@ async function openMemoryDatabase(databasePath, options = {}) {
     });
   }
 }
-async function initializeMemoryDatabase(database, migrations = MEMORY_MIGRATIONS) {
+async function initializeMemoryDatabase(database, migrations) {
   try {
     applyPragmas(database);
     await runSqliteMigrations(database, migrations);
@@ -24195,12 +24234,59 @@ function startWebServer(memory, options) {
   return serve({ fetch: app.fetch, port: options.port });
 }
 
+// src/workspace-resolver.ts
+import { execFile } from "node:child_process";
+import { basename, dirname as dirname2 } from "node:path";
+import { promisify } from "node:util";
+var execFileAsync = promisify(execFile);
+function createGitWorkspaceResolver(options = {}) {
+  const getGitCommonDir = options.getGitCommonDir ?? defaultGetGitCommonDir;
+  const cache = new Map;
+  return {
+    async resolve(workspace) {
+      const trimmed = normalizeOptionalString(workspace);
+      if (!trimmed) {
+        return;
+      }
+      const cached2 = cache.get(trimmed);
+      if (cached2) {
+        return cached2;
+      }
+      const pending = resolveWorkspace(trimmed, getGitCommonDir);
+      cache.set(trimmed, pending);
+      return pending;
+    }
+  };
+}
+async function resolveWorkspace(workspace, getGitCommonDir) {
+  try {
+    const gitCommonDir = (await getGitCommonDir(workspace)).trim();
+    if (basename(gitCommonDir) !== ".git") {
+      return workspace;
+    }
+    return dirname2(gitCommonDir);
+  } catch {
+    return workspace;
+  }
+}
+async function defaultGetGitCommonDir(cwd) {
+  const { stdout } = await execFileAsync("git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
+    cwd
+  });
+  return stdout.trim();
+}
+function normalizeOptionalString(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : undefined;
+}
+
 // src/index.ts
 var config2 = resolveConfig();
 var embeddingService = new EmbeddingService({ modelsCachePath: config2.modelsCachePath });
-var database = await openMemoryDatabase(config2.databasePath, { embeddingService });
+var workspaceResolver = createGitWorkspaceResolver();
+var database = await openMemoryDatabase(config2.databasePath, { embeddingService, workspaceResolver });
 var repository2 = new SqliteMemoryRepository(database);
-var memoryService = new MemoryService(repository2, embeddingService);
+var memoryService = new MemoryService(repository2, embeddingService, 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.15",
+  "version": "0.0.18",
   "bin": {
     "agent-memory": "dist/index.js"
   },