codex-dev-mcp-suite 1.2.0 → 1.4.0

package/lib/stats.js

@@ -0,0 +1,269 @@
+/**
+ * Dev MCP Suite — stats aggregation library.
+ *
+ * Pure functions for summarizing local memory storage across the three stores
+ * (vault / journal / checkpoints). No MCP, no stdio — used by bin/stats.mjs
+ * and safe to import from tests.
+ *
+ * Storage layout assumed (see each MCP server's server.js for source of truth):
+ *   <root>/vault/<slug>/notes/*.md            (one .md per memory_save note)
+ *   <root>/journal/<slug>/journal.jsonl       (append-only entries)
+ *   <root>/journal/<slug>/handoff.json        (optional)
+ *   <root>/checkpoints/<slug>/snapshots/<id>/ (one dir per snapshot)
+ *   <root>/checkpoints/<slug>/manifest.json   (checkpoint index)
+ */
+
+import fs from "fs";
+import path from "path";
+
+const VAULT_DIRNAME = "vault";
+const JOURNAL_DIRNAME = "journal";
+const CHECKPOINT_DIRNAME = "checkpoints";
+
+function safeListDirs(parent) {
+  try {
+    return fs
+      .readdirSync(parent, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+  } catch {
+    return [];
+  }
+}
+
+function safeListFiles(parent) {
+  try {
+    return fs.readdirSync(parent);
+  } catch {
+    return [];
+  }
+}
+
+function newestMtimeMs(dir) {
+  try {
+    const stat = fs.statSync(dir);
+    return stat.mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function isoFromMs(ms) {
+  if (!ms) return null;
+  return new Date(ms).toISOString();
+}
+
+function isTempSlug(slug) {
+  return /^tmp\./.test(slug);
+}
+
+function summarizeProject(slug, { root }) {
+  const vaultDir = path.join(root, VAULT_DIRNAME, slug);
+  const journalDir = path.join(root, JOURNAL_DIRNAME, slug);
+  const cpDir = path.join(root, CHECKPOINT_DIRNAME, slug);
+
+  const notesDir = path.join(vaultDir, "notes");
+  const notes = safeListFiles(notesDir).filter((f) => f.endsWith(".md")).length;
+
+  let journalEntries = 0;
+  let lastEntryTs = null;
+  const jl = path.join(journalDir, "journal.jsonl");
+  if (fs.existsSync(jl)) {
+    try {
+      const lines = fs.readFileSync(jl, "utf8").split("\n").filter(Boolean);
+      journalEntries = lines.length;
+      // journal entries are append-only and roughly time-ordered; parse first + last
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line);
+          if (obj && obj.ts) {
+            if (!lastEntryTs || obj.ts > lastEntryTs) lastEntryTs = obj.ts;
+          }
+        } catch { /* skip malformed */ }
+      }
+    } catch { /* ignore read errors */ }
+  }
+
+  // checkpoints: count snapshot dirs
+  let checkpoints = 0;
+  const snapsDir = path.join(cpDir, "snapshots");
+  if (fs.existsSync(snapsDir)) {
+    checkpoints = safeListDirs(snapsDir).length;
+  }
+
+  // last activity across all artifacts (mtime fallback)
+  let lastActivityMs = 0;
+  for (const d of [vaultDir, journalDir, cpDir]) {
+    const m = newestMtimeMs(d);
+    if (m > lastActivityMs) lastActivityMs = m;
+  }
+  // prefer parsed entry ts if newer than filesystem mtime
+  if (lastEntryTs) {
+    const t = Date.parse(lastEntryTs);
+    if (!Number.isNaN(t) && t > lastActivityMs) lastActivityMs = t;
+  }
+  const lastActivityTs = isoFromMs(lastActivityMs);
+
+  return {
+    slug,
+    notes,
+    journalEntries,
+    checkpoints,
+    lastActivityTs,
+    temp: isTempSlug(slug),
+  };
+}
+
+/**
+ * Compute aggregate stats for a memory root.
+ * @param {object} opts
+ * @param {string} opts.root - absolute path to memories root (containing vault/, journal/, checkpoints/)
+ * @param {number} [opts.topLimit=10] - max entries in topByNotes / recentActivity
+ * @returns {{
+ *   root: string,
+ *   totals: { notes: number, journalProjects: number, checkpoints: number },
+ *   projectCount: number,
+ *   topByNotes: Array<{ slug: string, notes: number }>,
+ *   recentActivity: Array<{ slug: string, ts: string }>,
+ *   tempSlugs: string[],
+ *   perProject: Array<{ slug: string, notes: number, journalEntries: number, checkpoints: number, lastActivityTs: string|null, temp: boolean }>,
+ * }}
+ */
+export function computeStats({ root, topLimit = 10 } = {}) {
+  if (!root) throw new Error("computeStats: `root` is required");
+
+  // union of slugs across all three stores
+  const slugSet = new Set();
+  for (const store of [VAULT_DIRNAME, JOURNAL_DIRNAME, CHECKPOINT_DIRNAME]) {
+    for (const slug of safeListDirs(path.join(root, store))) slugSet.add(slug);
+  }
+
+  const perProject = [...slugSet]
+    .map((slug) => summarizeProject(slug, { root }))
+    .sort((a, b) => {
+      if (a.temp !== b.temp) return a.temp ? 1 : -1; // real first
+      return a.slug.localeCompare(b.slug);
+    });
+
+  const totals = perProject.reduce(
+    (acc, p) => ({
+      notes: acc.notes + p.notes,
+      journalProjects: acc.journalProjects + (p.journalEntries > 0 ? 1 : 0),
+      checkpoints: acc.checkpoints + p.checkpoints,
+    }),
+    { notes: 0, journalProjects: 0, checkpoints: 0 },
+  );
+
+  const topByNotes = [...perProject]
+    .filter((p) => p.notes > 0)
+    .sort((a, b) => b.notes - a.notes || a.slug.localeCompare(b.slug))
+    .slice(0, topLimit)
+    .map((p) => ({ slug: p.slug, notes: p.notes }));
+
+  const recentActivity = [...perProject]
+    .filter((p) => p.lastActivityTs && !p.temp)
+    .sort((a, b) => (a.lastActivityTs < b.lastActivityTs ? 1 : -1))
+    .slice(0, topLimit)
+    .map((p) => ({ slug: p.slug, ts: p.lastActivityTs }));
+
+  const tempSlugs = perProject.filter((p) => p.temp).map((p) => p.slug).sort();
+
+  return {
+    root,
+    totals,
+    projectCount: perProject.length,
+    topByNotes,
+    recentActivity,
+    tempSlugs,
+    perProject,
+  };
+}
+
+/** Right-pad a slug to a fixed display width. */
+function pad(s, w) {
+  s = String(s);
+  if (s.length >= w) return s + " ";
+  return s + " ".repeat(w - s.length);
+}
+function rpadNum(n, w) {
+  const s = String(n);
+  return s.length >= w ? s : " ".repeat(w - s.length) + s;
+}
+
+function formatLocal(ts) {
+  if (!ts) return "—";
+  try {
+    return new Date(ts).toISOString().replace("T", " ").replace(/\.\d+Z$/, "Z");
+  } catch {
+    return ts;
+  }
+}
+
+/**
+ * Human-readable text summary.
+ * @param {ReturnType<typeof computeStats>} stats
+ * @param {object} [opts]
+ * @param {string} [opts.timezone="UTC"] - display-only label, not used to convert
+ */
+export function formatText(stats, opts = {}) {
+  const lines = [];
+  lines.push("Dev MCP Suite — stats");
+  lines.push("======================");
+  lines.push(`Storage root: ${stats.root}`);
+  lines.push("");
+  lines.push("Totals");
+  lines.push("------");
+  lines.push(`  Notes:           ${stats.totals.notes}`);
+  lines.push(`  Journal projects:${rpadNum(stats.totals.journalProjects, 2)}`);
+  lines.push(`  Checkpoints:     ${stats.totals.checkpoints}`);
+  lines.push(`  Distinct projects: ${stats.projectCount}`);
+  lines.push("");
+
+  if (stats.topByNotes.length) {
+    lines.push(`Top projects by notes (top ${stats.topByNotes.length})`);
+    lines.push("------------------------");
+    const slugW = Math.max(8, ...stats.topByNotes.map((p) => p.slug.length));
+    for (const p of stats.topByNotes) {
+      lines.push(`  ${rpadNum(p.notes, 4)}  ${pad(p.slug, slugW)}`);
+    }
+    lines.push("");
+  }
+
+  if (stats.recentActivity.length) {
+    lines.push("Most recent activity");
+    lines.push("--------------------");
+    const slugW = Math.max(8, ...stats.recentActivity.map((p) => p.slug.length));
+    for (const p of stats.recentActivity) {
+      lines.push(`  ${pad(p.slug, slugW)} ${formatLocal(p.ts)}`);
+    }
+    lines.push("");
+  }
+
+  if (stats.tempSlugs.length) {
+    lines.push(`Temp/cleanup candidates (${stats.tempSlugs.length})`);
+    lines.push("------------------------");
+    for (const slug of stats.tempSlugs) lines.push(`  ${slug}`);
+    lines.push("");
+  } else {
+    lines.push("Temp/cleanup candidates: none");
+    lines.push("");
+  }
+
+  lines.push(`Generated at ${new Date().toISOString()}`);
+  return lines.join("\n");
+}
+
+/** Stable JSON serialization (sorted keys for top-level + totals). */
+export function formatJson(stats) {
+  const out = {
+    root: stats.root,
+    totals: stats.totals,
+    projectCount: stats.projectCount,
+    topByNotes: stats.topByNotes,
+    recentActivity: stats.recentActivity,
+    tempSlugs: stats.tempSlugs,
+    perProject: stats.perProject,
+    generatedAt: new Date().toISOString(),
+  };
+  return JSON.stringify(out, null, 2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-dev-mcp-suite",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "Four local, file-based MCP servers for solo devs/vibecoders: persistent project memory, session handoff/resume, git-independent file checkpoints, and token-efficient project briefings. Works with any MCP client.",
   "type": "module",
   "license": "MIT",
@@ -32,10 +32,14 @@
     "project-memory-mcp": "bin/project-memory.mjs",
     "devjournal-mcp": "bin/devjournal.mjs",
     "checkpoint-mcp": "bin/checkpoint.mjs",
-    "context-pack-mcp": "bin/context-pack.mjs"
+    "context-pack-mcp": "bin/context-pack.mjs",
+    "stats": "bin/stats.mjs",
+    "prune": "bin/prune.mjs",
+    "provider-smoke": "bin/provider-smoke.mjs"
   },
   "scripts": {
-    "test": "node run-tests.mjs"
+    "test": "node run-tests.mjs",
+    "test:stats": "node tests/stats.test.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0"
@@ -70,6 +74,7 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
-    ".env.example"
+    ".env.example",
+    "lib/*.js"
   ]
 }

