@prom.codes/memory-mcp 0.15.1 → 0.16.0

package/dist/bin.js

@@ -301,6 +301,20 @@ function isHomeOrFilesystemRoot(root) {
   return false;
 }
 
+// ../shared/dist/workspace-path.js
+import { createHash } from "node:crypto";
+import { resolve as resolve2 } from "node:path";
+function canonicalizeWorkspacePath(p) {
+  const abs = resolve2(p);
+  return process.platform === "win32" ? abs.replace(/\\/g, "/").toLowerCase() : abs;
+}
+function stableWorkspaceId(root) {
+  return createHash("sha256").update(canonicalizeWorkspacePath(root)).digest("hex").slice(0, 16);
+}
+function legacyWorkspaceId(root) {
+  return createHash("sha256").update(resolve2(root)).digest("hex").slice(0, 16);
+}
+
 // ../shared/dist/heartbeat.js
 import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir as homedir3 } from "node:os";
@@ -471,9 +485,8 @@ function nativeBindingOption() {
 }
 
 // dist/composition.js
-import { createHash } from "node:crypto";
 import { homedir as homedir5 } from "node:os";
-import { basename, join as join7, resolve as resolve2 } from "node:path";
+import { basename, join as join7, resolve as resolve3 } from "node:path";
 
 // ../embeddings-openai-compat/dist/index.js
 var DEFAULT_BATCH = 96;
@@ -504,14 +517,14 @@ function parseRetryAfterMs(value, now = Date.now()) {
   return delta > 0 ? delta : 0;
 }
 function sleep(ms, signal) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve3();
+      resolve4();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -754,14 +767,14 @@ var DEFAULT_RETRIES2 = 4;
 var DEFAULT_BACKOFF2 = 250;
 var DEFAULT_TIMEOUT_MS2 = 15e3;
 function sleep2(ms, signal) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve3();
+      resolve4();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -1025,14 +1038,14 @@ function parseRetryAfterMs2(value, now = Date.now()) {
   return delta > 0 ? delta : 0;
 }
 function sleep3(ms, signal) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve3();
+      resolve4();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -1179,14 +1192,14 @@ var DEFAULT_RETRIES4 = 4;
 var DEFAULT_BACKOFF4 = 250;
 var DEFAULT_TIMEOUT_MS3 = 15e3;
 function sleep4(ms, signal) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve3();
