pi-mega-compact 0.11.5 → 0.11.6

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

@@ -16,7 +16,7 @@ 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 } from "./setup.js";
+import type { SetupStatusResponse, SetupDetectResponse, SetupConfigureRequest, SetupConfigureResponse } from "./setup.js";
 import type {
 	TurnsResponse,
 	ConversationTurnsResponse,
@@ -36,6 +36,8 @@ import type {
 	SchemaHealthResponse,
 } from "./maintenance.js";
 
+import type { CacheStripesResponse } from "./cache-stripes.js";
+
 import type {
 	GameScoreRow,
 	GameScoresQuery,
@@ -300,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). */
@@ -308,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. */
@@ -614,6 +626,16 @@ 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. */
@@ -639,4 +661,12 @@ export const ENDPOINTS = {
 		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

@@ -208,4 +208,19 @@ export type {
 export type { MemoryStatusResponse, MemoryStatsTopMemory } from "./memory.js";
 
 // Setup wizard — embedder configuration + backend detection
-export type { SetupStatusResponse, SetupDetectResponse, DetectResult, OllamaDetectResult } from "./setup.js";
+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";
+}

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

@@ -56,3 +56,25 @@ export interface SetupDetectResponse {
   /** Error message if detection itself failed, or null. */
   readonly error: string | null;
 }
+
+/** Request body for POST /api/setup-configure. */
+export interface SetupConfigureRequest {
+  /** Which embedder to configure. "trigram" clears the URL (uses built-in). */
+  readonly embedder: "ollama" | "llama" | "trigram";
+  /** Optional override URL (for non-default Ollama ports or llama.cpp). */
+  readonly url?: string;
+}
+
+/** Response for POST /api/setup-configure. */
+export interface SetupConfigureResponse {
+  /** The embedder that was configured. */
+  readonly embedder: string;
+  /** The URL that was written (null for trigram). */
+  readonly url: string | null;
+  /** Path to the .mega-compact.env file that was written. */
+  readonly envPath: string;
+  /** Whether the user needs to restart pi to activate. */
+  readonly restartRequired: boolean;
+  /** The already-active embedder, if the new config matches (no restart needed). */
+  readonly alreadyActive: boolean;
+}

package/extensions/dashboard-server/routes-cache.ts

@@ -196,4 +196,39 @@ export function handleProviderCache(
 	} catch {
 		return false;
 	}
-}
+}
+// ---------------------------------------------------------------------------
+// handleCacheStripes — "GET /api/cache-stripes"
+// ---------------------------------------------------------------------------
+
+export function handleCacheStripes(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (!req.url?.startsWith("/api/cache-stripes")) return false;
+	if (req.method !== "GET") {
+		res.writeHead(405, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "method_not_allowed" }));
+		return true;
+	}
+	try {
+		const stateDir = ctx.stateDir;
+		const pfReq = createRequire(import.meta.url);
+		const { readCacheStripes } = pfReq(
+			"../../src/store/sqlite/cache-stripes.js",
+		) as typeof import("../../src/store/sqlite/cache-stripes.js");
+		const result = readCacheStripes(stateDir);
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(result));
+	} catch (e) {
+		res.writeHead(500, { "Content-Type": "application/json" });
+		res.end(
+			JSON.stringify({
+				error: "cache_stripes_unavailable",
+				detail: String(e),
+			}),
+		);
+	}
+	return true;
+}

package/extensions/dashboard-server/routes-game.ts

