prism-mcp-server 3.1.1 → 4.2.0

package/dist/storage/sqlite.js

@@ -303,6 +303,36 @@ export class SqliteStorage {
         updated_at TEXT DEFAULT (datetime('now'))
       )
     `);
+        // ─── v4.0 Migration: Active Behavioral Memory ──────────────
+        // Three new columns for typed experience events and insight graduation.
+        // Uses the proven idempotent try/catch pattern for safe ALTER TABLE.
+        try {
+            await this.db.execute(`ALTER TABLE session_ledger ADD COLUMN event_type TEXT DEFAULT 'session'`);
+            debugLog("[SqliteStorage] v4.0 migration: added event_type column");
+        }
+        catch (e) {
+            if (!e.message?.includes("duplicate column name"))
+                throw e;
+        }
+        try {
+            await this.db.execute(`ALTER TABLE session_ledger ADD COLUMN confidence_score INTEGER DEFAULT NULL`);
+            debugLog("[SqliteStorage] v4.0 migration: added confidence_score column");
+        }
+        catch (e) {
+            if (!e.message?.includes("duplicate column name"))
+                throw e;
+        }
+        try {
+            await this.db.execute(`ALTER TABLE session_ledger ADD COLUMN importance INTEGER DEFAULT 0`);
+            debugLog("[SqliteStorage] v4.0 migration: added importance column");
+        }
+        catch (e) {
+            if (!e.message?.includes("duplicate column name"))
+                throw e;
+        }
+        // Composite indexes for behavioral queries (idempotent via IF NOT EXISTS)
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_ledger_event_type ON session_ledger(event_type)`);
+        await this.db.execute(`CREATE INDEX IF NOT EXISTS idx_ledger_importance ON session_ledger(importance DESC)`);
     }
     // ─── PostgREST Filter Parser ───────────────────────────────
     //
