@pyxmate/memory 1.17.19 → 1.18.0

package/dist/cli/pyx-mem.mjs

@@ -3,6 +3,14 @@ import {
   PERSISTENT_MEMORY_SECTION,
   buildDesignGuide
 } from "../chunk-EZERG25I.mjs";
+import {
+  MEMORY_PROJECT_LABEL_MAX_CHARS,
+  TAXONOMY_MAX_CATEGORIES,
+  TAXONOMY_MAX_PROJECTS,
+  TAXONOMY_MAX_SAMPLE_TOPICS,
+  TAXONOMY_MAX_TOP_ENTITIES
+} from "../chunk-KVYCISUI.mjs";
+import "../chunk-3OLH3HYR.mjs";
 
 // src/cli/exit-codes.ts
 var EXIT = {
@@ -328,6 +336,348 @@ async function doctorCommand(opts = {}) {
   return ok ? EXIT.OK : EXIT.DOCTOR_FAIL;
 }
 
+// src/cli/commands/insights.ts
+import { z } from "zod";
+
+// src/cli/commands/read-surface.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/mcp/errors.ts
+var RUN_LOGIN = "Run: pyx-mem login";
+var RUN_DOCTOR = "Run: pyx-mem doctor";
+function mcpText(text, isError = false) {
+  return { isError, content: [{ type: "text", text }] };
+}
+function mcpMissingCredentials() {
+  return mcpText(`pyx-memory credentials are not configured.
+${RUN_LOGIN}`, true);
+}
+function mcpKeychainError(message, guidance) {
+  const lines = ["pyx-memory credentials could not be read from the OS credential store."];
+  if (message) lines.push(message);
+  if (guidance) lines.push(guidance);
+  lines.push(RUN_LOGIN);
+  return mcpText(lines.join("\n"), true);
+}
+function mcpAuthFailed(status) {
+  return mcpText(`Authentication failed (HTTP ${status}).
+${RUN_LOGIN}`, true);
+}
+function mcpUnreachable(endpoint, reason) {
+  return mcpText(`Unable to reach pyx-memory at ${endpoint}: ${reason}.
+${RUN_DOCTOR}`, true);
+}
+function mcpHttpError(status, body) {
+  return mcpText(`${status}: ${body}`, true);
+}
+function mcpServerError(status, body) {
+  return mcpText(`pyx-memory server error (HTTP ${status}): ${body || "no body"}`, true);
+}
+function mcpEnvelopeError(message) {
+  return mcpText(message, true);
+}
+function mcpJson(payload) {
+  return mcpText(JSON.stringify(payload));
+}
+
+// src/mcp/http-client.ts
+var DEFAULT_TIMEOUT_MS = 15e3;
+function validateIdempotencyKey(key) {
+  if (key.length === 0 || !key.isWellFormed() || new TextEncoder().encode(key).byteLength > 256) {
+    throw new Error("idempotencyKey must be 1-256 well-formed UTF-8 bytes");
+  }
+  return key;
+}
+function createHttpClient(credentials, fetchImpl = fetch) {
+  const baseUrl = credentials.endpoint.replace(/\/+$/, "");
+  function buildUrl(path, query) {
+    const url = new URL(`${baseUrl}${path}`);
+    if (query) {
+      for (const [k, v] of Object.entries(query)) {
+        if (v === void 0) continue;
+        url.searchParams.set(k, String(v));
+      }
+    }
+    return url.toString();
+  }
+  function buildHeaders(scope, contentType, idempotencyKey) {
+    const headers = new Headers();
+    headers.set("Authorization", `Bearer ${credentials.apiKey}`);
+    headers.set("Accept", "application/json");
+    if (contentType) headers.set("Content-Type", contentType);
+    if (scope?.tenantId) headers.set("X-Tenant-Id", scope.tenantId);
+    if (scope?.namespaceId) headers.set("X-Namespace-Id", scope.namespaceId);
+    if (scope?.userId) headers.set("X-User-Id", scope.userId);
+    if (scope?.teamId) headers.set("X-Team-Id", scope.teamId);
+    if (scope?.callerAccessLevel) headers.set("X-Caller-Access-Level", scope.callerAccessLevel);
+    if (idempotencyKey !== void 0) {
+      headers.set("Idempotency-Key", validateIdempotencyKey(idempotencyKey));
+    }
+    return headers;
+  }
+  async function send(url, method, headers, body) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), DEFAULT_TIMEOUT_MS);
+    let res;
+    try {
+      res = await fetchImpl(url, { method, headers, body, signal: ctl.signal });
+    } catch (err) {
+      return {
+        ok: false,
+        result: mcpUnreachable(baseUrl, err instanceof Error ? err.message : String(err))
+      };
+    } finally {
+      clearTimeout(timer);
+    }
+    if (res.status === 401 || res.status === 403) {
+      return { ok: false, status: res.status, result: mcpAuthFailed(res.status) };
+    }
+    const text = await res.text().catch(() => "");
+    return parseHttpResponse(res, text);
+  }
+  return {
+    async requestJson(input) {
+      const url = buildUrl(input.path, input.query);
+      const hasBody = input.body !== void 0;
+      const headers = buildHeaders(
+        input.scope,
+        hasBody ? "application/json" : void 0,
+        input.idempotencyKey
+      );
+      return send(url, input.method, headers, hasBody ? JSON.stringify(input.body) : void 0);
+    },
+    async requestMultipart(input) {
+      const url = buildUrl(input.path);
+      const headers = buildHeaders(input.scope, void 0, input.idempotencyKey);
+      const form = await input.formData();
+      return send(url, "POST", headers, form);
+    }
+  };
+}
+function parseHttpResponse(res, text) {
+  if (res.status >= 500) {
+    return { ok: false, status: res.status, result: mcpServerError(res.status, text) };
+  }
+  const parsed = parseJsonText(text);
+  if (!parsed.ok) {
+    if (!res.ok) {
+      return {
+        ok: false,
+        status: res.status,
+        result: mcpHttpError(res.status, text || "no body")
+      };
+    }
+    return { ok: true, status: res.status, data: text };
+  }
+  if (!res.ok) {
+    const message = extractEnvelopeError(parsed.value) ?? text ?? `HTTP ${res.status}`;
+    return { ok: false, status: res.status, result: mcpHttpError(res.status, message) };
+  }
+  const envelopeError = extractEnvelopeError(parsed.value);
+  if (envelopeError) {
+    return { ok: false, status: res.status, result: mcpEnvelopeError(envelopeError) };
+  }
+  return { ok: true, status: res.status, data: parsed.value };
+}
+function parseJsonText(text) {
+  if (text.length === 0) return { ok: true, value: void 0 };
+  try {
+    return { ok: true, value: JSON.parse(text) };
+  } catch {
+    return { ok: false };
+  }
+}
+function extractEnvelopeError(parsed) {
+  if (parsed === null || typeof parsed !== "object") return null;
+  const obj = parsed;
+  if (obj.success === false) {
+    if (typeof obj.error === "string") return obj.error;
+    if (typeof obj.message === "string") return obj.message;
+    return "pyx-memory returned success: false";
+  }
+  return null;
+}
+
+// src/cli/commands/read-surface.ts
+async function readSurface(opts) {
+  const provider = opts.keychain ?? getDefaultKeychain();
+  let credentials;
+  try {
+    credentials = await provider.read();
+  } catch (error) {
+    return {
+      ok: false,
+      exit: error instanceof KeychainError ? error.exit : EXIT.CRED_UNAVAILABLE,
+      state: "error",
+      endpoint: null,
+      keySource: null,
+      problem: error instanceof KeychainError ? [error.message, error.guidance].filter(Boolean).join(" ") : "The OS credential store could not be read."
+    };
+  }
+  if (!credentials) {
+    return {
+      ok: false,
+      exit: EXIT.NOT_LOGGED_IN,
+      state: "signed_out",
+      endpoint: null,
+      keySource: null,
+      problem: null
+    };
+  }
+  if (!isHttpUrl(credentials.endpoint)) {
+    return {
+      ok: false,
+      exit: EXIT.DOCTOR_FAIL,
+      state: "error",
+      endpoint: null,
+      keySource: "keychain",
+      problem: "The stored pyx-memory endpoint is invalid. Run: pyx-mem login"
+    };
+  }
+  const http = createHttpClient(credentials, opts.fetchImpl ?? fetch);
+  const response = await http.requestJson({
+    ...opts.request,
+    idempotencyKey: `cli-${opts.surface}-${randomUUID2()}`
+  });
+  if (!response.ok) {
+    const signedOut = response.status === 401;
+    return {
+      ok: false,
+      exit: signedOut ? EXIT.NOT_LOGGED_IN : EXIT.DOCTOR_FAIL,
+      state: signedOut ? "signed_out" : "error",
+      endpoint: credentials.endpoint,
+      keySource: "keychain",
+      problem: requestFailure(opts.surface, response.status)
+    };
+  }
+  const parsed = opts.schema.safeParse(response.data);
+  if (!parsed.success) {
+    return {
+      ok: false,
+      exit: EXIT.DOCTOR_FAIL,
+      state: "error",
+      endpoint: credentials.endpoint,
+      keySource: "keychain",
+      problem: `pyx-memory returned an invalid ${opts.surface} response. Run: pyx-mem doctor`
+    };
+  }
+  return { ok: true, endpoint: credentials.endpoint, data: parsed.data };
+}
+function requestFailure(surface, status) {
+  if (status === 401) {
+    return "Stored pyx-memory credentials were rejected. Run: pyx-mem login";
+  }
+  if (status === 403) {
+    return "pyx-memory denied access (HTTP 403). Check the key scope and project access.";
+  }
+  if (status === void 0) {
+    return "Unable to reach pyx-memory. Run: pyx-mem doctor";
+  }
+  if (status >= 500) {
+    return `pyx-memory is unavailable (HTTP ${status}). Run: pyx-mem doctor`;
+  }
+  return `pyx-memory ${surface} failed (HTTP ${status}). Run: pyx-mem doctor`;
+}
+function isHttpUrl(value) {
+  try {
+    const url = new URL(value);
+    return url.protocol === "http:" || url.protocol === "https:";
+  } catch {
+    return false;
+  }
+}
+
+// src/cli/commands/insights.ts
+var INSIGHTS_SCHEMA_VERSION = 1;
+var metricsSchema = z.object({
+  activeEntries: z.number().int().nonnegative(),
+  retainedAdditions7d: z.number().int().nonnegative(),
+  appliedRecalls: z.number().int().nonnegative(),
+  reinforcedEntries: z.number().int().nonnegative(),
+  retrievedEntries: z.number().int().nonnegative(),
+  retrievals: z.number().int().nonnegative(),
+  lastAppliedAt: z.string().nullable(),
+  lastRetrievedAt: z.string().nullable()
+});
+var insightsSchema = z.object({
+  generatedAt: z.string(),
+  scope: z.literal("connected_memory"),
+  coverage: z.object({
+    retainedAdditions: z.object({
+      state: z.enum(["measured", "partial"]),
+      trackingSince: z.string().nullable(),
+      trackedEntries: z.number().int().nonnegative(),
+      totalEntries: z.number().int().nonnegative(),
+      reason: z.string().nullable()
+    }),
+    projectLabels: z.object({ state: z.literal("measured") }),
+    retrievalUsage: z.object({ state: z.literal("partial"), reason: z.string() }),
+    tokenEfficiency: z.object({ state: z.literal("not_instrumented"), reason: z.string() }),
+    contextAccuracy: z.object({ state: z.literal("not_instrumented"), reason: z.string() })
+  }),
+  summary: z.object({
+    activeEntries: z.number().int().nonnegative(),
+    observedProjectLabels: z.number().int().nonnegative(),
+    retainedAdditions7d: z.number().int().nonnegative().nullable(),
+    trackedEntries: z.number().int().nonnegative(),
+    appliedRecalls: z.number().int().nonnegative(),
+    reinforcedEntries: z.number().int().nonnegative(),
+    retrievedEntries: z.number().int().nonnegative(),
+    retrievals: z.number().int().nonnegative()
+  }),
+  projects: z.array(
+    metricsSchema.extend({
+      label: z.string().min(1).max(MEMORY_PROJECT_LABEL_MAX_CHARS)
+    })
+  ).max(TAXONOMY_MAX_PROJECTS),
+  other: metricsSchema.nullable()
+});
+var insightsResponseSchema = z.union([
+  insightsSchema,
+  z.object({ success: z.literal(true), data: insightsSchema }).transform(({ data }) => data)
+]);
+async function insightsCommand(opts = {}) {
+  const result = await readSurface({
+    surface: "insights",
+    request: { method: "GET", path: "/api/memory/insights" },
+    schema: insightsResponseSchema,
+    keychain: opts.keychain,
+    fetchImpl: opts.fetchImpl
+  });
+  if (!result.ok) {
+    emit(report(result.state, result.endpoint, result.keySource, result.problem));
+    return result.exit;
+  }
+  emit({
+    schemaVersion: INSIGHTS_SCHEMA_VERSION,
+    state: "ready",
+    endpoint: result.endpoint,
+    keySource: "keychain",
+    ...result.data,
+    problem: null
+  });
+  return EXIT.OK;
+}
+function report(state, endpoint, keySource, problem) {
+  return {
+    schemaVersion: INSIGHTS_SCHEMA_VERSION,
+    state,
+    endpoint,
+    keySource,
+    generatedAt: null,
+    scope: "connected_memory",
+    coverage: null,
+    summary: null,
+    projects: [],
+    other: null,
+    problem
+  };
+}
+function emit(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+
 // src/cli/prompt.ts
 async function readApiKeySecret() {
   if (process.stdin.isTTY) {
@@ -411,7 +761,7 @@ async function loginCommand(opts = {}) {
   const endpoint = normalizeEndpoint(
     opts.endpoint ?? await readExistingEndpoint(provider) ?? DEFAULT_ENDPOINT
   );
-  if (!isHttpUrl(endpoint)) {
+  if (!isHttpUrl2(endpoint)) {
     process.stderr.write(`Error: invalid --endpoint \`${endpoint}\` (expected http(s) URL).
 `);
     return EXIT.USAGE;
@@ -473,7 +823,7 @@ async function readExistingEndpoint(provider) {
 function normalizeEndpoint(input) {
   return input.replace(/\/+$/, "");
 }
-function isHttpUrl(value) {
+function isHttpUrl2(value) {
   try {
     const u = new URL(value);
     return u.protocol === "http:" || u.protocol === "https:";
@@ -500,44 +850,6 @@ ${err.guidance}
   }
 }
 
-// src/mcp/errors.ts
-var RUN_LOGIN = "Run: pyx-mem login";
-var RUN_DOCTOR = "Run: pyx-mem doctor";
-function mcpText(text, isError = false) {
-  return { isError, content: [{ type: "text", text }] };
-}
-function mcpMissingCredentials() {
-  return mcpText(`pyx-memory credentials are not configured.
-${RUN_LOGIN}`, true);
-}
-function mcpKeychainError(message, guidance) {
-  const lines = ["pyx-memory credentials could not be read from the OS credential store."];
-  if (message) lines.push(message);
-  if (guidance) lines.push(guidance);
-  lines.push(RUN_LOGIN);
-  return mcpText(lines.join("\n"), true);
-}
-function mcpAuthFailed(status) {
-  return mcpText(`Authentication failed (HTTP ${status}).
-${RUN_LOGIN}`, true);
-}
-function mcpUnreachable(endpoint, reason) {
-  return mcpText(`Unable to reach pyx-memory at ${endpoint}: ${reason}.
-${RUN_DOCTOR}`, true);
-}
-function mcpHttpError(status, body) {
-  return mcpText(`${status}: ${body}`, true);
-}
-function mcpServerError(status, body) {
-  return mcpText(`pyx-memory server error (HTTP ${status}): ${body || "no body"}`, true);
-}
-function mcpEnvelopeError(message) {
-  return mcpText(message, true);
-}
-function mcpJson(payload) {
-  return mcpText(JSON.stringify(payload));
-}
-
 // src/mcp/credentials.ts
 function createReadCredentials(providerFactory) {
   return async () => {
@@ -557,7 +869,7 @@ function createReadCredentials(providerFactory) {
 }
 
 // src/mcp/proxy-server.ts
-import { createHash, randomUUID as randomUUID2 } from "crypto";
+import { createHash, randomUUID as randomUUID3 } from "crypto";
 import { readFile, stat } from "fs/promises";
 import { basename, isAbsolute, resolve } from "path";
 import { Client as McpClient } from "@modelcontextprotocol/sdk/client/index.js";
@@ -571,130 +883,12 @@ import {
   ListToolsRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
-// src/mcp/http-client.ts
-var DEFAULT_TIMEOUT_MS = 15e3;
-function validateIdempotencyKey(key) {
-  if (key.length === 0 || !key.isWellFormed() || new TextEncoder().encode(key).byteLength > 256) {
-    throw new Error("idempotencyKey must be 1-256 well-formed UTF-8 bytes");
-  }
-  return key;
-}
-function createHttpClient(credentials, fetchImpl = fetch) {
-  const baseUrl = credentials.endpoint.replace(/\/+$/, "");
-  function buildUrl(path, query) {
-    const url = new URL(`${baseUrl}${path}`);
-    if (query) {
-      for (const [k, v] of Object.entries(query)) {
-        if (v === void 0) continue;
-        url.searchParams.set(k, String(v));
-      }
-    }
-    return url.toString();
-  }
-  function buildHeaders(scope, contentType, idempotencyKey) {
-    const headers = new Headers();
-    headers.set("Authorization", `Bearer ${credentials.apiKey}`);
-    headers.set("Accept", "application/json");
-    if (contentType) headers.set("Content-Type", contentType);
-    if (scope?.tenantId) headers.set("X-Tenant-Id", scope.tenantId);
-    if (scope?.namespaceId) headers.set("X-Namespace-Id", scope.namespaceId);
-    if (scope?.userId) headers.set("X-User-Id", scope.userId);
-    if (scope?.teamId) headers.set("X-Team-Id", scope.teamId);
-    if (scope?.callerAccessLevel) headers.set("X-Caller-Access-Level", scope.callerAccessLevel);
-    if (idempotencyKey !== void 0) {
-      headers.set("Idempotency-Key", validateIdempotencyKey(idempotencyKey));
-    }
-    return headers;
-  }
-  async function send(url, method, headers, body) {
-    const ctl = new AbortController();
-    const timer = setTimeout(() => ctl.abort(), DEFAULT_TIMEOUT_MS);
-    let res;
-    try {
-      res = await fetchImpl(url, { method, headers, body, signal: ctl.signal });
-    } catch (err) {
-      return {
-        ok: false,
-        result: mcpUnreachable(baseUrl, err instanceof Error ? err.message : String(err))
-      };
-    } finally {
-      clearTimeout(timer);
-    }
-    if (res.status === 401 || res.status === 403) {
-      return { ok: false, status: res.status, result: mcpAuthFailed(res.status) };
-    }
-    const text = await res.text().catch(() => "");
-    return parseHttpResponse(res, text);
-  }
-  return {
-    async requestJson(input) {
-      const url = buildUrl(input.path, input.query);
-      const hasBody = input.body !== void 0;
-      const headers = buildHeaders(
-        input.scope,
-        hasBody ? "application/json" : void 0,
-        input.idempotencyKey
-      );
-      return send(url, input.method, headers, hasBody ? JSON.stringify(input.body) : void 0);
-    },
-    async requestMultipart(input) {
-      const url = buildUrl(input.path);
-      const headers = buildHeaders(input.scope, void 0, input.idempotencyKey);
-      const form = await input.formData();
-      return send(url, "POST", headers, form);
-    }
-  };
-}
-function parseHttpResponse(res, text) {
-  if (res.status >= 500) {
-    return { ok: false, status: res.status, result: mcpServerError(res.status, text) };
-  }
-  const parsed = parseJsonText(text);
-  if (!parsed.ok) {
-    if (!res.ok) {
-      return {
-        ok: false,
-        status: res.status,
-        result: mcpHttpError(res.status, text || "no body")
-      };
-    }
-    return { ok: true, status: res.status, data: text };
-  }
-  if (!res.ok) {
-    const message = extractEnvelopeError(parsed.value) ?? text ?? `HTTP ${res.status}`;
-    return { ok: false, status: res.status, result: mcpHttpError(res.status, message) };
-  }
-  const envelopeError = extractEnvelopeError(parsed.value);
-  if (envelopeError) {
-    return { ok: false, status: res.status, result: mcpEnvelopeError(envelopeError) };
-  }
-  return { ok: true, status: res.status, data: parsed.value };
-}
-function parseJsonText(text) {
-  if (text.length === 0) return { ok: true, value: void 0 };
-  try {
-    return { ok: true, value: JSON.parse(text) };
-  } catch {
-    return { ok: false };
-  }
-}
-function extractEnvelopeError(parsed) {
-  if (parsed === null || typeof parsed !== "object") return null;
-  const obj = parsed;
-  if (obj.success === false) {
-    if (typeof obj.error === "string") return obj.error;
-    if (typeof obj.message === "string") return obj.message;
-    return "pyx-memory returned success: false";
-  }
-  return null;
-}
-
 // src/mcp/tools/shared.ts
 var LOCAL_UPLOAD_META_KEY = "pyx.dev/local-upload";
 
 // src/mcp/proxy-server.ts
 var REMOTE_MCP_PATH = "/mcp";
-function createMcpIdempotentFetch(fetchImpl = fetch, sessionNonce = randomUUID2()) {
+function createMcpIdempotentFetch(fetchImpl = fetch, sessionNonce = randomUUID3()) {
   const wrapped = async (input, init) => {
     const upstream = input instanceof Request ? input : new Request(String(input), init);
     const method = init?.method ?? upstream.method;
@@ -836,7 +1030,7 @@ function createProxyServer(client, version, uploadLocalFile) {
   return server;
 }
 async function runMcpProxyServer(opts) {
-  const version = opts.version ?? (true ? "1.17.19" : "0.0.0-dev");
+  const version = opts.version ?? (true ? "1.18.0" : "0.0.0-dev");
   const read = await opts.readCredentials();
   if (!read.ok) {
     const text = read.result.content.map((c) => c.type === "text" ? c.text : "").join(" ").trim();
@@ -1541,28 +1735,27 @@ function resolveMcpMode(flags) {
 }
 
 // src/cli/commands/overview.ts
-import { randomUUID as randomUUID3 } from "crypto";
-import { z } from "zod";
+import { z as z2 } from "zod";
 var OVERVIEW_SCHEMA_VERSION = 1;
 var RECENT_ENTRY_LIMIT = 3;
 var MAX_TOPIC_CHARS = 160;
 var MAX_PROJECT_CHARS = 80;
-var entrySchema = z.object({
-  id: z.string().min(1),
-  metadata: z.record(z.string(), z.unknown())
+var entrySchema = z2.object({
+  id: z2.string().min(1),
+  metadata: z2.record(z2.string(), z2.unknown())
 }).passthrough();
-var hostedEntriesResponseSchema = z.object({
-  memories: z.array(entrySchema),
-  total: z.number().int().nonnegative()
+var hostedEntriesResponseSchema = z2.object({
+  memories: z2.array(entrySchema),
+  total: z2.number().int().nonnegative()
 }).passthrough();
-var selfHostedEntriesResponseSchema = z.object({
-  success: z.literal(true),
-  data: z.object({
-    entries: z.array(entrySchema),
-    totalCount: z.number().int().nonnegative()
+var selfHostedEntriesResponseSchema = z2.object({
+  success: z2.literal(true),
+  data: z2.object({
+    entries: z2.array(entrySchema),
+    totalCount: z2.number().int().nonnegative()
   }).passthrough()
 }).passthrough();
-var entriesResponseSchema = z.union([
+var entriesResponseSchema = z2.union([
   hostedEntriesResponseSchema.transform(({ memories, total }) => ({
     entries: memories,
     totalCount: total
@@ -1570,65 +1763,25 @@ var entriesResponseSchema = z.union([
   selfHostedEntriesResponseSchema.transform(({ data }) => data)
 ]);
 async function overviewCommand(opts = {}) {
-  const provider = opts.keychain ?? getDefaultKeychain();
-  let credentials;
-  try {
-    credentials = await provider.read();
-  } catch (error) {
-    const detail = error instanceof KeychainError ? [error.message, error.guidance].filter(Boolean).join(" ") : "The OS credential store could not be read.";
-    emit(report("error", null, null, detail));
-    return error instanceof KeychainError ? error.exit : EXIT.CRED_UNAVAILABLE;
-  }
-  if (!credentials) {
-    emit(report("signed_out", null, null, null));
-    return EXIT.NOT_LOGGED_IN;
-  }
-  if (!isHttpUrl2(credentials.endpoint)) {
-    emit(
-      report(
-        "error",
-        null,
-        "keychain",
-        "The stored pyx-memory endpoint is invalid. Run: pyx-mem login"
-      )
-    );
-    return EXIT.DOCTOR_FAIL;
-  }
-  const http = createHttpClient(credentials, opts.fetchImpl ?? fetch);
-  const response = await http.requestJson({
-    method: "GET",
-    path: "/api/memory/entries",
-    query: { status: "active", limit: RECENT_ENTRY_LIMIT },
-    idempotencyKey: `cli-overview-${randomUUID3()}`
+  const result = await readSurface({
+    surface: "overview",
+    request: {
+      method: "GET",
+      path: "/api/memory/entries",
+      query: { status: "active", limit: RECENT_ENTRY_LIMIT }
+    },
+    schema: entriesResponseSchema,
+    keychain: opts.keychain,
+    fetchImpl: opts.fetchImpl
   });
-  if (!response.ok) {
-    const signedOut = response.status === 401;
-    emit(
-      report(
-        signedOut ? "signed_out" : "error",
-        credentials.endpoint,
-        "keychain",
-        overviewFailure(response.status)
-      )
-    );
-    return signedOut ? EXIT.NOT_LOGGED_IN : EXIT.DOCTOR_FAIL;
-  }
-  const parsed = entriesResponseSchema.safeParse(response.data);
-  if (!parsed.success) {
-    emit(
-      report(
-        "error",
-        credentials.endpoint,
-        "keychain",
-        "pyx-memory returned an invalid overview response. Run: pyx-mem doctor"
-      )
-    );
-    return EXIT.DOCTOR_FAIL;
-  }
-  emit({
-    ...report("ready", credentials.endpoint, "keychain", null),
-    totalCount: parsed.data.totalCount,
-    entries: parsed.data.entries.slice(0, RECENT_ENTRY_LIMIT).map((entry) => ({
+  if (!result.ok) {
+    emit2(report2(result.state, result.endpoint, result.keySource, result.problem));
+    return result.exit;
+  }
+  emit2({
+    ...report2("ready", result.endpoint, "keychain", null),
+    totalCount: result.data.totalCount,
+    entries: result.data.entries.slice(0, RECENT_ENTRY_LIMIT).map((entry) => ({
       id: entry.id,
       topic: boundedLabel(entry.metadata.topic, "Untitled", MAX_TOPIC_CHARS),
       project: boundedLabel(entry.metadata.project, "Unscoped", MAX_PROJECT_CHARS)
@@ -1636,7 +1789,7 @@ async function overviewCommand(opts = {}) {
   });
   return EXIT.OK;
 }
-function report(state, endpoint, keySource, problem) {
+function report2(state, endpoint, keySource, problem) {
   return {
     schemaVersion: OVERVIEW_SCHEMA_VERSION,
     state,
@@ -1647,39 +1800,16 @@ function report(state, endpoint, keySource, problem) {
     problem
   };
 }
-function emit(value) {
+function emit2(value) {
   process.stdout.write(`${JSON.stringify(value)}
 `);
 }
-function overviewFailure(status) {
-  if (status === 401) {
-    return "Stored pyx-memory credentials were rejected. Run: pyx-mem login";
-  }
-  if (status === 403) {
-    return "pyx-memory denied access (HTTP 403). Check the key scope and project access.";
-  }
-  if (status === void 0) {
-    return "Unable to reach pyx-memory. Run: pyx-mem doctor";
-  }
-  if (status >= 500) {
-    return `pyx-memory is unavailable (HTTP ${status}). Run: pyx-mem doctor`;
-  }
-  return `pyx-memory overview failed (HTTP ${status}). Run: pyx-mem doctor`;
-}
 function boundedLabel(value, fallback, maxChars) {
   if (typeof value !== "string" || value.trim().length === 0) return fallback;
   const normalized = value.trim();
   const chars = [...normalized];
   return chars.length > maxChars ? `${chars.slice(0, maxChars).join("")}\u2026` : normalized;
 }
-function isHttpUrl2(value) {
-  try {
-    const url = new URL(value);
-    return url.protocol === "http:" || url.protocol === "https:";
-  } catch {
-    return false;
-  }
-}
 
 // src/cli/commands/scaffold.ts
 import { existsSync as existsSync4, mkdirSync as mkdirSync3, statSync as statSync2, writeFileSync as writeFileSync3 } from "fs";
@@ -1861,10 +1991,10 @@ function scaffoldCommand(args = {}) {
 // src/cli/commands/status.ts
 async function statusCommand(opts = {}) {
   const provider = opts.keychain ?? getDefaultKeychain();
-  let report2;
+  let report4;
   try {
     const creds = await provider.read();
-    report2 = {
+    report4 = {
       endpoint: creds?.endpoint ?? null,
       keyPresent: creds !== null,
       keySource: creds !== null ? "keychain" : null,
@@ -1875,17 +2005,17 @@ async function statusCommand(opts = {}) {
     throw err;
   }
   if (opts.json) {
-    process.stdout.write(`${JSON.stringify(report2)}
+    process.stdout.write(`${JSON.stringify(report4)}
 `);
   } else {
     const lines = [
-      `endpoint:    ${report2.endpoint ?? "(not set)"}`,
-      `credentials: ${report2.loggedIn ? "present (keychain)" : "not logged in \u2014 run: pyx-mem login"}`
+      `endpoint:    ${report4.endpoint ?? "(not set)"}`,
+      `credentials: ${report4.loggedIn ? "present (keychain)" : "not logged in \u2014 run: pyx-mem login"}`
     ];
     process.stdout.write(`${lines.join("\n")}
 `);
   }
-  return report2.loggedIn ? EXIT.OK : EXIT.NOT_LOGGED_IN;
+  return report4.loggedIn ? EXIT.OK : EXIT.NOT_LOGGED_IN;
 }
 function emitError(err, json) {
   if (json) {
@@ -1901,6 +2031,76 @@ ${err.guidance}
   return err.exit;
 }
 
+// src/cli/commands/taxonomy.ts
+import { z as z3 } from "zod";
+var TAXONOMY_SCHEMA_VERSION = 1;
+var taxonomyStateSchema = z3.object({
+  clusters: z3.array(
+    z3.object({
+      size: z3.number().int().nonnegative(),
+      currentName: z3.string().nullable(),
+      categoryNodeId: z3.string().nullable(),
+      projects: z3.array(
+        z3.object({
+          name: z3.string().min(1).max(MEMORY_PROJECT_LABEL_MAX_CHARS),
+          memories: z3.number().int().positive()
+        })
+      ).max(TAXONOMY_MAX_PROJECTS),
+      sampleTopics: z3.array(z3.string()).max(TAXONOMY_MAX_SAMPLE_TOPICS),
+      topEntities: z3.array(
+        z3.object({
+          name: z3.string(),
+          type: z3.string(),
+          degree: z3.number().int().nonnegative()
+        })
+      ).max(TAXONOMY_MAX_TOP_ENTITIES)
+    })
+  ).max(TAXONOMY_MAX_CATEGORIES),
+  totals: z3.object({
+    clusters: z3.number().int().nonnegative(),
+    unnamed: z3.number().int().nonnegative(),
+    nodesConsidered: z3.number().int().nonnegative()
+  })
+});
+var taxonomyResponseSchema = z3.union([
+  taxonomyStateSchema,
+  z3.object({ success: z3.literal(true), data: taxonomyStateSchema }).transform(({ data }) => data)
+]);
+async function taxonomyCommand(opts = {}) {
+  const result = await readSurface({
+    surface: "taxonomy",
+    request: { method: "GET", path: "/api/memory/graph/taxonomy" },
+    schema: taxonomyResponseSchema,
+    keychain: opts.keychain,
+    fetchImpl: opts.fetchImpl
+  });
+  if (!result.ok) {
+    emit3(report3(result.state, result.endpoint, result.keySource, result.problem));
+    return result.exit;
+  }
+  emit3({
+    ...report3("ready", result.endpoint, "keychain", null),
+    clusters: result.data.clusters,
+    totals: result.data.totals
+  });
+  return EXIT.OK;
+}
+function report3(state, endpoint, keySource, problem) {
+  return {
+    schemaVersion: TAXONOMY_SCHEMA_VERSION,
+    state,
+    endpoint,
+    keySource,
+    clusters: [],
+    totals: { clusters: 0, unnamed: 0, nodesConsidered: 0 },
+    problem
+  };
+}
+function emit3(value) {
+  process.stdout.write(`${JSON.stringify(value)}
+`);
+}
+
 // src/cli/help.ts
 var HELP_TEXT = `pyx-mem \u2014 pyx-memory CLI
 
@@ -1911,6 +2111,8 @@ Commands:
   login [--endpoint <url>] [--api-key <key>]   Store endpoint and API key in OS credential store.
   status [--json]                              Show endpoint, key presence, MCP config status.
   overview --json                              Read memory count and three recent safe labels.
+  insights --json                              Read body-free memory usage and coverage aggregates.
+  taxonomy --json                              Read knowledge-graph cluster composition (read-only).
   logout                                       Delete stored pyx-memory credentials.
   doctor [--json]                              Diagnose keychain, credentials, backend, MCP startup.
   scaffold [--name <dir>]                      Generate Docker, env, SDK, and memory design-guide starter files.
@@ -2063,6 +2265,18 @@ async function main() {
         return EXIT.USAGE;
       }
       return overviewCommand();
+    case "insights":
+      if (parsed.flags.json !== true) {
+        process.stderr.write("Error: `pyx-mem insights` requires --json.\n");
+        return EXIT.USAGE;
+      }
+      return insightsCommand();
+    case "taxonomy":
+      if (parsed.flags.json !== true) {
+        process.stderr.write("Error: `pyx-mem taxonomy` requires --json.\n");
+        return EXIT.USAGE;
+      }
+      return taxonomyCommand();
     case "logout":
       return logoutCommand();
     case "doctor":