@jcyamacho/agent-memory 0.0.4 → 0.0.6

package/README.md

@@ -66,19 +66,17 @@ Recommended LLM instructions to pair with this MCP:
 Use `memory_recall` at task start and whenever prior preferences, project facts,
 or decisions may matter.
 
-Use `memory_remember` only for durable, reusable context: preferences,
-conventions, decisions, constraints, and stable workflow habits. Store one
-concise, self-contained fact per memory. Include `workspace` when available. Do
-not store secrets or temporary noise.
-
-For `memory_recall`, pass `terms` as 2-5 distinctive strings that describe what
-you are looking for. Prefer names, identifiers, package names, file names, and
-short phrases. Each term is matched independently — more terms cast a wider net,
-and results matching multiple terms rank higher. Stemming is applied
-automatically, so exact word forms are not required.
-
-Use `workspace` to bias ranking toward the current project. Use `created_*`
-only for exact scoping.
+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.
 ```
 
 ## What It Stores
@@ -104,8 +102,6 @@ Inputs:
 Output:
 
 - `id`
-- `workspace`
-- `created_at`
 
 ### `recall`
 
@@ -122,7 +118,7 @@ Inputs:
 
 Output:
 
-- `results[]` with `id`, `content`, `score`, `workspace`, and `created_at`
+- `results[]` with `id`, `content`, `score`, `workspace`, and `updated_at`
 
 ## Setup
 

package/dist/index.js

@@ -12464,7 +12464,7 @@ class StdioServerTransport {
   }
 }
 // package.json
-var version2 = "0.0.4";
+var version2 = "0.0.6";
 
 // src/config.ts
 import { homedir } from "node:os";
@@ -19908,9 +19908,17 @@ class PersistenceError extends MemoryError {
   }
 }
 
+// src/memory.ts
+var toNormalizedScore = (value) => value;
+
 // src/memory-service.ts
 var DEFAULT_LIMIT = 15;
 var MAX_LIMIT = 50;
+var RECALL_CANDIDATE_LIMIT_MULTIPLIER = 2;
+var RETRIEVAL_SCORE_WEIGHT = 8;
+var WORKSPACE_MATCH_WEIGHT = 2;
+var RECENCY_WEIGHT = 1;
+var MAX_COMPOSITE_SCORE = RETRIEVAL_SCORE_WEIGHT + WORKSPACE_MATCH_WEIGHT + RECENCY_WEIGHT;
 
 class MemoryService {
   repository;
@@ -19937,14 +19945,17 @@ class MemoryService {
     if (terms.length === 0) {
       throw new ValidationError("At least one search term is required.");
     }
+    const requestedLimit = normalizeLimit(input.limit);
+    const workspace = normalizeOptionalString(input.workspace);
     const normalizedQuery = {
       terms,
-      limit: normalizeLimit(input.limit),
-      workspace: normalizeOptionalString(input.workspace),
+      limit: requestedLimit * RECALL_CANDIDATE_LIMIT_MULTIPLIER,
       createdAfter: input.createdAfter,
       createdBefore: input.createdBefore
     };
-    return this.repository.search(normalizedQuery);
+    const results = await this.repository.search(normalizedQuery);
+    const reranked = rerankSearchResults(results, workspace);
+    return reranked.sort((a, b) => b.score - a.score).slice(0, requestedLimit);
   }
 }
 var normalizeLimit = (value) => {
@@ -19964,6 +19975,23 @@ var normalizeTerms = (terms) => {
   const normalizedTerms = terms.map((term) => term.trim()).filter(Boolean);
   return [...new Set(normalizedTerms)];
 };
+var rerankSearchResults = (results, workspace) => {
+  if (results.length <= 1) {
+    return results;
+  }
+  const updatedAtTimes = results.map((result) => result.updatedAt.getTime());
+  const minUpdatedAt = Math.min(...updatedAtTimes);
+  const maxUpdatedAt = Math.max(...updatedAtTimes);
+  return [...results].map((result) => {
+    const workspaceScore = workspace && result.workspace === workspace ? 1 : 0;
+    const recencyScore = maxUpdatedAt === minUpdatedAt ? 0 : (result.updatedAt.getTime() - minUpdatedAt) / (maxUpdatedAt - minUpdatedAt);
+    const combinedScore = (result.score * RETRIEVAL_SCORE_WEIGHT + workspaceScore * WORKSPACE_MATCH_WEIGHT + recencyScore * RECENCY_WEIGHT) / MAX_COMPOSITE_SCORE;
+    return {
+      ...result,
+      score: toNormalizedScore(combinedScore)
+    };
+  });
+};
 
 // src/tools/shared.ts
 var toMcpError = (error2) => {
@@ -19992,24 +20020,24 @@ var parseOptionalDate = (value, fieldName) => {
 
 // src/tools/recall.ts
 var recallInputSchema = {
-  terms: array(string2()).min(1).describe("Search terms to match against remembered content. Use distinctive keywords, IDs, names, file names, or short phrases as separate items."),
-  limit: number2().int().min(1).max(MAX_LIMIT).optional().describe("Maximum number of memory results to return. Use a small number when you only need the best matches."),
-  workspace: string2().optional().describe("Workspace or repository path. Memories from this workspace rank higher, but other workspaces are not excluded."),
-  created_after: string2().optional().describe("Only return memories created at or after this ISO 8601 timestamp."),
-  created_before: string2().optional().describe("Only return memories created at or before this ISO 8601 timestamp.")
+  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."),
+  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.")
 };
 var recallOutputSchema = {
   results: array(object({
     id: string2().describe("Stable identifier for the remembered item."),
-    content: string2().describe("The remembered content that matched the search terms."),
-    score: number2().describe("Relevance score for this result. Higher means a better match."),
+    content: string2().describe("Saved memory text that matched one or more search terms."),
+    score: number2().describe("Relative relevance score for ranking results. Higher means a stronger match."),
     workspace: string2().optional().describe("Workspace associated with the memory, if available."),
-    created_at: string2().describe("ISO 8601 timestamp showing when the memory was created.")
+    updated_at: string2().describe("ISO 8601 timestamp showing when the memory was last updated.")
   }))
 };
 var registerRecallTool = (server, memoryService) => {
   server.registerTool("recall", {
-    description: "Retrieve previously remembered context that may help with the current task. Use it for user preferences, project facts, prior decisions, constraints, or earlier conversation details.",
+    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.",
     inputSchema: recallInputSchema,
     outputSchema: recallOutputSchema
   }, async ({ terms, limit, workspace, created_after, created_before }) => {
@@ -20027,7 +20055,7 @@ var registerRecallTool = (server, memoryService) => {
           content: result.content,
           score: result.score,
           workspace: result.workspace,
-          created_at: result.createdAt.toISOString()
+          updated_at: result.updatedAt.toISOString()
         }))
       };
       const matchCount = structuredContent.results.length;
@@ -20053,9 +20081,7 @@ var rememberInputSchema = {
   workspace: string2().optional().describe("Repository or workspace path this memory belongs to. Use it to keep memories scoped to a project.")
 };
 var rememberOutputSchema = {
-  id: string2().describe("Stable identifier for the saved memory."),
-  workspace: string2().optional().describe("Workspace stored with the memory, if provided."),
-  created_at: string2().describe("ISO 8601 timestamp showing when the memory was created.")
+  id: string2().describe("Stable identifier for the saved memory.")
 };
 var registerRememberTool = (server, memoryService) => {
   server.registerTool("remember", {
@@ -20069,9 +20095,7 @@ var registerRememberTool = (server, memoryService) => {
         workspace
       });
       const structuredContent = {
-        id: memory.id,
-        workspace: memory.workspace,
-        created_at: memory.createdAt.toISOString()
+        id: memory.id
       };
       return {
         content: [
@@ -20165,8 +20189,6 @@ var initializeMemoryDatabase = (database) => {
 };
 
 // src/sqlite-repository.ts
-var WORKSPACE_BIAS = 0.1;
-
 class SqliteMemoryRepository {
   database;
   insertStatement;
@@ -20198,15 +20220,7 @@ class SqliteMemoryRepository {
   }
   async search(query) {
     try {
-      const selectParams = [];
       const whereParams = [toFtsQuery(query.terms)];
-      let scoreExpr;
-      if (query.workspace) {
-        scoreExpr = "MAX(0, -bm25(memories_fts) + CASE WHEN m.workspace = ? THEN ? ELSE 0.0 END)";
-        selectParams.push(query.workspace, WORKSPACE_BIAS);
-      } else {
-        scoreExpr = "MAX(0, -bm25(memories_fts))";
-      }
       const whereClauses = ["memories_fts MATCH ?"];
       if (query.createdAfter) {
         whereClauses.push("m.created_at >= ?");
@@ -20216,14 +20230,15 @@ class SqliteMemoryRepository {
         whereClauses.push("m.created_at <= ?");
         whereParams.push(query.createdBefore.getTime());
       }
-      const params = [...selectParams, ...whereParams, query.limit];
+      const params = [...whereParams, query.limit];
       const statement = this.database.prepare(`
         SELECT
           m.id,
           m.content,
           m.workspace,
           m.created_at,
-          ${scoreExpr} AS score
+          m.updated_at,
+          MAX(0, -bm25(memories_fts)) AS score
         FROM memories_fts
         INNER JOIN memories AS m ON m.rowid = memories_fts.rowid
         WHERE ${whereClauses.join(" AND ")}
@@ -20231,12 +20246,14 @@ class SqliteMemoryRepository {
         LIMIT ?
       `);
       const rows = statement.all(...params);
+      const maxScore = Math.max(...rows.map((row) => row.score), 0);
       return rows.map((row) => ({
         id: row.id,
         content: row.content,
-        score: row.score,
+        score: toNormalizedScore(maxScore > 0 ? row.score / maxScore : 0),
         workspace: row.workspace ?? undefined,
-        createdAt: new Date(row.created_at)
+        createdAt: new Date(row.created_at),
+        updatedAt: new Date(row.updated_at)
       }));
     } catch (error2) {
       throw new PersistenceError("Failed to search memories.", {

package/package.json

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