package/project-memory/embedding.js

@@ -1,47 +1,96 @@
 /**
- * Embedding helper for any OpenAI-compatible /v1/embeddings endpoint.
- * Degrades gracefully: returns null on any failure so callers fall back
+ * Embedding helper for any OpenAI-compatible /v1/embeddings endpoint,
+ * with first-class support for Cloudflare Workers AI (REST-only, non-OpenAI).
+ *
+ * Degrades gracefully: returns null/[] on any failure so callers fall back
  * to keyword search. Never throws.
+ *
+ * Endpoint formats:
+ *  - OpenAI-compatible:  POST {base}/v1/embeddings   body: {model, input:[...]}
+ *                        response: {data:[{embedding:[...], index}]}
+ *  - Cloudflare Workers: POST {base}/{model}          body: {text:[...]}
+ *                        response: {result:{data:[[...]], shape:[n,dim]}}
+ *
+ * Cloudflare is auto-detected by URL pattern (contains "api.cloudflare.com/client/v4/accounts").
+ * To use it: set MCP_EMBED_BASE_URL=https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/run/
+ * and MCP_EMBED_MODEL=@cf/baai/bge-base-en-v1.5
  */
 import http from "http";
 import https from "https";
 import { URL } from "url";
 import { deterministicEnabled } from "./env.js";
 
