pi-mega-compact 0.11.4 → 0.11.6

package/extensions/dashboard-client/src/tabs/SetupTab.tsx

@@ -0,0 +1,418 @@
+/**
+ * dashboard-client/src/tabs/SetupTab.tsx — Setup wizard tab (P0b).
+ *
+ * Shows current embedder configuration, warns about trigram recall quality,
+ * and mirrors the /megasetup command with detection results.
+ *
+ * PREVENT-PI-004: all data comes from localhost dashboard API endpoints —
+ * no external network calls.
+ */
+
+import type React from "react";
+import { useState, useEffect, useCallback } from "react";
+import type { SetupStatusResponse, SetupDetectResponse, SetupConfigureResponse } from "@contracts";
+import { fetchSetupStatus, fetchSetupDetect, configureEmbedder } from "../api/client";
+
+// ---------------------------------------------------------------------------
+// Style constants
+// ---------------------------------------------------------------------------
+
+const styles: Record<string, React.CSSProperties> = {
+	container: {
+		padding: "1rem",
+		maxWidth: "720px",
+		margin: "0 auto",
+		fontFamily: "system-ui, sans-serif",
+		color: "#e0e0e0",
+	},
+	section: {
+		background: "#1a1a2e",
+		borderRadius: "8px",
+		padding: "1rem",
+		marginBottom: "1rem",
+		border: "1px solid #2a2a4e",
+	},
+	sectionTitle: {
+		fontSize: "1.1rem",
+		fontWeight: 700,
+		marginTop: 0,
+		marginBottom: "0.75rem",
+		color: "#e0e0e0",
+		borderBottom: "1px solid #333",
+		paddingBottom: "0.5rem",
+	},
+	label: { fontWeight: 600, color: "#a0a0c0", marginRight: "0.5rem" },
+	value: { color: "#e0e0e0" },
+	row: { marginBottom: "0.4rem", fontSize: "0.9rem" },
+	warning: {
+		background: "#3a2a00",
+		border: "1px solid #665500",
+		borderRadius: "8px",
+		padding: "0.75rem",
+		marginTop: "0.5rem",
+		color: "#ffcc00",
+		fontSize: "0.85rem",
+	},
+	badge: {
+		display: "inline-block",
+		padding: "0.15rem 0.5rem",
+		borderRadius: "4px",
+		fontSize: "0.8rem",
+		fontWeight: 600,
+		marginLeft: "0.5rem",
+	},
+	detectRow: {
+		display: "flex",
+		justifyContent: "space-between",
+		alignItems: "center",
+		padding: "0.5rem 0",
+		borderBottom: "1px solid #2a2a4e",
+	},
+	button: {
+		background: "#3a5a9f",
+		color: "#fff",
+		border: "none",
+		borderRadius: "6px",
+		padding: "0.5rem 1rem",
+		cursor: "pointer",
+		fontSize: "0.9rem",
+		fontWeight: 600,
+	},
+};
+
+// ---------------------------------------------------------------------------
+// SetupTab component
+// ---------------------------------------------------------------------------
+
+export default function SetupTab(): React.ReactElement {
+	const [status, setStatus] = useState<SetupStatusResponse | null>(null);
+	const [detect, setDetect] = useState<SetupDetectResponse | null>(null);
+	const [statusError, setStatusError] = useState<string | null>(null);
+	const [detectError, setDetectError] = useState<string | null>(null);
+	const [runningDetect, setRunningDetect] = useState(false);
+	const [configuring, setConfiguring] = useState<string | null>(null);
+	const [configResult, setConfigResult] = useState<SetupConfigureResponse | null>(null);
+	const [configError, setConfigError] = useState<string | null>(null);
+
+	const applyEmbedder = useCallback((embedder: "ollama" | "llama" | "trigram") => {
+		setConfiguring(embedder);
+		setConfigError(null);
+		setConfigResult(null);
+		configureEmbedder({ embedder })
+			.then((r) => {
+				setConfigResult(r);
+				setConfiguring(null);
+				loadStatus();
+			})
+			.catch((e: unknown) => {
+				setConfigError(e instanceof Error ? e.message : String(e));
+				setConfiguring(null);
+			});
+	}, [loadStatus]);
+
+	const loadStatus = useCallback(() => {
+		fetchSetupStatus()
+			.then(setStatus)
+			.catch((e: unknown) =>
+				setStatusError(e instanceof Error ? e.message : String(e)),
+			);
+	}, []);
+
+	const runDetect = useCallback(() => {
+		setRunningDetect(true);
+		setDetectError(null);
+		fetchSetupDetect()
+			.then((d) => {
+				setDetect(d);
+				setRunningDetect(false);
+			})
+			.catch((e: unknown) => {
+				setDetectError(e instanceof Error ? e.message : String(e));
+				setRunningDetect(false);
+			});
+	}, []);
+
+	useEffect(() => {
+		loadStatus();
+	}, [loadStatus]);
+
+	// Poll status every 30s
+	useEffect(() => {
+		const id = setInterval(loadStatus, 30000);
+		return () => clearInterval(id);
+	}, [loadStatus]);
+
+	// -----------------------------------------------------------------------
+	// Render helpers
+	// -----------------------------------------------------------------------
+
+	const embedderLabel = (e: string): string => {
+		switch (e) {
+			case "trigram":
+				return "TrigramEmbedder (heuristic, default)";
+			case "http":
+				return "HTTP Embedder (BYO localhost)";
+			case "minilm":
+				return "MiniLM (experimental)";
+			default:
+				return "Unknown";
+		}
+	};
+
+	const trigramWarning = status?.currentEmbedder === "trigram" && (
+		<div style={styles.warning}>
+			<strong>Note:</strong> TrigramEmbedder is a heuristic-strength default
+			embedder. It works without any setup but recall quality may be lower
+			than a dedicated embedding backend. If you notice poor recall results,
+			consider installing Ollama and running the{" "}
+			<code>/megasetup</code> command, or set{" "}
+			<code>MEGACOMPACT_EMBEDDING_URL</code> to point at your own localhost
+			embedding server.
+		</div>
+	);
+
+	const detectBadge = (installed: boolean): React.ReactElement => {
+		const bg = installed ? "#1a5a1a" : "#3a1a1a";
+		const color = installed ? "#4caf50" : "#f44336";
+		return (
+			<span style={{ ...styles.badge, background: bg, color }}>
+				{installed ? "Detected" : "Not found"}
+			</span>
+		);
+	};
+
+	// -----------------------------------------------------------------------
+	// Main render
+	// -----------------------------------------------------------------------
+
+	return (
+		<div style={styles.container}>
+			<h2 style={{ fontSize: "1.3rem", marginTop: 0, marginBottom: "1rem" }}>
+				Embedder Setup
+			</h2>
+
+			{/* Current Config Section */}
+			<div style={styles.section}>
+				<h3 style={styles.sectionTitle}>Current Embedder Configuration</h3>
+				{statusError && (
+					<p style={{ color: "#f44336", fontSize: "0.85rem" }}>
+						Error: {statusError}
+					</p>
+				)}
+				{status && (
+					<>
+						<div style={styles.row}>
+							<span style={styles.label}>Active Embedder:</span>
+							<span style={styles.value}>
+								{embedderLabel(status.currentEmbedder)}
+							</span>
+						</div>
+						<div style={styles.row}>
+							<span style={styles.label}>Embedding URL:</span>
+							<span style={styles.value}>
+								{status.embeddingUrl ?? (
+									<span style={{ color: "#888" }}>not set</span>
+								)}
+							</span>
+						</div>
+						<div style={styles.row}>
+							<span style={styles.label}>Embed Cache:</span>
+							<span style={styles.value}>
+								{status.embedCache ?? (
+									<span style={{ color: "#888" }}>not set</span>
+								)}
+							</span>
+						</div>
+						<div style={styles.row}>
+							<span style={styles.label}>MiniLM:</span>
+							<span style={styles.value}>{status.minilm ? "enabled" : "disabled"}</span>
+						</div>
+						{trigramWarning}
+					</>
+				)}
+				{!status && !statusError && (
+					<p style={{ color: "#888", fontSize: "0.85rem" }}>
+						Loading configuration...
+					</p>
+				)}
+			</div>
+
+			{/* Detection Section */}
+			<div style={styles.section}>
+				<h3 style={styles.sectionTitle}>Local Embedder Detection</h3>
+				<p style={{ fontSize: "0.85rem", color: "#a0a0c0", marginTop: 0 }}>
+					Detect which local embedding backends are available on this machine.
+					No software is installed — detection only.
+				</p>
+
+				{detect && (
+					<>
+						{/* Ollama */}
+						<div style={styles.detectRow}>
+							<span>
+								<strong>Ollama</strong>
+							</span>
+							{detect.ollama !== null ? (
+								<span>
+									{detectBadge(detect.ollama.installed)}
+									{detect.ollama.installed && (
+										<span style={{ fontSize: "0.8rem", color: "#a0a0c0", marginLeft: "0.5rem" }}>
+											{detect.ollama.running
+												? `server running, ${detect.ollama.models.length} model(s)`
+												: "server not running"}
+										</span>
+									)}
+								</span>
+							) : (
+								<span style={{ color: "#888", fontSize: "0.85rem" }}>
+									not checked
+								</span>
+							)}
+						</div>
+
+						{/* llama.cpp */}
+						<div style={styles.detectRow}>
+							<span>
+								<strong>llama.cpp</strong>
+							</span>
+							{detect.llamaCpp !== null ? (
+								<span>
+									{detectBadge(detect.llamaCpp.installed)}
+									{detect.llamaCpp.installed && detect.llamaCpp.detail && (
+										<span style={{ fontSize: "0.8rem", color: "#a0a0c0", marginLeft: "0.5rem" }}>
+											{detect.llamaCpp.detail}
+										</span>
+									)}
+								</span>
+							) : (
+								<span style={{ color: "#888", fontSize: "0.85rem" }}>
+									not checked
+								</span>
+							)}
+						</div>
+
+						{/* ONNX */}
+						<div style={styles.detectRow}>
+							<span>
+								<strong>ONNX Runtime</strong>
+							</span>
+							{detect.onnx !== null ? (
+								<span>
+									{detectBadge(detect.onnx.installed)}
+									{detect.onnx.installed && detect.onnx.detail && (
+										<span style={{ fontSize: "0.8rem", color: "#a0a0c0", marginLeft: "0.5rem" }}>
+											{detect.onnx.detail}
+										</span>
+									)}
+								</span>
+							) : (
+								<span style={{ color: "#888", fontSize: "0.85rem" }}>
+									not checked
+								</span>
+							)}
+						</div>
+
+						{detect.error && (
+							<p style={{ color: "#f44336", fontSize: "0.8rem", marginTop: "0.5rem" }}>
+								Detection error: {detect.error}
+							</p>
+						)}
+					</>
+				)}
+
+				{detectError && (
+					<p style={{ color: "#f44336", fontSize: "0.85rem" }}>
+						Error: {detectError}
+					</p>
+				)}
+
+				<div style={{ marginTop: "1rem" }}>
+					<button
+						style={styles.button}
+						onClick={runDetect}
+						disabled={runningDetect}
+					>
+						{runningDetect ? "Detecting..." : "Run Detection"}
+					</button>
+					<span style={{ fontSize: "0.8rem", color: "#888", marginLeft: "0.75rem" }}>
+						Or run <code>/megasetup</code> in the chat for an interactive wizard.
+					</span>
+				</div>
+
+				{/* Configure buttons — appear after detection runs */}
+				{detect && (
+					<div style={{ marginTop: "1rem", paddingTop: "0.75rem", borderTop: "1px solid #2a2a4e" }}>
+						<div style={{ fontSize: "0.9rem", fontWeight: 600, marginBottom: "0.5rem" }}>
+							Configure
+						</div>
+						<div style={{ display: "flex", gap: "0.5rem", flexWrap: "wrap" }}>
+							<button
+								style={{ ...styles.button, opacity: detect.ollama?.installed ? 1 : 0.4 }}
+								onClick={() => applyEmbedder("ollama")}
+								disabled={!detect.ollama?.installed || configuring !== null}
+							>
+								{configuring === "ollama" ? "Writing..." : "Use Ollama"}
+							</button>
+							<button
+								style={{ ...styles.button, opacity: detect.llamaCpp?.installed ? 1 : 0.4 }}
+								onClick={() => applyEmbedder("llama")}
+								disabled={!detect.llamaCpp?.installed || configuring !== null}
+							>
+								{configuring === "llama" ? "Writing..." : "Use llama.cpp"}
+							</button>
+							<button
+								style={{ ...styles.button, background: "#444" }}
+								onClick={() => applyEmbedder("trigram")}
+								disabled={configuring !== null}
+							>
+								{configuring === "trigram" ? "Writing..." : "Use Trigram (default)"}
+							</button>
+						</div>
+						{configResult && (
+							<div style={styles.warning}>
+								{configResult.alreadyActive
+									? "Already active — no restart needed."
+									: `Configured ${configResult.embedder}. Restart pi to activate (config written to ${configResult.envPath}).`}
+							</div>
+						)}
+						{configError && (
+							<p style={{ color: "#f44336", fontSize: "0.85rem", marginTop: "0.5rem" }}>
+								Configure error: {configError}
+							</p>
+						)}
+					</div>
+				)}
+			</div>
+
+			{/* Help Section */}
+			<div style={styles.section}>
+				<h3 style={styles.sectionTitle}>How to Upgrade</h3>
+				<ul style={{ fontSize: "0.85rem", lineHeight: 1.6, paddingLeft: "1.25rem" }}>
+					<li>
+						<strong>Ollama:</strong> Install from{" "}
+						<a
+							href="https://ollama.com"
+							style={{ color: "#6a9fff" }}
+							target="_blank"
+							rel="noopener noreferrer"
+						>
+							ollama.com
+						</a>
+						, then <code>ollama pull nomic-embed-text</code> and restart pi.
+						Set <code>MEGACOMPACT_EMBEDDING_URL=http://localhost:11434/api/embeddings</code>.
+					</li>
+					<li>
+						<strong>llama.cpp:</strong> Build or install llama.cpp, run{" "}
+						<code>llama-server</code> with an embedding model, and set
+						the URL accordingly.
+					</li>
+					<li>
+						<strong>ONNX Runtime:</strong> Install{" "}
+						<code>onnxruntime-node</code> in the project root. Not yet
+						integrated — see docs for manual setup.
+					</li>
+				</ul>
+			</div>
+		</div>
+	);
+}