@@ -307,6 +307,9 @@ export function handlePerf(
 					avg: avg(get("cache_hit_pct")),
 					latest: latest(get("cache_hit_pct")),
 					n: get("cache_hit_pct").length,
+					samples: rows
+						.filter((r) => r.kind === "cache_hit_pct")
+						.map((r) => ({ pct: r.value, ts: r.ts })),
 				},
 				db_recompute_ms: {
 					p50: pct(get("db_recompute_ms"), 50),

package/extensions/dashboard-server/routes-memory-map.ts

@@ -0,0 +1,105 @@
+/**
+ * routes-memory-map.ts — GET /api/memory-map route handler (S46).
+ *
+ * Builds a memory graph from the local SQLite store and returns it as JSON.
+ * Uses an inline require to the pi-agnostic src/memoryGraph.ts builder.
+ */
+import { createRequire } from "node:module";
+import type { ServerResponse, IncomingMessage } from "node:http";
+import { parse as parseUrl } from "node:url";
+import type { RouteContext } from "./routes-core.js";
+import type { MemoryMapResponse, MemoryMapNode, MemoryMapEdgeEntry } from "./api-contracts/memory-map.js";
+
+const _req = createRequire(import.meta.url);
+
+// guardrails-allow PREVENT-PI-004: localhost-only dashboard API endpoint that reads from the local SQLite store — zero remote network calls.
+
+export function handleMemoryMap(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (req.method !== "GET") return false;
+	const parsed = parseUrl(req.url ?? "", true);
+	if (parsed.pathname !== "/api/memory-map") return false;
+
+	// guardrails-allow PREVENT-PI-004: local loopback-only dashboard server — reads the local SQLite store for graph data.
+	const { buildMemoryGraph } = _req("../../src/memoryGraph.js") as {
+		buildMemoryGraph: (opts?: {
+			sessionId?: string;
+			similarityThreshold?: number;
+			maxEdgesPerNode?: number;
+			stateDir?: string;
+			includeRaptorEdges?: boolean;
+			includeTemporalEdges?: boolean;
+		}) => MemoryGraphReturn;
+	};
+
+	type MemoryGraphReturn = {
+		nodes: Array<{
+			id: string;
+			sessionId: string;
+			label: string;
+			summaryTruncated: string;
+			tokenEstimate: number;
+			timestamp: number;
+			dedupStatus: string | undefined;
+			raptorLevel: number;
+			topicSummary: string | undefined;
+			decisionCount: number;
+			textSnippet: string;
+		}>;
+		edges: Array<{
+			source: string;
+			target: string;
+			weight: number;
+			type: "temporal" | "semantic" | "raptor_parent";
+		}>;
+		metadata: {
+			sessionCount: number;
+			totalCheckpoints: number;
+			totalEdges: number;
+			semanticEdgeCount: number;
+			temporalEdgeCount: number;
+			raptorEdgeCount: number;
+			similarityThresholdUsed: number;
+			builtAt: number;
+		};
+	};
+
+	const sessionId = typeof parsed.query.sessionId === "string" ? parsed.query.sessionId : undefined;
+	const threshold = typeof parsed.query.threshold === "string" ? Number.parseFloat(parsed.query.threshold) : undefined;
+	const maxEdges = typeof parsed.query.maxEdgesPerNode === "string" ? Number.parseInt(parsed.query.maxEdgesPerNode, 10) : undefined;
+	const raptorEdges = parsed.query.includeRaptorEdges === "false" ? false : true;
+	const temporalEdges = parsed.query.includeTemporalEdges === "false" ? false : true;
+
+	const graph = buildMemoryGraph({
+		sessionId,
+		similarityThreshold: threshold,
+		maxEdgesPerNode: maxEdges,
+		stateDir: ctx.stateDir,
+		includeRaptorEdges: raptorEdges,
+		includeTemporalEdges: temporalEdges,
+	});
+
+	const nodes: MemoryMapNode[] = graph.nodes.map((n) => ({
+		id: n.id,
+		sessionId: n.sessionId,
+		label: n.label,
+		summaryTruncated: n.summaryTruncated,
+		tokenEstimate: n.tokenEstimate,
+		timestamp: n.timestamp,
+		dedupStatus: n.dedupStatus,
+		raptorLevel: n.raptorLevel,
+		topicSummary: n.topicSummary,
+		decisionCount: n.decisionCount,
+		textSnippet: n.textSnippet,
+	}));
+
+	const edges: MemoryMapEdgeEntry[] = graph.edges as MemoryMapEdgeEntry[];
+	const response: MemoryMapResponse = { nodes, edges, metadata: graph.metadata };
+
+	res.writeHead(200, { "Content-Type": "application/json" });
+	res.end(JSON.stringify(response));
+	return true;
+}

package/extensions/dashboard-server/routes-setup.ts

@@ -11,11 +11,15 @@
 
 import { spawnSync } from "node:child_process"; // guardrails-allow PREVENT-PI-004: local subprocess detection only
 import { createRequire } from "node:module";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { RouteContext } from "./routes-core.js";
 import type {
 	SetupStatusResponse,
 	SetupDetectResponse,
+	SetupConfigureRequest,
+	SetupConfigureResponse,
 	DetectResult,
 	OllamaDetectResult,
 } from "./api-contracts/setup.js";
@@ -179,3 +183,111 @@ export function handleSetupDetect(
 	res.end(JSON.stringify(body));
 	return true;
 }
+
+// ---------------------------------------------------------------------------
+// handleSetupConfigure — POST "/api/setup-configure"
+// ---------------------------------------------------------------------------
+
+const OLLAMA_DEFAULT_URL = "http://localhost:11434/api/embeddings"; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+const LLAMA_DEFAULT_URL = "http://localhost:8080/v1/embeddings"; // guardrails-allow PREVENT-PI-004: localhost-only config string, not a runtime fetch
+
+function readJsonBody(
+	req: IncomingMessage,
+	cb: (
+		result:
+			| { ok: true; value: Record<string, unknown> }
+			| { ok: false; error: string },
+	) => void,
+): void {
+	let body = "";
+	let tooBig = false;
+	req.on("data", (chunk: Buffer) => {
+		if (body.length > 65536) { tooBig = true; return; }
+		body += chunk.toString();
+	});
+	req.on("end", () => {
+		if (tooBig) return cb({ ok: false, error: "body_too_large" });
+		try {
+			const v = body ? JSON.parse(body) : {}; // PREVENT-001: parsed value type-checked below
+			if (typeof v !== "object" || v === null || Array.isArray(v)) {
+				return cb({ ok: false, error: "invalid_object" });
+			}
+			cb({ ok: true, value: v as Record<string, unknown> });
+		} catch {
+			cb({ ok: false, error: "invalid_json" });
+		}
+	});
+	req.on("error", () => cb({ ok: false, error: "read_error" }));
+}
+
+export function handleSetupConfigure(
+	req: IncomingMessage,
+	res: ServerResponse,
+	ctx: RouteContext,
+): boolean {
+	if (req.url !== "/api/setup-configure") return false;
+	if (req.method !== "POST") {
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(405, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "method_not_allowed" }));
+		return true;
+	}
+	readJsonBody(req, (parsed) => {
+		if (!parsed.ok) {
+			// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: parsed.error }));
+			return;
+		}
+		const body = parsed.value as unknown as SetupConfigureRequest;
+		const embedder = body.embedder;
+		if (embedder !== "ollama" && embedder !== "llama" && embedder !== "trigram") {
+			res.writeHead(400, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: "invalid_embedder" }));
+			return;
+		}
+		const url = body.url;
+		let resolvedUrl: string | null;
+		if (embedder === "ollama") resolvedUrl = typeof url === "string" && url ? url : OLLAMA_DEFAULT_URL;
+		else if (embedder === "llama") resolvedUrl = typeof url === "string" && url ? url : LLAMA_DEFAULT_URL;
+		else resolvedUrl = null;
+
+		// Write .mega-compact.env to the state dir (loaded by env-loader at next startup).
+		const stateDir = ctx.stateDir;
+		const envPath = join(stateDir, ".mega-compact.env");
+		const lines: string[] = [
+			"# Mega-Compact Embedder Configuration",
+			`# Configured via dashboard Setup tab at ${new Date().toISOString()}`,
+		];
+		if (resolvedUrl) {
+			lines.push(`export MEGACOMPACT_EMBEDDING_URL="${resolvedUrl}"`);
+		} else {
+			lines.push("# trigram: built-in embedder, no URL needed");
+			lines.push("# unset MEGACOMPACT_EMBEDDING_URL (commented to override any shell-set value)");
+			lines.push("# export MEGACOMPACT_EMBEDDING_URL=");
+		}
+		lines.push("");
+		try {
+			mkdirSync(stateDir, { recursive: true });
+			writeFileSync(envPath, lines.join("\n"), "utf-8");
+		} catch (e) {
+			res.writeHead(500, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({ error: `write_failed: ${e instanceof Error ? e.message : String(e)}` }));
+			return;
+		}
+		// Detect if the new config matches what's already active (no restart needed).
+		const currentUrl = process.env["MEGACOMPACT_EMBEDDING_URL"];
+		const alreadyActive = (resolvedUrl === null && !currentUrl) || (resolvedUrl !== null && currentUrl === resolvedUrl);
+		const resp: SetupConfigureResponse = {
+			embedder,
+			url: resolvedUrl,
+			envPath,
+			restartRequired: !alreadyActive,
+			alreadyActive,
+		};
+		// guardrails-allow PREVENT-PI-004: loopback dashboard response (local)
+		res.writeHead(200, { "Content-Type": "application/json" });
+		res.end(JSON.stringify(resp));
+	});
+	return true;
+}

