@prom.codes/memory-mcp 0.7.1 → 0.7.3

package/README.md

@@ -7,45 +7,52 @@ procedures survive context-window resets. Records live in a local SQLite
 database (`~/.prometheus/memory.db`); project-scoped memories are mirrored
 as git-versioned markdown under `.prometheus/memories/` in your repo.
 
-## Quick start
-
-```jsonc
-// Claude Desktop / Cursor MCP config — dock under the server name `memory`
-// so the tools resolve to memory_read / memory_write / … (no double prefix).
-{
-  "mcpServers": {
-    "memory": {
-      "command": "npx",
-      "args": ["-y", "@prom.codes/memory-mcp@latest"],
-      "env": {
-        "PROMETHEUS_WORKSPACE_ROOT": "/absolute/path/to/your/repo",
-        "VOYAGE_API_KEY": "pa-…  // optional: enables semantic recall (search)"
-      }
-    }
-  }
-}
-```
+## Quick start (Claude Code)
 
-No API key is required to start: the server boots in keyword mode out of the
-box. Add a `VOYAGE_API_KEY` for semantic search (embeddings run Voyage-direct,
-fully local — only the memory text transits to Voyage), or a `prom_live_…`
-`PROMETHEUS_API_KEY` to route embeddings through the metered Prometheus proxy.
+```bash
+claude mcp add memory --env PROMETHEUS_API_KEY=prom_live_… -- npx -y @prom.codes/memory-mcp@latest
+```
 