package/extensions/dashboard-client/tsconfig.json

@@ -20,9 +20,10 @@
     "baseUrl": ".",
     "paths": {
       "@/*": ["./src/*"],
-      "@contracts": ["../dashboard-server/api-contracts/index.ts"]
+      "@contracts": ["../dashboard-server/api-contracts/index.ts"],
+      "@pricing": ["../../src/pricing.ts"]
     }
   },
-  "include": ["src/**/*.ts", "src/**/*.tsx"],
+  "include": ["src/**/*.ts", "src/**/*.tsx", "../../src/pricing.ts"],
   "exclude": ["node_modules", "dist"]
 }

package/extensions/dashboard-client/vite.config.ts

@@ -33,6 +33,8 @@ export default defineConfig({
 			"@contracts": fileURLToPath(
 				new URL("../dashboard-server/api-contracts", import.meta.url),
 			),
+			// Shared pricing module (computeCacheSavings, constants).
+			"@pricing": fileURLToPath(new URL("../../src/pricing.ts", import.meta.url)),
 		},
 	},
 });

package/extensions/dashboard-server/api-contracts/cache-stripes.ts

@@ -0,0 +1,49 @@
+/**
+ * api-contracts/cache-stripes.ts — Cache stripe API contract (A3, PLAN_V2 Phase 4).
+ *
+ * Response shape for GET /api/cache-stripes: per-stripe distribution counts,
+ * average stability, and a top-level health score. Loopback-only data;
+ * zero network (PREVENT-PI-004).
+ */
+
+/** A single stripe bucket with aggregate metadata. */
+export interface StripeBucket {
+	/** Stripe index 0–4 (0=permanent, 1=epoch, 2=topic, 3=thread, 4=volatile). */
+	readonly stripe: number;
+	/** Human-readable label for this stripe. */
+	readonly label: string;
+	/** Number of chunks assigned to this stripe. */
+	readonly count: number;
+	/** Average stability score (0.0–1.0) within this stripe. */
+	readonly avgStability: number;
+	/** Minimum stability in this stripe. */
+	readonly minStability: number;
+	/** Maximum stability in this stripe. */
+	readonly maxStability: number;
+}
+
+/** Overall cache health assessment. */
+export interface CacheHealthScore {
+	/** Composite health score 0.0–1.0 (1.0 = perfect). */
+	readonly score: number;
+	/** Human-readable label: "good" | "fair" | "degraded" | "poor". */
+	readonly label: string;
+	/** Dominant stability tier fraction. */
+	readonly dominantTier: number;
+	/** Stripe churn rate (0.0–1.0) — fraction of assignments changed since last epoch. */
+	readonly churnRate: number;
+}
+
+/** Response body for GET /api/cache-stripes. */
+export interface CacheStripesResponse {
+	/** Per-stripe bucket arrays (always 5 entries, stripes 0–4). */
+	readonly buckets: StripeBucket[];
+	/** Overall health assessment. */
+	readonly health: CacheHealthScore;
+	/** Epoch id these assignments belong to. */
+	readonly epochId: string | null;
+	/** Timestamp (epoch ms) of the last refresh. */
+	readonly lastRefreshAt: number;
+	/** Total chunk count across all stripes. */
+	readonly totalChunks: number;
+}