+      resolve4();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -1405,14 +1418,14 @@ function parseRetryAfterMs3(value, now = Date.now()) {
   return delta > 0 ? delta : 0;
 }
 function sleep5(ms, signal) {
-  return new Promise((resolve3, reject) => {
+  return new Promise((resolve4, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve3();
+      resolve4();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -1806,7 +1819,7 @@ var OpenAICompatRewriter = class {
 
 // dist/sqlite.js
 import { randomUUID } from "node:crypto";
-import { mkdirSync as mkdirSync3, readdirSync as readdirSync2, readFileSync as readFileSync3, rmSync as rmSync2 } from "node:fs";
+import { mkdirSync as mkdirSync3, readdirSync as readdirSync3, readFileSync as readFileSync3, rmSync as rmSync2 } from "node:fs";
 import { dirname as dirname4, join as join6 } from "node:path";
 import Database from "better-sqlite3";
 
@@ -1854,7 +1867,7 @@ function assertNoSecrets(text) {
 }
 
 // dist/recorder.js
-import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, renameSync, rmdirSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { dirname as dirname3, join as join5 } from "node:path";
 var SPOOL_VERSION = 1;
@@ -1890,6 +1903,46 @@ function recorderRoot(env = process.env) {
 function sanitizeSegment(s) {
   return s.replace(/[^A-Za-z0-9._-]/g, "_").slice(0, 128) || "_";
 }
+function migrateRecorderSpoolDir(oldId, newId, env = process.env) {
+  if (oldId === newId)
+    return { renamedDir: false, movedFiles: 0 };
+  const root = recorderRoot(env);
+  const oldDir = join5(root, sanitizeSegment(oldId));
+  const newDir = join5(root, sanitizeSegment(newId));
+  if (!existsSync2(oldDir))
+    return { renamedDir: false, movedFiles: 0 };
+  if (!existsSync2(newDir)) {
+    try {
+      renameSync(oldDir, newDir);
+      return { renamedDir: true, movedFiles: 0 };
+    } catch {
+    }
+  }
+  mkdirSync2(newDir, { recursive: true });
+  let moved = 0;
+  let names;
+  try {
+    names = readdirSync2(oldDir);
+  } catch {
+    return { renamedDir: false, movedFiles: 0 };
+  }
+  for (const name of names) {
+    const to = join5(newDir, name);
+    if (existsSync2(to))
+      continue;
+    try {
+      renameSync(join5(oldDir, name), to);
+      moved++;
+    } catch {
+    }
+  }
+  try {
+    if (readdirSync2(oldDir).length === 0)
+      rmdirSync(oldDir);
+  } catch {
+  }
+  return { renamedDir: false, movedFiles: moved };
+}
 function parseSpool(raw) {
   const lines = raw.split("\n");
   const events = [];
@@ -1921,7 +1974,7 @@ var RECORDER_HOOK_SCRIPT = String.raw`#!/usr/bin/env node
 // never disturb a coding session. Managed by prom.codes (memory-mcp recorder_setup).
 import { appendFileSync, mkdirSync, readFileSync, statSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 
 const SPOOL_CAP = ${SPOOL_CAP_BYTES};
@@ -1944,7 +1997,11 @@ function sensitivePath(p) {
   if (/(^|\/)(secrets?|credentials?)(\/|$)/.test(s)) return true;
   return false;
 }
-function projectIdOf(root) { return createHash("sha256").update(String(root)).digest("hex").slice(0, 16); }
+// Canonical workspace id — MUST match @prometheus/shared stableWorkspaceId so
+// the spool key equals memory-mcp's projectIdFor (the ingest side). Inlined
+// because this standalone hook cannot import from the package.
+function canonicalizeWorkspacePath(p) { const abs = resolve(p); return process.platform === "win32" ? abs.replace(/\\/g, "/").toLowerCase() : abs; }
+function projectIdOf(root) { return createHash("sha256").update(canonicalizeWorkspacePath(root)).digest("hex").slice(0, 16); }
 
 function dietTool(toolName, inp, result) {
   const tool = toolName; inp = inp || {};
@@ -2604,6 +2661,61 @@ var SqliteMemoryBackend = class {
     if (this.embedder !== void 0)
       this.queueUnembedded();
   }
+  /**
+   * Canonical-hash migration (spec 2026-07-19 §3.3): move every row keyed on the
+   * PRE-flip `oldId` onto the canonical `newId`, in ONE transaction. No re-embed
+   * (the vector is over `value`, which is unchanged) — the memory analogue of
+   * context's "no reindex".
+   *
+   *  - `agent_memory`: change `project_id`; for project-scoped rows the
+   *    `scope_id` (which equals the project id) moves too. The UNIQUE
+   *    `(scope, scope_id, type, key)` can then clash with a row already under
+   *    `newId` (the user used both path spellings). **Merge rule: newest
+   *    `updated_at` wins**; the loser is deleted (its vector + FTS entry GC'd by
+   *    the existing delete triggers). This mirrors `resolveScopeChain`'s own
+   *    newer-wins tie-break, so the survivor is the record recall already prefers.
+   *  - `agent_sessions` / `session_events`: `UPDATE OR IGNORE` the `project_id`;
+   *    a `(session_id, seq)` clash across two spellings is effectively impossible
+   *    (ids are unique per run under one spelling), and OR IGNORE leaves any
+   *    clash inert under the old id rather than throwing.
+   *
+   * Idempotent (afterwards no row has `project_id = oldId`) and a no-op when
+   * `oldId === newId` (POSIX / already-canonical).
+   */
+  migrateProjectIdentity(oldId, newId) {
+    if (oldId === newId) {
+      return { memoryRows: 0, memoryMerged: 0, sessions: 0, events: 0 };
+    }
+    const run = this.db.transaction(() => {
+      const incoming = this.db.prepare(`SELECT * FROM agent_memory WHERE project_id = ?`).all(oldId);
+      const findClash = this.db.prepare(`SELECT id, updated_at FROM agent_memory
+         WHERE scope = ? AND scope_id = ? AND type = ? AND key = ? AND id != ?`);
+      const del = this.db.prepare(`DELETE FROM agent_memory WHERE id = ?`);
+      const upd = this.db.prepare(`UPDATE agent_memory SET project_id = ?, scope_id = ? WHERE id = ?`);
+      let merged = 0;
+      for (const row of incoming) {
+        const newScopeId = row.scope === "project" && row.scope_id === oldId ? newId : row.scope_id;
+        const clash = findClash.get(row.scope, newScopeId, row.type, row.key, row.id);
+        if (clash !== void 0) {
+          if (row.updated_at > clash.updated_at) {
+            del.run(clash.id);
+            this.pendingEmbed.delete(clash.id);
+            upd.run(newId, newScopeId, row.id);
+          } else {
+            del.run(row.id);
+            this.pendingEmbed.delete(row.id);
+          }
+          merged++;
+        } else {
+          upd.run(newId, newScopeId, row.id);
+        }
+      }
+      const sessions = this.db.prepare(`UPDATE OR IGNORE agent_sessions SET project_id = ? WHERE project_id = ?`).run(newId, oldId).changes;
+      const events = this.db.prepare(`UPDATE OR IGNORE session_events SET project_id = ? WHERE project_id = ?`).run(newId, oldId).changes;
+      return { memoryRows: incoming.length, memoryMerged: merged, sessions, events };
+    });
+    return run();
+  }
   /**
    * Queue every record lacking a stored vector for a (re)embed. Run at
    * open so a DB first built keyword-only — or one whose vectors were
@@ -2688,7 +2800,8 @@ var SqliteMemoryBackend = class {
     const rows = this.db.prepare(sql).all(...params);
     const resolved = resolveScopeChain(rows.map(rowToRecord), query.chain);
     const deduped = this.dedupeRecords(resolved);
-    const limited = query.limit !== void 0 ? deduped.slice(0, query.limit) : deduped;
+    const offset = query.offset ?? 0;
+    const limited = query.limit !== void 0 ? deduped.slice(offset, offset + query.limit) : deduped.slice(offset);
     const bump = this.db.prepare(`UPDATE agent_memory SET use_count = use_count + 1 WHERE id = ?`);
     for (const rec of limited) {
       bump.run(rec.id);
@@ -3037,7 +3150,7 @@ ${h.record.value}`
     let deletedSpools = 0;
     let files;
     try {
-      files = readdirSync2(dir).filter((f) => f.endsWith(".jsonl"));
+      files = readdirSync3(dir).filter((f) => f.endsWith(".jsonl"));
     } catch {
       return { sessions: 0, events: 0, deletedSpools: 0 };
     }
@@ -3211,8 +3324,10 @@ ${h.record.value}`
 
 // dist/composition.js
 function projectIdFor(workspaceRoot) {
-  const abs = resolve2(workspaceRoot);
-  return createHash("sha256").update(abs).digest("hex").slice(0, 16);
+  return stableWorkspaceId(workspaceRoot);
+}
+function legacyProjectIdFor(workspaceRoot) {
+  return legacyWorkspaceId(workspaceRoot);
 }
 function defaultMemoryDbPath() {
   return join7(homedir5(), ".prometheus", "memory.db");
@@ -3462,7 +3577,7 @@ function composeFromEnv(opts) {
   const override = (opts.workspaceRootOverride ?? "").trim();
   const envRoot = (env.PROMETHEUS_WORKSPACE_ROOT ?? "").trim();
   const claudeRoot = (env.CLAUDE_PROJECT_DIR ?? "").trim();
-  const workspaceRoot = resolve2(override !== "" ? override : envRoot !== "" ? envRoot : claudeRoot !== "" ? claudeRoot : process.cwd());
+  const workspaceRoot = resolve3(override !== "" ? override : envRoot !== "" ? envRoot : claudeRoot !== "" ? claudeRoot : process.cwd());
   const projectId = projectIdFor(workspaceRoot);
   const projectName = basename(workspaceRoot) || workspaceRoot;
   const rawDbPath = env.PROMETHEUS_MEMORY_DB_PATH;
@@ -3481,6 +3596,21 @@ function composeFromEnv(opts) {
     temporal,
     dedup
   });
+  const legacyId = legacyProjectIdFor(workspaceRoot);
+  const canonMigrationOff = /^(off|0|false|no)$/i.test((env.PROMETHEUS_CANON_MIGRATION ?? "").trim());
+  if (legacyId !== projectId && !canonMigrationOff) {
+    try {
+      const m = backend.migrateProjectIdentity(legacyId, projectId);
+      const spool = migrateRecorderSpoolDir(legacyId, projectId, env);
+      if (m.memoryRows > 0 || m.sessions > 0 || m.events > 0 || spool.renamedDir || spool.movedFiles > 0) {
+        process.stderr.write(`[prom.codes] canonical-hash migration: ${m.memoryRows} memory row(s) (${m.memoryMerged} merged), ${m.sessions} session(s), ${m.events} event(s), spool ${spool.renamedDir ? "dir renamed" : `${spool.movedFiles} file(s)`} ${legacyId} -> ${projectId}
+`);
+      }
+    } catch (err) {
+      process.stderr.write(`[prom.codes] canonical-hash memory migration skipped (non-fatal): ${err.message}
+`);
+    }
+  }
   return {
     backend,
     recorder: backend,
@@ -3984,8 +4114,10 @@ function weave(records, options = {}) {
 
 // dist/tools.js
 var MAX_LIMIT = 100;
-var DEFAULT_READ_LIMIT = 50;
+var DEFAULT_READ_LIMIT = 25;
 var MAX_VALUE_CHARS = 64 * 1024;
+var RECORDS_TOKEN_BUDGET = 5e3;
+var MAX_VALUE_CHARS_IN_VIEW = 4e3;
 function textResult(payload) {
   return {
     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }]
@@ -4009,6 +4141,52 @@ function recordToJson(rec) {
     updatedAt: rec.updatedAt
   };
 }
+function recordToJsonPreview(rec, maxValueChars) {
+  const view = recordToJson(rec);
+  if (rec.value.length > maxValueChars) {
+    const omitted = rec.value.length - maxValueChars;
+    view.value = `${rec.value.slice(0, maxValueChars)}
+\u2026[+${omitted} chars omitted \u2014 use \`search\` for the full value]`;
+    view.valueTruncated = true;
+    view.valueChars = rec.value.length;
+  }
+  return view;
+}
+function boundRecordsForResult(records) {
+  const views = [];
+  let valuesPreviewed = 0;
+  let tokens = 0;
+  let overBudget = false;
+  for (const rec of records) {
+    const view = recordToJsonPreview(rec, MAX_VALUE_CHARS_IN_VIEW);
+    if (view.valueTruncated === true)
+      valuesPreviewed += 1;
+    const cost = estimateTokens(JSON.stringify(view));
+    if (views.length > 0 && tokens + cost > RECORDS_TOKEN_BUDGET) {
+      overBudget = true;
+      break;
+    }
+    views.push(view);
+    tokens += cost;
+  }
+  return { views, shown: views.length, fetched: records.length, valuesPreviewed, overBudget };
+}
+function boundedRecordsNote(b, opts) {
+  if (!b.overBudget && b.valuesPreviewed === 0 && b.fetched < opts.limit)
+    return void 0;
+  const parts = [];
+  if (b.overBudget) {
+    parts.push(`Showing ${b.shown} of ${b.fetched} fetched records \u2014 the result was trimmed to stay under the token budget. The \`woven\` block already carries the highest-value facts within its own cap.`);
+  }
+  if (b.valuesPreviewed > 0) {
+    parts.push(`${b.valuesPreviewed} value(s) previewed to ${MAX_VALUE_CHARS_IN_VIEW} chars.`);
+  }
+  if (b.fetched >= opts.limit) {
+    parts.push(`More records may exist beyond limit=${opts.limit}.`);
+  }
+  parts.push(`To see more: narrow with \`types\`, page with \`offset\` (e.g. offset=${(opts.offset ?? 0) + b.shown}), raise \`limit\`, or use \`search\` for specific facts.`);
+  return parts.join(" ");
+}
 function clampLimit(limit, def) {
   if (limit === void 0)
     return def;
@@ -4026,7 +4204,9 @@ var scopeEnum = z.enum(MEMORY_SCOPES);
 var typeEnum = z.enum(MEMORY_TYPES);
 var readInput = {
   types: z.array(typeEnum).min(1).optional(),
-  limit: z.number().int().positive().max(MAX_LIMIT).optional()
+  limit: z.number().int().positive().max(MAX_LIMIT).optional(),
+  /** Skip the first N resolved records — page through large memory sets. */
+  offset: z.number().int().nonnegative().optional()
 };
 var writeInput = {
   scope: scopeEnum.optional(),
@@ -4113,19 +4293,23 @@ function registerTools(server, source, hooks = {}) {
   }));
   reg("read", {
     title: "Recall agent memory",
-    description: "Read agent memory for this project along the scope chain (project \u2192 workspace \u2192 tenant \u2192 system; narrowest scope wins). Syncs `.prometheus/memories/*.md` first, then returns the resolved records plus a prompt-ready `woven` markdown block (token-capped). Call this at the START of a session or task to recall what earlier sessions learned.",
+    description: "Read agent memory for this project along the scope chain (project \u2192 workspace \u2192 tenant \u2192 system; narrowest scope wins). Syncs `.prometheus/memories/*.md` first, then returns the resolved records plus a prompt-ready `woven` markdown block (token-capped). The `records` array is bounded to a token budget; a `note` explains how to page (`offset`) or narrow (`types`, `search`) when trimmed. Call this at the START of a session or task to recall what earlier sessions learned.",
     inputSchema: readInput
   }, async (args) => {
     const deps = await ready();
     const { backend, workspaceRoot, projectId, projectName } = deps;
     const mirrorToFiles = !deps.rootIsHomeOrFsRoot;
     const limit = clampLimit(args.limit, DEFAULT_READ_LIMIT);
+    const offset = args.offset ?? 0;
     const sync = mirrorToFiles ? await syncProjectFiles(backend, { projectId, workspaceRoot }) : { synced: 0, pruned: 0, skipped: [] };
     const records = await backend.read({
       chain: defaultScopeChain(projectId),
       types: args.types,
-      limit
+      limit,
+      offset
     });
+    const bounded = boundRecordsForResult(records);
+    const note = boundedRecordsNote(bounded, { limit, offset });
     return textResult({
       projectId,
       projectName,
@@ -4133,7 +4317,12 @@ function registerTools(server, source, hooks = {}) {
       projectFilesPruned: sync.pruned,
       ...sync.skipped.length > 0 ? { skippedFiles: sync.skipped } : {},
       woven: weave(records),
-      records: records.map(recordToJson)
+      recordsShown: bounded.shown,
+      recordsFetched: bounded.fetched,
+      limit,
+      offset,
+      ...note !== void 0 ? { note } : {},
+      records: bounded.views
     });
   });
   reg("write", {
@@ -4285,11 +4474,17 @@ ${f.value}`);
       keyContains: args.keyContains,
       limit
     });
+    const bounded = boundRecordsForResult(records);
+    const note = boundedRecordsNote(bounded, { limit });
     return textResult({
       projectId,
       projectName,
       dbPath,
-      records: records.map(recordToJson)
+      recordsShown: bounded.shown,
+      recordsFetched: bounded.fetched,
+      limit,
+      ...note !== void 0 ? { note } : {},
+      records: bounded.views
     });
   });
   reg("delete", {
@@ -4433,7 +4628,7 @@ ${f.value}`);
         embeddingsError = err instanceof Error ? err.message : String(err);
       }
     }
-    const update = await buildUpdateStatus("@prom.codes/memory-mcp", "0.15.1", { isDevBuild: false });
+    const update = await buildUpdateStatus("@prom.codes/memory-mcp", "0.16.0", { isDevBuild: false });
     let recorder;
     try {
       const scopes = ["project-local", "project", "user"];
@@ -4515,7 +4710,7 @@ ${f.value}`);
 // dist/server.js
 var SERVER_IDENTITY = {
   name: "prometheus-memory-mcp",
-  version: "0.15.1",
+  version: "0.16.0",
   title: "prom.codes Memory"
 };
 var SERVER_INSTRUCTIONS = "Persistent agent memory for this workspace \u2014 USE IT PROACTIVELY; the user will not tell you to. Protocol:\n1. ONE-TIME: if this workspace has no Prometheus memory rule yet, call memory_setup now (idempotent) so the protocol is installed into the runtime rule files and survives future sessions. (The server also auto-installs it on startup when a project rule file already exists \u2014 memory_setup covers the rest.)\n2. SESSION START: before any non-trivial task, call memory_read to recall facts, decisions and procedures from earlier sessions.\n3. DURING WORK: when the user states a durable preference, decision, correction or project fact, store it with memory_write (semantic for facts, procedural for how-tos) \u2014 without being asked.\n4. LOOK-UP: use memory_search for keyword recall when memory_read is not specific enough.\n5. SESSION END: consolidate what was learned with memory_capture.\nCall memory_status anytime to check what is stored and whether the rule is installed. Never store secrets, API keys or credentials \u2014 such writes are rejected.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prom.codes/memory-mcp",
-  "version": "0.15.1",
+  "version": "0.16.0",
   "description": "prom.codes Memory — persistent, local-first agent memory as an MCP server.",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "better-sqlite3": "^12.10.0",
+    "better-sqlite3": "12.10.0",
     "zod": "^4.4.3"
   },
   "optionalDependencies": {