codex-dev-mcp-suite 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 1.3.0 - 2026-06-17
+
+### Added
+- New `stats` CLI: summarize local memory storage across vault / journal / checkpoints. Shows totals, top projects by notes, most recent activity, and temp-slug cleanup candidates.
+  - Usage: `npx -y -p codex-dev-mcp-suite stats` (or globally `stats`)
+  - Flags: `--root <path>`, `--json`, `--top N`, `--help`, `--version`
+  - Pure-function library at `lib/stats.js` (no MCP / no stdio); tested offline.
+- New top-level test runner hook: `tests/*.test.mjs` are auto-picked-up by `node run-tests.mjs`.
+
+
+
+
+### Added
+- New `prune` CLI: remove temp project slugs (prefix `tmp.`) from vault, journal, and checkpoints. Default is DRY-RUN — nothing is deleted without `--yes`.
+  - Usage: `npx -y -p codex-dev-mcp-suite prune` (or globally `prune`)
+  - Flags: `--root <path>`, `--yes`, `--json`, `--help`, `--version`
+  - Pure-function library at `lib/prune.js`; tested offline.
+  - Safety: refuses to delete any slug that does not start with `tmp.`.
+- New MCP tool `memory_stats` on the project-memory server: returns the same summary as the `stats` CLI. Useful for in-session introspection from an MCP client.
+  - Args: `root?`, `top?` (default 10), `json?` (default false).
+
 ## 1.2.0 - 2026-06-15
 
 ### Added

package/README.md

