prism-mcp-server 2.3.9 → 2.3.11

package/README.md

@@ -14,7 +14,16 @@
 
 ---
 
-## What's New in v2.3.8 — LangGraph Research Agent 🔬
+## What's New in v2.3.10 — Stability & Fixes 🛠️
+
+| Feature | Description |
+|---|---|
+| 🪲 **Windows Black Screen Fix** | Fixed Python `subprocess.Popen` spawning visible Node.js terminal windows on Windows. |
+| 📝 **Debug Logging** | Gated verbose startup logs behind `PRISM_DEBUG_LOGGING` for a cleaner default experience. |
+| ⚡ **Excess Loading Fixes** | Performance improvements to resolve excess loading loops. |
+
+<details>
+<summary><strong>What's in v2.3.8 — LangGraph Research Agent</strong></summary>
 
 | Feature | Description |
 |---|---|
@@ -24,6 +33,8 @@
 | 🔧 **Storage Abstraction Fix** | Resource/Prompt handlers now route through `getStorage()` instead of calling Supabase directly — eliminates EOF crashes when reading `memory://` resources. |
 | 🛡️ **Error Boundaries** | Resource handlers catch errors gracefully and return proper MCP error responses (`isError: true`) instead of crashing the server process. |
 
+</details>
+
 <details>
 <summary><strong>What's in v2.2.0</strong></summary>
 

package/dist/config.js

