@vellumai/assistant 0.10.9-dev.202607161337.f69e16e → 0.10.9-dev.202607161445.5757c2f

package/Dockerfile

@@ -129,6 +129,14 @@ COPY packages/twilio-client /app/packages/twilio-client
 
 COPY assistant /app/assistant
 
+# Materialize the git-ignored offline plugin manifest from its canonical source.
+# `assistant/src/cli/lib/plugin-catalog-local.ts` statically imports this JSON
+# (loaded even when platform features are enabled), so it must exist in the image
+# — the build installs with --ignore-scripts, so the postinstall sync that
+# regenerates it in dev never runs here. Mirrors how CI materializes the
+# feature-flag registry before building.
+COPY plugins/marketplace.json /app/assistant/src/cli/lib/bundled-marketplace.json
+
 # Install assistant CLI launcher backed by the bundled assistant package
 RUN printf '#!/usr/bin/env sh\nexec bun run /app/assistant/src/index.ts "$@"\n' > /usr/local/bin/assistant && \
     chmod +x /usr/local/bin/assistant

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/assistant",
-  "version": "0.10.9-dev.202607161337.f69e16e",
+  "version": "0.10.9-dev.202607161445.5757c2f",
   "license": "MIT",
   "type": "module",
   "exports": {

package/src/__tests__/plugin-import-boundary-reverse-guard.test.ts

@@ -81,6 +81,7 @@ const BASELINE: Record<string, readonly string[]> = {
     "src/cli/commands/memory/memory-v2-compare-render.ts",
     "src/cli/commands/memory/memory-v2.ts",
     "src/cli/commands/memory/memory-v3.ts",
+    "src/cli/commands/memory/nodes.ts",
     "src/config/bundled-skills/messaging/tools/messaging-analyze-style.ts",
     "src/config/bundled-skills/playbooks/tools/playbook-create.ts",
     "src/config/bundled-skills/playbooks/tools/playbook-delete.ts",

package/src/cli/commands/memory/index.help.ts

@@ -26,6 +26,7 @@ model (section-grain lanes cached as live shadow state). Each subgroup exposes
 operator-facing maintenance verbs — reindexing, backfills, validation, and evals.
 
 Examples:
+  $ assistant memory nodes stats
   $ assistant memory nodes list --search "coffee"
   $ assistant memory nodes delete "User prefers TypeScript"
   $ assistant memory nodes update "User prefers TypeScript" "User prefers TypeScript and Bun"
@@ -48,11 +49,33 @@ a remembered fact without first looking up its ID.
 All subcommands require memory v2 to be enabled and the assistant to be running.
 
 Examples:
+  $ assistant memory nodes stats
   $ assistant memory nodes list
   $ assistant memory nodes list --search "TypeScript" --limit 20
   $ assistant memory nodes delete "User prefers TypeScript"
   $ assistant memory nodes update "User prefers TypeScript" "User prefers TypeScript and Bun"`,
       subcommands: [
+        {
+          name: "stats",
+          description: "Show a health overview of the memory v2 graph",
+          options: [
+            {
+              flags: "--json",
+              description: "Machine-readable compact JSON output",
+            },
+          ],
+          helpText: `
+Behavior:
+  Scans all active memory graph nodes in a single pass and reports:
+  total count, breakdown by type and fidelity (with an ASCII bar chart),
+  nodes at risk of decay (significance < 15%), average significance,
+  oldest/newest node timestamps, last reinforcement, and the top 5 nodes
+  by significance. Does not require the daemon to be running.
+
+Examples:
+  $ assistant memory nodes stats
+  $ assistant memory nodes stats --json`,
+        },
         {
           name: "list",
           description: "List active memory graph nodes",

package/src/cli/commands/memory/nodes.ts

@@ -203,4 +203,150 @@ export function registerMemoryNodesCommand(memory: Command): void {
       log.info(result.message);
     },
   );
+
+  // ── stats ─────────────────────────────────────────────────────────────
+
+  subcommand(nodes, "stats").action(
+    async (opts: { json?: boolean }, cmd: Command) => {
+      // Deferred: loads config and the graph stats handler in-process.
+      // No daemon needed — reads directly from the workspace SQLite DB.
+      const [{ handleStatsMemory }, { getConfig }] = await Promise.all([
+        import("../../../plugins/defaults/memory/graph/tool-handlers.js") as Promise<
+          typeof import("../../../plugins/defaults/memory/graph/tool-handlers.js")
+        >,
+        import("../../../config/loader.js") as Promise<
+          typeof import("../../../config/loader.js")
+        >,
+      ]);
+
+      const result = handleStatsMemory(getConfig());
+
+      if (!result.success) {
+        log.error(result.message);
+        process.exitCode = 1;
+        return;
+      }
+
+      if (opts.json) {
+        writeOutput(cmd, result.stats);
+        return;
+      }
+
+      printStats(result.stats!);
+    },
+  );
+}
+
+const MEMORY_TYPES = [
+  "episodic",
+  "semantic",
+  "procedural",
+  "emotional",
+  "prospective",
+  "behavioral",
+  "narrative",
+  "shared",
+] as const;
+
+interface StatsData {
+  total: number;
+  byType: { [key: string]: number | undefined };
+  byFidelity: { vivid: number; clear: number; faded: number; gist: number };
+  atRisk: number;
+  edgeCount: number;
+  oldestCreated: number | null;
+  newestCreated: number | null;
+  lastReinforced: number | null;
+  avgSignificance: number;
+  topNodes: ReadonlyArray<{ content: string; significance: number }>;
+}
+
+function printStats(s: StatsData): void {
+  const n = s.total;
+  const e = s.edgeCount;
+
+  console.log(
+    `\nMemory graph  ${n} node${n === 1 ? "" : "s"} · ${e} edge${e === 1 ? "" : "s"}\n`,
+  );
+
+  if (n === 0) {
+    console.log("  The memory graph is empty.");
+    console.log("");
+    return;
+  }
+
+  // ── by type ─────────────────────────────────────────────────────────────
+
+  console.log("BY TYPE");
+  for (const t of MEMORY_TYPES) {
+    const count = s.byType[t] ?? 0;
+    if (count > 0) {
+      console.log(`  ${t.padEnd(12)}  ${count}`);
+    }
+  }
+
+  // ── by fidelity (with ASCII bar) ─────────────────────────────────────────
+
+  console.log("\nBY FIDELITY");
+  const fidelities = ["vivid", "clear", "faded", "gist"] as const;
+  for (const f of fidelities) {
+    const count = s.byFidelity[f];
+    const barLen = n > 0 ? Math.round((count / n) * 20) : 0;
+    const bar = "█".repeat(barLen);
+    console.log(`  ${f.padEnd(6)}  ${String(count).padStart(4)}  ${bar}`);
+  }
+
+  // ── significance ─────────────────────────────────────────────────────────
+
+  console.log("\nSIGNIFICANCE");
+  console.log(`  average    ${(s.avgSignificance * 100).toFixed(1)}%`);
+  if (s.atRisk > 0) {
+    console.log(
+      `  at risk    ${s.atRisk} node${s.atRisk === 1 ? "" : "s"} fading (significance < 15%)`,
+    );
+  }
+
+  // ── timeline ─────────────────────────────────────────────────────────────
+
+  console.log("\nTIMELINE");
+  const dateOpts: Intl.DateTimeFormatOptions = {
+    month: "short",
+    day: "numeric",
+    year: "numeric",
+  };
+  if (s.oldestCreated) {
+    console.log(
+      `  oldest      ${new Date(s.oldestCreated).toLocaleString("en-US", dateOpts)}`,
+    );
+  }
+  if (s.newestCreated) {
+    console.log(
+      `  newest      ${new Date(s.newestCreated).toLocaleString("en-US", dateOpts)}`,
+    );
+  }
+  if (s.lastReinforced) {
+    console.log(
+      `  reinforced  ${new Date(s.lastReinforced).toLocaleString("en-US", {
+        ...dateOpts,
+        hour: "numeric",
+        minute: "2-digit",
+      })}`,
+    );
+  }
+
+  // ── top nodes ────────────────────────────────────────────────────────────
+
+  if (s.topNodes.length > 0) {
+    console.log("\nTOP NODES BY SIGNIFICANCE");
+    const WIDTH = 60;
+    const trunc = (str: string) =>
+      str.length > WIDTH ? str.slice(0, WIDTH - 1) + "…" : str;
+    for (const node of s.topNodes) {
+      console.log(
+        `  ${(node.significance * 100).toFixed(0).padStart(3)}%  ${trunc(node.content)}`,
+      );
+    }
+  }
+
+  console.log("");
 }

package/src/cli/lib/plugin-catalog-local.ts

@@ -1,10 +1,14 @@
 /**
  * Offline plugin catalog reader backed by the manifest bundled into the
- * package at build time (see meta/sync-bundled-copies.ts).
+ * package at build time. `bundled-marketplace.json` is a generated artifact
+ * (git-ignored) that meta/sync-bundled-copies.ts copies from the canonical
+ * plugins/marketplace.json before every build, test, and install — the same
+ * treatment as the feature-flag registry.
  *
  * `getPluginCatalog` selects this reader only when platform features are
  * disabled (air-gapped / self-hosted, `VELLUM_DISABLE_PLATFORM=true`). Importing
- * the JSON directly (resolveJsonModule) means no filesystem path resolution, so
+ * the JSON directly (resolveJsonModule) inlines it into the bundle, so there is
+ * no filesystem path resolution and the manifest is always present at runtime —
  * it works identically in dev, Docker, and an npm-packed macOS install.
  */
 

package/src/plugins/defaults/memory/graph/store.ts

@@ -883,3 +883,117 @@ export function getNodeEditHistory(
     .limit(limit)
     .all();
 }
+
+// ---------------------------------------------------------------------------
+// Graph stats
+// ---------------------------------------------------------------------------
+
+/** Fidelity counts for active (non-gone) nodes. */
+export interface FidelityBreakdown {
+  vivid: number;
+  clear: number;
+  faded: number;
+  gist: number;
+}
+
+/** Aggregate health snapshot of the memory v2 graph. */
+export interface GraphStats {
+  /** Total active (non-gone) node count. */
+  total: number;
+  /** Node count by MemoryType. */
+  byType: Partial<Record<MemoryType, number>>;
+  /** Node count by fidelity, excluding gone. */
+  byFidelity: FidelityBreakdown;
+  /** Nodes with significance < 0.15 (at risk of decaying away). */
+  atRisk: number;
+  /** Live edge count — both endpoints are non-gone. */
+  edgeCount: number;
+  /** Epoch ms of the oldest active node, or null if the graph is empty. */
+  oldestCreated: number | null;
+  /** Epoch ms of the newest active node, or null if the graph is empty. */
+  newestCreated: number | null;
+  /** Epoch ms of the most recent reinforcement event, or null if none. */
+  lastReinforced: number | null;
+  /** Mean significance across all active nodes (0–1). */
+  avgSignificance: number;
+  /** Up to 5 highest-significance nodes (content, significance, fidelity, type). */
+  topNodes: Array<{
+    content: string;
+    significance: number;
+    fidelity: string;
+    type: string;
+  }>;
+}
+
+/**
+ * Compute a health snapshot of the memory v2 graph in two queries:
+ *   1. A full scan of active nodes (significance DESC) to derive all
+ *      per-node aggregates in one JS pass.
+ *   2. A SQL COUNT of live edges (both endpoints non-gone).
+ *
+ * Callers that only need the summary number can use `countNodes()` instead.
+ */
+export function computeGraphStats(): GraphStats {
+  // Full scan — significance DESC so topNodes is just the first slice.
+  const nodes = queryNodes({ fidelityNot: ["gone"] });
+
+  const byType: Partial<Record<MemoryType, number>> = {};
+  const byFidelity: FidelityBreakdown = {
+    vivid: 0,
+    clear: 0,
+    faded: 0,
+    gist: 0,
+  };
+  let atRisk = 0;
+  let sigSum = 0;
+  let oldestCreated: number | null = null;
+  let newestCreated: number | null = null;
+  let lastReinforced: number | null = null;
+
+  for (const n of nodes) {
+    byType[n.type] = (byType[n.type] ?? 0) + 1;
+    if (n.fidelity !== "gone") {
+      byFidelity[n.fidelity as keyof FidelityBreakdown] += 1;
+    }
+    if (n.significance < 0.15) atRisk++;
+    sigSum += n.significance;
+    if (oldestCreated === null || n.created < oldestCreated)
+      oldestCreated = n.created;
+    if (newestCreated === null || n.created > newestCreated)
+      newestCreated = n.created;
+    if (lastReinforced === null || n.lastReinforced > lastReinforced)
+      lastReinforced = n.lastReinforced;
+  }
+
+  // Live edge count: both endpoints must be non-gone.
+  const db = getDb();
+  const edgeResult = db
+    .select({ count: sql<number>`count(*)` })
+    .from(memoryGraphEdges)
+    .where(
+      and(
+        sql`NOT EXISTS (SELECT 1 FROM ${memoryGraphNodes} WHERE ${memoryGraphNodes.id} = ${memoryGraphEdges.sourceNodeId} AND ${memoryGraphNodes.fidelity} = 'gone')`,
+        sql`NOT EXISTS (SELECT 1 FROM ${memoryGraphNodes} WHERE ${memoryGraphNodes.id} = ${memoryGraphEdges.targetNodeId} AND ${memoryGraphNodes.fidelity} = 'gone')`,
+      ),
+    )
+    .get();
+
+  return {
+    total: nodes.length,
+    byType,
+    byFidelity,
+    atRisk,
+    edgeCount: edgeResult?.count ?? 0,
+    oldestCreated,
+    newestCreated,
+    lastReinforced,
+    avgSignificance: nodes.length > 0 ? sigSum / nodes.length : 0,
+    // nodes is already sorted significance DESC — slice gives the top N.
+    topNodes: nodes.slice(0, 5).map((n) => ({
+      content: n.content,
+      significance: n.significance,
+      fidelity: n.fidelity,
+      type: n.type,
+    })),
+  };
+}

package/src/plugins/defaults/memory/graph/tool-handlers.ts

@@ -14,7 +14,14 @@ import { enqueueMemoryJob } from "../../../../persistence/jobs-store.js";
 import { enqueuePkbIndexJob } from "../jobs/embed-pkb-file.js";
 import { getLogger } from "../logging.js";
 import { getWorkspaceDir } from "../paths.js";
-import { deleteNode, queryNodes, recordNodeEdit, updateNode } from "./store.js";
+import type { GraphStats } from "./store.js";
+import {
+  computeGraphStats,
+  deleteNode,
+  queryNodes,
+  recordNodeEdit,
+  updateNode,
+} from "./store.js";
 
 const log = getLogger("graph-tool-handlers");
 
@@ -429,3 +436,31 @@ export function handleListMemory(
     total: filtered.length,
   };
 }
+
+// ---------------------------------------------------------------------------
+// handleStatsMemory
+// ---------------------------------------------------------------------------
+
+export interface StatsMemoryResult {
+  success: boolean;
+  message: string;
+  stats: GraphStats | null;
+}
+
+export function handleStatsMemory(config: AssistantConfig): StatsMemoryResult {
+  if (!config.memory.v2.enabled) {
+    return {
+      success: false,
+      message: "stats requires memory v2.",
+      stats: null,
+    };
+  }
+  const stats = computeGraphStats();
+  const n = stats.total;
+  const e = stats.edgeCount;
+  return {
+    success: true,
+    message: `${n} active node${n === 1 ? "" : "s"}, ${e} edge${e === 1 ? "" : "s"}.`,
+    stats,
+  };
+}