@@ -434,8 +464,10 @@ export class SqliteStorage {
         await this.db.execute({
             sql: `INSERT INTO session_ledger
         (id, project, conversation_id, user_id, role, summary, todos, files_changed,
-         decisions, keywords, is_rollup, rollup_count, title, agent_name, created_at, session_date)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+         decisions, keywords, is_rollup, rollup_count, title, agent_name,
+         event_type, confidence_score, importance,
+         created_at, session_date)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
             args: [
                 id,
                 entry.project,
@@ -451,6 +483,9 @@ export class SqliteStorage {
                 entry.rollup_count || 0,
                 entry.is_rollup ? `Session Rollup (${entry.rollup_count || 0} entries)` : null,
                 entry.is_rollup ? "prism-compactor" : null,
+                entry.event_type || "session", // v4.0: default to 'session'
+                entry.confidence_score ?? null, // v4.0: nullable
+                entry.importance || 0, // v4.0: default to 0
                 now,
                 now,
             ],
@@ -674,6 +709,27 @@ export class SqliteStorage {
         context.active_decisions = this.parseJsonColumn(handoff.active_decisions);
         context.active_branch = handoff.active_branch;
         context.key_context = handoff.key_context;
+        // ─── v4.0: Behavioral Warnings (Standard & Deep) ────────────
+        // Hoisted above the branch so both levels get warnings without duplication.
+        // Filters: role-scoped, non-archived, non-deleted, high importance.
+        const warningsResult = await this.db.execute({
+            sql: `SELECT summary, importance
+            FROM session_ledger
+            WHERE project = ? AND user_id = ? AND role = ?
+              AND event_type = 'correction'
+              AND importance >= 3
+              AND deleted_at IS NULL
+              AND archived_at IS NULL
+            ORDER BY importance DESC
+            LIMIT 5`,
+            args: [project, userId, effectiveRole],
+        });
+        if (warningsResult.rows.length > 0) {
+            context.behavioral_warnings = warningsResult.rows.map(r => ({
+                summary: r.summary,
+                importance: r.importance,
+            }));
+        }
         if (level === "standard") {
             // Add recent ledger entries (role-scoped)
             const recentLedger = await this.db.execute({
@@ -1297,6 +1353,42 @@ export class SqliteStorage {
         });
         const expired = result.rowsAffected || 0;
         debugLog(`[SqliteStorage] TTL sweep: expired ${expired} entries for "${project}" (cutoff: ${cutoffStr})`);
+        // ─── v4.0: Importance Decay ──────────────────────────────────
+        // Decay importance of experience entries not referenced in 30 days.
+        // This prevents "Insight Bloat" — old corrections that are no longer
+        // relevant gradually lose their weight and stop appearing as warnings.
+        // Only targets typed experience events (event_type != 'session'),
+        // so regular session logs are never affected.
+        const decayResult = await this.db.execute({
+            sql: `UPDATE session_ledger
+            SET importance = MAX(0, importance - 1)
+            WHERE project = ? AND user_id = ?
+              AND importance > 0
+              AND event_type != 'session'
+              AND created_at < datetime('now', '-30 days')
+              AND deleted_at IS NULL`,
+            args: [project, userId],
+        });
+        const decayed = decayResult.rowsAffected || 0;
+        if (decayed > 0) {
+            debugLog(`[SqliteStorage] Importance decay: reduced ${decayed} entries for "${project}"`);
+        }
         return { expired };
     }
+    // ─── v4.0: Insight Graduation ──────────────────────────────────
+    //
+    // Adjusts the importance score of a ledger entry.
+    // Used by knowledge_upvote (+1) and knowledge_downvote (-1).
+    // Importance is clamped via MAX(0, ...) — never goes negative.
+    // Entries reaching importance >= 7 are considered "graduated"
+    // and will appear prominently in behavioral warnings.
+    async adjustImportance(id, delta, userId) {
+        await this.db.execute({
+            sql: `UPDATE session_ledger
+            SET importance = MAX(0, importance + ?)
+            WHERE id = ? AND user_id = ?`,
+            args: [delta, id, userId],
+        });
+        debugLog(`[SqliteStorage] Adjusted importance for ${id} by ${delta > 0 ? "+" : ""}${delta}`);
+    }
 }

package/dist/storage/supabase.js

@@ -15,10 +15,18 @@
 import { supabasePost, supabaseGet, supabaseRpc, supabasePatch, supabaseDelete, } from "../utils/supabaseApi.js";
 import { debugLog } from "../utils/logger.js";
 import { getSetting as cfgGet, setSetting as cfgSet, getAllSettings as cfgGetAll } from "./configStorage.js";
+import { runAutoMigrations } from "./supabaseMigrations.js";
 export class SupabaseStorage {
     // ─── Lifecycle ─────────────────────────────────────────────
     async initialize() {
         debugLog("[SupabaseStorage] Initialized (REST API, stateless)");
+        // Auto-apply pending schema migrations (non-fatal)
+        try {
+            await runAutoMigrations();
+        }
+        catch (err) {
+            console.error("[SupabaseStorage] Auto-migration failed. Server will continue, but some tools may be unstable.", err instanceof Error ? err.message : err);
+        }
     }
     async close() {
         debugLog("[SupabaseStorage] Closed (no-op for REST)");
@@ -41,6 +49,10 @@ export class SupabaseStorage {
                 title: `Session Rollup (${entry.rollup_count || 0} entries)`,
                 agent_name: "prism-compactor",
             }),
+            // v4.0: Active Behavioral Memory fields
+            event_type: entry.event_type || "session",
+            ...(entry.confidence_score !== undefined && { confidence_score: entry.confidence_score }),
+            importance: entry.importance || 0,
         };
         return supabasePost("session_ledger", record);
     }
@@ -348,4 +360,27 @@ export class SupabaseStorage {
         debugLog(`[SupabaseStorage] TTL sweep completed for "${project}" (cutoff: ${cutoffStr})`);
         return { expired: 0 };
     }
+    // ─── v4.0: Insight Graduation ──────────────────────────────────
+    async adjustImportance(id, delta, userId) {
+        // Supabase PATCH can't do MAX(0, importance + delta) directly.
+        // Fetch current value first, compute new, then patch.
+        try {
+            const data = await supabaseGet("session_ledger", {
+                id: `eq.${id}`,
+                user_id: `eq.${userId}`,
+                select: "importance",
+            });
+            const rows = Array.isArray(data) ? data : [];
+            const current = rows[0]?.importance ?? 0;
+            const newVal = Math.max(0, current + delta);
+            await supabasePatch("session_ledger", { importance: newVal }, {
+                id: `eq.${id}`,
+                user_id: `eq.${userId}`,
+            });
+            debugLog(`[SupabaseStorage] Adjusted importance for ${id} by ${delta > 0 ? "+" : ""}${delta} (${current} → ${newVal})`);
+        }
+        catch (e) {
+            debugLog("[SupabaseStorage] adjustImportance failed: " + (e instanceof Error ? e.message : String(e)));
+        }
+    }
 }

package/dist/storage/supabaseMigrations.js

@@ -0,0 +1,110 @@
+/**
+ * Supabase Auto-Migration Runner (v4.1)
+ *
+ * On server startup, this module checks the `prism_schema_versions` table
+ * and applies any pending DDL migrations via the `prism_apply_ddl` RPC.
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * HOW IT WORKS:
+ *   1. For each migration in MIGRATIONS[], call prism_apply_ddl(version, name, sql)
+ *   2. The Postgres function checks if the version is already applied (idempotent)
+ *   3. If not applied, it EXECUTE's the SQL and records the version
+ *
+ * GRACEFUL DEGRADATION:
+ *   If prism_apply_ddl doesn't exist (PGRST202), the runner logs a
+ *   warning and skips — the server still starts, but v4+ tools may
+ *   fail against an old schema.
+ *
+ * SECURITY NOTE:
+ *   prism_apply_ddl is SECURITY DEFINER (runs as postgres owner).
+ *   The prism_schema_versions table has RLS: only service_role can write.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+import { supabaseRpc } from "../utils/supabaseApi.js";
+/**
+ * All Supabase DDL migrations.
+ *
+ * IMPORTANT: Only add migrations for schema changes that Supabase
+ * users need. SQLite handles its own schema in sqlite.ts.
+ *
+ * Each `sql` string is passed to Postgres EXECUTE — it runs as a
+ * single transaction. Use IF NOT EXISTS / IF EXISTS guards generously.
+ */
+export const MIGRATIONS = [
+    {
+        version: 26,
+        name: "active_behavioral_memory",
+        sql: `
+      -- v4.0: Active Behavioral Memory columns
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS event_type TEXT NOT NULL DEFAULT 'session';
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS confidence_score INTEGER DEFAULT NULL;
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS importance INTEGER NOT NULL DEFAULT 0;
+
+      -- Soft-delete / archival columns
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMPTZ DEFAULT NULL;
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS archived_at TIMESTAMPTZ DEFAULT NULL;
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS deleted_reason TEXT DEFAULT NULL;
+
+      -- Indexes
+      CREATE INDEX IF NOT EXISTS idx_ledger_event_type ON session_ledger(event_type);
+      CREATE INDEX IF NOT EXISTS idx_ledger_importance ON session_ledger(importance DESC);
+
+      -- Partial index for high-priority warnings
+      CREATE INDEX IF NOT EXISTS idx_ledger_behavioral_warnings
+        ON session_ledger(project, user_id, role, importance DESC)
+        WHERE event_type = 'correction' AND importance >= 3
+          AND deleted_at IS NULL AND archived_at IS NULL;
+    `,
+    },
+    // Future migrations go here (version 28+)
+];
+/**
+ * Current schema version — derived from the MIGRATIONS array.
+ * Automatically updates when new migrations are added.
+ * Used for logging and diagnostics.
+ */
+export const CURRENT_SCHEMA_VERSION = MIGRATIONS.length > 0 ? MIGRATIONS[MIGRATIONS.length - 1].version : 27;
+// ─── Runner ──────────────────────────────────────────────────────
+/**
+ * Run all pending auto-migrations on Supabase startup.
+ *
+ * Called from SupabaseStorage.initialize(). Non-fatal: if the
+ * migration infrastructure (027) hasn't been applied, the runner
+ * logs a warning and returns silently.
+ */
+export async function runAutoMigrations() {
+    if (MIGRATIONS.length === 0) {
+        return; // Nothing to apply
+    }
+    console.error(`[Prism Auto-Migration] Schema v${CURRENT_SCHEMA_VERSION} — checking ${MIGRATIONS.length} migration(s)…`);
+    for (const migration of MIGRATIONS) {
+        try {
+            const result = await supabaseRpc("prism_apply_ddl", {
+                p_version: migration.version,
+                p_name: migration.name,
+                p_sql: migration.sql,
+            });
+            // Parse the JSON result from the RPC
+            const data = (typeof result === "string" ? JSON.parse(result) : result);
+            if (data?.status === "applied") {
+                console.error(`[Prism Auto-Migration] ✅ Applied migration ${migration.version}: ${migration.name}`);
+            }
+            else if (data?.status === "already_applied") {
+                // Silent skip — expected for idempotent restarts
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            // PGRST202 = function not found → migration infra (027) not applied yet
+            if (errMsg.includes("PGRST202") || errMsg.includes("Could not find the function")) {
+                console.error("[Prism Auto-Migration] ⚠️  prism_apply_ddl() not found. " +
+                    "Apply migration 027_auto_migration_infra.sql to enable auto-migrations.\n" +
+                    "  Run: supabase db push  (or apply the SQL in the Supabase Dashboard SQL Editor)");
+                return; // Stop — no point trying further migrations
+            }
+            // Any other error: log and throw to surface the problem
+            console.error(`[Prism Auto-Migration] ❌ Migration ${migration.version} (${migration.name}) failed: ${errMsg}`);
+            throw err;
+        }
+    }
+}

package/dist/tools/index.js

@@ -26,8 +26,8 @@ export { webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, br
 // This file always exports them — server.ts decides whether to include them in the tool list.
 //
 // v0.4.0: Added SESSION_COMPACT_LEDGER_TOOL and SESSION_SEARCH_MEMORY_TOOL
-export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL } from "./sessionMemoryDefinitions.js";
-export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler, knowledgeSetRetentionHandler } from "./sessionMemoryHandlers.js";
+export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_FORGET_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL } from "./sessionMemoryDefinitions.js";
+export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionSaveImageHandler, sessionViewImageHandler, sessionHealthCheckHandler, sessionForgetMemoryHandler, knowledgeSetRetentionHandler, sessionSaveExperienceHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler } from "./sessionMemoryHandlers.js";
 // ── Compaction Handler (v0.4.0 — Enhancement #2) ──
 // The compaction handler is in a separate file because it's significantly
 // more complex than the other session memory handlers (chunked Gemini

package/dist/tools/sessionMemoryDefinitions.js

@@ -37,7 +37,7 @@ export const SESSION_SAVE_LEDGER_TOOL = {
             },
             role: {
                 type: "string",
-                description: "v3.0: Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Defaults to 'global'.",
+                description: "Optional. Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Omit to let the server auto-resolve from dashboard settings.",
             },
         },
         required: ["project", "conversation_id", "summary"],
@@ -90,7 +90,7 @@ export const SESSION_SAVE_HANDOFF_TOOL = {
             },
             role: {
                 type: "string",
-                description: "v3.0: Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Defaults to 'global'.",
+                description: "Optional. Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Omit to let the server auto-resolve from dashboard settings.",
             },
         },
         required: ["project"],
@@ -119,7 +119,12 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
             },
             role: {
                 type: "string",
-                description: "v3.0: Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Defaults to 'global'. When set, also injects active_team roster.",
+                description: "Optional. Agent role for Hivemind scoping (e.g., 'dev', 'qa', 'pm'). Omit to let the server auto-resolve from dashboard settings. When set, also injects active_team roster.",
+            },
+            // v4.0: Token Budget
+            max_tokens: {
+                type: "integer",
+                description: "Maximum token budget for context response. Uses 1 token ≈ 4 chars heuristic. When set, the response is truncated to fit within the budget. Default: unlimited.",
             },
         },
         required: ["project"],
@@ -635,3 +640,106 @@ export function isKnowledgeSetRetentionArgs(args) {
         "ttl_days" in args &&
         typeof args.ttl_days === "number");
 }
+// ─── v4.0: Active Behavioral Memory Tools ────────────────────
+export const SESSION_SAVE_EXPERIENCE_TOOL = {
+    name: "session_save_experience",
+    description: "Record a typed experience event. Unlike session_save_ledger (flat logs), " +
+        "this captures structured behavioral data for pattern detection.\n\n" +
+        "Event Types:\n" +
+        "- **correction**: Agent was corrected by user\n" +
+        "- **success**: Task completed successfully\n" +
+        "- **failure**: Task failed\n" +
+        "- **learning**: New knowledge acquired",
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project identifier.",
+            },
+            event_type: {
+                type: "string",
+                enum: ["correction", "success", "failure", "learning"],
+                description: "Type of behavioral event.",
+            },
+            context: {
+                type: "string",
+                description: "What the agent was doing when the event occurred.",
+            },
+            action: {
+                type: "string",
+                description: "What action was tried.",
+            },
+            outcome: {
+                type: "string",
+                description: "What happened as a result.",
+            },
+            correction: {
+                type: "string",
+                description: "What should have been done instead (for correction type).",
+            },
+            confidence_score: {
+                type: "integer",
+                minimum: 1,
+                maximum: 100,
+                description: "Agent's confidence in the outcome (1-100).",
+            },
+            role: {
+                type: "string",
+                description: "Optional. Agent role for Hivemind scoping. Omit to let the server auto-resolve from dashboard settings.",
+            },
+        },
+        required: ["project", "event_type", "context", "action", "outcome"],
+    },
+};
+export function isSessionSaveExperienceArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "project" in args &&
+        typeof args.project === "string" &&
+        "event_type" in args &&
+        typeof args.event_type === "string" &&
+        "context" in args &&
+        typeof args.context === "string" &&
+        "action" in args &&
+        typeof args.action === "string" &&
+        "outcome" in args &&
+        typeof args.outcome === "string");
+}
+export const KNOWLEDGE_UPVOTE_TOOL = {
+    name: "knowledge_upvote",
+    description: "Upvote a memory entry to increase its importance (graduation). " +
+        "Entries with importance >= 7 become 'graduated' insights that always " +
+        "surface in behavioral warnings.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: {
+                type: "string",
+                description: "The UUID of the ledger entry to upvote.",
+            },
+        },
+        required: ["id"],
+    },
+};
+export const KNOWLEDGE_DOWNVOTE_TOOL = {
+    name: "knowledge_downvote",
+    description: "Downvote a memory entry to decrease its importance. " +
+        "Importance cannot go below 0.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            id: {
+                type: "string",
+                description: "The UUID of the ledger entry to downvote.",
+            },
+        },
+        required: ["id"],
+    },
+};
+export function isKnowledgeVoteArgs(args) {
+    return (typeof args === "object" &&
+        args !== null &&
+        "id" in args &&
+        typeof args.id === "string");
+}

package/dist/tools/sessionMemoryHandlers.js

@@ -33,7 +33,8 @@ import { captureLocalEnvironment } from "../utils/autoCapture.js";
 import { isSessionSaveLedgerArgs, isSessionSaveHandoffArgs, isSessionLoadContextArgs, isKnowledgeSearchArgs, isKnowledgeForgetArgs, isSessionSearchMemoryArgs, isBackfillEmbeddingsArgs, isMemoryHistoryArgs, isMemoryCheckoutArgs, isSessionHealthCheckArgs, // v2.2.0: health check type guard
 isSessionForgetMemoryArgs, // Phase 2: GDPR-compliant memory deletion type guard
 isKnowledgeSetRetentionArgs, // v3.1: TTL retention policy type guard
- } from "./sessionMemoryDefinitions.js";
+// v4.0: Active Behavioral Memory type guards
+isSessionSaveExperienceArgs, isKnowledgeVoteArgs, } from "./sessionMemoryDefinitions.js";
 // v3.1: In-memory debounce lock for auto-compaction.
 // Prevents multiple concurrent Gemini compaction tasks for the same project
 // when many agents call session_save_ledger at the same time.
@@ -54,6 +55,23 @@ export async function sessionSaveLedgerHandler(args) {
     }
     const { project, conversation_id, summary, todos, files_changed, decisions, role } = args;
     const storage = await getStorage();
+    // ─── Repo path mismatch validation (v4.2) ───
+    let repoPathWarning = "";
+    if (files_changed && files_changed.length > 0) {
+        try {
+            const configuredPath = await getSetting(`repo_path:${project}`, "");
+            if (configuredPath && configuredPath.trim()) {
+                const normalizedPath = configuredPath.trim().replace(/\\/g, "/").replace(/\/+$/, ""); // normalize + strip trailing slash
+                const mismatched = files_changed.filter((f) => !f.replace(/\\/g, "/").startsWith(normalizedPath));
+                if (mismatched.length === files_changed.length) {
+                    repoPathWarning = `\n\n⚠️ Project mismatch: none of the files_changed paths match repo_path "${normalizedPath}" ` +
+                        `configured for project "${project}". Consider saving under the correct project.`;
+                    debugLog(`[session_save_ledger] Repo path mismatch for "${project}": expected prefix "${normalizedPath}"`);
+                }
+            }
+        }
+        catch { /* getSetting non-fatal */ }
+    }
     debugLog(`[session_save_ledger] Saving ledger entry for project="${project}"`);
     // Auto-extract keywords from summary + decisions for knowledge accumulation
     const combinedText = [summary, ...(decisions || [])].join(" ");
@@ -129,6 +147,7 @@ export async function sessionSaveLedgerHandler(args) {
                     (files_changed?.length ? `Files changed: ${files_changed.length}\n` : "") +
                     (decisions?.length ? `Decisions: ${decisions.length}\n` : "") +
                     (GOOGLE_API_KEY ? `📊 Embedding generation queued for semantic search.\n` : "") +
+                    repoPathWarning +
                     `\nRaw response: ${JSON.stringify(result)}`,
             }],
         isError: false,
@@ -359,6 +378,8 @@ export async function sessionLoadContextHandler(args) {
         throw new Error("Invalid arguments for session_load_context");
     }
     const { project, level = "standard", role } = args;
+    const maxTokens = args.max_tokens
+        || parseInt(await getSetting("max_tokens", "0"), 10) || undefined; // v4.0: arg > dashboard setting > none
     const agentName = await getSetting("agent_name", "");
     const validLevels = ["quick", "standard", "deep"];
     if (!validLevels.includes(level)) {
@@ -533,11 +554,27 @@ export async function sessionLoadContextHandler(args) {
         const skillPart = skillLoaded ? ` · 📜 \`${effectiveRole}\` skill loaded` : (effectiveRole ? " · 📜 No skill configured" : "");
         greetingBlock = `\n\n[👤 AGENT IDENTITY]\n${namePart}${rolePart}${skillPart}`;
     }
+    // Build the response object before v4.0 augmentations
+    let responseText = `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${driftReport}${briefingBlock}${greetingBlock}${visualMemoryBlock}${skillBlock}${versionNote}`;
+    // ─── v4.0: Behavioral Warnings Injection ───────────────────
+    // If loadContext returned behavioral_warnings, add them to the
+    // formatted output so the agent sees them prominently.
+    const behavWarnings = data?.behavioral_warnings;
+    if (behavWarnings && behavWarnings.length > 0) {
+        responseText += `\n\n[⚠️ BEHAVIORAL WARNINGS]\n` +
+            behavWarnings.map(w => `- ${w.summary} (importance: ${w.importance})`).join("\n");
+    }
+    // ─── v4.0: Token Budget Truncation ─────────────────────────
+    // 1 token ≈ 4 chars heuristic. Truncate if response exceeds budget.
+    if (maxTokens && maxTokens > 0) {
+        const maxChars = maxTokens * 4;
+        if (responseText.length > maxChars) {
+            responseText = responseText.slice(0, maxChars) + "\n\n[… truncated to fit token budget]";
+            debugLog(`[session_load_context] Truncated response to ${maxTokens} tokens (${maxChars} chars)`);
+        }
+    }
     return {
-        content: [{
-                type: "text",
-                text: `📋 Session context for "${project}" (${level}):\n\n${formattedContext.trim()}${driftReport}${briefingBlock}${greetingBlock}${visualMemoryBlock}${skillBlock}${versionNote}`,
-            }],
+        content: [{ type: "text", text: responseText }],
         isError: false,
     };
 }
@@ -1553,3 +1590,116 @@ export async function knowledgeSetRetentionHandler(args) {
         isError: false,
     };
 }
