prism-mcp-server 6.2.2 → 6.5.1

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/prism-mcp-server?color=cb0000&label=npm)](https://www.npmjs.com/package/prism-mcp-server)
 [![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-00ADD8?logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyTDIgN2wxMCA1IDEwLTUtMTAtNXpNMiAxN2wxMCA1IDEwLTV2LTJMMTI0djJMMiA5djh6Ii8+PC9zdmc+)](https://registry.modelcontextprotocol.io)
 [![Glama](https://img.shields.io/badge/Glama-listed-FF5601)](https://glama.ai/mcp/servers/dcostenco/prism-mcp)
-[![Smithery](https://img.shields.io/badge/Smithery-listed-6B4FBB)](https://smithery.ai/server/prism-mcp-server)
+[![Smithery](https://img.shields.io/badge/Smithery-listed-6B4FBB)](https://smithery.ai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
@@ -395,8 +395,18 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 
 ## 🆕 What's New
 
-### v6.2 — The "Synthesize & Prune" Phase ✅
-> **Current stable release (v6.2.1).** The Mind Palace becomes self-organizing.
+### v6.5 — HDC Cognitive Routing ✅
+> **Current stable release.** The Mind Palace gains a brain-inspired routing engine.
+
+- 🧠 **Hyperdimensional Cognitive Routing** — New `session_cognitive_route` tool composes the agent's current state, role, and action into a single 768-dim binary hypervector via XOR binding, then resolves it to a semantic concept via Hamming distance. Three-outcome policy gateway: `direct` / `clarify` / `fallback`.
+- 🎛️ **Per-Project Threshold Overrides** — Fallback and clarify thresholds are configurable per-project and persisted via the existing `getSetting`/`setSetting` contract (no new migrations).
+- 🔬 **Explainability Mode** — When `explain: true`, responses include convergence steps, raw Hamming distance, and ambiguity flags for full auditability.
+- 📊 **Cognitive Observability** — `graphMetrics.ts` tracks route distribution (direct/clarify/fallback), rolling confidence/distance averages, ambiguity rates, and null-concept counts. Warning heuristics for fallback > 30% and ambiguity > 40%.
+- 🖥️ **Dashboard Integration** — Cognitive metrics card with route distribution bar, confidence gauges, and warning badges. On-demand "Cognitive Route" button in the Node Editor panel.
+- 🔒 **Feature Gating** — Entire pipeline gated behind `PRISM_HDC_ENABLED` (default: `true`). Clean error + zero telemetry when disabled.
+
+<details>
+<summary><strong>v6.2 — The "Synthesize & Prune" Phase</strong></summary>
 
 - 🕸️ **Edge Synthesis ("The Dream Procedure")** — Automated background linker discovers semantically similar but disconnected memory nodes via cosine similarity (≥ 0.7 threshold). Batch-limited to 50 sources × 3 neighbors. New `session_synthesize_edges` tool for on-demand graph enrichment.
 - ✂️ **Graph Pruning (Soft-Prune)** — Configurable strength-based pruning soft-deletes weak links. Includes per-project cooldown, backpressure guards, and sweep budget controls. Enable with `PRISM_GRAPH_PRUNING_ENABLED=true`.
@@ -406,6 +416,8 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 - ⚡ **Supabase Weak-Link RPC (WS4.1)** — New `prism_summarize_weak_links` Postgres function (migration 036) aggregates pruning server-side, eliminating N+1 network roundtrips.
 - 🔒 **Migration 035** — Tenant-safe graph writes + soft-delete hardening for MemoryLinks.
 
+</details>
+
 <details>
 <summary><strong>v6.1 — Prism-Port, Cognitive Load & Semantic Search</strong></summary>
 
@@ -447,41 +459,49 @@ Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.z
 
 ## ⚔️ How Prism Compares
 
-While standard Memory MCPs act as passive filing cabinets, Prism is an **active cognitive architecture** that manages its own health, compresses its own data, and learns autonomously in the background.
-
-| Feature | 🧠 **Prism MCP** | Official Anthropic Memory | Cloud APIs (Mem0 / Zep) | Simple SQLite/File MCPs |
-|:---|:---:|:---:|:---:|:---:|
-| **Paradigm** | **Active & Autonomous** | Passive Entity Graph | Passive Vector Store | Passive Log |
-| **Context Assembly** | **Progressive (Quick/Std/Deep)** | Manual JSON retrieval | Similarity Search only | Dump all / exact match |
-| **Graph Generation** | **Auto-Synthesized (Edges)** | Manual (LLM must write JSON) | Often none / black box | None |
-| **Context Window Mgmt** | **Auto-Compaction & Decay** | Endless unbounded growth | Requires paid API logic | Manual deletion required |
-| **Storage Engine** | **Local SQLite OR Supabase** | Local File | Cloud Only (Vendor lock-in) | Local SQLite |
-| **Vector Search** | **Three-Tier (Native / TQ / FTS5)** | ❌ None | ✅ Yes (Remote) | ❌ None |
-| **Vector Compression** | **TurboQuant (10× smaller)** | ❌ N/A | ❌ Expensive/Opaque | ❌ N/A |
-| **Multi-Agent Sync** | **CRDTs + Hivemind Watchdog** | ❌ Single-agent only | ✅ Paid feature | ❌ Data collisions |
-| **Observability** | **OTel Traces + Web Dashboard** | ❌ None | ✅ Web Dashboard | ❌ None |
-| **Data Portability** | **Prism-Port (Obsidian Vault ZIP)** | ❌ Raw JSON | ❌ API Export | ❌ Raw DB file |
-| **Cost Model** | **Free + BYOM (Ollama)** | Free (limited) | Per-API-call pricing | Free (limited) |
-
-### 🏆 Why Prism Wins: The "Big Three" Differentiators
-
-**1. Zero Cold-Starts with Progressive Loading & OCC**
-Other systems require the LLM to waste tokens and reasoning steps asking "What was I doing?" and calling tools to fetch memory. Prism uses MCP Resources to instantly inject the live project state into the context window *before* the LLM generates its first token. CRDT-backed Optimistic Concurrency Control ensures multiple agents (e.g., Claude + Cursor) can work on the same project simultaneously without data collisions.
-
-**2. Self-Cleaning & Self-Optimizing**
-If you use a standard memory tool long enough, it clogs the LLM's context window with thousands of obsolete tokens. Prism runs an autonomous Background Scheduler that:
-- **Ebbinghaus Decays** older, unreferenced memories — importance fades unless reinforced.
-- **Auto-Compacts** large session histories into dense, LLM-generated summaries.
-- **Deep Purges** high-precision vectors, replacing them with 400-byte TurboQuant compressed blobs, saving ~90% of disk space.
+Standard memory servers (like Mem0, Zep, or the baseline Anthropic MCP) act as passive filing cabinets — they wait for the LLM to search them. **Prism is an active cognitive architecture.** Designed specifically for the **Model Context Protocol (MCP)**, Prism doesn't just store vectors; it manages the LLM's context window autonomously.
 
-> 💰 **Token Economics:** Progressive Context Loading (Quick ~50 tokens / Standard ~200 / Deep ~1000+) plus auto-compaction means you never blow your Claude/OpenAI token budget fetching 50 pages of raw chat history.
+### 📊 Feature-by-Feature Comparison
 
-**3. The Associative Memory Graph**
-Prism doesn't just store logs; it connects them. When a session is saved, Prism automatically creates temporal chains (what happened next) and keyword overlap edges. In the background, Edge Synthesis actively scans for latent relationships and *synthesizes* new graph edges between conceptually similar but disconnected memories — turning passive storage into an active, self-organizing knowledge graph.
+| Feature / Architecture | 🧠 Prism MCP | 🐘 Mem0 | ⚡ Zep | 🧪 Anthropic Base MCP |
+| :--- | :--- | :--- | :--- | :--- |
+| **Primary Interface** | **Native MCP** (Tools, Prompts, Resources) | REST API & Python/TS SDKs | REST API & Python/TS SDKs | Native MCP (Tools only) |
+| **Storage Engine** | **BYO SQLite or Supabase** | Managed Cloud / VectorDBs | Managed Cloud / Postgres | Local SQLite only |
+| **Context Assembly** | **Progressive (Quick/Std/Deep)** | Top-K Semantic Search | Top-K + Temporal Summaries | Basic Entity Search |
+| **Memory Mechanics** | **Ebbinghaus Decay, SDM, HDC** | Basic Vector + Entity | Fading Temporal Graph | None (Infinite growth) |
+| **Multi-Agent Sync** | **CRDT (Add-Wins / LWW)** | Cloud locks | Postgres locks | ❌ None (Data races) |
+| **Data Compression** | **TurboQuant (7x smaller vectors)** | ❌ Standard F32 Vectors | ❌ Standard Vectors | ❌ No Vectors |
+| **Observability** | **OTel Traces + Built-in PWA UI** | Cloud Dashboard | Cloud Dashboard | ❌ None |
+| **Maintenance** | **Autonomous Background Scheduler** | Manual/API driven | Automated (Cloud) | ❌ Manual |
+| **Data Portability** | **Prism-Port (Obsidian/Logseq Vault)** | JSON Export | JSON Export | Raw `.db` file |
+| **Cost Model** | **Free + BYOM (Ollama)** | Per-API-call pricing | Per-API-call pricing | Free (limited) |
 
-> 🔌 **BYOM (Bring Your Own Model):** While tools like Mem0 charge per API call, Prism's pluggable architecture lets you run `nomic-embed-text` locally via Ollama for **free vectors**, while using Claude or GPT for high-level reasoning. Zero vendor lock-in.
+### 🏆 Where Prism Crushes the Giants
+
+#### 1. MCP-Native, Not an Adapted API
+Mem0 and Zep are APIs that *can* be wrapped into an MCP server. Prism was built *for* MCP from day one. Instead of wasting tokens on "search" tool calls, Prism uses **MCP Prompts** (`/resume_session`) to inject context *before* the LLM thinks, and **MCP Resources** (`memory://project/handoff`) to attach live, subscribing context.
+
+#### 2. Academic-Grade Cognitive Computer Science
+The giants use standard RAG (Retrieval-Augmented Generation). Prism uses biological and academic models of memory: **TurboQuant** for extreme vector compression, **Ebbinghaus curves** for importance decay, and **Sparse Distributed Memory (SDM)**. This makes Prism vastly more efficient on a local machine than running a giant Postgres/pgvector instance.
+
+#### 3. True Multi-Agent Coordination (CRDTs)
+If Cursor (Agent A) and Claude Desktop (Agent B) try to update a Mem0 or standard SQLite database at the exact same time, you get a race condition and data loss. Prism uses **Optimistic Concurrency Control (OCC) with CRDT OR-Maps** — mathematically guaranteeing that simultaneous agent edits merge safely. Enterprise-grade distributed systems on a local machine.
+
+#### 4. The PKM "Prism-Port" Export
+AI memory is a black box. Developers hate black boxes. Prism exports memory directly into an **Obsidian/Logseq-compatible Markdown Vault** with YAML frontmatter and `[[Wikilinks]]`. Neither Mem0 nor Zep do this.
+
+#### 5. Self-Cleaning & Self-Optimizing
+If you use a standard memory tool long enough, it clogs the LLM's context window with thousands of obsolete tokens. Prism runs an autonomous [Background Scheduler](src/backgroundScheduler.ts) that Ebbinghaus-decays older memories, auto-compacts session histories into dense summaries, and deep-purges high-precision vectors — saving ~90% of disk space automatically.
+
+### 🤝 Where the Giants Currently Win (Honest Trade-offs)
+
+1. **Framework Integrations:** Mem0 and Zep have pre-built integrations for LangChain, LlamaIndex, Flowise, AutoGen, CrewAI, etc. Prism requires the host application to support the MCP protocol.
+2. **Managed Cloud Infrastructure:** The giants offer SaaS. Users pay $20/month and don't think about databases. Prism users must set up their own local SQLite or provision their own Supabase instance.
+3. **Implicit Memory Extraction (NER):** Zep automatically extracts names, places, and facts from raw chat logs using NLP models. Prism relies on the LLM explicitly calling the `session_save_ledger` tool to structure its own memories.
+
+> 💰 **Token Economics:** Progressive Context Loading (Quick ~50 tokens / Standard ~200 / Deep ~1000+) plus auto-compaction means you never blow your Claude/OpenAI token budget fetching 50 pages of raw chat history.
 >
-> 🏛️ **Prism-Port for PKM:** Prism turns your AI's brain into a readable [Obsidian](https://obsidian.md) / [Logseq](https://logseq.com) vault. Export with `session_export_memory(format='vault')` — complete with YAML frontmatter, `[[Wikilinks]]`, and keyword backlink indices. No more black-box AI memory.
+> 🔌 **BYOM (Bring Your Own Model):** While tools like Mem0 charge per API call, Prism's pluggable architecture lets you run `nomic-embed-text` locally via Ollama for **free vectors**, while using Claude or GPT for high-level reasoning. Zero vendor lock-in.
 
 ---
 
@@ -557,6 +577,17 @@ Prism ships 30+ tools, but **90% of your workflow uses just three:**
 
 </details>
 
+<details>
+<summary><strong>Cognitive Architecture (1 tool)</strong></summary>
+
+Requires `PRISM_HDC_ENABLED=true` (default).
+
+| Tool | Purpose |
+|------|---------|
+| `session_cognitive_route` | HDC compositional state resolution with policy-gated routing |
+
+</details>
+
 <details>
 <summary><strong>Multi-Agent Hivemind (3 tools)</strong></summary>
 
@@ -600,6 +631,8 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | `PRISM_SCHOLAR_INTERVAL_MS` | No | Scholar interval in ms (default: `0` = manual only) |
 | `PRISM_SCHOLAR_TOPICS` | No | Comma-separated research topics (default: `"ai,agents"`) |
 | `PRISM_SCHOLAR_MAX_ARTICLES_PER_RUN` | No | Max articles per Scholar run (default: `3`) |
+| `PRISM_HDC_ENABLED` | No | `"true"` (default) to enable HDC cognitive routing pipeline |
+| `PRISM_HDC_EXPLAINABILITY_ENABLED` | No | `"true"` (default) to include convergence/distance/ambiguity in cognitive route responses |
 
 </details>
 
@@ -684,7 +717,8 @@ Prism is evolving from smart session logging toward a **cognitive memory archite
 | **v5.5** | SDM Decoder Foundation — pre-allocated typed-array hot loop, zero GC thrash | Kanerva's Sparse Distributed Memory (1988) | ✅ Shipped |
 | **v5.5** | Architectural Hardening — transactional migrations, graceful shutdown, thundering herd prevention | Production reliability engineering | ✅ Shipped |
 | **v6.1** | Intuitive Recall — proactive surface of relevant past decisions without explicit search; `session_intuitive_recall` tool | Predictive memory (cognitive science) | ✅ Shipped |
-| **v6.2+** | Full Superposed Memory (SDM) — O(1) key-value retrieval via Hamming correlation | Kanerva's SDM | 🔬 In Progress |
+| **v6.5** | HDC Cognitive Routing — compositional state-machine with XOR binding, Hamming resolution, and policy-gated routing | Hyperdimensional Computing (Kanerva, Gayler) | ✅ Shipped |
+| **v6.5** | Cognitive Observability — route distribution, confidence/distance tracking, ambiguity warnings | Production reliability engineering | ✅ Shipped |
 | **v6.1** | Prism-Port Vault Export — Obsidian/Logseq `.zip` with YAML frontmatter & `[[Wikilinks]]` | Data sovereignty, PKM interop | ✅ Shipped |
 | **v6.1** | Cognitive Load & Semantic Search — dynamic graph thinning, search highlights | Contextual working memory | ✅ Shipped |
 | **v6.2** | Synthesize & Prune — automated edge synthesis, graph pruning, SLO observability | Implicit associative memory | ✅ Shipped |
@@ -702,8 +736,12 @@ Prism is evolving from smart session logging toward a **cognitive memory archite
 ### v6.2: The "Synthesize & Prune" Phase ✅
 Shipped in v6.2.0. Edge synthesis, graph pruning with SLO observability, temporal decay heatmaps, active recall prompt generation, and full dashboard metrics integration.
 
-### v7.x: Affect-Tagged Memory
-Sentiment and emotional valence shape what gets recalled — bringing affect-modulated retrieval from neuroscience into agentic memory.
+### v6.5: Cognitive Architecture (Primary)
+Full Superposed Memory (SDM) + Hyperdimensional Computing (HDC/VSA) becomes the next major implementation phase, targeting compositional memory states and faster associative retrieval at scale.
+
+### After v6.5: Future Tracks
+- **v7.x: Affect-Tagged Memory** — Recall prioritization improves by weighting memories with affective/contextual valence, making surfaced context more behaviorally useful.
+- **v8+: Zero-Search Retrieval** — Direct vector-addressed recall (“just ask the vector”) reduces retrieval indirection and moves Prism toward truly native associative memory.
 
 ---
 

package/dist/config.js

@@ -73,38 +73,39 @@ export const PRISM_STORAGE = process.env.PRISM_STORAGE || "supabase";
 // When both SUPABASE_URL and SUPABASE_KEY are set, session memory tools
 // are registered. These tools allow AI agents to persist and recover
 // context between sessions.
-export const SUPABASE_URL = process.env.SUPABASE_URL;
-export const SUPABASE_KEY = process.env.SUPABASE_KEY;
-/**
- * SESSION_MEMORY_ENABLED — Master toggle for session persistence tools.
- *
- * Hardcoded to `true` since v3.0. This flag was originally used to gate
- * session memory tools when Supabase credentials were optional. Now that
- * session memory is a core feature (both SQLite and Supabase backends),
- * it is always enabled.
- *
- * The flag is kept (rather than removed) because several modules import
- * it for conditional registration of MCP tools. Removing it would require
- * a broader refactor with no functional benefit.
- */
-export const SESSION_MEMORY_ENABLED = true;
-// Note: debug() is defined at the bottom of this file; these lines
-// execute at import time after the full module is loaded by Node.
-if (!SESSION_MEMORY_ENABLED) {
-    console.error("Info: Session memory disabled (set PRISM_STORAGE=local or configure Supabase)");
+function sanitizeEnv(value) {
+    if (!value)
+        return undefined;
+    const trimmed = value.trim();
+    // Treat unresolved template placeholders as unset (e.g. "${SUPABASE_URL}")
+    if (!trimmed || trimmed.includes("${"))
+        return undefined;
+    return trimmed;
 }
-// ─── Optional: Multi-Tenant User ID ──────────────────────────
-// REVIEWER NOTE: When multiple users share the same Supabase instance,
-// PRISM_USER_ID isolates their data. Each user sets a unique ID in their
-// Claude Desktop config. All queries are scoped to this user_id.
-//
-// Defaults to "default" for backward compatibility — existing single-user
-// installations work without any config changes.
-//
-// For enterprise: use a stable unique identifier (UUID, email hash, etc.)
-// For personal use: any unique string works (e.g., "alice", "bob")
+function isHttpUrl(value) {
+    try {
+        const parsed = new URL(value);
+        return parsed.protocol === "http:" || parsed.protocol === "https:";
+    }
+    catch {
+        return false;
+    }
+}
+export const SUPABASE_URL = sanitizeEnv(process.env.SUPABASE_URL);
+export const SUPABASE_KEY = sanitizeEnv(process.env.SUPABASE_KEY);
+export const SUPABASE_CONFIGURED = !!SUPABASE_URL &&
+    !!SUPABASE_KEY &&
+    isHttpUrl(SUPABASE_URL);
+if (process.env.SUPABASE_URL && !SUPABASE_URL) {
+    console.error("Warning: SUPABASE_URL appears unresolved/empty (e.g. template placeholder). Falling back to local storage unless explicitly fixed.");
+}
+if (SUPABASE_URL && !isHttpUrl(SUPABASE_URL)) {
+    console.error("Warning: SUPABASE_URL is not a valid http(s) URL. Falling back to local storage.");
+}
+// Session memory remains core-enabled in both local and Supabase modes.
+export const SESSION_MEMORY_ENABLED = true;
+// Optional multi-tenant scope ID (used by storage queries and handoffs).
 export const PRISM_USER_ID = process.env.PRISM_USER_ID || "default";
-// Multi-tenant info logged at debug level in startServer()
 // ─── v2.1: Auto-Capture Feature ─────────────────────────────
 // REVIEWER NOTE: Automatically captures HTML snapshots of local dev servers
 // when handoffs are saved. Prevents UI context loss between sessions.
@@ -175,6 +176,30 @@ export const PRISM_SCHOLAR_TOPICS = (process.env.PRISM_SCHOLAR_TOPICS || "ai,age
 // Controls the age threshold for link strength decay.
 // Links not traversed in the last N days lose 0.1 strength per sweep.
 export const PRISM_LINK_DECAY_DAYS = parseInt(process.env.PRISM_LINK_DECAY_DAYS || "30", 10);
+// ─── v6.5: Cognitive Architecture (HDC Policy Gateway) ─────────────
+// Master feature flag for HDC-driven cognitive routing APIs.
+export const PRISM_HDC_ENABLED = process.env.PRISM_HDC_ENABLED === "true";
+// Explainability payload toggle for cognitive routing responses.
+export const PRISM_HDC_EXPLAINABILITY_ENABLED = process.env.PRISM_HDC_EXPLAINABILITY_ENABLED !== "false"; // default true
+const DEFAULT_HDC_FALLBACK_THRESHOLD = 0.85;
+const DEFAULT_HDC_CLARIFY_THRESHOLD = 0.95;
+const rawHdcFallbackThreshold = parseFloat(process.env.PRISM_HDC_POLICY_FALLBACK_THRESHOLD || String(DEFAULT_HDC_FALLBACK_THRESHOLD));
+const rawHdcClarifyThreshold = parseFloat(process.env.PRISM_HDC_POLICY_CLARIFY_THRESHOLD || String(DEFAULT_HDC_CLARIFY_THRESHOLD));
+const hdcThresholdsValid = Number.isFinite(rawHdcFallbackThreshold) &&
+    Number.isFinite(rawHdcClarifyThreshold) &&
+    rawHdcFallbackThreshold >= 0 &&
+    rawHdcFallbackThreshold < rawHdcClarifyThreshold &&
+    rawHdcClarifyThreshold <= 1;
+if (!hdcThresholdsValid) {
+    console.error("Warning: Invalid HDC policy thresholds. Falling back to defaults " +
+        `(fallback=${DEFAULT_HDC_FALLBACK_THRESHOLD}, clarify=${DEFAULT_HDC_CLARIFY_THRESHOLD}).`);
+}
+export const PRISM_HDC_POLICY_FALLBACK_THRESHOLD = hdcThresholdsValid
+    ? rawHdcFallbackThreshold
+    : DEFAULT_HDC_FALLBACK_THRESHOLD;
+export const PRISM_HDC_POLICY_CLARIFY_THRESHOLD = hdcThresholdsValid
+    ? rawHdcClarifyThreshold
+    : DEFAULT_HDC_CLARIFY_THRESHOLD;
 // ─── v6.2: Graph Soft-Pruning ───────────────────────────────
 // Soft-pruning filters weak links from graph/retrieval reads while preserving
 // underlying rows for provenance. This does NOT delete links.

package/dist/dashboard/graphRouter.js

@@ -312,6 +312,60 @@ export async function handleGraphRoutes(url, req, res, getStorageSafe) {
             return true;
         }
     }
+    // ─── API: Cognitive Route Explainability (v6.5) ───
+    if (url.pathname === "/api/graph/cognitive-route" && req.method === "GET") {
+        const project = url.searchParams.get("project");
+        const state = url.searchParams.get("state");
+        const role = url.searchParams.get("role");
+        const action = url.searchParams.get("action");
+        const explain = url.searchParams.get("explain");
+        const fallbackThresholdRaw = url.searchParams.get("fallback_threshold");
+        const clarifyThresholdRaw = url.searchParams.get("clarify_threshold");
+        if (!project || !state || !role || !action) {
+            res.writeHead(400, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                error: "project, state, role, and action are required",
+            }));
+            return true;
+        }
+        try {
+            const { sessionCognitiveRouteHandler } = await import("../tools/graphHandlers.js");
+            const args = {
+                project,
+                state,
+                role,
+                action,
+                explain: explain === null ? true : explain !== "false",
+            };
+            if (fallbackThresholdRaw !== null) {
+                const parsed = Number(fallbackThresholdRaw);
+                if (!Number.isNaN(parsed))
+                    args.fallback_threshold = parsed;
+            }
+            if (clarifyThresholdRaw !== null) {
+                const parsed = Number(clarifyThresholdRaw);
+                if (!Number.isNaN(parsed))
+                    args.clarify_threshold = parsed;
+            }
+            const result = await sessionCognitiveRouteHandler(args);
+            const contentText = result.content && result.content.length > 0
+                ? result.content[0].text
+                : "";
+            res.writeHead(result.isError ? 400 : 200, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({
+                ok: !result.isError,
+                isError: !!result.isError,
+                text: contentText,
+            }));
+            return true;
+        }
+        catch (err) {
+            console.error("[Dashboard] Cognitive route error:", err);
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: err instanceof Error ? err.message : "Cognitive route failed" }));
+            return true;
+        }
+    }
     // ─── API: Graph Metrics (v6.0 Observability) ───
     if (url.pathname === "/api/graph/metrics" && req.method === "GET") {
         const snapshot = getGraphMetricsSnapshot();

package/dist/dashboard/ui.js

@@ -842,6 +842,12 @@ export function renderDashboardHTML(version) {
               <button id="testMeBtn" onclick="triggerTestMe()" class="btn-modern" style="padding:0.3rem 0.6rem; font-size:0.75rem; background:var(--accent-teal); border-color:var(--accent-teal);" title="Generate 3 quiz questions using AI">📝 Test Me</button>
             </div>
             <div id="testMeContainer" style="margin-top:0.8rem; display:flex; flex-direction:column; gap:0.5rem;"></div>
+            <div style="display:flex; justify-content:space-between; align-items:center; margin-top:0.8rem;">
+              <span style="font-size:0.75rem; color:var(--text-muted); font-weight:600;">Cognitive Route (v6.5)</span>
+              <button id="cognitiveRouteBtn" onclick="triggerCognitiveRoute()" class="btn-modern" style="padding:0.3rem 0.6rem; font-size:0.75rem; background:var(--accent-blue); border-color:var(--accent-blue);" title="Resolve concept route and explain why it surfaced">🧭 Route</button>
+            </div>
+            <div id="cognitiveRouteContainer" style="margin-top:0.6rem; display:flex; flex-direction:column; gap:0.4rem;"></div>
+
           </div>
         </div>
 
@@ -2372,7 +2378,66 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
       }
     }
 
-    window.triggerTestMe = triggerTestMe;
+
+
+    async function triggerCognitiveRoute() {
+      var input = document.getElementById('nodeEditorInput');
+      var state = input && input.dataset && input.dataset.oldId ? input.dataset.oldId : '';
+      var _gpf = document.getElementById('graphProjectFilter');
+      var _ps = document.getElementById('projectSelect');
+      var project = (_gpf ? _gpf.value : '') || (_ps ? _ps.value : '');
+      var container = document.getElementById('cognitiveRouteContainer');
+      var btn = document.getElementById('cognitiveRouteBtn');
+
+      if (!project || !state) {
+        if (container) {
+          container.innerHTML = '<div style="font-size:0.75rem;color:var(--accent-rose);">Select a project and click a graph node first.</div>';
+        }
+        return;
+      }
+
+      if (btn) {
+        btn.disabled = true;
+        btn.textContent = '...';
+      }
+      if (container) {
+        container.innerHTML = '<div style="font-size:0.75rem;color:var(--text-muted);text-align:center;padding:0.6rem 0;">Resolving cognitive route...</div>';
+      }
+
+      try {
+        var url = '/api/graph/cognitive-route' +
+          '?project=' + encodeURIComponent(project) +
+          '&state=' + encodeURIComponent('State:' + state) +
+          '&role=' + encodeURIComponent('Role:dev') +
+          '&action=' + encodeURIComponent('Action:inspect') +
+          '&explain=true';
+
+        var res = await fetch(url);
+        var data = await res.json();
+
+        if (!res.ok || data.isError) {
+          if (container) {
+            container.innerHTML = '<div style="font-size:0.75rem;color:var(--accent-rose);">' + escapeHtml(data.error || data.text || 'Cognitive route failed') + '</div>';
+          }
+          return;
+        }
+
+        if (container) {
+          var txt = data.text || '';
+          container.innerHTML = '<pre style="margin:0;white-space:pre-wrap;font-size:0.72rem;line-height:1.45;background:var(--bg-secondary);border:1px solid var(--border-subtle);border-radius:6px;padding:0.6rem;color:var(--text-secondary);">' + escapeHtml(txt) + '</pre>';
+        }
+      } catch (err) {
+        if (container) {
+          container.innerHTML = '<div style="font-size:0.75rem;color:var(--accent-rose);">' + escapeHtml(err.message || 'Route error') + '</div>';
+        }
+      } finally {
+        if (btn) {
+          btn.disabled = false;
+          btn.textContent = '🧭 Route';
+        }
+      }
+    }
+
     async function triggerTestMe() {
       var input = document.getElementById('nodeEditorInput');
       var oldId = input.dataset.oldId;
@@ -3057,6 +3122,58 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
           parts.push('</div>');
         }
 
+        // Cognitive Routing row (v6.5)
+        if (m.cognitive && m.cognitive.evaluations_total > 0) {
+          parts.push('<div style="border-top:1px solid var(--border-glass);padding-top:0.4rem;margin-top:0.2rem;font-size:0.75rem">');
+          parts.push('<strong>🧠 Cognitive Routing</strong>');
+          parts.push('<br>Evaluations: <strong>' + m.cognitive.evaluations_total + '</strong>');
+
+          // Route distribution bar
+          var cogTotal = m.cognitive.evaluations_total;
+          var autoP = Math.round((m.cognitive.route_auto_total / cogTotal) * 100);
+          var clarP = Math.round((m.cognitive.route_clarify_total / cogTotal) * 100);
+          var fallP = 100 - autoP - clarP;
+          parts.push('<div style="display:flex;height:8px;border-radius:4px;overflow:hidden;margin:4px 0;background:var(--surface-glass)">');
+          if (autoP > 0) parts.push('<div style="width:' + autoP + '%;background:var(--accent-green)" title="Auto: ' + autoP + '%"></div>');
+          if (clarP > 0) parts.push('<div style="width:' + clarP + '%;background:var(--accent-amber)" title="Clarify: ' + clarP + '%"></div>');
+          if (fallP > 0) parts.push('<div style="width:' + fallP + '%;background:var(--accent-rose)" title="Fallback: ' + fallP + '%"></div>');
+          parts.push('</div>');
+          parts.push('<span style="color:var(--accent-green)">● Auto ' + autoP + '%</span>');
+          parts.push(' <span style="color:var(--accent-amber)">● Clarify ' + clarP + '%</span>');
+          parts.push(' <span style="color:var(--accent-rose)">● Fallback ' + fallP + '%</span>');
+
+          // Rates
+          if (m.cognitive.ambiguity_rate !== null) {
+            var ambPct = Math.round(m.cognitive.ambiguity_rate * 100);
+            var ambColor = ambPct > 40 ? 'var(--accent-rose)' : ambPct > 20 ? 'var(--accent-amber)' : 'var(--accent-green)';
+            parts.push('<br>Ambiguity: <span style="color:' + ambColor + ';font-weight:600">' + ambPct + '%</span>');
+          }
+          if (m.cognitive.fallback_rate !== null) {
+            var fbPct = Math.round(m.cognitive.fallback_rate * 100);
+            var fbColor = fbPct > 30 ? 'var(--accent-rose)' : fbPct > 15 ? 'var(--accent-amber)' : 'var(--accent-green)';
+            parts.push(' · Fallback: <span style="color:' + fbColor + ';font-weight:600">' + fbPct + '%</span>');
+          }
+
+          // Convergence steps
+          if (m.cognitive.median_convergence_steps !== null) {
+            parts.push('<br>Convergence: ' + m.cognitive.median_convergence_steps + ' steps (avg)');
+          }
+          if (m.cognitive.duration_p50_ms !== null) {
+            parts.push(' · p50: ' + m.cognitive.duration_p50_ms + 'ms');
+          }
+
+          // Last evaluation
+          if (m.cognitive.last_run_at) {
+            var lastRoute = m.cognitive.last_route || '—';
+            var lastConcept = m.cognitive.last_concept || '(none)';
+            var lastConf = m.cognitive.last_confidence !== null ? Math.round(m.cognitive.last_confidence * 100) + '%' : '—';
+            parts.push('<br>Last: ' + lastRoute + ' → ' + lastConcept + ' (' + lastConf + ')');
+            parts.push('<br><span style="color:var(--text-muted)">' + timeAgo(m.cognitive.last_run_at) + '</span>');
+          }
+
+          parts.push('</div>');
+        }
+
 
         el.innerHTML = parts.join('');
 
@@ -3072,6 +3189,12 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
           if (m.warnings.synthesis_failure_warning) {
             badges.push('<span style="background:var(--accent-rose);color:#fff;padding:2px 6px;border-radius:3px;font-size:0.65rem;font-weight:600" title="Over 20% of synthesis runs are failing">⚠ Failures</span>');
           }
+          if (m.warnings.cognitive_fallback_rate_warning) {
+            badges.push('<span style="background:var(--accent-rose);color:#fff;padding:2px 6px;border-radius:3px;font-size:0.65rem;font-weight:600" title="Over 30% of cognitive routes land on FALLBACK">⚠ Cog Fallback</span>');
+          }
+          if (m.warnings.cognitive_ambiguity_rate_warning) {
+            badges.push('<span style="background:var(--accent-amber);color:#000;padding:2px 6px;border-radius:3px;font-size:0.65rem;font-weight:600" title="Over 40% of cognitive evaluations are ambiguous">⚠ Cog Ambiguity</span>');
+          }
           warn.innerHTML = badges.join('');
         }
       } catch(e) {

package/dist/observability/graphMetrics.js

@@ -3,11 +3,12 @@
  *
  * ═══════════════════════════════════════════════════════════════════
  * PURPOSE:
- *   Lightweight, zero-dependency metrics collection for graph synthesis
- *   and test-me flows. All state is in-memory (resets on restart).
+ *   Lightweight, zero-dependency metrics collection for graph synthesis,
+ *   test-me flows, and v6.5 cognitive routing.
+ *   All state is in-memory (resets on restart).
  *
  * DESIGN:
- *   - Singleton counters + timestamps for synthesis and test-me
+ *   - Singleton counters + timestamps for synthesis, test-me, and cognitive
  *   - Bounded ring buffer (100 entries) for duration p50 approximation
  *   - Warning flags computed on snapshot (not continuously)
  *   - Structured JSON log emission via debugLog channel
@@ -16,8 +17,9 @@
  * METRICS MODEL:
  *   A) Synthesis: runs, failures, links created, candidates, below-threshold, duration
  *   B) Test-Me: requests, success, no_api_key, generation_failed, bad_request, duration
- *   C) Warning flags: quality drift, provider issues, failure rate
+ *   C) Warning flags: quality drift, provider issues, failure rate, cognitive fallback/ambiguity
  *   D) SLO derivations: success rate, net new links, prune ratio, sweep duration (WS4)