@@ -85,16 +85,13 @@ export const PRISM_CAPTURE_PORTS = (process.env.PRISM_CAPTURE_PORTS || "3000,300
     .split(",")
     .map(p => parseInt(p.trim(), 10))
     .filter(p => !isNaN(p));
+// ─── v2.3: Debug Logging ──────────────────────────────────────
+// Optionally enable verbose output (stderr) for Prism initialization,
+// memory indexing, and background tasks.
+export const PRISM_DEBUG_LOGGING = process.env.PRISM_DEBUG_LOGGING === "true";
 if (PRISM_AUTO_CAPTURE) {
-    console.error(`[AutoCapture] Enabled for ports: ${PRISM_CAPTURE_PORTS.join(", ")}`);
-}
-// ─── Debug Logging ──────────────────────────────────────────────
-// Set PRISM_DEBUG=true to enable verbose startup and operational logs.
-// When disabled (default), only warnings and errors are printed.
-export const PRISM_DEBUG = process.env.PRISM_DEBUG === "true";
-/** Conditional debug logger — only prints when PRISM_DEBUG=true. */
-export function debug(...args) {
-    if (PRISM_DEBUG) {
-        console.error(...args);
+    // Use console.error instead of debugLog here to prevent circular dependency
+    if (PRISM_DEBUG_LOGGING) {
+        console.error(`[AutoCapture] Enabled for ports: ${PRISM_CAPTURE_PORTS.join(", ")}`);
     }
 }

package/dist/server.js

@@ -58,7 +58,7 @@ ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequ
 // Claude Desktop that the attached resource has changed.
 // Without this, the paperclipped context becomes stale.
 SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { SERVER_CONFIG, SESSION_MEMORY_ENABLED, PRISM_USER_ID, debug } from "./config.js";
+import { SERVER_CONFIG, SESSION_MEMORY_ENABLED, PRISM_USER_ID } from "./config.js";
 import { getSyncBus } from "./sync/factory.js";
 import { startDashboardServer } from "./dashboard/server.js";
 // ─── v2.3.6 FIX: Use Storage Abstraction for Prompts/Resources ───
@@ -147,7 +147,6 @@ const activeSubscriptions = new Set();
 export function notifyResourceUpdate(project, server) {
     const uri = `memory://${project}/handoff`;
     if (activeSubscriptions.has(uri)) {
-        debug(`[resource-subscription] Notifying update for ${uri}`);
         server.notification({
             method: "notifications/resources/updated",
             params: { uri },
@@ -165,8 +164,6 @@ export function notifyResourceUpdate(project, server) {
  *                with subscribe support for live refresh
  */
 export function createServer() {
-    debug(`Creating Prism MCP server v${SERVER_CONFIG.version}`);
-    debug(`Registering ${ALL_TOOLS.length} tools (${BASE_TOOLS.length} base + ${SESSION_MEMORY_ENABLED ? SESSION_MEMORY_TOOLS.length : 0} session memory)`);
     const server = new Server({
         name: SERVER_CONFIG.name,
         version: SERVER_CONFIG.version,
@@ -196,7 +193,6 @@ export function createServer() {
     // REVIEWER NOTE: The initialize handler is unchanged from v0.3.0
     // except that it now reports the expanded capabilities.
     server.setRequestHandler(InitializeRequestSchema, async (request) => {
-        debug(`Client connected: ${request.params.clientInfo?.name || 'unknown'}`);
         return {
             protocolVersion: request.params.protocolVersion,
             serverInfo: {
@@ -214,7 +210,6 @@ export function createServer() {
     });
     // ── Handler: List Tools ──
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        debug("Received list tools request");
         return {
             tools: ALL_TOOLS,
         };
@@ -271,7 +266,6 @@ export function createServer() {
             }
             const project = promptArgs?.project || "default";
             const level = promptArgs?.level || "standard";
-            debug(`[prompt:resume_session] Loading ${level} context for "${project}"`);
             // v2.3.6 FIX: Use storage abstraction instead of direct supabaseRpc
             const storage = await getStorage();
             const result = await storage.loadContext(project, level, PRISM_USER_ID);
@@ -365,7 +359,6 @@ export function createServer() {
                 throw new Error(`Unknown resource URI: ${uri}. Expected format: memory://{project}/handoff`);
             }
             const project = decodeURIComponent(match[1]);
-            debug(`[resource:read] Fetching handoff for "${project}"`);
             try {
                 // v2.3.6 FIX: Use storage abstraction instead of direct supabaseRpc
                 const storage = await getStorage();
@@ -404,13 +397,11 @@ export function createServer() {
         // for projects the client hasn't attached.
         server.setRequestHandler(SubscribeRequestSchema, async (request) => {
             const uri = request.params.uri;
-            debug(`[resource-subscription] Client subscribed to ${uri}`);
             activeSubscriptions.add(uri);
             return {};
         });
         server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
             const uri = request.params.uri;
-            debug(`[resource-subscription] Client unsubscribed from ${uri}`);
             activeSubscriptions.delete(uri);
             return {};
         });
@@ -422,13 +413,11 @@ export function createServer() {
     // The server reference is passed to sessionSaveHandoffHandler so it
     // can trigger resource update notifications on successful saves.
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        debug(`Tool call: ${request.params.name}`);
         try {
             const { name, arguments: args } = request.params;
             if (!args) {
                 throw new Error("No arguments provided");
             }
-            debug(`Processing ${name} with arguments: ${JSON.stringify(args)}`);
             switch (name) {
                 // ── Search & Analysis Tools (always available) ──
                 case "brave_web_search":
@@ -595,11 +584,8 @@ export function createSandboxServer() {
  * responses to stdout. Log messages go to stderr.
  */
 export async function startServer() {
-    debug("Initializing Prism MCP server...");
     const server = createServer();
-    debug("Creating stdio transport...");
     const transport = new StdioServerTransport();
-    debug("Connecting server to transport...");
     await server.connect(transport);
     // ─── v2.0 Step 6: Initialize SyncBus (Telepathy) ───
     if (SESSION_MEMORY_ENABLED) {
@@ -607,8 +593,6 @@ export async function startServer() {
             const syncBus = await getSyncBus();
             await syncBus.startListening();
             syncBus.on("update", (event) => {
-                debug(`[Telepathy] Memory for project '${event.project}' ` +
-                    `updated to v${event.version} by another agent!`);
                 // Send an MCP logging notification to the IDE
                 try {
                     server.sendLoggingMessage({
@@ -622,7 +606,6 @@ export async function startServer() {
                     console.error(`[Telepathy] Failed to send notification: ${err}`);
                 }
             });
-            debug("[Telepathy] SyncBus active — multi-client sync enabled");
         }
         catch (err) {
             console.error(`[Telepathy] SyncBus init failed (non-fatal): ${err}`);
@@ -632,7 +615,6 @@ export async function startServer() {
     startDashboardServer().catch(err => {
         console.error(`[Dashboard] Mind Palace startup failed (non-fatal): ${err}`);
     });
-    debug(`Prism MCP Server v${SERVER_CONFIG.version} running on stdio`);
     // Keep the process alive — without this, Node.js would exit
     // because there are no active event loop handles after the
     // synchronous setup completes.

package/dist/storage/index.js

@@ -10,6 +10,7 @@
  *   // Pass `storage` to all session memory handlers
  */
 import { PRISM_STORAGE } from "../config.js";
+import { debugLog } from "../utils/logger.js";
 import { SupabaseStorage } from "./supabase.js";
 let storageInstance = null;
 /**
@@ -24,7 +25,7 @@ let storageInstance = null;
 export async function getStorage() {
     if (storageInstance)
         return storageInstance;
-    console.error(`[Prism Storage] Initializing backend: ${PRISM_STORAGE}`);
+    debugLog(`[Prism Storage] Initializing backend: ${PRISM_STORAGE}`);
     if (PRISM_STORAGE === "local") {
         const { SqliteStorage } = await import("./sqlite.js");
         storageInstance = new SqliteStorage();

package/dist/storage/sqlite.js

@@ -20,6 +20,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { randomUUID } from "crypto";
+import { debugLog } from "../utils/logger.js";
 export class SqliteStorage {
     db;
     dbPath;
@@ -38,11 +39,11 @@ export class SqliteStorage {
         await this.db.execute("PRAGMA journal_mode=WAL");
         // Run all migrations
         await this.runMigrations();
-        console.error(`[SqliteStorage] Initialized at ${this.dbPath}`);
+        debugLog(`[SqliteStorage] Initialized at ${this.dbPath}`);
     }
     async close() {
         this.db.close();
-        console.error("[SqliteStorage] Closed");
+        debugLog("[SqliteStorage] Closed");
     }
     // ─── Migrations ────────────────────────────────────────────
     async runMigrations() {

package/dist/storage/supabase.js

@@ -13,17 +13,18 @@
  * ═══════════════════════════════════════════════════════════════════
  */
 import { supabasePost, supabaseGet, supabaseRpc, supabasePatch, supabaseDelete, } from "../utils/supabaseApi.js";
+import { debugLog } from "../utils/logger.js";
 export class SupabaseStorage {
     // ─── Lifecycle ─────────────────────────────────────────────
     async initialize() {
         // Supabase is always ready — connection is stateless (REST API).
         // The SUPABASE_URL and SUPABASE_KEY are validated at import time
         // by supabaseApi.ts's guard clause.
-        console.error("[SupabaseStorage] Initialized (REST API, stateless)");
+        debugLog("[SupabaseStorage] Initialized (REST API, stateless)");
     }
     async close() {
         // No-op for Supabase — connections are stateless.
-        console.error("[SupabaseStorage] Closed (no-op for REST)");
+        debugLog("[SupabaseStorage] Closed (no-op for REST)");
     }
     // ─── Ledger Operations ─────────────────────────────────────
     async saveLedger(entry) {

package/dist/sync/factory.js

@@ -7,6 +7,7 @@
  * Singleton pattern — only one bus per process (prevents duplicate watchers).
  */
 import { PRISM_STORAGE } from "../config.js";
+import { debugLog } from "../utils/logger.js";
 let _bus = null;
 export async function getSyncBus() {
     if (_bus)
@@ -28,6 +29,6 @@ export async function getSyncBus() {
             _bus = new SupabaseSyncBus(url, key);
         }
     }
-    console.error(`[SyncBus] Initialized: ${_bus.constructor.name} (client=${_bus.clientId.substring(0, 8)})`);
+    debugLog(`[SyncBus] Initialized: ${_bus.constructor.name} (client=${_bus.clientId.substring(0, 8)})`);
     return _bus;
 }

package/dist/sync/sqliteSync.js

@@ -29,6 +29,7 @@ import * as fs from "fs";
 import * as path from "path";
 import * as os from "os";
 import { SyncBus } from "./index.js";
+import { debugLog } from "../utils/logger.js";
 export class SqliteSyncBus extends SyncBus {
     lockFilePath;
     watching = false;
@@ -53,7 +54,7 @@ export class SqliteSyncBus extends SyncBus {
         };
         // Atomic write — content is < 200 bytes, well within single-page write
         fs.writeFileSync(this.lockFilePath, JSON.stringify(payload), "utf8");
-        console.error(`[SyncBus] Broadcast: project=${project}, version=${version}, ` +
+        debugLog(`[SyncBus] Broadcast: project=${project}, version=${version}, ` +
             `client=${this.clientId.substring(0, 8)}`);
     }
     async startListening() {
@@ -69,7 +70,7 @@ export class SqliteSyncBus extends SyncBus {
                     const event = JSON.parse(data);
                     // Only emit if it came from a DIFFERENT Prism MCP instance
                     if (event.client_id && event.client_id !== this.clientId) {
-                        console.error(`[SyncBus] Received update from client ${event.client_id.substring(0, 8)}: ` +
+                        debugLog(`[SyncBus] Received update from client ${event.client_id.substring(0, 8)}: ` +
                             `project=${event.project}, version=${event.version}`);
                         this.emit("update", event);
                     }
@@ -79,7 +80,7 @@ export class SqliteSyncBus extends SyncBus {
                 }
             }
         });
-        console.error(`[SyncBus] Listening for updates on ${this.lockFilePath} ` +
+        debugLog(`[SyncBus] Listening for updates on ${this.lockFilePath} ` +
             `(client=${this.clientId.substring(0, 8)})`);
     }
     async stopListening() {
@@ -87,6 +88,6 @@ export class SqliteSyncBus extends SyncBus {
             return;
         this.watching = false;
         fs.unwatchFile(this.lockFilePath);
-        console.error("[SyncBus] Stopped listening");
+        debugLog("[SyncBus] Stopped listening");
     }
 }

package/dist/sync/supabaseSync.js

@@ -17,6 +17,7 @@
  * ═══════════════════════════════════════════════════════════════════
  */
 import { SyncBus } from "./index.js";
+import { debugLog } from "../utils/logger.js";
 export class SupabaseSyncBus extends SyncBus {
     supabaseUrl;
     supabaseKey;
@@ -47,7 +48,7 @@ export class SupabaseSyncBus extends SyncBus {
             }, (payload) => {
                 const newRow = payload.new;
                 if (newRow) {
-                    console.error(`[SyncBus:Supabase] Received update: project=${newRow.project}, version=${newRow.version}`);
+                    debugLog(`[SyncBus:Supabase] Received update: project=${newRow.project}, version=${newRow.version}`);
                     this.emit("update", {
                         project: newRow.project,
                         version: newRow.version,
@@ -57,9 +58,9 @@ export class SupabaseSyncBus extends SyncBus {
                 }
             })
                 .subscribe((status) => {
-                console.error(`[SyncBus:Supabase] Channel status: ${status}`);
+                debugLog(`[SyncBus:Supabase] Channel status: ${status}`);
             });
-            console.error(`[SyncBus:Supabase] Listening for realtime updates ` +
+            debugLog(`[SyncBus:Supabase] Listening for realtime updates ` +
                 `(client=${this.clientId.substring(0, 8)})`);
         }
         catch (err) {
@@ -72,7 +73,7 @@ export class SupabaseSyncBus extends SyncBus {
         if (this.channel && this.supabase) {
             try {
                 await this.supabase.removeChannel(this.channel);
-                console.error("[SyncBus:Supabase] Stopped listening");
+                debugLog("[SyncBus:Supabase] Stopped listening");
             }
             catch {
                 // Ignore cleanup errors

package/dist/tools/compactionHandler.js

@@ -9,6 +9,7 @@
 import { getStorage } from "../storage/index.js";
 import { GOOGLE_API_KEY, PRISM_USER_ID } from "../config.js";
 import { GoogleGenerativeAI } from "@google/generative-ai";
+import { debugLog } from "../utils/logger.js";
 // ─── Constants ────────────────────────────────────────────────
 const COMPACTION_CHUNK_SIZE = 10;
 const MAX_ENTRIES_PER_RUN = 100;
@@ -44,7 +45,7 @@ export async function compactLedgerHandler(args) {
         throw new Error("Invalid arguments for session_compact_ledger");
     }
     const { project, threshold = 50, keep_recent = 10, dry_run = false, } = args;
-    console.error(`[compact_ledger] ${dry_run ? "DRY RUN: " : ""}` +
+    debugLog(`[compact_ledger] ${dry_run ? "DRY RUN: " : ""}` +
         `project=${project || "auto-detect"}, threshold=${threshold}, keep_recent=${keep_recent}`);
     const storage = await getStorage();
     // Step 1: Find candidates
@@ -102,7 +103,7 @@ export async function compactLedgerHandler(args) {
     for (const candidate of candidates) {
         const proj = candidate.project;
         const toCompact = Math.min(candidate.to_compact, MAX_ENTRIES_PER_RUN);
-        console.error(`[compact_ledger] Compacting ${toCompact} entries for "${proj}"`);
+        debugLog(`[compact_ledger] Compacting ${toCompact} entries for "${proj}"`);
         // Fetch oldest entries (the ones to be rolled up)
         const oldEntries = await storage.getLedgerEntries({
             project: `eq.${proj}`,

package/dist/tools/handlers.js

@@ -24,6 +24,7 @@ import { analyzePaperWithGemini } from "../utils/googleAi.js";
 import { isBraveWebSearchArgs, isBraveLocalSearchArgs, isBraveAnswersArgs, isGeminiResearchPaperAnalysisArgs, isBraveWebSearchCodeModeArgs, isBraveLocalSearchCodeModeArgs, isCodeModeTransformArgs } from "./definitions.js";
 import { runInSandbox } from "../utils/executor.js";
 import { CODE_MODE_TEMPLATES, getTemplateNames } from "../templates/codeMode.js";
+import { debugLog } from "../utils/logger.js";
 // ─── Simple Search Handlers ──────────────────────────────────
 /** Performs a standard web search and returns formatted text results. */
 export async function webSearchHandler(args) {
@@ -56,11 +57,11 @@ export async function braveWebSearchCodeModeHandler(args) {
         };
     }
     // 1. Fetch raw data
-    console.error(`Fetching web search for code mode: "${query}"`);
+    debugLog(`Fetching web search for code mode: "${query}"`);
     const rawDataStr = await performWebSearchRaw(query, count, offset);
     const beforeSizeKB = (Buffer.byteLength(rawDataStr, 'utf8') / 1024).toFixed(1);
     // 2. Run code mode sandbox
-    console.error(`Executing code mode sandbox...`);
+    debugLog(`Executing code mode sandbox...`);
     const { stdout, error, executionTimeMs } = await runInSandbox(rawDataStr, code);
     if (error) {
         return {
@@ -93,10 +94,10 @@ export async function braveLocalSearchCodeModeHandler(args) {
             isError: true,
         };
     }
-    console.error(`Fetching local search for code mode: "${query}"`);
+    debugLog(`Fetching local search for code mode: "${query}"`);
     const rawDataStr = await performLocalSearchRaw(query, count);
     const beforeSizeKB = (Buffer.byteLength(rawDataStr, "utf8") / 1024).toFixed(1);
-    console.error("Executing local search code mode sandbox...");
+    debugLog("Executing local search code mode sandbox...");
     const { stdout, error, executionTimeMs } = await runInSandbox(rawDataStr, code);
     if (error) {
         return {
@@ -151,7 +152,7 @@ export async function codeModeTransformHandler(args) {
         };
     }
     const beforeSizeKB = (Buffer.byteLength(data, "utf8") / 1024).toFixed(1);
-    console.error(`[code_mode_transform] source=${source_tool}, template=${templateUsed}, input=${beforeSizeKB}KB`);
+    debugLog(`[code_mode_transform] source=${source_tool}, template=${templateUsed}, input=${beforeSizeKB}KB`);
     const { stdout, error, executionTimeMs } = await runInSandbox(data, scriptToRun);
     if (error) {
         return {
@@ -215,7 +216,7 @@ export async function researchPaperAnalysisHandler(args) {
         };
     }
     try {
-        console.error(`Analyzing research paper with Gemini (${analysisType} analysis)...`);
+        debugLog(`Analyzing research paper with Gemini (${analysisType} analysis)...`);
         const analysis = await analyzePaperWithGemini(paperContent, analysisType, additionalContext);
         return {
             content: [{ type: "text", text: analysis }],

package/dist/tools/sessionMemoryHandlers.js

@@ -15,6 +15,7 @@
  * without any code changes.
  * ═══════════════════════════════════════════════════════════════════
  */
+import { debugLog } from "../utils/logger.js";
 import { getStorage } from "../storage/index.js";
 import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { generateEmbedding } from "../utils/embeddingApi.js";
@@ -39,11 +40,11 @@ export async function sessionSaveLedgerHandler(args) {
     }
     const { project, conversation_id, summary, todos, files_changed, decisions } = args;
     const storage = await getStorage();
-    console.error(`[session_save_ledger] Saving ledger entry for project="${project}"`);
+    debugLog(`[session_save_ledger] Saving ledger entry for project="${project}"`);
     // Auto-extract keywords from summary + decisions for knowledge accumulation
     const combinedText = [summary, ...(decisions || [])].join(" ");
     const keywords = toKeywordArray(combinedText);
-    console.error(`[session_save_ledger] Extracted ${keywords.length} keywords: ${keywords.slice(0, 5).join(", ")}...`);
+    debugLog(`[session_save_ledger] Extracted ${keywords.length} keywords: ${keywords.slice(0, 5).join(", ")}...`);
     // Save via storage backend
     const result = await storage.saveLedger({
         project,
@@ -66,7 +67,7 @@ export async function sessionSaveLedgerHandler(args) {
                 await storage.patchLedger(entryId, {
                     embedding: JSON.stringify(embedding),
                 });
-                console.error(`[session_save_ledger] Embedding saved for entry ${entryId}`);
+                debugLog(`[session_save_ledger] Embedding saved for entry ${entryId}`);
             })
                 .catch((err) => {
                 console.error(`[session_save_ledger] Embedding generation failed (non-fatal): ${err.message}`);
@@ -97,13 +98,13 @@ export async function sessionSaveHandoffHandler(args, server) {
     }
     const { project, expected_version, open_todos, active_branch, last_summary, key_context, } = args;
     const storage = await getStorage();
-    console.error(`[session_save_handoff] Saving handoff for project="${project}" ` +
+    debugLog(`[session_save_handoff] Saving handoff for project="${project}" ` +
         `(expected_version=${expected_version ?? "none"})`);
     // Auto-extract keywords from summary + context for knowledge accumulation
     const combinedText = [last_summary || "", key_context || ""].filter(Boolean).join(" ");
     const keywords = combinedText ? toKeywordArray(combinedText) : undefined;
     if (keywords) {
-        console.error(`[session_save_handoff] Extracted ${keywords.length} keywords: ${keywords.slice(0, 5).join(", ")}...`);
+        debugLog(`[session_save_handoff] Extracted ${keywords.length} keywords: ${keywords.slice(0, 5).join(", ")}...`);
     }
     // Auto-capture Git state for Reality Drift Detection (v2.0 Step 5)
     const gitState = getCurrentGitState();
@@ -111,7 +112,7 @@ export async function sessionSaveHandoffHandler(args, server) {
     if (gitState.isRepo) {
         metadata.git_branch = gitState.branch;
         metadata.last_commit_sha = gitState.commitSha;
-        console.error(`[session_save_handoff] Git state captured: branch=${gitState.branch}, sha=${gitState.commitSha?.substring(0, 8)}`);
+        debugLog(`[session_save_handoff] Git state captured: branch=${gitState.branch}, sha=${gitState.commitSha?.substring(0, 8)}`);
     }
     // Save via storage backend (OCC-aware)
     const data = await storage.saveHandoff({
@@ -127,7 +128,7 @@ export async function sessionSaveHandoffHandler(args, server) {
     }, expected_version ?? null);
     // ─── Handle version conflict ───
     if (data.status === "conflict") {
-        console.error(`[session_save_handoff] VERSION CONFLICT for "${project}": ` +
+        debugLog(`[session_save_handoff] VERSION CONFLICT for "${project}": ` +
             `expected=${expected_version}, current=${data.current_version}`);
         return {
             content: [{
@@ -213,7 +214,7 @@ export async function sessionSaveHandoffHandler(args, server) {
                             key_context: ctx.key_context ?? null,
                             active_branch: ctx.active_branch ?? null,
                         }, newVersion);
-                        console.error(`[AutoCapture] HTML snapshot indexed in visual memory for "${project}"`);
+                        debugLog(`[AutoCapture] HTML snapshot indexed in visual memory for "${project}"`);
                     }
                 }
                 catch (err) {
@@ -244,14 +245,14 @@ export async function sessionSaveHandoffHandler(args, server) {
                 const oldKeyContext = oldState?.key_context || ""; // extract old key_context
                 // Step 2: Skip merge if old context is empty (nothing to merge with)
                 if (!oldKeyContext || oldKeyContext.trim().length === 0) {
-                    console.error("[FactMerger] No old context to merge — skipping");
+                    debugLog("[FactMerger] No old context to merge — skipping");
                     return; // first handoff for this project, no merge needed
                 }
                 // Step 3: Call Gemini to intelligently merge old + new context
                 const mergedContext = await consolidateFacts(oldKeyContext, key_context);
                 // Step 4: Skip patch if merged result is same as current key_context
                 if (mergedContext === key_context) {
-                    console.error("[FactMerger] No changes after merge — skipping patch");
+                    debugLog("[FactMerger] No changes after merge — skipping patch");
                     return; // Gemini determined no contradictions existed
                 }
                 // Step 5: Silently patch the database with the merged context
@@ -268,14 +269,14 @@ export async function sessionSaveHandoffHandler(args, server) {
                     active_branch: active_branch ?? null, // preserve existing branch
                     metadata: {}, // no metadata changes
                 }, newVersion); // use current version for OCC
-                console.error("[FactMerger] Context merged and patched for \"" + project + "\"");
+                debugLog("[FactMerger] Context merged and patched for \"" + project + "\"");
             }
             catch (err) {
                 // OCC conflict = user saved again while merge was running (expected)
                 const errMsg = err instanceof Error ? err.message : String(err);
                 if (errMsg.includes("conflict") || errMsg.includes("version")) {
                     // This is GOOD behavior — user's active input takes precedence
-                    console.error("[FactMerger] Merge skipped due to active session (OCC conflict)");
+                    debugLog("[FactMerger] Merge skipped due to active session (OCC conflict)");
                 }
                 else {
                     // Unexpected error — log but don't crash
@@ -319,7 +320,7 @@ export async function sessionLoadContextHandler(args) {
             isError: true,
         };
     }
-    console.error(`[session_load_context] Loading ${level} context for project="${project}"`);
+    debugLog(`[session_load_context] Loading ${level} context for project="${project}"`);
     const storage = await getStorage();
     const data = await storage.loadContext(project, level, PRISM_USER_ID);
     if (!data) {
@@ -348,7 +349,7 @@ export async function sessionLoadContextHandler(args) {
                 driftReport = `\n\n⚠️ **CONTEXT SHIFT:** This memory was saved on branch ` +
                     `\`${meta.git_branch}\`, but you are currently on branch \`${currentGit.branch}\`. ` +
                     `Code may have diverged — review carefully before making changes.`;
-                console.error(`[session_load_context] Context shift detected: ${meta.git_branch} → ${currentGit.branch}`);
+                debugLog(`[session_load_context] Context shift detected: ${meta.git_branch} → ${currentGit.branch}`);
             }
             else if (currentGit.commitSha !== meta.last_commit_sha) {
                 // Same branch, different commits — calculate drift
@@ -358,11 +359,11 @@ export async function sessionLoadContextHandler(args) {
                         `Since this memory was saved (commit ${meta.last_commit_sha.substring(0, 8)}), ` +
                         `the following files were modified outside of agent sessions:\n\`\`\`\n${changes}\n\`\`\`\n` +
                         `Please review these files if they overlap with your current task.`;
-                    console.error(`[session_load_context] Reality drift detected! ${changes.split("\n").length} files changed`);
+                    debugLog(`[session_load_context] Reality drift detected! ${changes.split("\n").length} files changed`);
                 }
             }
             else {
-                console.error(`[session_load_context] No drift — repo matches saved state`);
+                debugLog(`[session_load_context] No drift — repo matches saved state`);
             }
         }
     }
@@ -415,7 +416,7 @@ export async function sessionLoadContextHandler(args) {
             if (currentVersion) {
                 storage.saveHandoff(handoffUpdate, currentVersion).catch(err => console.error(`[Morning Briefing] Cache save failed (non-fatal): ${err}`));
             }
-            console.error(`[session_load_context] Morning Briefing generated for "${project}"`);
+            debugLog(`[session_load_context] Morning Briefing generated for "${project}"`);
         }
         catch (err) {
             console.error(`[session_load_context] Morning Briefing failed (non-fatal): ${err}`);
@@ -424,7 +425,7 @@ export async function sessionLoadContextHandler(args) {
     else if (meta?.morning_briefing) {
         // Show the cached briefing (generated within last 4 hours)
         briefingBlock = `\n\n[🌅 MORNING BRIEFING]\n${meta.morning_briefing}`;
-        console.error(`[session_load_context] Showing cached Morning Briefing for "${project}"`);
+        debugLog(`[session_load_context] Showing cached Morning Briefing for "${project}"`);
     }
     // ─── Visual Memory Index (v2.0 Step 9) ───
     // Show lightweight index of saved images — never loads actual image data
@@ -436,10 +437,33 @@ export async function sessionLoadContextHandler(args) {
             visualMemoryBlock += `- [ID: ${v.id}] ${v.description} (${v.timestamp?.split("T")[0] || "unknown"})\n`;
         });
     }
+    const d = data;
+    let formattedContext = ``;
+    if (d.last_summary)
+        formattedContext += `📝 Last Summary: ${d.last_summary}\n`;
+    if (d.active_branch)
+        formattedContext += `🌿 Active Branch: ${d.active_branch}\n`;
+    if (d.key_context)
+        formattedContext += `💡 Key Context: ${d.key_context}\n`;
+    if (d.pending_todo?.length) {
+        formattedContext += `\n✅ Open TODOs:\n` + d.pending_todo.map((t) => `  - ${t}`).join("\n") + `\n`;
+    }
+    if (d.active_decisions?.length) {
+        formattedContext += `\n⚖️ Active Decisions:\n` + d.active_decisions.map((dec) => `  - ${dec}`).join("\n") + `\n`;
+    }
+    if (d.keywords?.length) {
+        formattedContext += `\n🔑 Keywords: ${d.keywords.join(", ")}\n`;
+    }
+    if (d.recent_sessions?.length) {
+        formattedContext += `\n⏳ Recent Sessions:\n` + d.recent_sessions.map((s) => `  [${s.session_date?.split("T")[0]}] ${s.summary}`).join("\n") + `\n`;
+    }
+    if (d.session_history?.length) {
+        formattedContext += `\n📂 Session History (${d.session_history.length} entries):\n` + d.session_history.map((s) => `  [${s.session_date?.split("T")[0]}] ${s.summary}`).join("\n") + `\n`;
+    }
     return {
         content: [{
                 type: "text",
-                text: `📋 Session context for "${project}" (${level}):\n\n${JSON.stringify(data, null, 2)}${driftReport}${briefingBlock}${visualMemoryBlock}${versionNote}`,
+                text: `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${driftReport}${briefingBlock}${visualMemoryBlock}${versionNote}`,
             }],
         isError: false,
     };
@@ -453,7 +477,7 @@ export async function knowledgeSearchHandler(args) {
         throw new Error("Invalid arguments for knowledge_search");
     }
     const { project, query, category, limit = 10 } = args;
-    console.error(`[knowledge_search] Searching: project=${project || "all"}, query="${query || ""}", category=${category || "any"}, limit=${limit}`);
+    debugLog(`[knowledge_search] Searching: project=${project || "all"}, query="${query || ""}", category=${category || "any"}, limit=${limit}`);
     const searchKeywords = query ? toKeywordArray(query) : [];
     const storage = await getStorage();
     const data = await storage.searchKnowledge({
@@ -506,7 +530,7 @@ export async function knowledgeForgetHandler(args) {
             isError: true,
         };
     }
-    console.error(`[knowledge_forget] ${dry_run ? "DRY RUN: " : ""}Forgetting: ` +
+    debugLog(`[knowledge_forget] ${dry_run ? "DRY RUN: " : ""}Forgetting: ` +
         `project=${project || "ALL"}, category=${category || "any"}, ` +
         `older_than=${older_than_days || "any"}d, clear_handoff=${clear_handoff}`);
     const storage = await getStorage();
@@ -564,7 +588,7 @@ export async function sessionSearchMemoryHandler(args) {
         throw new Error("Invalid arguments for session_search_memory");
     }
     const { query, project, limit = 5, similarity_threshold = 0.7, } = args;
-    console.error(`[session_search_memory] Semantic search: query="${query}", ` +
+    debugLog(`[session_search_memory] Semantic search: query="${query}", ` +
         `project=${project || "all"}, limit=${limit}, threshold=${similarity_threshold}`);
     // Step 1: Generate embedding for the search query
     if (!GOOGLE_API_KEY) {
@@ -672,7 +696,7 @@ export async function backfillEmbeddingsHandler(args) {
     }
     const { project, limit = 20, dry_run = false } = args;
     const safeLimit = Math.min(limit, 50);
-    console.error(`[backfill_embeddings] ${dry_run ? "DRY RUN: " : ""}` +
+    debugLog(`[backfill_embeddings] ${dry_run ? "DRY RUN: " : ""}` +
         `project=${project || "all"}, limit=${safeLimit}`);
     const storage = await getStorage();
     // Find entries missing embeddings
@@ -721,7 +745,7 @@ export async function backfillEmbeddingsHandler(args) {
                 ...(e.decisions || []),
             ].filter(Boolean).join(" | ");
             if (!textToEmbed.trim()) {
-                console.error(`[backfill] Skipping entry ${e.id}: no text content`);
+                debugLog(`[backfill] Skipping entry ${e.id}: no text content`);
                 failed++;
                 continue;
             }
@@ -730,7 +754,7 @@ export async function backfillEmbeddingsHandler(args) {
                 embedding: JSON.stringify(embedding),
             });
             repaired++;
-            console.error(`[backfill] ✅ Repaired ${e.id} (${e.project})`);
+            debugLog(`[backfill] ✅ Repaired ${e.id} (${e.project})`);
         }
         catch (err) {
             failed++;
@@ -762,7 +786,7 @@ export async function memoryHistoryHandler(args) {
     }
     const { project, limit = 10 } = args;
     const storage = await getStorage();
-    console.error(`[memory_history] Fetching history for project="${project}" (limit=${limit})`);
+    debugLog(`[memory_history] Fetching history for project="${project}" (limit=${limit})`);
     const history = await storage.getHistory(project, PRISM_USER_ID, Math.min(limit, 50));
     if (history.length === 0) {
         return {
@@ -803,7 +827,7 @@ export async function memoryCheckoutHandler(args) {
     }
     const { project, target_version } = args;
     const storage = await getStorage();
-    console.error(`[memory_checkout] Reverting project="${project}" to version ${target_version}`);
+    debugLog(`[memory_checkout] Reverting project="${project}" to version ${target_version}`);
     // 1. Find the target snapshot
     const history = await storage.getHistory(project, PRISM_USER_ID, 50);
     const targetState = history.find(h => h.version === target_version);
@@ -955,7 +979,7 @@ export async function sessionSaveImageHandler(args) {
     await storage.saveHandoff(handoffUpdate, currentVersion);
     const fileSize = fs.statSync(vaultPath).size;
     const sizeKB = (fileSize / 1024).toFixed(1);
-    console.error(`[Visual Memory] Saved image [${imageId}] for "${project}" (${sizeKB}KB, ${ext})`);
+    debugLog(`[Visual Memory] Saved image [${imageId}] for "${project}" (${sizeKB}KB, ${ext})`);
     return {
         content: [{
                 type: "text",
@@ -1025,7 +1049,7 @@ export async function sessionViewImageHandler(args) {
     };
     const mimeType = MIME_MAP[ext] || "image/png";
     const fileSize = fs.statSync(vaultPath).size;
-    console.error(`[Visual Memory] Retrieved image [${image_id}] for "${project}" (${(fileSize / 1024).toFixed(1)}KB)`);
+    debugLog(`[Visual Memory] Retrieved image [${image_id}] for "${project}" (${(fileSize / 1024).toFixed(1)}KB)`);
     // Return MCP content array with text + image
     return {
         content: [
@@ -1069,7 +1093,7 @@ export async function sessionHealthCheckHandler(args) {
         };
     }
     const autoFix = args.auto_fix || false; // default: read-only scan
-    console.error("[Health Check] Running fsck (auto_fix=" + autoFix + ")");
+    debugLog("[Health Check] Running fsck (auto_fix=" + autoFix + ")");
     try {
         // Get the storage backend (SQLite or Supabase)
         const storage = await getStorage();
@@ -1082,11 +1106,11 @@ export async function sessionHealthCheckHandler(args) {
         if (autoFix && report.issues.length > 0) {
             const embeddingIssue = report.issues.find(i => i.check === "missing_embeddings");
             if (embeddingIssue && embeddingIssue.count > 0) {
-                console.error("[Health Check] Auto-fixing " + embeddingIssue.count + " missing embeddings...");
+                debugLog("[Health Check] Auto-fixing " + embeddingIssue.count + " missing embeddings...");
                 try {
                     await backfillEmbeddingsHandler({ dry_run: false, limit: 50 });
                     fixedCount += embeddingIssue.count;
-                    console.error("[Health Check] Backfill complete.");
+                    debugLog("[Health Check] Backfill complete.");
                 }
                 catch (err) {
                     console.error("[Health Check] Backfill failed: " + err);

package/dist/utils/briefing.js

@@ -14,6 +14,7 @@
  */
 import { GoogleGenerativeAI } from "@google/generative-ai";
 import { GOOGLE_API_KEY } from "../config.js";
+import { debugLog } from "./logger.js";
 /**
  * Generates a 3-bullet Morning Briefing using Gemini.
  *
@@ -58,7 +59,7 @@ Rules:
     try {
         const result = await model.generateContent(prompt);
         const text = result.response.text().trim();
-        console.error(`[Morning Briefing] Generated for "${context.project}" (${text.length} chars)`);
+        debugLog(`[Morning Briefing] Generated for "${context.project}" (${text.length} chars)`);
         return text;
     }
     catch (error) {

package/dist/utils/embeddingApi.js

@@ -34,6 +34,7 @@
  */
 import { GoogleGenerativeAI, TaskType } from "@google/generative-ai";
 import { GOOGLE_API_KEY } from "../config.js";
+import { debugLog } from "./logger.js";
 // ─── Constants ────────────────────────────────────────────────
 // REVIEWER NOTE: Maximum characters to send to the embedding API.
 // gemini-embedding-001 supports up to 2048 tokens. At ~4 chars/token,
@@ -68,7 +69,7 @@ export async function generateEmbedding(text) {
     // Fix: truncate at the last word boundary before the limit.
     let inputText = text;
     if (inputText.length > MAX_EMBEDDING_CHARS) {
-        console.error(`[embedding] Input text truncated from ${inputText.length} to ~${MAX_EMBEDDING_CHARS} chars (word-safe)`);
+        debugLog(`[embedding] Input text truncated from ${inputText.length} to ~${MAX_EMBEDDING_CHARS} chars (word-safe)`);
         inputText = inputText.substring(0, MAX_EMBEDDING_CHARS);
         // Snap back to the last space to avoid splitting a word or surrogate pair
         const lastSpace = inputText.lastIndexOf(' ');
@@ -83,7 +84,7 @@ export async function generateEmbedding(text) {
     const genAI = new GoogleGenerativeAI(GOOGLE_API_KEY);
     const model = genAI.getGenerativeModel({ model: "gemini-embedding-001" }, { apiVersion: "v1beta" } // gemini-embedding-001 requires v1beta
     );
-    console.error(`[embedding] Generating 768-dim embedding for ${inputText.length} chars`);
+    debugLog(`[embedding] Generating 768-dim embedding for ${inputText.length} chars`);
     const result = await model.embedContent({
         content: {
             role: "user",

package/dist/utils/factMerger.js

@@ -35,6 +35,7 @@
  */
 import { GoogleGenerativeAI } from "@google/generative-ai"; // Gemini SDK for LLM calls
 import { GOOGLE_API_KEY } from "../config.js"; // API key from environment
+import { debugLog } from "./logger.js";
 /**
  * Merge old and new key_context using Gemini to resolve contradictions.
  *
@@ -57,7 +58,7 @@ import { GOOGLE_API_KEY } from "../config.js"; // API key from environment
 export async function consolidateFacts(oldContext, newContext) {
     // Guard: need API key to call Gemini
     if (!GOOGLE_API_KEY) {
-        console.error("[FactMerger] Skipped — no GOOGLE_API_KEY configured");
+        debugLog("[FactMerger] Skipped — no GOOGLE_API_KEY configured");
         return newContext; // fallback: just use the new context as-is
     }
     // Guard: if either context is empty, no merging needed
@@ -69,7 +70,7 @@ export async function consolidateFacts(oldContext, newContext) {
     }
     // Guard: if old and new are identical, skip the LLM call entirely
     if (oldContext.trim() === newContext.trim()) {
-        console.error("[FactMerger] Old and new context are identical — skipping merge");
+        debugLog("[FactMerger] Old and new context are identical — skipping merge");
         return newContext; // no changes needed
     }
     // Initialize Gemini with the configured API key
@@ -96,7 +97,7 @@ export async function consolidateFacts(oldContext, newContext) {
     // Extract and trim the merged text from Gemini's response
     const mergedText = result.response.text().trim();
     // Log the merge result for debugging (to stderr, not stdout)
-    console.error("[FactMerger] Merged context (" +
+    debugLog("[FactMerger] Merged context (" +
         oldContext.length + " chars old + " +
         newContext.length + " chars new → " +
         mergedText.length + " chars merged)");

package/dist/utils/healthCheck.js

@@ -23,6 +23,7 @@
  */
 import { GoogleGenerativeAI } from "@google/generative-ai"; // Gemini SDK
 import { GOOGLE_API_KEY } from "../config.js"; // API key from env
+import { debugLog } from "./logger.js";
 /**
  * Scan agent memory for prompt injection attacks.
  *
@@ -44,7 +45,7 @@ import { GOOGLE_API_KEY } from "../config.js"; // API key from env
 export async function scanForPromptInjection(projectContext) {
     // No API key = skip scan gracefully (don't block health check)
     if (!GOOGLE_API_KEY) {
-        console.error("[Security Scan] Skipped — no GOOGLE_API_KEY configured");
+        debugLog("[Security Scan] Skipped — no GOOGLE_API_KEY configured");
         return { safe: true }; // assume safe when we can't check
     }
     // Don't scan empty context — nothing to analyze
@@ -81,7 +82,7 @@ export async function scanForPromptInjection(projectContext) {
             .replace(/```/g, "") // remove ```
             .trim(); // trim whitespace
         const parsed = JSON.parse(cleaned); // parse JSON
-        console.error("[Security Scan] Result: safe=" + parsed.safe +
+        debugLog("[Security Scan] Result: safe=" + parsed.safe +
             (parsed.reason ? ", reason=" + parsed.reason : ""));
         return {
             safe: Boolean(parsed.safe), // normalize to boolean

package/dist/utils/logger.js

@@ -0,0 +1,12 @@
+import { PRISM_DEBUG_LOGGING } from "../config.js";
+/**
+ * Logs a message to stderr only if PRISM_DEBUG_LOGGING is true.
+ * Use this for verbose traces (e.g., initialization, request tracking)
+ * that should be hidden from users by default but remain available
+ * for troubleshooting.
+ */
+export function debugLog(message) {
+    if (PRISM_DEBUG_LOGGING) {
+        console.error(message);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "2.3.9",
+  "version": "2.3.11",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — local-first MCP server with persistent memory (SQLite/Supabase), visual dashboard, time travel, multi-agent sync, Morning Briefings, reality drift detection, code mode templates, semantic vector search, and Brave Search + Gemini analysis. Zero-config local mode.",
   "module": "index.ts",