+// ─── v4.0: Experience Save Handler ───────────────────────────
+/**
+ * Records a typed experience event for behavioral pattern detection.
+ * Unlike session_save_ledger (flat logs), this captures structured
+ * context → action → outcome data with confidence scoring.
+ *
+ * Corrections start with importance = 1 to jumpstart visibility;
+ * all other event types start at 0.
+ */
+export async function sessionSaveExperienceHandler(args) {
+    if (!isSessionSaveExperienceArgs(args)) {
+        throw new Error("Invalid arguments for session_save_experience");
+    }
+    const { project, event_type, context: ctx, action, outcome, correction, confidence_score, role } = args;
+    const storage = await getStorage();
+    debugLog(`[session_save_experience] Recording ${event_type} event for project="${project}"`);
+    // Format structured summary from event fields
+    let summary = `[${event_type.toUpperCase()}] ${ctx} → ${action} → ${outcome}`;
+    if (event_type === "correction" && correction) {
+        summary += ` | CORRECTION: ${correction}`;
+    }
+    // Auto-extract keywords from the structured summary
+    const keywords = toKeywordArray(summary);
+    debugLog(`[session_save_experience] Extracted ${keywords.length} keywords: ${keywords.slice(0, 5).join(", ")}...`);
+    const effectiveRole = role || await getSetting("default_role", "global");
+    const result = await storage.saveLedger({
+        project,
+        conversation_id: "experience-event",
+        user_id: PRISM_USER_ID,
+        role: effectiveRole,
+        event_type,
+        summary,
+        decisions: [
+            `Context: ${ctx}`,
+            `Action: ${action}`,
+            `Outcome: ${outcome}`,
+            ...(correction ? [`Correction: ${correction}`] : []),
+        ],
+        keywords,
+        confidence_score: typeof confidence_score === "number" ? confidence_score : undefined,
+        // Corrections start with importance 1 to jumpstart visibility
+        importance: event_type === "correction" ? 1 : 0,
+    });
+    // Fire-and-forget embedding generation
+    if (GOOGLE_API_KEY && result) {
+        const embeddingText = summary;
+        const savedEntry = Array.isArray(result) ? result[0] : result;
+        const entryId = savedEntry?.id;
+        if (entryId) {
+            generateEmbedding(embeddingText)
+                .then(async (embedding) => {
+                await storage.patchLedger(entryId, {
+                    embedding: JSON.stringify(embedding),
+                });
+                debugLog(`[session_save_experience] Embedding saved for entry ${entryId}`);
+            })
+                .catch((err) => {
+                console.error(`[session_save_experience] Embedding failed (non-fatal): ${err.message}`);
+            });
+        }
+    }
+    return {
+        content: [{
+                type: "text",
+                text: `✅ Experience recorded: ${event_type} for project "${project}"\n` +
+                    `Summary: ${summary}\n` +
+                    (confidence_score !== undefined ? `Confidence: ${confidence_score}%\n` : "") +
+                    `Importance: ${event_type === "correction" ? 1 : 0} (upvote to increase)`,
+            }],
+        isError: false,
+    };
+}
+// ─── v4.0: Knowledge Upvote Handler ──────────────────────────
+/**
+ * Upvotes a ledger entry to increase its importance.
+ * Entries reaching importance >= 7 are considered "graduated"
+ * and will always surface as Behavioral Warnings.
+ */
+export async function knowledgeUpvoteHandler(args) {
+    if (!isKnowledgeVoteArgs(args)) {
+        throw new Error("Invalid arguments for knowledge_upvote");
+    }
+    const storage = await getStorage();
+    await storage.adjustImportance(args.id, 1, PRISM_USER_ID);
+    debugLog(`[knowledge_upvote] Upvoted entry ${args.id}`);
+    return {
+        content: [{
+                type: "text",
+                text: `👍 Entry ${args.id} upvoted (+1 importance).`,
+            }],
+        isError: false,
+    };
+}
+// ─── v4.0: Knowledge Downvote Handler ────────────────────────
+/**
+ * Downvotes a ledger entry to decrease its importance.
+ * Importance is clamped at 0 (never goes negative).
+ */
+export async function knowledgeDownvoteHandler(args) {
+    if (!isKnowledgeVoteArgs(args)) {
+        throw new Error("Invalid arguments for knowledge_downvote");
+    }
+    const storage = await getStorage();
+    await storage.adjustImportance(args.id, -1, PRISM_USER_ID);
+    debugLog(`[knowledge_downvote] Downvoted entry ${args.id}`);
+    return {
+        content: [{
+                type: "text",
+                text: `👎 Entry ${args.id} downvoted (-1 importance).`,
+            }],
+        isError: false,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "3.1.1",
+  "version": "4.2.0",
   "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",