package/extensions/dashboard-server/routes.ts

@@ -21,4 +21,6 @@ export { handleTurns } from "./routes-turns.js";
 export { handleMaintenance } from "./routes-maintenance.js";
 export { handleProviderCache } from "./routes-cache.js";
 export { handleMemoryStatus } from "./routes-memory.js";
-export { handleSetupStatus, handleSetupDetect } from "./routes-setup.js";
+export { handleSetupStatus, handleSetupDetect, handleSetupConfigure } from "./routes-setup.js";
+export { handleMemoryMap } from "./routes-memory-map.js";
+export { handleCacheStripes } from "./routes-cache.js";

package/extensions/dashboard-server/server.ts

@@ -38,9 +38,12 @@ import {
 	handleTurns,
 	handleMaintenance,
 	handleProviderCache,
+	handleCacheStripes,
 	handleMemoryStatus,
 	handleSetupStatus,
 	handleSetupDetect,
+	handleSetupConfigure,
+	handleMemoryMap,
 	handleStatic,
 } from "./routes.js";
 
@@ -231,8 +234,11 @@ export async function launchDashboardServer(
 		if (handleMaintenance(req, res, ctx)) return;
 		if (handleProviderCache(req, res, ctx)) return;
 		if (handleMemoryStatus(req, res, ctx)) return;
+		if (handleCacheStripes(req, res, ctx)) return;
 		if (handleSetupStatus(req, res, ctx)) return;
 		if (handleSetupDetect(req, res, ctx)) return;
+		if (handleSetupConfigure(req, res, ctx)) return;
+		if (handleMemoryMap(req, res, ctx)) return;
 		handleStatic(req, res, ctx);
 	});
 