-const BASE = process.env.MCP_EMBED_BASE_URL || process.env.MCP_LLM_BASE_URL || process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128";
-const KEY = process.env.MCP_EMBED_API_KEY || process.env.MCP_LLM_API_KEY || process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "";
-const MODEL = process.env.MCP_EMBED_MODEL || process.env.EMBED_MODEL || "bm/baai/bge-m3";
-const TIMEOUT_MS = Number(process.env.EMBED_TIMEOUT_MS || 15000);
+/** Read env at runtime (not module-load time) so tests can override and config is dynamic). */
+function readEnv() {
+  return {
+    base: process.env.MCP_EMBED_BASE_URL || process.env.MCP_LLM_BASE_URL || process.env.LLM_BASE_URL || process.env.EMBED_URL || process.env.NINEROUTER_URL || "http://localhost:20128",
+    key: process.env.MCP_EMBED_API_KEY || process.env.MCP_LLM_API_KEY || process.env.LLM_API_KEY || process.env.EMBED_KEY || process.env.NINEROUTER_KEY || "",
+    model: process.env.MCP_EMBED_MODEL || process.env.EMBED_MODEL || "bm/baai/bge-m3",
+    timeoutMs: Number(process.env.EMBED_TIMEOUT_MS || 15000),
+  };
+}
+
+/**
+ * Resolve what retrieval mode memory_recall will use, given current env.
+ * Returns one of: "deterministic" | "semantic" | "keyword".
+ * Independent of MCP_RERANK_ENABLED (rerank layers on top of either).
+ */
+export function recallMode() {
+  if (deterministicEnabled()) return "deterministic";
+  const { key } = readEnv();
+  return key ? "semantic" : "keyword";
+}
 
 export function embeddingConfig() {
-  return { base: BASE, model: MODEL, enabled: Boolean(KEY) && !deterministicEnabled(), deterministic: deterministicEnabled() };
+  const { base, key, model } = readEnv();
+  return {
+    base,
+    model,
+    enabled: Boolean(key) && !deterministicEnabled(),
+    deterministic: deterministicEnabled(),
+    endpoint: isCloudflareURL(base) ? "cloudflare" : "openai-compatible",
+    mode: recallMode(),
+  };
 }
 
