@jcyamacho/agent-memory 0.0.17 → 0.0.19

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,67 +27,72 @@ Codex CLI:
 codex mcp add memory -- npx -y @jcyamacho/agent-memory
 ```
 
-Optional LLM instructions to reinforce the MCP's built-in guidance:
+OpenCode:
 
-```text
-Use `memory_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. `memory_recall` is lexical-first; if it misses, retry once
-with overlapping alternate terms. Use `memory_remember` for one durable fact, then
-use `memory_revise` instead of duplicates and `memory_forget` for wrong or obsolete
-memories. Always pass workspace unless the memory is truly global. Git worktree
-paths are canonicalized to the main repo root on save and recall.
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "memory": {
+      "type": "local",
+      "command": ["npx", "-y", "@jcyamacho/agent-memory"]
+    }
+  }
+}
 ```
 
-## What It Stores
+## Optional LLM Instructions
 
-This MCP is useful for context that should survive across turns and sessions:
+Optional LLM instructions to reinforce the MCP's built-in guidance:
 
-- 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
+```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.
+```
 
 ## 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:
 
 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.
 
@@ -98,8 +103,12 @@ 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
 
-## Database location
+### Database Location
 
 By default, the SQLite database is created at:
 
@@ -119,7 +128,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:
 
@@ -142,36 +151,6 @@ Set `AGENT_MEMORY_MODELS_CACHE_PATH` when you want to:
 Schema changes are migrated automatically, including workspace normalization for
 existing git worktree memories when the original path can still be resolved.
 
-## 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
-```
-
 ## License
 
 MIT

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.17";
+var version2 = "0.0.19";
 
 // 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 {
@@ -20080,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;
@@ -20126,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
@@ -20205,6 +20203,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,
@@ -20216,7 +20215,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(remapSearchResultWorkspace(result, workspace, queryWorkspace)));
   }
 }
 function toPublicMemoryRecord(memory) {
@@ -20266,14 +20265,27 @@ 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("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("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. Git worktree paths are normalized to the main repo root for matching. 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("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)}"` : "";
@@ -20285,7 +20297,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; git worktree paths are normalized to the main repo root for matching. Returns `<memories>...</memories>` or a no-match hint.",
+    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 {
@@ -20296,7 +20313,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>`;
@@ -20311,12 +20328,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. Git worktree paths are saved as the main repo root automatically. 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("Current working directory for project-scoped memory. Omit for facts that apply across projects.")
 };
 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, 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 {
@@ -20335,12 +20358,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.")
 };
 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. Returns `<memory id="..." updated_at="..." />`.',
     inputSchema: reviseInputSchema
   }, async ({ id, content }) => {
     try {
@@ -20361,15 +20390,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. Git worktree paths are canonicalized to the main repo root on save and recall. Omit workspace 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 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."
 ].join(" ");
 function createMcpServer(memory, version3) {
   const server = new McpServer({
@@ -24224,7 +24250,7 @@ function createGitWorkspaceResolver(options = {}) {
   const cache = new Map;
   return {
     async resolve(workspace) {
-      const trimmed = normalizeOptionalString(workspace);
+      const trimmed = normalizeOptionalString2(workspace);
       if (!trimmed) {
         return;
       }
@@ -24255,7 +24281,7 @@ async function defaultGetGitCommonDir(cwd) {
   });
   return stdout.trim();
 }
-function normalizeOptionalString(value) {
+function normalizeOptionalString2(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : undefined;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jcyamacho/agent-memory",
   "main": "dist/index.js",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "bin": {
     "agent-memory": "dist/index.js"
   },