package/extensions/dashboard-server/api-contracts/endpoints.ts

@@ -15,6 +15,8 @@ import type { IndexesIndexRow, IndexesSummaryResponse } from "./multi-repo.js";
 import type { GameStateResponse } from "./game.js";
 import type { SseEvent } from "./index.js";
 import type { ProviderCacheResponse } from "./provider-cache.js";
+import type { MemoryStatusResponse } from "./memory.js";
+import type { SetupStatusResponse, SetupDetectResponse, SetupConfigureRequest, SetupConfigureResponse } from "./setup.js";
 import type {
 	TurnsResponse,
 	ConversationTurnsResponse,
@@ -34,6 +36,8 @@ import type {
 	SchemaHealthResponse,
 } from "./maintenance.js";
 
+import type { CacheStripesResponse } from "./cache-stripes.js";
+
 import type {
 	GameScoreRow,
 	GameScoresQuery,
@@ -298,6 +302,14 @@ export interface PerfLatest {
 	readonly n: number;
 }
 
+/** A single cache hit rate sample with timestamp. */
+export interface CacheHitSample {
+	/** Cache hit percentage (0–100). */
+	readonly pct: number;
+	/** Epoch ms timestamp of the sample. */
+	readonly ts: number;
+}
+
 /** Average + latest statistics for cache hit percentage. */
 export interface PerfCacheHit {
 	/** Average cache hit percentage (0–100). */
@@ -306,6 +318,8 @@ export interface PerfCacheHit {
 	readonly latest: number;
 	/** Number of samples in the window. */
 	readonly n: number;
+	/** Raw cache hit samples with timestamps for time-series charting. */
+	readonly samples: CacheHitSample[];
 }
 
 /** Diagnostic counters from the live dashboard snapshot. */
@@ -586,15 +600,21 @@ export const ENDPOINTS = {
 	schemaHealth: {
 		method: "GET",
 		path: "/api/maintenance/schema-health",
-		description: "SCHEMA_VERSION, PRAGMA integrity_check, FK check, and per-column audit.",
+		description:
+			"SCHEMA_VERSION, PRAGMA integrity_check, FK check, and per-column audit.",
 	} as const satisfies EndpointDef<"GET", undefined, SchemaHealthResponse>,
 
 	/** POST /api/maintenance/action — Trigger a maintenance action. */
 	maintenanceAction: {
 		method: "POST",
 		path: "/api/maintenance/action",
-		description: "Run vacuum, checkpoint, reindex, fts5-rebuild, reconcile-dedup, prune, or integrity-check.",
-	} as const satisfies EndpointDef<"POST", MaintenanceAction, MaintenanceActionResult>,
+		description:
+			"Run vacuum, checkpoint, reindex, fts5-rebuild, reconcile-dedup, prune, or integrity-check.",
+	} as const satisfies EndpointDef<
+		"POST",
+		MaintenanceAction,
+		MaintenanceActionResult
+	>,
 
 	// ─── Provider Cache (Sprint A.2) ─────────────────────────────────
 
@@ -606,4 +626,47 @@ export const ENDPOINTS = {
 			"Lifetime provider prompt cache hit-rate aggregates + dollar savings estimate.",
 	} as const satisfies EndpointDef<"GET", undefined, ProviderCacheResponse>,
 
+
+		// ─── A3 Cache Stripes (PLAN_V2 Phase 4) ───────────────────────────
+
+		/** GET /api/cache-stripes — Per-stripe distribution + health score. */
+		cacheStripes: {
+			method: "GET",
+			path: "/api/cache-stripes",
+			description:
+				"Per-stripe distribution counts, average stability scores, and composite cache health.",
+		} as const satisfies EndpointDef<"GET", undefined, CacheStripesResponse>,
+	// ─── Memory Effectiveness (S53B) ───────────────────────────────────────
+
+	/** GET /api/memory-status — Memory store aggregate statistics. */
+	memoryStatus: {
+		method: "GET",
+		path: "/api/memory-status",
+		description:
+			"Memory store statistics: total count, 30-day window, top-N stable memories, avg recall score.",
+	} as const satisfies EndpointDef<"GET", undefined, MemoryStatusResponse>,
+
+	/** GET /api/setup-status — Current embedder configuration. */
+	setupStatus: {
+		method: "GET",
+		path: "/api/setup-status",
+		description:
+			"Current embedder configuration (which embedder is active, embedding URL, cache, MiniLM flag).",
+	} as const satisfies EndpointDef<"GET", undefined, SetupStatusResponse>,
+
+	/** GET /api/setup-detect — Detect available local embedder backends. */
+	setupDetect: {
+		method: "GET",
+		path: "/api/setup-detect",
+		description:
+			"Best-effort detection of local embedder backends (ollama, llama.cpp, ONNX) available on the machine.",
+	} as const satisfies EndpointDef<"GET", undefined, SetupDetectResponse>,
+
+	/** POST /api/setup-configure — Write embedder config to .mega-compact.env. */
+	setupConfigure: {
+		method: "POST",
+		path: "/api/setup-configure",
+		description:
+			"Write the chosen embedder configuration to .mega-compact.env (loaded at next startup). Returns whether a restart is required.",
+	} as const satisfies EndpointDef<"POST", SetupConfigureRequest, SetupConfigureResponse>,
 } as const;

package/extensions/dashboard-server/api-contracts/index.ts

@@ -147,6 +147,7 @@ export type {
 export type {
 	ProviderCacheSavings,
 	ProviderCacheResponse,
+	ProviderCacheByModel,
 } from "./provider-cache.js";
 
 export { ENDPOINTS } from "./endpoints.js";
@@ -202,3 +203,24 @@ export type {
 	PruneTurnsResponse,
 	TopicMemoriesResponse,
 } from "./turns.js";
+
+// S53B — memory effectiveness stats
+export type { MemoryStatusResponse, MemoryStatsTopMemory } from "./memory.js";
+
+// Setup wizard — embedder configuration + backend detection
+export type { SetupStatusResponse, SetupDetectResponse, SetupConfigureRequest, SetupConfigureResponse, DetectResult, OllamaDetectResult } from "./setup.js";
+
+// S46 — memory graph (visual memory map)
+export type {
+	MemoryMapResponse,
+	MemoryMapNode,
+	MemoryMapEdgeEntry,
+	MemoryMapQuery,
+} from "./memory-map.js";
+
+// A3 — cache stripe distribution + health
+export type {
+	StripeBucket,
+	CacheHealthScore,
+	CacheStripesResponse,
+} from "./cache-stripes.js";

package/extensions/dashboard-server/api-contracts/memory-map.ts

@@ -0,0 +1,50 @@
+/**
+ * api-contracts/memory-map.ts — Memory graph API contract (S46).
+ *
+ * Response shape for GET /api/memory-map: graph nodes, edges, and metadata.
+ * This is a read-only JSON payload consumed by the MemoryMapTab React component.
+ */
+import type { GraphMetadata } from "../../../src/memoryGraph.js";
+
+/**
+ * Query parameters for GET /api/memory-map.
+ * All fields are optional.
+ */
+export interface MemoryMapQuery {
+  /** Filter to a single session ID. */
+  readonly sessionId?: string;
+  /** Cosine similarity threshold (0..1). Default 0.7. */
+  readonly threshold?: number;
+  /** Max semantic edges per node. Default 3. */
+  readonly maxEdgesPerNode?: number;
+}
+
+/** Response body for GET /api/memory-map. */
+export interface MemoryMapResponse {
+  readonly nodes: MemoryMapNode[];
+  readonly edges: MemoryMapEdgeEntry[];
+  readonly metadata: GraphMetadata;
+}
+
+/** A node in the response (client-safe subset — no full embedding vector). */
+export interface MemoryMapNode {
+  readonly id: string;
+  readonly sessionId: string;
+  readonly label: string;
+  readonly summaryTruncated: string;
+  readonly tokenEstimate: number;
+  readonly timestamp: number;
+  readonly dedupStatus: string | undefined;
+  readonly raptorLevel: number;
+  readonly topicSummary: string | undefined;
+  readonly decisionCount: number;
+  readonly textSnippet: string;
+}
+
+/** An edge entry in the response. */
+export interface MemoryMapEdgeEntry {
+  readonly source: string;
+  readonly target: string;
+  readonly weight: number;
+  readonly type: "temporal" | "semantic" | "raptor_parent";
+}