@jcyamacho/agent-memory 0.0.8 → 0.0.9

package/README.md

@@ -60,23 +60,12 @@ With a custom database path:
 }
 ```
 
-Recommended LLM instructions to pair with this MCP:
+Optional LLM instructions to reinforce the MCP's built-in guidance:
 
 ```text
-Use `memory_recall` at task start and whenever prior preferences, project facts,
-or decisions may matter.
-
-Use `memory_remember` only for durable context worth reusing later:
-preferences, conventions, decisions, constraints, and stable workflow habits.
-Store one concise fact per memory, include `workspace` when relevant, and avoid
-secrets or temporary notes.
-
-For `memory_recall`, pass 2-5 short, distinctive `terms` as separate array
-items. Prefer project names, file names, APIs, feature names, issue IDs, and
-brief phrases. Avoid one long sentence.
-
-Use `workspace` to bias results toward the current project. Use `created_*`
-only when time range matters.
+Use `recall` at the start of every conversation. Use `remember` when the user
+corrects your approach, a key decision is established, or you learn project
+context not obvious from the code.
 ```
 
 ## What It Stores
@@ -130,25 +119,31 @@ Inputs:
   memory content; avoid full natural-language questions
 - `limit` -> maximum results to return
 - `workspace` -> workspace or repo path; biases ranking toward this workspace
-- `created_after` -> ISO 8601 lower bound
-- `created_before` -> ISO 8601 upper bound
+- `updated_after` -> ISO 8601 lower bound
+- `updated_before` -> ISO 8601 upper bound
 
 Output:
 
 - `results[]` with `id`, `content`, `score`, `workspace`, and `updated_at`
 
-## Setup
-
-For normal usage:
+## How Ranking Works
 
-- Node.js
+`recall` uses a multi-signal ranking system to surface the most relevant
+memories:
 
-For local development or running from source:
+1. **Text relevance** is the primary signal -- memories whose content best
+   matches your search terms rank highest.
+2. **Workspace match** is a strong secondary signal. When you pass `workspace`,
+   memories saved with the same workspace rank above unrelated ones.
+3. **Global memories** (saved without a workspace) are treated as relevant
+   everywhere. They rank between workspace-matching and non-matching memories.
+4. **Recency** is a minor tiebreaker -- newer memories rank slightly above older
+   ones when other signals are equal.
 
-- Bun
-- Node.js
+For best results, always pass `workspace` when calling `recall`. Save memories
+without a workspace only when they apply across all projects.
 
-### Database location
+## Database location
 
 By default, the SQLite database is created at:
 
@@ -171,9 +166,17 @@ Set `AGENT_MEMORY_DB_PATH` when you want to:
 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.
 
-## Run from source
+## Development
+
+For working on the project itself or running from source. Requires Bun and
+Node.js.
+
+```bash
+bun install
+bun run build
+```
 
-If you are developing locally instead of using the published package:
+To use a local build as your MCP server:
 
 ```json
 {
@@ -182,39 +185,17 @@ If you are developing locally instead of using the published package:
       "command": "node",
       "args": [
         "/absolute/path/to/agent-memory/dist/index.js"
-      ],
-      "env": {
-        "AGENT_MEMORY_DB_PATH": "/absolute/path/to/memory.db"
-      }
+      ]
     }
   }
 }
 ```
 
-Build first:
-
 ```bash
-bun install
-bun run build
-```
-
-## Local Development
-
-Only needed if you want to work on the project itself.
-
-```bash
-bun install
 bun lint
 bun test