-function postJson(urlStr, payload) {
+/** Detect Cloudflare Workers AI by URL pattern. */
+export function isCloudflareURL(urlStr) {
+  return typeof urlStr === "string" && urlStr.includes("api.cloudflare.com/client/v4/accounts");
+}
+
+/**
+ * POST a JSON body to an absolute URL with Bearer auth. Returns:
+ *   { status: 200, body: <parsed JSON> } on success
+ *   { status: <code>, body: <raw text> } on non-200
+ *   null on network/timeout/parse error
+ * Caller is responsible for building the full URL (we don't append /v1/embeddings etc).
+ */
+function httpPostJson(urlStr, payload) {
   return new Promise((resolve) => {
     let u;
-    try { u = new URL("/v1/embeddings", urlStr); } catch { return resolve(null); }
+    try { u = new URL(urlStr); } catch { return resolve(null); }
     const data = Buffer.from(JSON.stringify(payload));
+    const { key, timeoutMs } = readEnv();
     const lib = u.protocol === "https:" ? https : http;
     const req = lib.request(
       {
         hostname: u.hostname,
         port: u.port || (u.protocol === "https:" ? 443 : 80),
-        path: u.pathname,
+        path: u.pathname + (u.search || ""),
         method: "POST",
         headers: {
           "Content-Type": "application/json",
           "Content-Length": data.length,
-          Authorization: `Bearer ${KEY}`,
+          ...(key ? { Authorization: `Bearer ${key}` } : {}),
         },
-        timeout: TIMEOUT_MS,
+        timeout: timeoutMs,
       },
       (res) => {
         let body = "";
         res.on("data", (c) => (body += c));
         res.on("end", () => {
-          if (res.statusCode !== 200) return resolve(null);
-          try { resolve(JSON.parse(body)); } catch { resolve(null); }
+          if (res.statusCode !== 200) return resolve({ status: res.statusCode, body });
+          try { resolve({ status: 200, body: JSON.parse(body) }); } catch { resolve({ status: res.statusCode, body }); }
         });
       }
     );
@@ -52,30 +101,59 @@ function postJson(urlStr, payload) {
   });
 }
 
-/** Returns array of vectors aligned to inputs, or null if unavailable. */
+async function embedOpenAI(inputs) {
+  const { base, key, model } = readEnv();
+  if (!key) return [];
+  try {
+    const res = await httpPostJson(`${base.replace(/\/$/, "")}/v1/embeddings`, { model, input: inputs });
+    if (!res || res.status !== 200 || !res.body || !Array.isArray(res.body.data)) return [];
+    const json = res.body;
+    const sorted = [...json.data].sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
+    return sorted.map((d) => d.embedding).filter(Boolean);
+  } catch { return []; }
+}
+
+async function embedCloudflare(inputs) {
+  const { base: rawBase, key, model } = readEnv();
+  if (!key) return [];
+  // Cloudflare: model is in URL path; do NOT URL-encode ("@" and "/" must stay literal).
+  const base = rawBase.replace(/\/$/, "");
+  const url = `${base}/${model}`;
+  try {
+    const res = await httpPostJson(url, { text: inputs });
+    if (!res || res.status !== 200 || !res.body || !res.body.result) return [];
+    const data = res.body.result.data;
+    if (!Array.isArray(data)) return [];
+    return data.filter((v) => Array.isArray(v));
+  } catch { return []; }
+}
+
+/**
+ * Embed an array of strings (or a single string) and return an array of
+ * numeric vectors. Returns [] when no API key is configured, deterministic
+ * mode is on, or the endpoint fails.
+ */
 export async function embed(inputs) {
-  if (!KEY || deterministicEnabled()) return null;
+  if (deterministicEnabled()) return [];
+  const { base, key } = readEnv();
+  if (!key) return [];
   const arr = Array.isArray(inputs) ? inputs : [inputs];
-  if (arr.length === 0) return [];
-  const json = await postJson(BASE, { model: MODEL, input: arr });
-  if (!json || !Array.isArray(json.data)) return null;
-  try {
-    const sorted = json.data.slice().sort((a, b) => (a.index ?? 0) - (b.index ?? 0));
-    const vecs = sorted.map((d) => d.embedding);
-    if (vecs.some((v) => !Array.isArray(v) || v.length === 0)) return null;
-    return vecs;
-  } catch { return null; }
+  if (isCloudflareURL(base)) return await embedCloudflare(arr);
+  return await embedOpenAI(arr);
 }
 
 export async function embedOne(text) {
   const v = await embed([text]);
-  return v ? v[0] : null;
+  return v[0] || null;
 }
 
 export function cosine(a, b) {
-  if (!a || !b || a.length !== b.length) return 0;
+  if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return 0;
   let dot = 0, na = 0, nb = 0;
-  for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; na += a[i] * a[i]; nb += b[i] * b[i]; }
-  if (na === 0 || nb === 0) return 0;
-  return dot / (Math.sqrt(na) * Math.sqrt(nb));
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i], y = b[i];
+    dot += x * y; na += x * x; nb += y * y;
+  }
+  const denom = Math.sqrt(na) * Math.sqrt(nb);
+  return denom === 0 ? 0 : dot / denom;
 }