@@ -2,6 +2,9 @@
 
 [![CI](https://github.com/verrysimatupang99/codex-dev-mcp-suite/actions/workflows/ci.yml/badge.svg)](https://github.com/verrysimatupang99/codex-dev-mcp-suite/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/codex-dev-mcp-suite.svg)](https://www.npmjs.com/package/codex-dev-mcp-suite)
+[![npm downloads](https://img.shields.io/npm/dm/codex-dev-mcp-suite.svg)](https://www.npmjs.com/package/codex-dev-mcp-suite)
+[![license](https://img.shields.io/npm/l/codex-dev-mcp-suite.svg)](./LICENSE)
+[![node](https://img.shields.io/node/v/codex-dev-mcp-suite.svg)](https://nodejs.org)
 
 Published as `codex-dev-mcp-suite` for backward compatibility.
 
@@ -14,6 +17,51 @@ per-project** by the working directory. Works with any MCP-capable client
 (Codex CLI, Claude Code, Cursor, Cline, Gemini-compatible launchers, Hermes,
 or any stdio MCP host).
 
+## Quickstart
+
+Try it in 10 seconds (no clone, no config):
+
+```bash
+npx -y -p codex-dev-mcp-suite project-memory-mcp --help
+```
+
+Local-first by default: no hosted backend, no telemetry. Works offline with
+keyword recall; model/provider config is optional. For strict no-network mode,
+set `MCP_DETERMINISTIC_FALLBACK=true`.
+
+Register all four servers with an MCP client (Codex CLI shown):
+
+```toml
+# ~/.codex/config.toml
+[mcp_servers.project-memory]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "project-memory-mcp"]
+
+[mcp_servers.devjournal]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "devjournal-mcp"]
+
+[mcp_servers.checkpoint]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "checkpoint-mcp"]
+
+[mcp_servers.context-pack]
+command = "npx"
+args = ["-y", "-p", "codex-dev-mcp-suite", "context-pack-mcp"]
+```
+
+Inspect any server without starting it:
+
+```bash
+project-memory-mcp --version
+project-memory-mcp --doctor   # config diagnostics; API keys redacted
+```
+
+Other clients (Claude Code, Cursor, Cline, ...): see
+[`docs/clients/`](docs/clients/). Full env reference:
+[`docs/configuration.md`](docs/configuration.md). Data flow:
+[`docs/privacy.md`](docs/privacy.md).
+
 ## The four servers
 
 | Server | What it does | Key tools |
@@ -138,6 +186,69 @@ node backfill-sessions-v2.mjs --dry --min-prompts 2     # preview
 node backfill-sessions-v2.mjs --min-prompts 2           # import
 ```
 
+## Stats CLI
+
+A read-only summary of your local memory storage — totals, top projects,
+recent activity, and temp-slug cleanup candidates.
+
+```bash
+npx -y -p codex-dev-mcp-suite stats             # human-readable
+npx -y -p codex-dev-mcp-suite stats --json      # machine-readable
+npx -y -p codex-dev-mcp-suite stats --root /tmp/mem   # different root
+npx -y -p codex-dev-mcp-suite stats --top 5     # trim top lists
+```
+
+Example output:
+
+```
+Dev MCP Suite — stats
+======================
+Storage root: /home/you/.codex/memories
+
+Totals
+------
+  Notes:           89
+  Journal projects:19
+  Checkpoints:     1
+  Distinct projects: 25
+
+Top projects by notes (top 10)
+------------------------
+    24  mrtrickster99-fd1ff0fa
+    14  Coding-17e063ef
+    ...
+
+Temp/cleanup candidates (2)
+------------------------
+  tmp.itbtDn9eB3-b62798fd
+  tmp.iHqM2Uh5K2-8d3660a2
+```
+
+The CLI is a thin wrapper around `lib/stats.js`, which is also importable
+directly from your own scripts. The default storage root is
+`~/.codex/memories`, but `--root` (or the existing `MEMORY_VAULT_DIR` /
+`JOURNAL_DIR` / `CHECKPOINT_DIR` env vars) override it.
+
+
+## Prune CLI
+
+Remove temp project slugs (prefix `tmp.`) from vault / journal / checkpoints.
+Default is DRY-RUN — nothing is deleted without `--yes`.
+
+```bash
+npx -y -p codex-dev-mcp-suite prune           # dry-run report
+npx -y -p codex-dev-mcp-suite prune --yes     # actually delete
+npx -y -p codex-dev-mcp-suite prune --json    # machine-readable
+npx -y -p codex-dev-mcp-suite prune --root /tmp/mem   # different root
+```
+
+Safety: refuses to delete any slug that does not start with `tmp.`. Useful
+right after heavy refactors or after imports that left tmp scratch dirs.
+
+For in-session use from an MCP client, the project-memory server exposes a
+`memory_stats` tool that returns the same summary text (or JSON) as the `stats`
+CLI above.
+
 ## Tests
 
 ```bash

package/bin/prune.mjs

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * bin/prune.mjs — Dev MCP Suite prune CLI.
+ *
+ * Removes temp project slugs (prefix `tmp.`) from all stores. Default is
+ * DRY-RUN — nothing is deleted unless you pass `--yes`.
+ *
+ * Usage:
+ *   prune [--root <path>] [--yes] [--json]
+ *   prune --help | --version
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { findTempSlugs, planPrune, applyPrune } from "../lib/prune.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+function resolveRoot() {
+  const fromFlag = process.env.PRUNE_ROOT;
+  if (fromFlag) return path.resolve(fromFlag);
+  for (const k of ["MEMORY_VAULT_DIR", "JOURNAL_DIR", "CHECKPOINT_DIR"]) {
+    const v = process.env[k];
+    if (v) {
+      const sub = k === "MEMORY_VAULT_DIR" ? "vault" : k === "JOURNAL_DIR" ? "journal" : "checkpoints";
+      const parent = path.dirname(v);
+      if (path.basename(parent) === sub) return parent;
+      return parent;
+    }
+  }
+  return path.join(os.homedir(), ".codex", "memories");
+}
+
+function parseArgs(argv) {
+  const opts = { root: null, yes: false, json: false, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--yes" || a === "-y") opts.yes = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--dry-run") opts.yes = false;
+    else if (a === "--root") opts.root = path.resolve(argv[++i]);
+    else if (a.startsWith("--root=")) opts.root = path.resolve(a.slice("--root=".length));
+    else if (!a.startsWith("-")) opts.root = path.resolve(a);
+    else {
+      process.stderr.write(`prune: unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n} B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)} KB`;
+  return `${(n / 1024 / 1024).toFixed(2)} MB`;
+}
+
+function printHelp() {
+  const out = [
+    `prune (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Remove temp project slugs (prefix tmp.) from vault, journal, and",
+    "checkpoints. Default is DRY-RUN — nothing is deleted without --yes.",
+    "",
+    "Usage:",
+    "  prune [root] [--root <path>] [--yes] [--json]",
+    "  prune --help | --version",
+    "",
+    "Options:",
+    "  --yes, -y    Actually delete. Without this, only a dry-run report is printed.",
+    "  --dry-run    Force dry-run mode (default).",
+    "  --json       Machine-readable JSON output.",
+    "  --root <p>   Storage root (default: ~/.codex/memories or first env var of",
+    "               MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)",
+    "  -h, --help",
+    "  -v, --version",
+    "",
+    "Safety: refuses to delete any slug that does not start with `tmp.`.",
+    "",
+    "Examples:",
+    "  prune                       # dry-run report",
+    "  prune --yes                 # delete after seeing the plan",
+    "  prune --yes --json          # machine-readable delete report",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.version) { process.stdout.write(`${pkgVersion()}\n`); process.exit(0); }
+if (opts.help) { printHelp(); process.exit(0); }
+
+const root = opts.root || resolveRoot();
+const plan = planPrune({ root });
+
+if (plan.length === 0) {
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ root, plan: [], removed: [], skipped: [], errors: [] }, null, 2) + "\n");
+  } else {
+    process.stdout.write(`No temp slugs found under ${root}.\n`);
+  }
+  process.exit(0);
+}
+
+if (!opts.yes) {
+  // dry-run report
+  if (opts.json) {
+    process.stdout.write(JSON.stringify({ root, dryRun: true, plan, removed: [], skipped: [], errors: [] }, null, 2) + "\n");
+  } else {
+    const lines = [];
+    lines.push(`Dev MCP Suite — prune (DRY RUN)`);
+    lines.push("=================================");
+    lines.push(`Storage root: ${root}`);
+    lines.push(`Found ${plan.length} temp slug${plan.length === 1 ? "" : "s"}:`);
+    let totalBytes = 0;
+    for (const e of plan) {
+      lines.push(`  ${e.slug.padEnd(36)} ${fmtBytes(e.bytes).padStart(10)}   stores: ${e.stores.join(",")}`);
+      totalBytes += e.bytes;
+    }
+    lines.push(`  ${"TOTAL".padEnd(36)} ${fmtBytes(totalBytes).padStart(10)}`);
+    lines.push("");
+    lines.push("Re-run with `--yes` to actually delete.");
+    process.stdout.write(lines.join("\n") + "\n");
+  }
+  process.exit(0);
+}
+
+// actually delete
+const slugs = plan.map((p) => p.slug);
+const result = applyPrune({ root, slugs, dryRun: false });
+const totalFreed = plan.reduce((a, p) => a + p.bytes, 0);
+
+if (opts.json) {
+  process.stdout.write(JSON.stringify({ root, dryRun: false, plan, ...result, bytesFreed: totalFreed }, null, 2) + "\n");
+} else {
+  const lines = [];
+  lines.push(`Dev MCP Suite — prune`);
+  lines.push("=====================");
+  lines.push(`Storage root: ${root}`);
+  lines.push(`Removed ${result.removed.length} slug${result.removed.length === 1 ? "" : "s"} (freed ~${fmtBytes(totalFreed)})`);
+  for (const slug of result.removed) lines.push(`  ✓ ${slug}`);
+  if (result.errors.length) {
+    lines.push("");
+    lines.push(`Errors (${result.errors.length}):`);
+    for (const e of result.errors) lines.push(`  ✗ ${e.slug} [${e.store}]: ${e.error}`);
+  }
+  process.stdout.write(lines.join("\n") + "\n");
+}
+
+process.exit(result.errors.length > 0 ? 1 : 0);

package/bin/stats.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * bin/stats.mjs — Dev MCP Suite stats CLI.
+ *
+ * Usage:
+ *   stats [--root <path>] [--json] [--top N] [--help] [--version]
+ *
+ * Default storage root: ~/.codex/memories (override via --root or
+ * MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR siblings).
+ */
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { fileURLToPath } from "url";
+import { computeStats, formatText, formatJson } from "../lib/stats.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+function pkgVersion() {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(__dirname, "..", "package.json"), "utf8")).version || "unknown";
+  } catch { return "unknown"; }
+}
+
+function resolveRoot() {
+  // Precedence: explicit --root > vault env > journal env > checkpoint env > ~/.codex/memories
+  const fromFlag = process.env.STATS_ROOT;
+  if (fromFlag) return path.resolve(fromFlag);
+  for (const k of ["MEMORY_VAULT_DIR", "JOURNAL_DIR", "CHECKPOINT_DIR"]) {
+    const v = process.env[k];
+    if (v) {
+      // each server stores under <root>/<subdir>, so the root is the parent
+      const sub = k === "MEMORY_VAULT_DIR" ? "vault" : k === "JOURNAL_DIR" ? "journal" : "checkpoints";
+      const parent = path.dirname(v);
+      if (path.basename(parent) === sub) return parent;
+      return parent;
+    }
+  }
+  return path.join(os.homedir(), ".codex", "memories");
+}
+
+function parseArgs(argv) {
+  const opts = { root: null, json: false, top: 10, help: false, version: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "-h" || a === "--help") opts.help = true;
+    else if (a === "-v" || a === "--version") opts.version = true;
+    else if (a === "--json") opts.json = true;
+    else if (a === "--root") opts.root = path.resolve(argv[++i]);
+    else if (a.startsWith("--root=")) opts.root = path.resolve(a.slice("--root=".length));
+    else if (a === "--top") opts.top = parseInt(argv[++i], 10) || 10;
+    else if (a.startsWith("--top=")) opts.top = parseInt(a.slice("--top=".length), 10) || 10;
+    else if (a === "--") { /* ignore rest */ break; }
+    else if (!a.startsWith("-")) opts.root = path.resolve(a);
+    else {
+      process.stderr.write(`stats: unknown flag: ${a}\n`);
+      process.exit(2);
+    }
+  }
+  return opts;
+}
+
+function printHelp() {
+  const out = [
+    `stats (Dev MCP Suite) v${pkgVersion()}`,
+    "",
+    "Summarize local memory storage (vault / journal / checkpoints).",
+    "",
+    "Usage:",
+    "  stats [root] [--root <path>] [--json] [--top N]",
+    "  stats --help | --version",
+    "",
+    "Options:",
+    "  --root <path>   Storage root (default: ~/.codex/memories or first env var of",
+    "                  MEMORY_VAULT_DIR / JOURNAL_DIR / CHECKPOINT_DIR)",
+    "  --json          Emit machine-readable JSON instead of human text",
+    "  --top N         How many entries in top-project / recent-activity lists",
+    "                  (default: 10)",
+    "  -h, --help      Show this help",
+    "  -v, --version   Print version",
+    "",
+    "Examples:",
+    "  stats                       # summary of default storage",
+    "  stats --json | jq .totals   # totals only",
+    "  stats --root /tmp/mem       # use a different root",
+  ];
+  process.stdout.write(out.join("\n") + "\n");
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.version) { process.stdout.write(`${pkgVersion()}\n`); process.exit(0); }
+if (opts.help) { printHelp(); process.exit(0); }
+
+const root = opts.root || resolveRoot();
+const stats = computeStats({ root, topLimit: opts.top });
+
+if (opts.json) {
+  process.stdout.write(formatJson(stats) + "\n");
+} else {
+  process.stdout.write(formatText(stats) + "\n");
+}

package/lib/prune.js

@@ -0,0 +1,114 @@
+/**
+ * Dev MCP Suite — prune library.
+ *
+ * Identifies and removes "temp" project slugs (prefix `tmp.`) from all three
+ * stores. Used by `bin/prune.mjs`. No MCP, no stdio — safe to import from tests.
+ *
+ * Storage layout (matches the rest of the suite):
+ *   <root>/vault/<slug>/
+ *   <root>/journal/<slug>/
+ *   <root>/checkpoints/<slug>/
+ */
+
+import fs from "fs";
+import path from "path";
+
+export const STORES = ["vault", "journal", "checkpoints"];
+const TEMP_PREFIX = "tmp.";
+
+/** Returns the list of slug names matching temp pattern across all stores. */
+export function findTempSlugs({ root }) {
+  const set = new Set();
+  for (const store of STORES) {
+    let entries = [];
+    try {
+      entries = fs.readdirSync(path.join(root, store), { withFileTypes: true });
+    } catch { continue; }
+    for (const e of entries) {
+      if (e.isDirectory() && e.name.startsWith(TEMP_PREFIX)) set.add(e.name);
+    }
+  }
+  return [...set].sort();
+}
+
+/** Recursively sum bytes under each slug's directories across stores. */
+export function estimateBytes({ root, slugs }) {
+  let total = 0;
+  for (const slug of slugs) {
+    for (const store of STORES) {
+      total += dirSize(path.join(root, store, slug));
+    }
+  }
+  return total;
+}
+
+function dirSize(p) {
+  let total = 0;
+  let stack = [p];
+  while (stack.length) {
+    const cur = stack.pop();
+    let stat;
+    try { stat = fs.lstatSync(cur); } catch { continue; }
+    if (stat.isDirectory()) {
+      let children = [];
+      try { children = fs.readdirSync(cur); } catch { continue; }
+      for (const c of children) stack.push(path.join(cur, c));
+    } else {
+      total += stat.size;
+    }
+  }
+  return total;
+}
+
+/** Validate slugs only contain temp prefix — refuse to delete otherwise. */
+function assertTempSlugs(slugs) {
+  for (const s of slugs) {
+    if (!s.startsWith(TEMP_PREFIX)) {
+      throw new Error(`refusing to remove non-temp slug: "${s}" (must start with "${TEMP_PREFIX}")`);
+    }
+  }
+}
+
+/** Compute a plan: per-slug list of stores where the dir exists + total bytes. */
+export function planPrune({ root }) {
+  const slugs = findTempSlugs({ root });
+  return slugs.map((slug) => {
+    const stores = [];
+    for (const store of STORES) {
+      const p = path.join(root, store, slug);
+      try {
+        if (fs.existsSync(p)) stores.push(store);
+      } catch { /* ignore */ }
+    }
+    const bytes = estimateBytes({ root, slugs: [slug] });
+    return { slug, stores, bytes };
+  });
+}
+
+/**
+ * Remove temp slugs from all stores. Default is dry-run (no deletion).
+ * @param {{ root: string, slugs: string[], dryRun?: boolean }} opts
+ * @returns {{ removed: string[], skipped: string[], errors: Array<{slug:string,store:string,error:string}> }}
+ */
+export function applyPrune({ root, slugs, dryRun = true }) {
+  assertTempSlugs(slugs);
+  const removed = [];
+  const skipped = [];
+  const errors = [];
+  for (const slug of slugs) {
+    let anyRemoved = false;
+    for (const store of STORES) {
+      const p = path.join(root, store, slug);
+      if (!fs.existsSync(p)) continue;
+      if (dryRun) { skipped.push(slug); continue; }
+      try {
+        fs.rmSync(p, { recursive: true, force: true });
+        anyRemoved = true;
+      } catch (e) {
+        errors.push({ slug, store, error: String(e && e.message || e) });
+      }
+    }
+    if (anyRemoved) removed.push(slug);
+  }
+  return { removed, skipped, errors };
+}

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.3.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,13 @@
     "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"
   },
   "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 +73,7 @@
     "CHANGELOG.md",
     "README.md",
     "LICENSE",
-    ".env.example"
+    ".env.example",
+    "lib/*.js"
   ]
 }

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 ||
@@ -220,6 +221,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 +246,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) {
@@ -439,6 +453,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);