+ *   E) Cognitive (v6.5): intent evaluations, route distribution, ambiguity rate, convergence steps
  * ═══════════════════════════════════════════════════════════════════
  */
 import { debugLog } from "../utils/logger.js";
@@ -63,6 +65,7 @@ let synthesis = createFreshSynthesisMetrics();
 let testMe = createFreshTestMeMetrics();
 let schedulerSynthesis = createFreshSchedulerMetrics();
 let pruning = createFreshPruningMetrics();
+let cognitive = createFreshCognitiveMetrics();
 function createFreshSynthesisMetrics() {
     return {
         runs_total: 0,
@@ -119,6 +122,21 @@ function createFreshPruningMetrics() {
         last_run_at: null,
     };
 }
+function createFreshCognitiveMetrics() {
+    return {
+        evaluations_total: 0,
+        route_auto_total: 0,
+        route_clarify_total: 0,
+        route_fallback_total: 0,
+        ambiguous_total: 0,
+        convergence_steps_total: 0,
+        last_run_at: null,
+        last_route: null,
+        last_concept: null,
+        last_confidence: null,
+        duration_buffer: new DurationBuffer(),
+    };
+}
 function emitGraphEvent(event) {
     try {
         debugLog(JSON.stringify(event));
@@ -246,6 +264,40 @@ export function recordSweepDuration(duration_ms) {
         duration_ms,
     });
 }
+export function recordCognitiveRoute(data) {
+    const now = new Date().toISOString();
+    cognitive.evaluations_total++;
+    cognitive.last_run_at = now;
+    cognitive.last_route = data.route;
+    cognitive.last_concept = data.concept;
+    cognitive.last_confidence = data.confidence;
+    cognitive.duration_buffer.push(data.duration_ms);
+    cognitive.convergence_steps_total += data.steps;
+    if (data.ambiguous) {
+        cognitive.ambiguous_total++;
+    }
+    // Route distribution — match ActionRoute enum values
+    if (data.route === "ACTION_AUTO_ROUTE") {
+        cognitive.route_auto_total++;
+    }
+    else if (data.route === "ACTION_CLARIFY") {
+        cognitive.route_clarify_total++;
+    }
+    else if (data.route === "ACTION_FALLBACK") {
+        cognitive.route_fallback_total++;
+    }
+    emitGraphEvent({
+        event: "cognitive_route_evaluation",
+        project: data.project,
+        route: data.route,
+        concept: data.concept,
+        confidence: data.confidence,
+        distance: data.distance,
+        ambiguous: data.ambiguous,
+        steps: data.steps,
+        duration_ms: data.duration_ms,
+    });
+}
 // ─── Warning Flag Computation ────────────────────────────────────
 function computeWarningFlags() {
     // Quality warning: >85% of candidates are below threshold (min 50 candidates)
@@ -256,10 +308,18 @@ function computeWarningFlags() {
     // Failure rate warning: >20% of synthesis runs failed (min 5 runs)
     const synthesis_failure_warning = synthesis.runs_total >= 5 &&
         synthesis.runs_failed / synthesis.runs_total > 0.2;
+    // Cognitive fallback rate warning: >30% routes go to FALLBACK (min 10 evaluations)
+    const cognitive_fallback_rate_warning = cognitive.evaluations_total >= 10 &&
+        cognitive.route_fallback_total / cognitive.evaluations_total > 0.3;
+    // Cognitive ambiguity rate warning: >40% evaluations are ambiguous (min 10 evaluations)
+    const cognitive_ambiguity_rate_warning = cognitive.evaluations_total >= 10 &&
+        cognitive.ambiguous_total / cognitive.evaluations_total > 0.4;
     return {
         synthesis_quality_warning,
         testme_provider_warning,
         synthesis_failure_warning,
+        cognitive_fallback_rate_warning,
+        cognitive_ambiguity_rate_warning,
     };
 }
 // ─── SLO Derivation (WS4) ────────────────────────────────────────
@@ -283,6 +343,17 @@ function computeSloMetrics() {
     };
 }
 export function getGraphMetricsSnapshot() {
+    // Derived cognitive rates
+    const cogEvalTotal = cognitive.evaluations_total;
+    const ambiguity_rate = cogEvalTotal > 0
+        ? parseFloat((cognitive.ambiguous_total / cogEvalTotal).toFixed(4))
+        : null;
+    const fallback_rate = cogEvalTotal > 0
+        ? parseFloat((cognitive.route_fallback_total / cogEvalTotal).toFixed(4))
+        : null;
+    const median_convergence_steps = cogEvalTotal > 0
+        ? parseFloat((cognitive.convergence_steps_total / cogEvalTotal).toFixed(2))
+        : null;
     return {
         synthesis: {
             runs_total: synthesis.runs_total,
@@ -332,6 +403,22 @@ export function getGraphMetricsSnapshot() {
             skipped_budget_last: pruning.skipped_budget_last,
             last_run_at: pruning.last_run_at,
         },
+        cognitive: {
+            evaluations_total: cognitive.evaluations_total,
+            route_auto_total: cognitive.route_auto_total,
+            route_clarify_total: cognitive.route_clarify_total,
+            route_fallback_total: cognitive.route_fallback_total,
+            ambiguous_total: cognitive.ambiguous_total,
+            convergence_steps_total: cognitive.convergence_steps_total,
+            median_convergence_steps,
+            ambiguity_rate,
+            fallback_rate,
+            last_run_at: cognitive.last_run_at,
+            last_route: cognitive.last_route,
+            last_concept: cognitive.last_concept,
+            last_confidence: cognitive.last_confidence,
+            duration_p50_ms: cognitive.duration_buffer.getP50(),
+        },
         slo: computeSloMetrics(),
         warnings: computeWarningFlags(),
     };
@@ -342,6 +429,7 @@ export function resetGraphMetricsForTests() {
     testMe = createFreshTestMeMetrics();
     schedulerSynthesis = createFreshSchedulerMetrics();
     pruning = createFreshPruningMetrics();
+    cognitive = createFreshCognitiveMetrics();
     sweepDurationMsLast = 0;
     sweepLastAt = null;
 }

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, PRISM_ENABLE_HIVEMIND, WATCHDOG_INTERVAL_MS, WATCHDOG_STALE_MIN, WATCHDOG_FROZEN_MIN, WATCHDOG_OFFLINE_MIN, WATCHDOG_LOOP_THRESHOLD, PRISM_SCHEDULER_ENABLED, PRISM_SCHEDULER_INTERVAL_MS, PRISM_SCHOLAR_ENABLED, } from "./config.js";
+import { SERVER_CONFIG, SESSION_MEMORY_ENABLED, PRISM_USER_ID, PRISM_ENABLE_HIVEMIND, WATCHDOG_INTERVAL_MS, WATCHDOG_STALE_MIN, WATCHDOG_FROZEN_MIN, WATCHDOG_OFFLINE_MIN, WATCHDOG_LOOP_THRESHOLD, PRISM_SCHEDULER_ENABLED, PRISM_SCHEDULER_INTERVAL_MS, PRISM_SCHOLAR_ENABLED, PRISM_HDC_ENABLED, } from "./config.js";
 import { startWatchdog, drainAlerts } from "./hivemindWatchdog.js";
 import { startScheduler, startScholarScheduler } from "./backgroundScheduler.js";
 import { getSyncBus } from "./sync/factory.js";
@@ -95,9 +95,9 @@ KNOWLEDGE_SET_RETENTION_TOOL,
 // v4.0: Active Behavioral Memory tools
 SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, 
 // v6.0: Associative Memory Graph tools
-SESSION_BACKFILL_LINKS_TOOL, SESSION_SYNTHESIZE_EDGES_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+SESSION_BACKFILL_LINKS_TOOL, SESSION_SYNTHESIZE_EDGES_TOOL, SESSION_COGNITIVE_ROUTE_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
-compactLedgerHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, sessionBackfillLinksHandler, sessionSynthesizeEdgesHandler, 
+compactLedgerHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, sessionBackfillLinksHandler, sessionSynthesizeEdgesHandler, sessionCognitiveRouteHandler, 
 // ─── v2.0: Time Travel handlers ───
 memoryHistoryHandler, memoryCheckoutHandler, 
 // ─── v2.0: Visual Memory handlers ───
@@ -193,6 +193,7 @@ function buildSessionMemoryTools(autoloadList) {
         // ─── v6.0: Associative Memory Graph tools ───
         SESSION_BACKFILL_LINKS_TOOL, // session_backfill_links — retroactive graph edge creation
         SESSION_SYNTHESIZE_EDGES_TOOL, // session_synthesize_edges — inferred semantic graph enrichment
+        SESSION_COGNITIVE_ROUTE_TOOL, // session_cognitive_route — HDC policy-gated concept routing (v6.5)
         // ─── v6.1: Storage Hygiene tool ───
         MAINTENANCE_VACUUM_TOOL, // maintenance_vacuum — reclaim SQLite disk space post-purge
     ];
@@ -756,6 +757,13 @@ export function createServer() {
                             throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                         result = await sessionSynthesizeEdgesHandler(args);
                         break;
+                    case "session_cognitive_route":
+                        if (!SESSION_MEMORY_ENABLED)
+                            throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                        if (!PRISM_HDC_ENABLED)
+                            throw new Error("HDC cognitive routing not enabled. Set PRISM_HDC_ENABLED=true.");
+                        result = await sessionCognitiveRouteHandler(args);
+                        break;
                     case "session_backfill_embeddings":
                         if (!SESSION_MEMORY_ENABLED)
                             throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");

package/dist/storage/index.js

@@ -1,15 +1,4 @@
-/**
- * Storage Factory (v2.0 — Step 1)
- *
- * Unified entry point for storage initialization.
- * Routes between Supabase (cloud) and SQLite (local) based on
- * the PRISM_STORAGE environment variable.
- *
- * Usage in server.ts:
- *   const storage = await getStorage();
- *   // Pass `storage` to all session memory handlers
- */
-import { PRISM_STORAGE as ENV_PRISM_STORAGE } from "../config.js";
+import { PRISM_STORAGE as ENV_PRISM_STORAGE, SUPABASE_CONFIGURED } from "../config.js";
 import { debugLog } from "../utils/logger.js";
 import { SupabaseStorage } from "./supabase.js";
 import { getSetting } from "./configStorage.js";
@@ -20,16 +9,22 @@ export let activeStorageBackend = "local";
  *
  * On first call: creates and initializes the appropriate backend.
  * On subsequent calls: returns the cached instance.
- *
- * @throws Error if PRISM_STORAGE=local (not yet implemented in Step 1)
- * @throws Error if PRISM_STORAGE=supabase but Supabase is not configured
  */
 export async function getStorage() {
     if (storageInstance)
         return storageInstance;
     // Use environment variable if explicitly set, otherwise fall back to db config
     const envStorage = process.env.PRISM_STORAGE;
-    activeStorageBackend = envStorage || await getSetting("PRISM_STORAGE", ENV_PRISM_STORAGE);
+    const requestedBackend = (envStorage || await getSetting("PRISM_STORAGE", ENV_PRISM_STORAGE));
+    // Guardrail: if Supabase is requested but credentials are unresolved/invalid,
+    // transparently fall back to local mode to keep dashboard + core tools usable.
+    if (requestedBackend === "supabase" && !SUPABASE_CONFIGURED) {
+        activeStorageBackend = "local";
+        console.error("[Prism Storage] Supabase backend requested but SUPABASE_URL/SUPABASE_KEY are invalid or unresolved. Falling back to local storage.");
+    }
+    else {
+        activeStorageBackend = requestedBackend;
+    }
     debugLog(`[Prism Storage] Initializing backend: ${activeStorageBackend}`);
     if (activeStorageBackend === "local") {
         const { SqliteStorage } = await import("./sqlite.js");

package/dist/tools/graphHandlers.js

@@ -17,6 +17,7 @@ import { formatRulesBlock, applySentinelBlock } from "./commonHelpers.js";
  * ═══════════════════════════════════════════════════════════════════
  */
 import { debugLog } from "../utils/logger.js";
+import { recordCognitiveRoute } from "../observability/graphMetrics.js";
 import { getStorage } from "../storage/index.js";
 import { toKeywordArray } from "../utils/keywordExtractor.js";
 import { getLLMProvider } from "../utils/llm/factory.js";
@@ -31,7 +32,7 @@ import { createMemoryTrace, traceToContentBlock } from "../utils/tracing.js";
 import { GOOGLE_API_KEY, PRISM_USER_ID } from "../config.js";
 import { isKnowledgeSearchArgs, isKnowledgeForgetArgs, isSessionSearchMemoryArgs, isKnowledgeVoteArgs, 
 // v4.2: Sync Rules type guard
-isKnowledgeSyncRulesArgs, isSessionIntuitiveRecallArgs, isSessionSynthesizeEdgesArgs, } from "./sessionMemoryDefinitions.js";
+isKnowledgeSyncRulesArgs, isSessionIntuitiveRecallArgs, isSessionSynthesizeEdgesArgs, isSessionCognitiveRouteArgs, } from "./sessionMemoryDefinitions.js";
 // v4.2: File system access for knowledge_sync_rules
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -50,6 +51,11 @@ const activeCompactions = new Set();
  * After saving, generates an embedding vector for the entry via fire-and-forget.
  */
 import { computeEffectiveImportance, updateLastAccessed } from "../utils/cognitiveMemory.js";
+import { HdcStateMachine } from "../sdm/stateMachine.js";
+import { ConceptDictionary } from "../sdm/conceptDictionary.js";
+import { PolicyGateway } from "../sdm/policyGateway.js";
+import { getSdmEngine } from "../sdm/sdmEngine.js";
+import { PRISM_HDC_ENABLED, PRISM_HDC_EXPLAINABILITY_ENABLED, PRISM_HDC_POLICY_FALLBACK_THRESHOLD, PRISM_HDC_POLICY_CLARIFY_THRESHOLD, } from "../config.js";
 export async function knowledgeSearchHandler(args) {
     if (!isKnowledgeSearchArgs(args)) {
         throw new Error("Invalid arguments for knowledge_search");
@@ -670,7 +676,6 @@ export async function sessionIntuitiveRecallHandler(args) {
         };
     }
     try {
-        const { getSdmEngine } = await import("../sdm/sdmEngine.js");
         const { decodeSdmVector } = await import("../sdm/sdmDecoder.js");
         const queryVector = await getLLMProvider().generateEmbedding(args.query);
         const sdmEngine = getSdmEngine(args.project);
@@ -702,6 +707,113 @@ export async function sessionIntuitiveRecallHandler(args) {
         };
     }
 }
+export async function sessionCognitiveRouteHandler(args) {
+    if (!isSessionCognitiveRouteArgs(args)) {
+        return {
+            content: [{ type: "text", text: "Invalid arguments for session_cognitive_route" }],
+            isError: true,
+        };
+    }
+    if (!PRISM_HDC_ENABLED) {
+        return {
+            content: [{
+                    type: "text",
+                    text: "⚠️ session_cognitive_route is disabled. Set PRISM_HDC_ENABLED=true to enable v6.5 cognitive routing.",
+                }],
+            isError: true,
+        };
+    }
+    try {
+        const storage = await getStorage();
+        const sdmEngine = getSdmEngine(args.project);
+        const dict = new ConceptDictionary(storage);
+        const stateVector = await dict.getConcept(args.state);
+        const roleVector = await dict.getConcept(args.role);
+        const actionVector = await dict.getConcept(args.action);
+        const machine = new HdcStateMachine(stateVector, sdmEngine);
+        machine.transition(roleVector, actionVector);
+        const fallbackKey = `hdc:fallback_threshold:${args.project}`;
+        const clarifyKey = `hdc:clarify_threshold:${args.project}`;
+        const persistedFallbackRaw = await storage.getSetting(fallbackKey);
+        const persistedClarifyRaw = await storage.getSetting(clarifyKey);
+        const persistedFallback = persistedFallbackRaw !== null ? Number(persistedFallbackRaw) : NaN;
+        const persistedClarify = persistedClarifyRaw !== null ? Number(persistedClarifyRaw) : NaN;
+        const baseFallbackThreshold = Number.isFinite(persistedFallback)
+            ? persistedFallback
+            : PRISM_HDC_POLICY_FALLBACK_THRESHOLD;
+        const baseClarifyThreshold = Number.isFinite(persistedClarify)
+            ? persistedClarify
+            : PRISM_HDC_POLICY_CLARIFY_THRESHOLD;
+        const fallbackThreshold = args.fallback_threshold ?? baseFallbackThreshold;
+        const clarifyThreshold = args.clarify_threshold ?? baseClarifyThreshold;
+        const explain = args.explain !== undefined ? args.explain : true;
+        if (!(fallbackThreshold >= 0 && fallbackThreshold < clarifyThreshold && clarifyThreshold <= 1)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: `Invalid policy thresholds for project "${args.project}": ` +
+                            `fallback=${fallbackThreshold}, clarify=${clarifyThreshold}. ` +
+                            "Expected 0 <= fallback < clarify <= 1.",
+                    }],
+                isError: true,
+            };
+        }
+        // Phase 2 parity hook: persist project-specific threshold overrides via storage settings.
+        // This works on both SQLite and Supabase backends through the shared StorageBackend API.
+        if (args.fallback_threshold !== undefined || args.clarify_threshold !== undefined) {
+            await storage.setSetting(fallbackKey, String(fallbackThreshold));
+            await storage.setSetting(clarifyKey, String(clarifyThreshold));
+        }
+        const gateway = new PolicyGateway(dict, {
+            fallbackThreshold,
+            clarifyThreshold,
+        });
+        const cogStart = Date.now();
+        const result = await gateway.evaluateIntent(machine);
+        const cogDuration = Date.now() - cogStart;
+        // Phase 4: Record cognitive route telemetry
+        recordCognitiveRoute({
+            project: args.project,
+            route: result.route,
+            concept: result.concept || null,
+            confidence: result.confidence,
+            distance: result.distance,
+            ambiguous: result.ambiguous,
+            steps: result.steps,
+            duration_ms: cogDuration,
+        });
+        const lines = [];
+        lines.push(`🧠 Cognitive Route — project \"${args.project}\"`);
+        lines.push("");
+        lines.push(`State: ${args.state}`);
+        lines.push(`Role: ${args.role}`);
+        lines.push(`Action: ${args.action}`);
+        lines.push("");
+        lines.push(`Route: ${result.route}`);
+        lines.push(`Concept: ${result.concept || "(none)"}`);
+        lines.push(`Confidence: ${(result.confidence * 100).toFixed(2)}%`);
+        lines.push(`Distance: ${result.distance}`);
+        lines.push(`Ambiguous: ${result.ambiguous ? "yes" : "no"}`);
+        lines.push(`Convergence Steps: ${result.steps}`);
+        if (PRISM_HDC_EXPLAINABILITY_ENABLED && explain) {
+            lines.push("");
+            lines.push("Explainability:");
+            lines.push(`- Policy thresholds: fallback=${fallbackThreshold}, clarify=${clarifyThreshold}`);
+            lines.push("- Routing logic: below fallback => FALLBACK, ambiguous/below clarify => CLARIFY, else AUTO_ROUTE");
+        }
+        return {
+            content: [{ type: "text", text: lines.join("\n") }],
+            isError: false,
+        };
+    }
+    catch (err) {
+        debugLog(`[session_cognitive_route] Failed: ${err instanceof Error ? err.message : String(err)}`);
+        return {
+            content: [{ type: "text", text: `Error triggering cognitive route: ${err instanceof Error ? err.message : String(err)}` }],
+            isError: true,
+        };
+    }
+}
 export async function synthesizeEdgesCore({ project, similarity_threshold = 0.7, max_entries = 50, max_neighbors_per_entry = 3, randomize_selection = false, }) {
     const storage = await getStorage();
     const llm = getLLMProvider();

package/dist/tools/index.js

@@ -26,11 +26,11 @@ 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, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, SESSION_BACKFILL_LINKS_TOOL, MAINTENANCE_VACUUM_TOOL, isDeepStoragePurgeArgs, SESSION_SYNTHESIZE_EDGES_TOOL, isSessionSynthesizeEdgesArgs } from "./sessionMemoryDefinitions.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, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, SESSION_BACKFILL_LINKS_TOOL, MAINTENANCE_VACUUM_TOOL, isDeepStoragePurgeArgs, SESSION_SYNTHESIZE_EDGES_TOOL, isSessionSynthesizeEdgesArgs, SESSION_COGNITIVE_ROUTE_TOOL, isSessionCognitiveRouteArgs } from "./sessionMemoryDefinitions.js";
 // 1. Ledger (Core CRUD & State)
 export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionSaveExperienceHandler, sessionSaveImageHandler, sessionViewImageHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionForgetMemoryHandler, sessionExportMemoryHandler } from "./ledgerHandlers.js";
 // 2. Graph (Semantic Search & Weighting)