package/project-memory/server.js

@@ -29,6 +29,7 @@ import crypto from "crypto";
 import { embed, embedOne, cosine, embeddingConfig } from "./embedding.js";
 import { rerank, rerankConfig } from "./rerank.js";
 import { deterministicEnabled } from "./env.js";
+import { computeStats, formatText, formatJson } from "../lib/stats.js";
 
 const VAULT_ROOT =
   process.env.MEMORY_VAULT_DIR ||
@@ -162,7 +163,7 @@ class ProjectMemoryServer {
         {
           name: "memory_recall",
           description:
-            "Retrieve the most relevant saved notes for a query using the keyword index. Call this at the start of a new session instead of re-pasting context.",
+            "Retrieve the most relevant saved notes for a query. Falls back gracefully: semantic -> keyword -> LLM rerank. Set mode to control behavior: 'auto' (default), 'semantic' (require embedding), 'keyword' (skip embedding).",
           inputSchema: {
             type: "object",
             properties: {
@@ -170,6 +171,7 @@ class ProjectMemoryServer {
               dir: { type: "string", description: "Project directory (defaults to CWD)" },
               limit: { type: "number", description: "Max notes to return", default: 5 },
               full: { type: "boolean", description: "Return full bodies instead of excerpts", default: false },
+              mode: { type: "string", enum: ["auto", "semantic", "keyword"], default: "auto", description: "Retrieval mode: 'auto' (default, smart fallback), 'semantic' (require embedding), 'keyword' (skip embedding)" },
             },
             required: ["query"],
           },
@@ -220,6 +222,18 @@ class ProjectMemoryServer {
             },
           },
         },
+        {
+          name: "memory_stats",
+          description: "Summarize local memory storage across vault / journal / checkpoints: totals, top projects, recent activity, and temp-slug cleanup candidates. Returns the same text as the `stats` CLI.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              root: { type: "string", description: "Storage root (default: ~/.codex/memories or first env var of MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)" },
+              top: { type: "number", description: "How many entries in top-project / recent-activity lists (default 10)", default: 10 },
+              json: { type: "boolean", description: "Return machine-readable JSON instead of human text", default: false },
+            },
+          },
+        },
       ],
     }));
 
