@prom.codes/memory-mcp 0.10.2 → 0.11.0

package/README.md

@@ -51,8 +51,9 @@ your home dir. Open a project folder so memories scope correctly.
 Tools (docked as `memory`): `memory_read`, `memory_write`, `memory_capture`,
 `memory_search`, `memory_list`, `memory_delete`, `memory_setup`,
 `memory_status` (health check: which folder, how many records, does the key
-work?). Secrets are rejected on every write. Your memories never leave your
-machine (only short query/record text transits when embeddings are enabled).
+work, is a newer version published?). Secrets are rejected on every write.
+Your memories never leave your machine (only short query/record text
+transits when embeddings are enabled).
 
 ## Native modules
 

package/dist/bin.js

@@ -34,10 +34,11 @@ var LANGUAGE_IDS = [
 ];
 
 // ../shared/dist/update-check.js
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
+var UPGRADE_COMMAND = "npm install -g @prom.codes/context-mcp @prom.codes/memory-mcp @prom.codes/saver --ignore-scripts=false --foreground-scripts";
 async function packageIdentity(binImportMetaUrl) {
   try {
     const binPath = fileURLToPath(binImportMetaUrl);
@@ -92,6 +93,29 @@ function cachePath(dir, name) {
   const safe = name.replace(/[^a-zA-Z0-9._-]+/g, "_");
   return join(dir, `.update-check-${safe}.json`);
 }
+function availabilityMarkerPath(dir, name) {
+  const safe = name.replace(/[^a-zA-Z0-9._-]+/g, "_");
+  return join(dir, `.update-available-${safe}.json`);
+}
+async function syncAvailabilityMarker(dir, name, current, latest, updateAvailable) {
+  const file = availabilityMarkerPath(dir, name);
+  try {
+    if (updateAvailable && latest !== null) {
+      const marker = {
+        name,
+        current,
+        latest,
+        command: UPGRADE_COMMAND,
+        notedAt: Date.now()
+      };
+      await mkdir(dir, { recursive: true }).catch(() => void 0);
+      await writeFile(file, JSON.stringify(marker), "utf8");
+    } else if (latest !== null) {
+      await rm(file, { force: true });
+    }
+  } catch {
+  }
+}
 async function readCache(path2) {
   try {
     const raw = await readFile(path2, "utf8");
@@ -120,7 +144,7 @@ async function fetchLatest(name, fetchImpl, timeoutMs) {
     const url = `https://registry.npmjs.org/${name.replace("/", "%2F")}/latest`;
     const res = await fetchImpl(url, {
       signal: controller.signal,
-      headers: { accept: "application/vnd.npm.install-v1+json" }
+      headers: { accept: "application/json" }
     });
     if (!res.ok)
       return null;
@@ -155,6 +179,7 @@ async function checkForUpdate(options) {
       const updateAvailable2 = cached.latest !== null && isNewerVersion(cached.latest, version);
       if (updateAvailable2)
         notify(log, name, version, cached.latest);
+      await syncAvailabilityMarker(cacheDir, name, version, cached.latest, updateAvailable2);
       return {
         ...base,
         latest: cached.latest,
@@ -173,13 +198,62 @@ async function checkForUpdate(options) {
   const updateAvailable = isNewerVersion(latest, version);
   if (updateAvailable)
     notify(log, name, version, latest);
+  await syncAvailabilityMarker(cacheDir, name, version, latest, updateAvailable);
   return { ...base, latest, checked: true, updateAvailable };
 }
+async function getLatestVersion(name, options = {}) {
+  const { env = process.env, fetch: fetchImpl = globalThis.fetch, cacheDir = join(homedir(), ".prometheus"), cacheTtlMs = DEFAULT_TTL_MS, timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+  const file = cachePath(cacheDir, name);
+  const cached = await readCache(file);
+  const now = Date.now();
+  if (cached !== null && cached.latest !== null && now - cached.checkedAt < cacheTtlMs) {
+    return cached.latest;
+  }
+  if (OPT_OUT_RE.test(env.PROMETHEUS_NO_UPDATE_CHECK ?? "") || typeof fetchImpl !== "function") {
+    return cached?.latest ?? null;
+  }
+  const latest = await fetchLatest(name, fetchImpl, timeoutMs);
+  if (latest !== null) {
+    await mkdir(cacheDir, { recursive: true }).catch(() => void 0);
+    await writeCache(file, { checkedAt: now, latest });
+    return latest;
+  }
+  return cached?.latest ?? null;
+}
 function notify(log, name, current, latest) {
   log(`${name}: a newer version (${latest}) is available \u2014 you are on ${current}. npx users get it automatically on the next restart; for a global install run \`npm update -g ${name}\`. (Set PROMETHEUS_NO_UPDATE_CHECK=1 to silence.)
 `);
 }
 
+// ../shared/dist/update-info.js
+async function buildUpdateStatus(pkgName, currentVersion, options = {}) {
+  const base = { current: currentVersion, command: UPGRADE_COMMAND };
+  if (options.isDevBuild === true) {
+    return {
+      ...base,
+      latest: null,
+      updateAvailable: null,
+      note: "dev build (workspace) \u2014 version comparison skipped"
+    };
+  }
+  let latest = null;
+  try {
+    latest = await getLatestVersion(pkgName, {
+      ...options.env !== void 0 ? { env: options.env } : {},
+      ...options.fetch !== void 0 ? { fetch: options.fetch } : {},
+      ...options.cacheDir !== void 0 ? { cacheDir: options.cacheDir } : {},
+      timeoutMs: options.timeoutMs ?? 1500
+    });
+  } catch {
+    latest = null;
+  }
+  return {
+    ...base,
+    latest,
+    updateAvailable: latest !== null ? isNewerVersion(latest, currentVersion) : null
+  };
+}
+
 // ../shared/dist/workspace-root.js
 import { homedir as homedir2 } from "node:os";
 import { dirname, resolve } from "node:path";
@@ -194,10 +268,80 @@ function isHomeOrFilesystemRoot(root) {
   return false;
 }
 
+// ../shared/dist/heartbeat.js
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join2 } from "node:path";
+var DEFAULT_HEARTBEAT_INTERVAL_MS = 6e4;
+var STALE_AFTER_MS = 5 * 6e4;
+function defaultStatusDir(env = process.env) {
+  const override = (env.PROMETHEUS_STATUS_DIR ?? "").trim();
+  if (override !== "")
+    return override;
+  return join2(homedir3(), ".prometheus", "status");
+}
+function startHeartbeat(options) {
+  const dir = options.dir ?? defaultStatusDir(options.env ?? process.env);
+  const file = join2(dir, `${options.server}-${process.pid}.json`);
+  const intervalMs = options.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+  let record = {
+    server: options.server,
+    pid: process.pid,
+    version: options.version,
+    startedAt: Date.now(),
+    updatedAt: Date.now(),
+    workspaceRoot: options.workspaceRoot ?? null
+  };
+  let stopped = false;
+  const persist = () => {
+    if (stopped)
+      return;
+    try {
+      mkdirSync(dir, { recursive: true });
+      writeFileSync(file, JSON.stringify(record), "utf8");
+    } catch {
+    }
+  };
+  const remove = () => {
+    try {
+      rmSync(file, { force: true });
+    } catch {
+    }
+  };
+  persist();
+  const timer = setInterval(() => {
+    record = { ...record, updatedAt: Date.now() };
+    persist();
+  }, intervalMs);
+  timer.unref?.();
+  const onExit = () => {
+    stopped = true;
+    remove();
+  };
+  process.once("exit", onExit);
+  return {
+    file,
+    update(patch) {
+      if (stopped)
+        return;
+      record = { ...record, ...patch, updatedAt: Date.now() };
+      persist();
+    },
+    stop() {
+      if (stopped)
+        return;
+      stopped = true;
+      clearInterval(timer);
+      process.removeListener("exit", onExit);
+      remove();
+    }
+  };
+}
+
 // dist/composition.js
 import { createHash } from "node:crypto";
-import { homedir as homedir3 } from "node:os";
-import { basename, join as join2, resolve as resolve2 } from "node:path";
+import { homedir as homedir4 } from "node:os";
+import { basename, join as join3, resolve as resolve2 } from "node:path";
 
 // ../embeddings-openai-compat/dist/index.js
 var DEFAULT_BATCH = 96;
@@ -1445,7 +1589,7 @@ var OpenAICompatRewriter = class {
 
 // dist/sqlite.js
 import { randomUUID } from "node:crypto";
-import { mkdirSync } from "node:fs";
+import { mkdirSync as mkdirSync2 } from "node:fs";
 import { dirname as dirname2 } from "node:path";
 import Database from "better-sqlite3";
 
@@ -1773,7 +1917,7 @@ var SqliteMemoryBackend = class {
   closed = false;
   constructor(dbPath, opts = {}) {
     if (dbPath !== ":memory:") {
-      mkdirSync(dirname2(dbPath), { recursive: true });
+      mkdirSync2(dirname2(dbPath), { recursive: true });
     }
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
@@ -2226,7 +2370,7 @@ function projectIdFor(workspaceRoot) {
   return createHash("sha256").update(abs).digest("hex").slice(0, 16);
 }
 function defaultMemoryDbPath() {
-  return join2(homedir3(), ".prometheus", "memory.db");
+  return join3(homedir4(), ".prometheus", "memory.db");
 }
 function intEnv(env, name, def) {
   const raw = env[name];
@@ -2667,9 +2811,9 @@ function assertNoSecrets(text) {
 }
 
 // dist/setup.js
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname3, join as join4 } from "node:path";
+import { dirname as dirname3, join as join5 } from "node:path";
 var MEMORY_RUNTIMES = [
   "claude-code",
   "cursor",
@@ -2713,13 +2857,13 @@ alwaysApply: true
 var TARGETS = {
   "claude-code": { relPath: "CLAUDE.md", mode: "block", detect: "CLAUDE.md" },
   cursor: {
-    relPath: join4(".cursor", "rules", "prometheus-memory.mdc"),
+    relPath: join5(".cursor", "rules", "prometheus-memory.mdc"),
     mode: "file",
     fileContent: CURSOR_FRONTMATTER + withMarkers(RULE_BLOCK) + "\n",
     detect: ".cursor"
   },
   augment: {
-    relPath: join4(".augment", "rules", "prometheus-memory.md"),
+    relPath: join5(".augment", "rules", "prometheus-memory.md"),
     mode: "file",
     fileContent: withMarkers(RULE_BLOCK) + "\n",
     detect: ".augment"
@@ -2727,19 +2871,19 @@ var TARGETS = {
   agents: { relPath: "AGENTS.md", mode: "block", detect: "AGENTS.md" }
 };
 function detectRuntimes(workspaceRoot) {
-  const found = MEMORY_RUNTIMES.filter((rt) => existsSync(join4(workspaceRoot, TARGETS[rt].detect)));
+  const found = MEMORY_RUNTIMES.filter((rt) => existsSync(join5(workspaceRoot, TARGETS[rt].detect)));
   return found.length > 0 ? found : ["agents"];
 }
 function existingRuntimes(workspaceRoot) {
-  return MEMORY_RUNTIMES.filter((rt) => existsSync(join4(workspaceRoot, TARGETS[rt].detect)));
+  return MEMORY_RUNTIMES.filter((rt) => existsSync(join5(workspaceRoot, TARGETS[rt].detect)));
 }
 function installedRuntimes(workspaceRoot) {
   return MEMORY_RUNTIMES.filter((rt) => {
-    const p = join4(workspaceRoot, TARGETS[rt].relPath);
+    const p = join5(workspaceRoot, TARGETS[rt].relPath);
     if (!existsSync(p))
       return false;
     try {
-      return readFileSync(p, "utf-8").includes(BLOCK_START);
+      return readFileSync2(p, "utf-8").includes(BLOCK_START);
     } catch {
       return false;
     }
@@ -2764,7 +2908,7 @@ function upsertBlock(existing, block) {
 }
 async function installRuntime(workspaceRoot, runtime) {
   const target = TARGETS[runtime];
-  const absPath = join4(workspaceRoot, target.relPath);
+  const absPath = join5(workspaceRoot, target.relPath);
   const exists = existsSync(absPath);
   const before = exists ? await readFile3(absPath, "utf-8") : "";
   const after = target.mode === "file" ? target.fileContent : upsertBlock(before, RULE_BLOCK);
@@ -2930,9 +3074,19 @@ var setupInput = {
   runtimes: z.array(runtimeEnum).min(1).optional()
 };
 var emptyInput = {};
-function registerTools(server, source) {
+function registerTools(server, source, hooks = {}) {
   const ready = typeof source === "function" ? source : () => Promise.resolve(source);
-  server.registerTool("read", {
+  const onToolCall = hooks.onToolCall;
+  const reg = ((name, meta, handler) => server.registerTool(name, meta, (...callArgs) => {
+    if (onToolCall !== void 0) {
+      try {
+        onToolCall(name);
+      } catch {
+      }
+    }
+    return handler(...callArgs);
+  }));
+  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.",
     inputSchema: readInput
@@ -2955,7 +3109,7 @@ function registerTools(server, source) {
       records: records.map(recordToJson)
     });
   });
-  server.registerTool("write", {
+  reg("write", {
     title: "Store agent memory",
     description: "Upsert one memory record (identity: scope+type+key). Use type `semantic` for durable facts, `procedural` for how-to knowledge, `episodic` for session events, `working` for short-lived notes. Default scope `project` also mirrors the value to `.prometheus/memories/<key>.md` (git-versioned, human-editable). Values matching the secret deny-list are rejected. Call this whenever the user states a durable preference, decision, or correction worth remembering.",
     inputSchema: writeInput
@@ -2985,7 +3139,7 @@ ${args.value}`);
     }
     return textResult({ record: recordToJson(record), projectFile });
   });
-  server.registerTool("capture", {
+  reg("capture", {
     title: "Consolidate session learnings",
     description: "Session-end consolidation: `plan`/`outcome` become one episodic record (key = sessionId), `facts` become semantic upserts, `procedures` become procedural upserts. Secret-bearing payloads are rejected. Call this at the END of a session to persist what was learned.",
     inputSchema: captureInput
@@ -3049,7 +3203,7 @@ ${f.value}`);
     });
     return textResult({ written: written.map(recordToJson), extracted: extractedCount });
   });
-  server.registerTool("search", {
+  reg("search", {
     title: "Search agent memory",
     description: "Full-text search (FTS5) over memory keys and values within this project's scope chain, ranked by relevance. Returns matching records plus a highlighted snippet per hit. Use this when memory_read's recall is not specific enough. Does not bump useCount.",
     inputSchema: searchInput
@@ -3075,7 +3229,7 @@ ${f.value}`);
       }))
     });
   });
-  server.registerTool("list", {
+  reg("list", {
     title: "List stored memory (admin)",
     description: "Flat listing of this project's memory records without scope resolution \u2014 inspection/debug surface. Optional filters: scope, type, keyContains (case-insensitive substring).",
     inputSchema: listInput
@@ -3096,7 +3250,7 @@ ${f.value}`);
       records: records.map(recordToJson)
     });
   });
-  server.registerTool("delete", {
+  reg("delete", {
     title: "Delete stored memory",
     description: "Delete one memory record by identity (scope+type+key). For project-scoped semantic records the mirrored `.prometheus/memories/<key>.md` file is removed as well. Returns whether a record/file was actually removed.",
     inputSchema: deleteInput
@@ -3118,7 +3272,7 @@ ${f.value}`);
     }
     return textResult({ removed, fileRemoved });
   });
-  server.registerTool("setup", {
+  reg("setup", {
     title: "Install memory rules into runtime configs",
     description: "Idempotently install the Prometheus memory-protocol rule block into agent runtime configs in this workspace: CLAUDE.md (claude-code), .cursor/rules/prometheus-memory.mdc (cursor), .augment/rules/prometheus-memory.md (augment), AGENTS.md (agents). Without `runtimes` it auto-detects which runtimes are present (fallback: agents). Only the marked block is written \u2014 existing content is never touched. Re-running updates the block in place.",
     inputSchema: setupInput
@@ -3140,7 +3294,7 @@ ${f.value}`);
     }
     return textResult({ workspaceRoot, results });
   });
-  server.registerTool("status", {
+  reg("status", {
     title: "Memory status / health check",
     description: "Health check for this project's agent memory. Reports the resolved workspace root, project id, DB path, how many records are stored (total + by scope), the embedding provider with a zero-cost key-reachability probe, and which quality levers are active (rerank / rewrite / temporal). CALL THIS to confirm where memory is stored, how much is there, and whether the API key works.",
     inputSchema: emptyInput
@@ -3161,7 +3315,8 @@ ${f.value}`);
         embeddingsError = err instanceof Error ? err.message : String(err);
       }
     }
-    const summary = deps.rootIsHomeOrFsRoot ? `Memory at ${dbPath}: ${stats.total} records, but the workspace resolved to ${workspaceRoot} (home/root) \u2014 open a project folder so memories scope and mirror correctly.` : `Memory at ${dbPath}: ${stats.total} records for project "${projectName}".`;
+    const update = await buildUpdateStatus("@prom.codes/memory-mcp", "0.11.0", { isDevBuild: false });
+    const summary = deps.rootIsHomeOrFsRoot ? `Memory at ${dbPath}: ${stats.total} records, but the workspace resolved to ${workspaceRoot} (home/root) \u2014 open a project folder so memories scope and mirror correctly.` : `Memory at ${dbPath}: ${stats.total} records for project "${projectName}".${update.updateAvailable === true ? ` Update available: ${update.current} \u2192 ${update.latest} (ask me to run update via the context server's update_servers tool).` : ""}`;
     return textResult({
       installed: true,
       project: { id: projectId, name: projectName, workspaceRoot },
@@ -3187,6 +3342,7 @@ ${f.value}`);
         dedup: deps.dedupEnabled,
         extract: deps.extractorId
       },
+      update,
       summary
     });
   });
@@ -3195,7 +3351,7 @@ ${f.value}`);
 // dist/server.js
 var SERVER_IDENTITY = {
   name: "prometheus-memory-mcp",
-  version: "0.10.2",
+  version: "0.11.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.";
@@ -3211,6 +3367,11 @@ async function main() {
   const claudeRoot = (env.CLAUDE_PROJECT_DIR ?? "").trim();
   const eagerVia = explicitRoot !== "" ? "PROMETHEUS_WORKSPACE_ROOT" : claudeRoot !== "" ? "CLAUDE_PROJECT_DIR" : null;
   void maybeNotifyUpdate(import.meta.url, env);
+  const heartbeat = startHeartbeat({
+    server: "memory",
+    version: SERVER_IDENTITY.version,
+    env
+  });
   const transport = new StdioServerTransport();
   const server = new McpServer2(SERVER_IDENTITY, {
     capabilities: { tools: {} },
@@ -3221,10 +3382,17 @@ async function main() {
   const composedReady = new Promise((res) => {
     composedResolve = res;
   });
-  registerTools(server, () => composedReady);
-  const shutdown = async (signal) => {
-    process.stderr.write(`prometheus-memory-mcp: received ${signal}, shutting down
+  registerTools(server, () => composedReady, {
+    onToolCall: (tool) => heartbeat.update({ lastTool: tool, lastToolCallAt: Date.now() })
+  });
+  let shuttingDown = false;
+  const shutdown = async (reason) => {
+    if (shuttingDown)
+      return;
+    shuttingDown = true;
+    process.stderr.write(`prometheus-memory-mcp: ${reason}, shutting down
 `);
+    heartbeat.stop();
     try {
       await server.close();
     } finally {
@@ -3233,8 +3401,11 @@ async function main() {
       process.exit(0);
     }
   };
-  process.once("SIGINT", shutdown);
-  process.once("SIGTERM", shutdown);
+  process.once("SIGINT", () => void shutdown("received SIGINT"));
+  process.once("SIGTERM", () => void shutdown("received SIGTERM"));
+  process.stdin.once("end", () => void shutdown("stdin closed (client exited)"));
+  process.stdin.once("close", () => void shutdown("stdin closed (client exited)"));
+  server.server.onclose = () => void shutdown("transport closed (client exited)");
   const boot = (override, via) => {
     composed = composeFromEnv({
       env,
@@ -3242,6 +3413,15 @@ async function main() {
     });
     process.stderr.write(`prometheus-memory-mcp: workspace=${composed.workspaceRoot} (via ${via}) project=${composed.projectName} (${composed.projectId}) db=${composed.dbPath} embed=${composed.embedderId}${composed.embeddingsEnabled ? "" : " (keyword-only)"} rerank=${composed.rerankerId} extract=${composed.extractorId} rewrite=${composed.rewriterId} temporal=${composed.temporalEnabled ? "on" : "off"} dedup=${composed.dedupEnabled ? "on" : "off"}
 `);
+    heartbeat.update({
+      workspaceRoot: composed.workspaceRoot,
+      extra: {
+        dbPath: composed.dbPath,
+        projectId: composed.projectId,
+        projectName: composed.projectName,
+        embed: composed.embedderId
+      }
+    });
     if (composed.rootIsHomeOrFsRoot) {
       process.stderr.write(`prometheus-memory-mcp: workspace resolved to ${composed.workspaceRoot} (your home directory or a filesystem root) \u2014 project memories will NOT be mirrored to markdown there. Open a project folder (Claude Code passes it via CLAUDE_PROJECT_DIR) or set PROMETHEUS_WORKSPACE_ROOT. Call memory_status for details.
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prom.codes/memory-mcp",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "description": "prom.codes Memory — persistent, local-first agent memory as an MCP server.",
   "type": "module",
   "bin": {