package/extensions/mega-compact.ts

@@ -30,6 +30,7 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { closeVectorIndex } from "../src/store/vectorIndex.js";
 import { closeMemoryIndex } from "../src/store/memoryIndex.js";
 import { loadConfig } from "./mega-config.js";
+import { loadMegaEnv } from "./mega-runtime/env-loader.js";
 import { MegaRuntime } from "./mega-runtime.js";
 import { registerEventHandlers } from "./mega-events.js";
 import { registerCommands } from "./mega-commands.js";
@@ -41,6 +42,10 @@ import { registerMetricsCommands } from "./mega-metrics-cmds.js";
 import { registerTopicsCommands } from "./mega-topics-cmds.js";
 
 export default function (pi: ExtensionAPI) {
+	// Load .mega-compact.env (written by /mega-setup + dashboard Setup tab) BEFORE
+	// config resolution so the wizard's choices take effect. Shell env wins over
+	// the file (see env-loader.ts). Non-fatal: missing/malformed file is a no-op.
+	loadMegaEnv(loadConfig().stateDir);
 	const config = loadConfig();
 	// S38.9: preflight env validation — check for obviously invalid values at startup.
 	// Non-fatal: log warnings and fall back to defaults.

package/extensions/mega-config.ts

@@ -168,9 +168,21 @@ export interface MegaConfig {
 	 *  the tail of the view when auto is OFF AND no trim action is needed. Default ON
 	 *  (true). When false, restores the pre-sprint systemPrompt prepend behavior. */
 	recallTailInject: boolean;
+	/** A1 PLAN_V2 Phase 2: Message Separation — isolate user/assistant turns
+	 *  from volatile tool results so the prompt-cache prefix stays stable.
+	 *  Default OFF (flag-OFF = byte-identical pre-sprint). */
+	messageSeparation: boolean;
 	debug: boolean;
 	/** Master reconciliation: TUI shutdown widget (MEGACOMPACT_TUI_WIDGET=0 to disable). */
 	tuiWidget: boolean;
+	/** S57 B1: Query reformulation via embedding-neighbor keyword expansion. */
+	ragQueryReformulation: boolean;
+	/** S57 B2: Tiered recall router (L0 cache -> L1 FTS5 -> L2). */
+	ragTieredRouter: boolean;
+	/** S57 B3: Recall quality metrics (precision/recall scoring + logging). */
+	ragRecallMetrics: boolean;
+	/** S57 B4: Memory graph traversal (dashboard-oriented). */
+	ragMemoryGraph: boolean;
 }
 
 function envFlag(name: string, fallback: number): number {
@@ -332,7 +344,12 @@ export function loadConfig(): MegaConfig {
 		recallMaxTokens: envFlag("MEGACOMPACT_RECALL_MAX_TOKENS", 1500),
 		windowDedupe: envBool("MEGACOMPACT_WINDOW_DEDUPE", true),
 		recallTailInject: envBool("MEGACOMPACT_RECALL_TAIL_INJECT", true),
+		messageSeparation: envBool("MEGACOMPACT_MESSAGE_SEPARATION", false),
 		tuiWidget: envBool("MEGACOMPACT_TUI_WIDGET", true),
+		ragQueryReformulation: envBool("MEGACOMPACT_QUERY_REFORMULATION", false),
+		ragTieredRouter: envBool("MEGACOMPACT_TIERED_ROUTER", false),
+		ragRecallMetrics: envBool("MEGACOMPACT_RECALL_METRICS", false),
+		ragMemoryGraph: envBool("MEGACOMPACT_MEMORY_GRAPH", false),
 		// D.1: env-overridable recompact delta (minimum context growth % before
 		// re-compacting instead of replaying the cached live trim). Default 50.
 		recompactPctDelta: envFlag("MEGACOMPACT_RECOMPACT_PCT_DELTA", 50),

package/extensions/mega-events/context-handler.ts

@@ -37,6 +37,7 @@ import {
 } from "../mega-config.js";
 import { appendMirrorMessages } from "./mirror-append.js";
 import { stagedForTail, withRecallTail } from "./recall-tail.js";
+import { buildSeparatedPrompt } from "./separated-prompt.js";
 
 /** Register the context event handler (live-trim auto-trigger). */
 export function registerContextHandler(
@@ -69,8 +70,15 @@ export function registerContextHandler(
 		// REAL transcript before any view is built, so the injected tail never
 		// reaches raw_transcript (PREVENT-PI: append-only, view-only).
 		const tailResult = (msgs?: readonly AgentMessage[]) => {
-			if (!stagedForTail(runtime, config)) return undefined;
-			return { messages: withRecallTail(msgs ?? messages, runtime, config) };
+			const base = msgs ?? messages;
+			if (!stagedForTail(runtime, config) && !config.messageSeparation) return undefined;
+			let result: AgentMessage[] = stagedForTail(runtime, config)
+				? withRecallTail(base, runtime, config)
+				: (base as AgentMessage[]);
+			if (config.messageSeparation) {
+				result = buildSeparatedPrompt(result);
+			}
+			return { messages: result };
 		};
 		// Always track context for the dashboard/widget, even when auto is off.
 		// (v0.8 regression: !config.auto gate sat above this, leaving ctx stats