@@ -233,6 +247,7 @@ class ProjectMemoryServer {
           case "memory_get": return await this.get(args || {});
           case "memory_delete": return await this.del(args || {});
           case "memory_reindex": return await this.reindex(args || {});
+          case "memory_stats": return await this.stats(args || {});
           default: throw new Error(`Unknown tool: ${name}`);
         }
       } catch (error) {
@@ -302,7 +317,7 @@ class ProjectMemoryServer {
     return { content: [{ type: "text", text: `Saved note ${id} → ${p.slug}\nFile: ${file}\nKeywords indexed: ${keywords.length}${embedded ? " (semantic embedding stored)" : " (keyword-only; embeddings unavailable)"}` }] };
   }
 
-  async recall({ query, dir, limit: lim = 5, full = false }) {
+  async recall({ query, dir, limit: lim = 5, full = false, mode: requestedMode = "auto" }) {
     query = limit(query, "query", 2000);
     const p = this.paths(dir);
     const index = await this.loadIndex(p);
@@ -319,10 +334,17 @@ class ProjectMemoryServer {
       return score;
     };
 
+    // Tier 2.1: respect requested mode. "auto" = smart fallback.
     let mode = deterministicEnabled() ? "deterministic" : "keyword";
-    const qVec = deterministicEnabled() ? null : await embedOne(query);
+    const useEmbed = requestedMode !== "keyword" && !deterministicEnabled();
+    const qVec = useEmbed ? await embedOne(query) : null;
     const haveEmb = qVec && notes.some((n) => Array.isArray(n.embedding));
 
+    // Tier 2.1: "semantic" requested but unavailable -> error
+    if (requestedMode === "semantic" && !haveEmb) {
+      return { content: [{ type: "text", text: `memory_recall(mode=semantic) requested but no embeddings available. Set MCP_EMBED_API_KEY + MCP_EMBED_MODEL, or omit mode for keyword fallback.` }], isError: true };
+    }
+
     let scored;
     if (haveEmb) {
       mode = "semantic";
@@ -381,7 +403,12 @@ class ProjectMemoryServer {
       const tag = mode === "semantic" ? `sim:${(sim ?? 0).toFixed(3)}` : (mode === "rerank" ? "llm-ranked" : `score:${score}`);
       blocks.push(`### ${n.title}  (id:${n.id}, ${tag}, ${n.created})\n${text}`);
     }
-    return { content: [{ type: "text", text: `Recall for "${query}" in ${p.slug} [${mode}]:\n\n${blocks.join("\n\n---\n\n")}` }] };
+    // Tier 2.2: annotate mode with rerank indicator
+    const isReranked = rerankConfig().enabled && blocks.length > 1;
+    const displayMode = mode === "semantic" && isReranked ? "semantic+rerank"
+      : mode === "keyword" && isReranked ? "keyword+rerank"
+      : mode;
+    return { content: [{ type: "text", text: `Recall for "${query}" in ${p.slug} [${displayMode}]:\n\n${blocks.join("\n\n---\n\n")}` }] };
   }
 
   async list({ dir, limit: lim = 20 }) {
@@ -439,6 +466,21 @@ class ProjectMemoryServer {
     return { content: [{ type: "text", text: `Reindex ${p.slug}: embedded ${done}, failed ${failed} (embeddings ${embeddingConfig().enabled ? "configured" : "not configured"}). ${failed ? "Failures usually mean the embedding model is unavailable right now." : ""}` }] };
   }
 
+  async stats({ root: explicitRoot, top = 10, json = false } = {}) {
+    const root = explicitRoot
+      ? path.resolve(explicitRoot)
+      : (process.env.MEMORY_VAULT_DIR
+          ? path.dirname(process.env.MEMORY_VAULT_DIR)
+          : process.env.JOURNAL_DIR
+            ? path.dirname(process.env.JOURNAL_DIR)
+            : process.env.CHECKPOINT_DIR
+              ? path.dirname(process.env.CHECKPOINT_DIR)
+              : path.join(os.homedir(), ".codex", "memories"));
+    const stats = computeStats({ root, topLimit: top });
+    const text = json ? formatJson(stats) : formatText(stats);
+    return { content: [{ type: "text", text }] };
+  }
+
   async run() {
     const transport = new StdioServerTransport();
     await this.server.connect(transport);