@jcyamacho/agent-memory 0.0.17 → 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,52 +27,56 @@ 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, 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.
+```
 
 ## 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:
@@ -99,7 +103,9 @@ 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.
 
-## Database location
+## Configuration
+
+### Database Location
 
 By default, the SQLite database is created at:
 
@@ -119,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:
 
@@ -142,36 +148,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.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 {
@@ -20269,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. 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("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)}"` : "";
@@ -20285,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; 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: "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 {
@@ -20296,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>`;
@@ -20311,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. 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("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 {
@@ -20335,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 {
@@ -20361,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. 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 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({

package/package.json

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