-Then ask your agent to run `memory_setup` once per workspace — it installs
-the memory protocol into your runtime rule files (CLAUDE.md, .cursor/rules,
-.augment/rules or AGENTS.md) so the agent reads memory at session start and
-captures learnings at session end.
+Docks under the server name `memory`, so tools resolve to `memory_read` /
+`memory_write` / … `claude mcp add` defaults to local scope; add
+`--scope project` for a committable `.mcp.json`. Other hosts (Cursor, VS Code)
+use the same command/args in their own config.
+
+Then ask your agent to run `memory_setup` once per workspace — it installs the
+memory protocol into your runtime rule files (CLAUDE.md, .cursor/rules,
+AGENTS.md) so the agent reads memory at session start and captures learnings at
+session end.
+
+## Configuration
+
+- **Works with no key at all** — boots keyword-only (FTS5) and fully offline. A
+  `PROMETHEUS_API_KEY` (real `prom_live_<tag>_<secret>` from
+  [app.prom.codes/app/api-keys](https://app.prom.codes)) adds **semantic** recall
+  via the managed proxy — the same one key as Context and Saver.
+- **Workspace root is auto-detected** (Claude Code `CLAUDE_PROJECT_DIR` / MCP
+  `roots`) — no need to set `PROMETHEUS_WORKSPACE_ROOT`.
+- **Optional quality levers** (documented): `PROMETHEUS_MEMORY_RERANK_PROVIDER`
+  (cross-encoder rerank — reranked recall ties full-context at ~28× fewer tokens
+  on LoCoMo) and `PROMETHEUS_MEMORY_REWRITE_PROVIDER` (HyDE). Temporal-intent
+  ranking ("latest/earliest" queries) is **on by default**; disable with
+  `PROMETHEUS_MEMORY_TEMPORAL=off`.
+
+If a fresh window opens with no project, the workspace falls back to the host
+cwd (often home); in that case memory still works but project memories are NOT
+mirrored to markdown there and `memory_setup` refuses to write rule files into
+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`. Secrets are
-rejected on every write. Your memories never leave your machine.
+`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).
 
 ## Native modules
 
 Uses `better-sqlite3` (native). Prebuilt binaries are fetched automatically on
 common platforms (macOS x64/arm64, Linux x64/arm64, Windows x64) — no compiler
 needed. On an unsupported platform/Node ABI, install C/C++ build tools so the
-module can compile (Windows: `npm i -g windows-build-tools` or VS Build Tools).
-Requires Node ≥ 20.10.
+module can compile (Windows: VS Build Tools). Requires Node ≥ 20.10.
 
-Docs: https://prom.codes/docs
+Docs: https://prom.codes/docs/mcp/memory

package/dist/bin.js

@@ -180,13 +180,27 @@ function notify(log, name, current, latest) {
 `);
 }
 
+// ../shared/dist/workspace-root.js
+import { homedir as homedir2 } from "node:os";
+import { dirname, resolve } from "node:path";
+function isHomeOrFilesystemRoot(root) {
+  const abs = resolve(root);
+  if (abs === "")
+    return true;
+  if (abs === resolve(homedir2()))
+    return true;
+  if (dirname(abs) === abs)
+    return true;
+  return false;
+}
+
 // ../shared/dist/index.js
 var PROMETHEUS_VERSION = "0.1.0";
 
 // dist/composition.js
 import { createHash } from "node:crypto";
-import { homedir as homedir2 } from "node:os";
-import { basename, join as join2, resolve } from "node:path";
+import { homedir as homedir3 } from "node:os";
+import { basename, join as join2, resolve as resolve2 } from "node:path";
 
 // ../embeddings-openai-compat/dist/index.js
 var DEFAULT_BATCH = 96;
@@ -217,14 +231,14 @@ function parseRetryAfterMs(value, now = Date.now()) {
   return delta > 0 ? delta : 0;
 }
 function sleep(ms, signal) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve2();
+      resolve3();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -466,14 +480,14 @@ var DEFAULT_BATCH_CHARS = 4e5;
 var DEFAULT_RETRIES2 = 4;
 var DEFAULT_BACKOFF2 = 250;
 function sleep2(ms, signal) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve2();
+      resolve3();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -713,14 +727,14 @@ function parseRetryAfterMs2(value, now = Date.now()) {
   return delta > 0 ? delta : 0;
 }
 function sleep3(ms, signal) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve2();
+      resolve3();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -885,14 +899,14 @@ function parseRetryAfterMs3(value, now = Date.now()) {
   return delta > 0 ? delta : 0;
 }
 function sleep4(ms, signal) {
-  return new Promise((resolve2, reject) => {
+  return new Promise((resolve3, reject) => {
     if (signal?.aborted === true) {
       reject(new Error("aborted"));
       return;
     }
     const timer = setTimeout(() => {
       signal?.removeEventListener("abort", onAbort);
-      resolve2();
+      resolve3();
     }, ms);
     const onAbort = () => {
       clearTimeout(timer);
@@ -1254,7 +1268,7 @@ var OpenAICompatRewriter = class {
 // dist/sqlite.js
 import { randomUUID } from "node:crypto";
 import { mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname as dirname2 } from "node:path";
 import Database from "better-sqlite3";
 
 // dist/rrf.js
@@ -1526,7 +1540,7 @@ var SqliteMemoryBackend = class {
   closed = false;
   constructor(dbPath, opts = {}) {
     if (dbPath !== ":memory:") {
-      mkdirSync(dirname(dbPath), { recursive: true });
+      mkdirSync(dirname2(dbPath), { recursive: true });
     }
     this.db = new Database(dbPath);
     this.db.pragma("journal_mode = WAL");
@@ -1870,6 +1884,16 @@ ${h.record.value}`
     this.audit("delete", input, result.changes > 0 ? "removed" : "no-op");
     return result.changes > 0;
   }
+  async stats(projectId) {
+    const rows = this.db.prepare(`SELECT scope, COUNT(*) AS n FROM agent_memory WHERE project_id = ? GROUP BY scope`).all(projectId);
+    let total = 0;
+    const byScope = {};
+    for (const r of rows) {
+      byScope[r.scope] = r.n;
+      total += r.n;
+    }
+    return { total, byScope };
+  }
   async consolidate(input) {
     const written = [];
     if (input.plan || input.outcome) {
@@ -1926,11 +1950,11 @@ ${h.record.value}`
 
 // dist/composition.js
 function projectIdFor(workspaceRoot) {
-  const abs = resolve(workspaceRoot);
+  const abs = resolve2(workspaceRoot);
   return createHash("sha256").update(abs).digest("hex").slice(0, 16);
 }
 function defaultMemoryDbPath() {
-  return join2(homedir2(), ".prometheus", "memory.db");
+  return join2(homedir3(), ".prometheus", "memory.db");
 }
 function intEnv(env, name, def) {
   const raw = env[name];
@@ -2149,7 +2173,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 = resolve(override !== "" ? override : envRoot !== "" ? envRoot : claudeRoot !== "" ? claudeRoot : process.cwd());
+  const workspaceRoot = resolve2(override !== "" ? override : envRoot !== "" ? envRoot : claudeRoot !== "" ? claudeRoot : process.cwd());
   const projectId = projectIdFor(workspaceRoot);
   const projectName = basename(workspaceRoot) || workspaceRoot;
   const rawDbPath = env.PROMETHEUS_MEMORY_DB_PATH;
@@ -2173,6 +2197,7 @@ function composeFromEnv(opts) {
     dbPath,
     embeddingsEnabled: embedder !== void 0,
     embedderId,
+    embedder,
     reranker,
     rerankerId,
     extractor,
@@ -2180,6 +2205,7 @@ function composeFromEnv(opts) {
     rewriter,
     rewriterId,
     temporalEnabled: temporal.enabled,
+    rootIsHomeOrFsRoot: isHomeOrFilesystemRoot(workspaceRoot),
     close: () => backend.close()
   };
 }
@@ -2338,7 +2364,7 @@ function assertNoSecrets(text) {
 // dist/setup.js
 import { existsSync } from "node:fs";
 import { mkdir as mkdir3, readFile as readFile3, writeFile as writeFile3 } from "node:fs/promises";
-import { dirname as dirname2, join as join4 } from "node:path";
+import { dirname as dirname3, join as join4 } from "node:path";
 var MEMORY_RUNTIMES = [
   "claude-code",
   "cursor",
@@ -2418,7 +2444,7 @@ async function installRuntime(workspaceRoot, runtime) {
   if (exists && before === after) {
     return { runtime, path: absPath, action: "unchanged" };
   }
-  await mkdir3(dirname2(absPath), { recursive: true });
+  await mkdir3(dirname3(absPath), { recursive: true });
   await writeFile3(absPath, after, "utf-8");
   return { runtime, path: absPath, action: exists ? "updated" : "created" };
 }
@@ -2576,15 +2602,17 @@ var runtimeEnum = z.enum(MEMORY_RUNTIMES);
 var setupInput = {
   runtimes: z.array(runtimeEnum).min(1).optional()
 };
+var emptyInput = {};
 function registerTools(server, deps) {
   const { backend, workspaceRoot, projectId, projectName, dbPath, extractor } = deps;
+  const mirrorToFiles = !deps.rootIsHomeOrFsRoot;
   server.registerTool("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
   }, async (args) => {
     const limit = clampLimit(args.limit, DEFAULT_READ_LIMIT);
-    const synced = await syncProjectFiles(backend, { projectId, workspaceRoot });
+    const synced = mirrorToFiles ? await syncProjectFiles(backend, { projectId, workspaceRoot }) : 0;
     const records = await backend.read({
       chain: defaultScopeChain(projectId),
       types: args.types,
@@ -2620,7 +2648,7 @@ ${args.value}`);
       source: "user"
     });
     let projectFile = null;
