@hasna/mementos 0.10.15 → 0.10.17

package/dist/mcp/index.js

@@ -9826,6 +9826,73 @@ ${lines.join(`
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
+server.tool("memory_health", "Comprehensive health check for memories. Detects: stale (old + 0 access), high-importance-forgotten (importance>=7 + not accessed in 60d), and possibly-superseded (newer memory with similar key). Returns actionable summary.", {
+  stale_days: exports_external.coerce.number().optional().describe("Days with no access to consider a memory stale (default: 30)"),
+  forgotten_days: exports_external.coerce.number().optional().describe("Days since access for high-importance memories (default: 60)"),
+  project_id: exports_external.string().optional(),
+  agent_id: exports_external.string().optional(),
+  limit: exports_external.coerce.number().optional().describe("Max per category (default: 10)")
+}, async (args) => {
+  try {
+    const db = getDatabase();
+    const staleDays = args.stale_days ?? 30;
+    const forgottenDays = args.forgotten_days ?? 60;
+    const limit = args.limit ?? 10;
+    const extraWhere = [
+      ...args.project_id ? ["project_id = ?"] : [],
+      ...args.agent_id ? ["agent_id = ?"] : []
+    ].join(" AND ");
+    const extraParams = [
+      ...args.project_id ? [args.project_id] : [],
+      ...args.agent_id ? [args.agent_id] : []
+    ];
+    const base = `status = 'active' AND pinned = 0${extraWhere ? " AND " + extraWhere : ""}`;
+    const stale = db.prepare(`SELECT id, key, value, importance, scope, created_at FROM memories
+         WHERE ${base} AND access_count = 0 AND created_at < datetime('now', '-${staleDays} days')
+         ORDER BY created_at ASC LIMIT ?`).all(...extraParams, limit);
+    const forgotten = db.prepare(`SELECT id, key, value, importance, scope, accessed_at FROM memories
+         WHERE ${base} AND importance >= 7
+           AND (accessed_at IS NULL OR accessed_at < datetime('now', '-${forgottenDays} days'))
+         ORDER BY importance DESC, COALESCE(accessed_at, created_at) ASC LIMIT ?`).all(...extraParams, limit);
+    const dupes = db.prepare(`SELECT key, COUNT(*) as cnt, MAX(updated_at) as latest, MIN(created_at) as oldest
+         FROM memories WHERE ${base}
+         GROUP BY key HAVING cnt > 1
+         ORDER BY cnt DESC LIMIT ?`).all(...extraParams, limit);
+    const parts = [`Memory Health Report
+`];
+    if (stale.length > 0) {
+      parts.push(`\u26A0\uFE0F  STALE (${stale.length}) \u2014 created ${staleDays}d+ ago, never accessed:`);
+      for (const m of stale) {
+        parts.push(`  \u2022 [${m.importance}] ${m.key} (${m.scope}) \u2014 created ${m.created_at.slice(0, 10)}`);
+      }
+      parts.push("");
+    }
+    if (forgotten.length > 0) {
+      parts.push(`\uD83D\uDD14  HIGH-IMPORTANCE FORGOTTEN (${forgotten.length}) \u2014 importance\u22657, not accessed in ${forgottenDays}d+:`);
+      for (const m of forgotten) {
+        parts.push(`  \u2022 [${m.importance}] ${m.key} (${m.scope}) \u2014 last: ${m.accessed_at?.slice(0, 10) || "never"}`);
+      }
+      parts.push("");
+    }
+    if (dupes.length > 0) {
+      parts.push(`\uD83D\uDD04  POSSIBLY SUPERSEDED (${dupes.length}) \u2014 same key with multiple versions:`);
+      for (const d of dupes) {
+        parts.push(`  \u2022 ${d.key} \xD7 ${d.cnt} copies \u2014 newest: ${d.latest.slice(0, 10)}`);
+      }
+      parts.push("");
+    }
+    if (stale.length === 0 && forgotten.length === 0 && dupes.length === 0) {
+      parts.push("\u2713 No health issues found. All memories look fresh.");
+    } else {
+      parts.push(`Summary: ${stale.length} stale, ${forgotten.length} forgotten, ${dupes.length} possibly-superseded.`);
+      parts.push("Suggested actions: archive stale memories, review forgotten ones, merge duplicates.");
+    }
+    return { content: [{ type: "text", text: parts.join(`
+`) }] };
+  } catch (e) {
+    return { content: [{ type: "text", text: formatError(e) }], isError: true };
+  }
+});
 server.tool("memory_search", "Search memories by keyword across key, value, summary, and tags", {
   query: exports_external.string(),
   scope: exports_external.enum(["global", "shared", "private"]).optional(),
@@ -10753,11 +10820,13 @@ Summary: ${newMems.length} new, ${updatedMems.length} updated, ${expiredMems.len
     return { content: [{ type: "text", text: formatError(e) }], isError: true };
   }
 });
-server.tool("memory_context", "Get memories relevant to current context, filtered by scope/importance/recency.", {
+server.tool("memory_context", "Get memories relevant to current context. Uses time-weighted scoring: score = importance \xD7 decay(age). Pinned memories are exempt. Returns effective_score on each memory.", {
   agent_id: exports_external.string().optional(),
   project_id: exports_external.string().optional(),
   scope: exports_external.enum(["global", "shared", "private"]).optional(),
-  limit: exports_external.coerce.number().optional()
+  limit: exports_external.coerce.number().optional(),
+  decay_halflife_days: exports_external.coerce.number().optional().describe("Importance half-life in days (default: 90). Lower = more weight on recent memories."),
+  no_decay: exports_external.coerce.boolean().optional().describe("Set true to disable decay and sort purely by importance.")
 }, async (args) => {
   try {
     const filter = {
@@ -10765,16 +10834,31 @@ server.tool("memory_context", "Get memories relevant to current context, filtere
       agent_id: args.agent_id,
       project_id: args.project_id,
       status: "active",
-      limit: args.limit || 30
+      limit: (args.limit || 30) * 2
     };
     const memories = listMemories(filter);
     if (memories.length === 0) {
       return { content: [{ type: "text", text: "No memories in current context." }] };
     }
-    for (const m of memories) {
+    const halflifeDays = args.decay_halflife_days ?? 90;
+    const now2 = Date.now();
+    const scored = memories.map((m) => {
+      let effectiveScore = m.importance;
+      if (!args.no_decay && !m.pinned) {
+        const ageMs = now2 - new Date(m.updated_at).getTime();
+        const ageDays = ageMs / (1000 * 60 * 60 * 24);
+        const decayFactor = Math.pow(0.5, ageDays / halflifeDays);
+        effectiveScore = m.importance * decayFactor;
+      }
+      return { ...m, effective_score: Math.round(effectiveScore * 100) / 100 };
+    });
+    const limit = args.limit || 30;
+    scored.sort((a, b) => b.effective_score - a.effective_score);
+    const top = scored.slice(0, limit);
+    for (const m of top) {
       touchMemory(m.id);
     }
-    const lines = memories.map((m) => `[${m.scope}/${m.category}] ${m.key}: ${m.value} (importance: ${m.importance})`);
+    const lines = top.map((m) => `[${m.scope}/${m.category}] ${m.key}: ${m.value} (score: ${m.effective_score}, raw: ${m.importance}${m.pinned ? ", pinned" : ""})`);
     return { content: [{ type: "text", text: lines.join(`
 `) }] };
   } catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/mementos",
-  "version": "0.10.15",
+  "version": "0.10.17",
   "description": "Universal memory system for AI agents - CLI + MCP server + library API",
   "type": "module",
   "main": "dist/index.js",