-export { sessionSearchMemoryHandler, knowledgeSearchHandler, sessionIntuitiveRecallHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, knowledgeForgetHandler, knowledgeSyncRulesHandler, sessionSynthesizeEdgesHandler } from "./graphHandlers.js";
+export { sessionSearchMemoryHandler, knowledgeSearchHandler, sessionIntuitiveRecallHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, knowledgeForgetHandler, knowledgeSyncRulesHandler, sessionSynthesizeEdgesHandler, sessionCognitiveRouteHandler } from "./graphHandlers.js";
 // 3. Hygiene (Maintenance & Integrity)
 export { deepStoragePurgeHandler, maintenanceVacuumHandler, sessionHealthCheckHandler, backfillEmbeddingsHandler, sessionBackfillLinksHandler, knowledgeSetRetentionHandler } from "./hygieneHandlers.js";
 // ── Compaction Handler (v0.4.0 — Enhancement #2) ──

package/dist/tools/sessionMemoryDefinitions.js

@@ -1238,3 +1238,67 @@ export function isSessionSynthesizeEdgesArgs(args) {
         return false;
     return true;
 }
+export const SESSION_COGNITIVE_ROUTE_TOOL = {
+    name: "session_cognitive_route",
+    description: "Resolve an HDC compositional state into a nearest semantic concept with policy-gated routing. " +
+        "Returns concept, confidence, distance, ambiguity, convergence steps, and route outcome. " +
+        "Use this for explainable cognitive recall decisions in v6.5.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            project: {
+                type: "string",
+                description: "Project identifier.",
+            },
+            state: {
+                type: "string",
+                description: "Current state concept key (e.g. 'State:ActiveSession').",
+            },
+            role: {
+                type: "string",
+                description: "Role concept key used for transition binding.",
+            },
+            action: {
+                type: "string",
+                description: "Action concept key used for transition binding.",
+            },
+            fallback_threshold: {
+                type: "number",
+                description: "Optional route fallback threshold override (0 <= fallback < clarify <= 1).",
+            },
+            clarify_threshold: {
+                type: "number",
+                description: "Optional route clarify threshold override (0 <= fallback < clarify <= 1).",
+            },
+            explain: {
+                type: "boolean",
+                description: "If true, include expanded explainability details in the response. Default: true.",
+            },
+        },
+        required: ["project", "state", "role", "action"],
+    },
+};
+export function isSessionCognitiveRouteArgs(args) {
+    if (typeof args !== "object" || args === null)
+        return false;
+    const a = args;
+    if (typeof a.project !== "string")
+        return false;
+    if (typeof a.state !== "string")
+        return false;
+    if (typeof a.role !== "string")
+        return false;
+    if (typeof a.action !== "string")
+        return false;
+    if (a.fallback_threshold !== undefined && typeof a.fallback_threshold !== "number")
+        return false;
+    if (a.clarify_threshold !== undefined && typeof a.clarify_threshold !== "number")
+        return false;
+    if (a.explain !== undefined && typeof a.explain !== "boolean")
+        return false;
+    if (typeof a.fallback_threshold === "number" &&
+        typeof a.clarify_threshold === "number" &&
+        !(a.fallback_threshold >= 0 && a.fallback_threshold < a.clarify_threshold && a.clarify_threshold <= 1))
+        return false;
+    return true;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "6.2.2",
+  "version": "6.5.1",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — persistent memory (SQLite/Supabase), behavioral learning & IDE rules sync, multimodal VLM image captioning, pluggable LLM providers (OpenAI/Anthropic/Gemini/Ollama), OpenTelemetry distributed tracing, GDPR export, multi-agent Hivemind sync, time travel, visual Mind Palace dashboard. Zero-config local mode.",
   "module": "index.ts",