-bun run build
 ```
 
-## Notes
-
-- `better-sqlite3` stays external in the build so its native binding loads
-  correctly at runtime.
-- Runtime output is Node-compatible and built to `dist/index.js`.
-
 ## License
 
 MIT

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.8";
+var version2 = "0.0.9";
 
 // src/config.ts
 import { homedir } from "node:os";
@@ -19971,8 +19971,8 @@ class MemoryService {
     const normalizedQuery = {
       terms,
       limit: requestedLimit * RECALL_CANDIDATE_LIMIT_MULTIPLIER,
-      createdAfter: input.createdAfter,
-      createdBefore: input.createdBefore
+      updatedAfter: input.updatedAfter,
+      updatedBefore: input.updatedBefore
     };
     const results = await this.repository.search(normalizedQuery);
     const reranked = rerankSearchResults(results, workspace);
@@ -20049,11 +20049,11 @@ var parseOptionalDate = (value, fieldName) => {
 
 // src/tools/recall.ts
 var recallInputSchema = {
-  terms: array(string2()).min(1).describe("Search terms used to find relevant memories. Pass 2-5 short, distinctive items as separate array entries, such as project names, file names, APIs, feature names, issue IDs, or brief phrases. Avoid one long sentence."),
+  terms: array(string2()).min(1).describe("Search terms used to find relevant memories. Pass 2-5 short, distinctive items as separate array entries. Focus on the topic, not the project name -- use workspace for project scoping. Prefer file names, APIs, feature names, or brief phrases. Avoid full sentences."),
   limit: number2().int().min(1).max(MAX_LIMIT).optional().describe("Maximum number of matches to return. Keep this small when you only need the strongest hits."),
-  workspace: string2().optional().describe("Preferred repository or workspace path for ranking. Use the current project path to bias results toward local context, while still allowing cross-workspace matches."),
-  created_after: string2().optional().describe("Only return memories created at or after this ISO 8601 timestamp. Use it when you need to narrow recall to newer context."),
-  created_before: string2().optional().describe("Only return memories created at or before this ISO 8601 timestamp. Use it when you need to narrow recall to older context.")
+  workspace: string2().optional().describe("Always pass the current working directory. Biases ranking toward the active project while still allowing cross-workspace matches. Memories saved without a workspace are treated as global and rank between matching and non-matching results."),
+  updated_after: string2().optional().describe("Only return memories updated at or after this ISO 8601 timestamp. Use it when you need to narrow recall to newer context."),
+  updated_before: string2().optional().describe("Only return memories updated at or before this ISO 8601 timestamp. Use it when you need to narrow recall to older context.")
 };
 var recallOutputSchema = {
   results: array(object({
@@ -20066,17 +20066,17 @@ var recallOutputSchema = {
 };
 var registerRecallTool = (server, memoryService) => {
   server.registerTool("recall", {
-    description: "Recall previously saved context for the current task. Best results usually come from 2-5 short, distinctive terms such as project names, file names, APIs, decisions, or issue IDs.",
+    description: "Recall previously saved context for the current task. Call this at the start of every conversation and whenever prior preferences, decisions, or project context may be relevant. Pass workspace to bias results toward the active project.",
     inputSchema: recallInputSchema,
     outputSchema: recallOutputSchema
-  }, async ({ terms, limit, workspace, created_after, created_before }) => {
+  }, async ({ terms, limit, workspace, updated_after, updated_before }) => {
     try {
       const results = await memoryService.search({
         terms,
         limit,
         workspace,
-        createdAfter: parseOptionalDate(created_after, "created_after"),
-        createdBefore: parseOptionalDate(created_before, "created_before")
+        updatedAfter: parseOptionalDate(updated_after, "updated_after"),
+        updatedBefore: parseOptionalDate(updated_before, "updated_before")
       });
       const structuredContent = {
         results: results.map((result) => ({
@@ -20106,15 +20106,15 @@ var registerRecallTool = (server, memoryService) => {
 
 // src/tools/remember.ts
 var rememberInputSchema = {
-  content: string2().describe("The exact fact, preference, decision, or context to remember for future retrieval. Use a self-contained sentence or short note."),
-  workspace: string2().optional().describe("Repository or workspace path this memory belongs to. Use it to keep memories scoped to a project.")
+  content: string2().describe("The fact, preference, decision, or context to remember. Use a single self-contained sentence or short note. One fact per memory."),
+  workspace: string2().optional().describe("Always pass the current working directory to scope this memory to a project. Omit only when the memory applies across all projects (global preference).")
 };
 var rememberOutputSchema = {
   id: string2().describe("Stable identifier for the saved memory.")
 };
 var registerRememberTool = (server, memoryService) => {
   server.registerTool("remember", {
-    description: "Save durable context for later recall. Use this for user preferences, project facts, decisions, constraints, or other information worth remembering across turns and tools.",
+    description: "Save durable context for later recall. Use this when the user corrects your approach, states a preference, a key decision or convention is established, or you learn project context not obvious from the code. Store one concise fact per memory. Do not store secrets, ephemeral task state, or information already in the codebase.",
     inputSchema: rememberInputSchema,
     outputSchema: rememberOutputSchema
   }, async ({ content, workspace }) => {
@@ -20142,10 +20142,19 @@ var registerRememberTool = (server, memoryService) => {
 };
 
 // src/mcp-server.ts
+var SERVER_INSTRUCTIONS = [
+  "Persistent memory for coding agents.",
+  "Use `recall` at the start of every conversation and whenever prior preferences, decisions, or project context may be relevant.",
+  "Use `remember` when the user corrects your approach, states a preference, a key decision is established, or you learn project context not obvious from the code.",
+  "Always pass workspace (the current working directory) to scope results to the active project.",
+  "Omit workspace only when saving a memory that applies across all projects."
+].join(" ");
 var createMcpServer = (memoryService, version3) => {
   const server = new McpServer({
     name: "agent-memory",
     version: version3
+  }, {
+    instructions: SERVER_INSTRUCTIONS
   });
   registerRememberTool(server, memoryService);
   registerRecallTool(server, memoryService);
@@ -20259,13 +20268,13 @@ class SqliteMemoryRepository {
     try {
       const whereParams = [toFtsQuery(query.terms)];
       const whereClauses = ["memories_fts MATCH ?"];
-      if (query.createdAfter) {
-        whereClauses.push("m.created_at >= ?");
-        whereParams.push(query.createdAfter.getTime());
+      if (query.updatedAfter) {
+        whereClauses.push("m.updated_at >= ?");
+        whereParams.push(query.updatedAfter.getTime());
       }
-      if (query.createdBefore) {
-        whereClauses.push("m.created_at <= ?");
-        whereParams.push(query.createdBefore.getTime());
+      if (query.updatedBefore) {
+        whereClauses.push("m.updated_at <= ?");
+        whereParams.push(query.updatedBefore.getTime());
       }
       const params = [...whereParams, query.limit];
       const statement = this.database.prepare(`

package/package.json

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