-    if (scope === "project" && args.type === "semantic") {
+    if (mirrorToFiles && scope === "project" && args.type === "semantic") {
       projectFile = await writeProjectFile(workspaceRoot, args.key, args.value);
     }
     return textResult({ record: recordToJson(record), projectFile });
@@ -2694,7 +2722,8 @@ ${f.value}`);
     inputSchema: searchInput
   }, async (args) => {
     const limit = clampLimit(args.limit, 20);
-    await syncProjectFiles(backend, { projectId, workspaceRoot });
+    if (mirrorToFiles)
+      await syncProjectFiles(backend, { projectId, workspaceRoot });
     const hits = await backend.search({
       chain: defaultScopeChain(projectId),
       query: args.query,
@@ -2744,7 +2773,7 @@ ${f.value}`);
       key: args.key
     });
     let fileRemoved = false;
-    if (scope === "project" && args.type === "semantic") {
+    if (mirrorToFiles && scope === "project" && args.type === "semantic") {
       fileRemoved = await deleteProjectFile(workspaceRoot, args.key);
     }
     return textResult({ removed, fileRemoved });
@@ -2754,6 +2783,13 @@ ${f.value}`);
     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
   }, async (args) => {
+    if (!mirrorToFiles) {
+      return textResult({
+        workspaceRoot,
+        installed: false,
+        reason: "Workspace resolved to your home directory or a filesystem root \u2014 refusing to write rule files there. Open your project folder (Claude Code passes it via CLAUDE_PROJECT_DIR) or set PROMETHEUS_WORKSPACE_ROOT, then retry."
+      });
+    }
     const runtimes = args.runtimes ?? detectRuntimes(workspaceRoot);
     const results = [];
     for (const runtime of runtimes) {
@@ -2761,6 +2797,46 @@ ${f.value}`);
     }
     return textResult({ workspaceRoot, results });
   });
+  server.registerTool("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
+  }, async () => {
+    const stats = await backend.stats(projectId);
+    let embeddingsReachable = null;
+    let embeddingsError = null;
+    const resolveIdentity = deps.embedder?.resolveIdentity;
+    if (deps.embeddingsEnabled && typeof resolveIdentity === "function") {
+      try {
+        await resolveIdentity.call(deps.embedder);
+        embeddingsReachable = true;
+      } catch (err) {
+        embeddingsReachable = false;
+        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}".`;
+    return textResult({
+      installed: true,
+      project: { id: projectId, name: projectName, workspaceRoot },
+      rootIsHomeOrFsRoot: deps.rootIsHomeOrFsRoot,
+      storage: { dbPath, projectFileMirror: mirrorToFiles },
+      records: { total: stats.total, byScope: stats.byScope },
+      embeddings: {
+        enabled: deps.embeddingsEnabled,
+        provider: deps.embedderId,
+        reachable: embeddingsReachable,
+        ...embeddingsError !== null ? { error: embeddingsError } : {}
+      },
+      levers: {
+        rerank: deps.rerankerId,
+        rewrite: deps.rewriterId,
+        temporal: deps.temporalEnabled,
+        extract: deps.extractorId
+      },
+      summary
+    });
+  });
 }
 
 // dist/server.js
@@ -2808,6 +2884,10 @@ 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"}
 `);
+    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.
+`);
+    }
     registerTools(server, composed);
   };
   if (eagerVia !== null) {

package/package.json

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