prism-mcp-server 3.1.1 → 4.0.0

package/README.md

@@ -14,11 +14,13 @@
 
 ## Table of Contents
 
-- [What's New (v3.1.0)](#whats-new-in-v310---memory-lifecycle-)
+- [What's New (v4.0.0)](#whats-new-in-v400--behavioral-memory-)
 - [How Prism Compares](#how-prism-compares)
 - [Quick Start](#quick-start-zero-config--local-mode)
 - [Mind Palace Dashboard](#-the-mind-palace-dashboard)
 - [Integration Examples](#integration-examples)
+- [Claude Code Integration (Hooks)](#claude-code-integration-hooks)
+- [Gemini / Antigravity Integration](#gemini--antigravity-integration)
 - [Use Cases](#use-cases)
 - [Architecture](#architecture)
 - [Tool Reference](#tool-reference)
@@ -39,7 +41,18 @@
 
 ---
 
-## What's New in v3.1.0 — Memory Lifecycle 🔄
+## What's New in v4.0.0 — Behavioral Memory 🧠
+
+| Feature | Description |
+|---|---|
+| 🧠 **Active Behavioral Memory** | New `session_save_experience` tool — agents log actions, outcomes, corrections, and confidence scores. Prism tracks importance, applies decay over time, and injects behavioral warnings into context loading so agents learn from past mistakes. |
+| 🎯 **Dynamic Role Resolution** | Role parameter is now fully optional across all tools. The server auto-resolves from dashboard settings via `getSetting("default_role")` — set your role once in the Mind Palace Dashboard, and it applies everywhere. No more hardcoding `role: "global"`. |
+| 📏 **Token Budget** | New `max_tokens` parameter on `session_load_context` — set a token budget and the response is intelligently truncated to fit. Uses a 1 token ≈ 4 chars heuristic. |
+| 📉 **Importance Decay** | Stale behavioral experiences automatically decay over time — older corrections fade in importance to keep context fresh and relevant. |
+| 🔧 **Claude Code Hooks** | Refined SessionStart/Stop hook samples that reliably trigger MCP tool calls. Simplified from multi-step workflows to single imperative instructions. |
+
+<details>
+<summary><strong>What's in v3.1.0 — Memory Lifecycle 🔄</strong></summary>
 
 | Feature | Description |
 |---|---|
@@ -49,6 +62,8 @@
 | 📦 **PKM Export (Obsidian / Logseq)** | Export any project's full memory as a ZIP archive of Markdown files — one file per session with YAML-like frontmatter, TODOs, decisions, files-changed, and `#hashtag` keywords. Includes an `_index.md` with `[[wikilink]]` references. Click **Export ZIP** in the dashboard Lifecycle Controls card. |
 | 🧪 **Expanded Test Suite** | 37 new Vitest tests (95 total) — covers analytics queries, TTL soft-delete idempotency, rollup preservation, `activeCompactions` Set memory-leak prevention, type guards, export Markdown structure, and TTL sweep scheduler contracts. |
 
+</details>
+
 <details>
 <summary><strong>What's in v3.0.1 — Agent Identity & Brain Clean-up 🧹</strong></summary>
 
@@ -363,36 +378,124 @@ Add to your Continue `config.json` or Cline MCP settings:
 
 ---
 
-## Claude Code + Gemini Startup Compatibility
+## Claude Code Integration (Hooks)
 
-If you want consistent behavior across clients, treat startup in two phases:
+Claude Code supports **lifecycle hooks** in `~/.claude/settings.json` that fire automatically at session start and end. Use these to auto-hydrate and persist Prism memory without manual prompting.
 
-1. **Server availability**: ensure `prism-mcp` is enabled in MCP config so tools are available.
-2. **Context hydration**: explicitly call `session_load_context` at session start.
+### SessionStart Hook
 
-Recommended startup call:
+Automatically loads context when a new session begins:
 
 ```json
 {
-  "projectName": "<your-project>",
-  "level": "standard"
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json; print(json.dumps({'continue': True, 'suppressOutput': False, 'systemMessage': 'You MUST call mcp__prism-mcp__session_load_context twice before responding to the user: first with project=my-project level=standard, then with project=my-other-project level=standard. Do not skip this.'}))\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
-Important distinction:
+### Stop Hook
 
-- Auto-loading `prism-mcp` makes the server available.
-- It does **not** guarantee memory context is auto-hydrated unless your client runtime/hook invokes `session_load_context`.
+Automatically saves session memory when a session ends:
 
-Client notes:
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json; print(json.dumps({'continue': True, 'suppressOutput': False, 'systemMessage': 'MANDATORY END WORKFLOW: 1) Call mcp__prism-mcp__session_save_ledger with project and summary. 2) Call mcp__prism-mcp__session_save_handoff with expected_version set to the loaded version.'}))\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### How the Hooks Work
 
-- **Gemini runtimes** may support native startup execution depending on configuration.
-- **Claude Code** should use a local `SessionStart` hook in `~/.claude/settings.json` for deterministic startup context loading.
+The hook `command` runs a Python one-liner that returns a JSON object to Claude Code:
+
+| Field | Purpose |
+|---|---|
+| `continue: true` | Tell Claude Code to proceed (don't abort the session) |
+| `suppressOutput: false` | Show the hook result to the agent |
+| `systemMessage` | Instruction injected as a system message — the agent follows it |
 
-Verification pattern (same for both clients):
+The agent receives the `systemMessage` as an instruction and executes the tool calls. The server resolves the agent's **role** and **name** automatically from the dashboard — no need to specify them in the hook.
 
-- Print a startup marker after successful `session_load_context` (for example, `PRISM_CONTEXT_LOADED`).
-- If the marker is missing, startup hydration did not run.
+### Role Resolution — No Hardcoding Needed
+
+Prism resolves the agent role dynamically using a priority chain:
+
+```
+explicit tool argument  →  dashboard setting  →  "global" (default)
+```
+
+1. **Explicit arg wins** — if `role` is passed in the tool call, it's used directly.
+2. **Dashboard fallback** — if `role` is omitted, the server calls `getSetting("default_role")` and uses whatever role you configured in the **Mind Palace Dashboard ⚙️ Settings → Agent Identity**.
+3. **Final default** — if no dashboard setting exists, falls back to `"global"`.
+
+Change your role once in the dashboard, and it automatically applies to every session — CLI, extension, and all MCP clients.
+
+### Verification
+
+If hydration ran successfully, the agent's output will include:
+- A `[👤 AGENT IDENTITY]` block showing your dashboard-configured role and name
+- `PRISM_CONTEXT_LOADED` marker text
+
+If the marker is missing, the hook did not fire or the MCP server is not connected.
+
+---
+
+## Gemini / Antigravity Integration
+
+Gemini-based clients (like Antigravity) use `GEMINI.md` global rules or user rules for startup behavior. The server resolves the role from the dashboard automatically.
+
+### Global Rules (`~/.gemini/GEMINI.md`)
+
+```markdown
+## Prism MCP Memory Auto-Load (CRITICAL)
+At the start of every new session, call `mcp__prism-mcp__session_load_context`
+for these projects:
+- `my-project` (level=standard)
+- `my-other-project` (level=standard)
+
+After both succeed, print PRISM_CONTEXT_LOADED.
+```
+
+### User Rules (Antigravity Settings)
+
+If your Gemini client supports user rules, add the same instructions there. The key points:
+
+1. **Call `session_load_context` as a tool** — not `read_resource`. Only the tool returns the `[👤 AGENT IDENTITY]` block.
+2. **Verify** — confirm the response includes `version` and `last_summary`.
+
+### Session End
+
+At the end of each session, save state:
+
+```markdown
+## Session End Protocol
+1) Call `mcp__prism-mcp__session_save_ledger` with project and summary.
+2) Call `mcp__prism-mcp__session_save_handoff` with expected_version from the loaded version.
+```
 
 ---
 
@@ -763,48 +866,11 @@ The agent boots up knowing exactly what to do — zero prompting needed.
 
 For the best experience, configure your AI coding assistant to **automatically call `session_load_context`** at the start of every new session. This ensures your agent always boots with full project memory — no manual prompting needed.
 
-<details>
-<summary><strong>Claude Code (.clauderules / CLAUDE.md)</strong></summary>
-
-Add this rule to your project's `.clauderules` or `CLAUDE.md`:
-
-```markdown
-
-## Prism MCP Memory Auto-Load (CRITICAL)
-At the start of every new session, you MUST call `session_load_context`
-at the `standard` level for these projects:
-- `my-project`
-- `my-other-project`
-
-Do NOT skip this step.
-```
-
-</details>
-
-<details>
-<summary><strong>Gemini / Antigravity (GEMINI.md)</strong></summary>
-
-Add this rule to your `~/.gemini/GEMINI.md` global rules file:
-
-```markdown
-
-## Prism MCP Memory Auto-Load (CRITICAL)
-
-**At the start of every new session**, immediately after displaying
-the startup block, you MUST call `session_load_context` (via the
-`prism-mcp` MCP server) at the `standard` level for these projects:
-- `my-project`
-- `my-other-project`
+See the full setup guides for each client:
+- **[Claude Code Integration (Hooks)](#claude-code-integration-hooks)** — `SessionStart` and `Stop` hook JSON samples for `~/.claude/settings.json`
+- **[Gemini / Antigravity Integration](#gemini--antigravity-integration)** — global rules for `~/.gemini/GEMINI.md` or user rules
 
-This ensures accumulated project memory, pending TODOs, and key context
-from previous sessions are always available. Do NOT skip this step.
-
-**IMPORTANT:** The `prism-mcp` MCP server is always available.
-Do NOT display any warnings or notes about MCP server availability
-— just call the tools directly. Never claim the server is unavailable.
-```
-
-</details>
+> **Key principle:** Never hardcode a `role` in your hooks or rules. Set your role once in the **Mind Palace Dashboard ⚙️ Settings → Agent Identity**, and Prism automatically resolves it for every tool call across all clients. See [Role Resolution](#role-resolution--no-hardcoding-needed).
 
 > **Tip:** Replace `my-project` with your actual project identifiers. You can list as many projects as you need — each one gets its own independent memory timeline.
 
@@ -1136,6 +1202,18 @@ See [What's New in v3.0.1](#whats-new-in-v301---agent-identity--brain-clean-up-)
 
 See [What's New in v3.0.0 — Agent Hivemind](#whats-new-in-v300---agent-hivemind-) above.
 
+### 🔜 v4.0 — Active Behavioral Memory (In Development)
+
+Evolves Prism from passive session logging to an **experience learning engine** that shapes agent behavior over time.
+
+| Feature | Description |
+|---------|-------------|
+| **Structured Event Types** | Typed experience events (`correction`, `success`, `failure`, `learning`) with `confidence_score` (1-100) — agents don't just log, they learn |
+| **Token-Budgeted Context Loading** | `max_tokens` param on `session_load_context` — guarantees constant cost regardless of DB size (1 token ≈ 4 chars heuristic) |
+| **`session_save_experience` Tool** | Dedicated tool for behavioral data: context → action → outcome → correction. Auto-extracts keywords, seeds importance |
+| **Insight Graduation System** | `knowledge_upvote` / `knowledge_downvote` tools. Importance ≥ 7 → graduated rule. 30-day decay prevents bloat |
+| **Behavioral Warnings** | High-importance corrections auto-surface as `[⚠️ BEHAVIORAL WARNINGS]` in `session_load_context` — agents proactively avoid past mistakes |
+
 ### 🚀 Future Ideas
 
 | Feature | Issue | Description |

package/dist/server.js

@@ -84,7 +84,9 @@ SESSION_HEALTH_CHECK_TOOL,
 // ─── Phase 2: GDPR Memory Deletion tool definition ───
 SESSION_FORGET_MEMORY_TOOL, 
 // ─── v3.1: TTL Retention tool ───
-KNOWLEDGE_SET_RETENTION_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+KNOWLEDGE_SET_RETENTION_TOOL, 
+// v4.0: Active Behavioral Memory tools
+SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
 compactLedgerHandler, sessionSearchMemoryHandler, 
 // ─── v2.0: Time Travel handlers ───
@@ -97,6 +99,8 @@ sessionHealthCheckHandler,
 sessionForgetMemoryHandler, 
 // ─── v3.1: TTL Retention handler ───
 knowledgeSetRetentionHandler, 
+// v4.0: Active Behavioral Memory handlers
+sessionSaveExperienceHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, 
 // ─── v3.0: Agent Hivemind tools ───
 AGENT_REGISTRY_TOOLS, agentRegisterHandler, agentHeartbeatHandler, agentListTeamHandler, } from "./tools/index.js";
 // ─── Dynamic Tool Registration ───────────────────────────────────
@@ -133,6 +137,10 @@ const SESSION_MEMORY_TOOLS = [
     SESSION_FORGET_MEMORY_TOOL, // session_forget_memory — GDPR-compliant memory deletion (Phase 2)
     // ─── v3.1: TTL Retention tool ───
     KNOWLEDGE_SET_RETENTION_TOOL, // knowledge_set_retention — set auto-expiry TTL for a project
+    // ─── v4.0: Active Behavioral Memory tools ───
+    SESSION_SAVE_EXPERIENCE_TOOL, // session_save_experience — record typed experience events
+    KNOWLEDGE_UPVOTE_TOOL, // knowledge_upvote — increase entry importance
+    KNOWLEDGE_DOWNVOTE_TOOL, // knowledge_downvote — decrease entry importance
 ];
 // Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
 // can enumerate the full capability set. Runtime guards in the CallTool handler
@@ -586,6 +594,19 @@ export function createServer() {
                     if (!SESSION_MEMORY_ENABLED)
                         throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                     return await knowledgeSetRetentionHandler(args);
+                // ─── v4.0: Active Behavioral Memory Tools ───
+                case "session_save_experience":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await sessionSaveExperienceHandler(args);
+                case "knowledge_upvote":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await knowledgeUpvoteHandler(args);
+                case "knowledge_downvote":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await knowledgeDownvoteHandler(args);
                 // ─── v3.0: Agent Hivemind Tools ───
                 case "agent_register":
                     if (!SESSION_MEMORY_ENABLED)

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

@@ -41,6 +41,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 +352,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/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.
@@ -359,6 +360,7 @@ 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; // v4.0
     const agentName = await getSetting("agent_name", "");
     const validLevels = ["quick", "standard", "deep"];
     if (!validLevels.includes(level)) {
@@ -533,11 +535,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 +1571,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.0.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",