prism-mcp-server 20.2.9 → 20.3.0

package/README.md

@@ -77,6 +77,21 @@ to the patched 8.5.23 release.
 
 ---
 
+## What's New in v20.3.0
+
+### Hybrid Memory Search (Portal Tier)
+
+`session_search_memory` on Synalux-backed installs now fuses semantic
+similarity with exact-term lexical matching (weighted reciprocal-rank
+fusion). On blind probes against a real 8.5k-entry corpus this lifted
+top-1 retrieval from 45% (semantic alone) to 59%; exact identifiers such
+as TPNs, function names and error strings now rescue queries that
+embeddings blur. Results say how they were found — `hybrid retrieval`
+headers, per-hit `sem#/lex#` arms — and a lexical-only rescue is labelled
+`exact-term match` instead of pretending to a similarity score. Local
+SQLite installs keep pure vector search; hybrid needs the portal's
+lexical index.
+
 ## What's New in v20.2.6
 
 ### Safer Configuration Updates Across Every Agent

package/dist/storage/portalContracts.js

@@ -39,4 +39,8 @@ export const KnowledgeSearchResponseSchema = z.object({
     action: z.literal("knowledge_search"),
     count: z.number(),
     results: z.array(z.record(z.string(), z.unknown())),
+    /** How the portal matched. Optional so an older portal deployment that
+     *  predates the ranked search RPC still validates. When present and
+     *  'relaxed', callers MUST NOT present the rows as exact hits. */
+    match_mode: z.enum(["strict", "relaxed", "unfiltered", "none"]).optional(),
 });

package/dist/storage/synalux.js

@@ -25,17 +25,30 @@
  *     - searchKnowledge   → POST /api/v1/prism/memory  action=search
  *     - softDeleteLedger  → POST /api/v1/prism/memory  action=forget_memory (Phase 3 Tier A)
  *     - hardDeleteLedger  → POST /api/v1/prism/memory  action=forget_memory (Phase 3 Tier A)
+ *     - searchMemory      → POST /api/v1/prism/memory  action=search_memory
+ *     - getHistory        → POST /api/v1/prism/memory  action=memory_history
+ *     - patchLedger       → POST /api/v1/prism/memory  action=save_embedding
+ *     - getEntriesMissingEmbeddings → POST /api/v1/prism/memory  action=list_missing_embeddings
  *
  *   Methods still falling through to SupabaseStorage (Phase 3 Tier B+):
- *   semantic searchMemory, save_experience direct entrypoint,
- *   compactLedger, image ops, history, hivemind, etc.
+ *   save_experience direct entrypoint, compactLedger, image ops,
+ *   hivemind, etc. Anything in this group requires a direct SUPABASE_URL
+ *   and therefore does NOT work on paid-tier installs — that is precisely
+ *   how embedding writes failed silently: patchLedger was inherited, threw
+ *   against a URL that is not configured, and the caller swallowed it.
+ *   Before relying on an inherited method, check it is actually reachable.
+ *
+ *   NOTE: this list was previously wrong — it named searchMemory and
+ *   history as falling through when both had already been overridden.
+ *   A stale routing map here sends the next reader down the wrong path,
+ *   so amend it in the same commit that moves a method.
  *   See portal/docs/PHASE_3_PORTAL_ENDPOINTS.md for the full catalog.
  * ═══════════════════════════════════════════════════════════════════
  */
 import { SupabaseStorage } from "./supabase.js";
 import { debugLog } from "../utils/logger.js";
 import { PRISM_SYNALUX_BASE_URL, PRISM_SYNALUX_API_KEY } from "../config.js";
-import { KnowledgeSearchRequestSchema } from "./portalContracts.js";
+import { KnowledgeSearchRequestSchema, KnowledgeSearchResponseSchema } from "./portalContracts.js";
 function resolveKnowledgeScope(callerScope) {
     if (callerScope === "user" || callerScope === "workspace") {
         return callerScope;
@@ -330,6 +343,8 @@ export class SynaluxStorage extends SupabaseStorage {
         const result = await this.portalPost("/api/v1/prism/memory", {
             action: "search_memory",
             project: params.project ?? undefined,
+            // Enables the portal's hybrid lexical+semantic fusion (see interface).
+            query: params.queryText || undefined,
             query_embedding: parsed,
             similarity_threshold: params.similarityThreshold,
             limit: params.limit,
@@ -358,9 +373,81 @@ export class SynaluxStorage extends SupabaseStorage {
             scope: resolveKnowledgeScope(params.scope),
         });
         const result = await this.portalPost("/api/v1/prism/memory", wireBody);
+        // Validate the RESPONSE against the shared contract, not just the request.
+        // Before this, only the outgoing shape was checked — so a portal-side
+        // field rename would have gone unnoticed on both sides, which is exactly
+        // the 2026-05-24 class of incident this file exists to prevent.
+        // safeParse (not parse) on purpose: drift must be loud, but it must not
+        // take knowledge_search offline. The build-time contract test is what
+        // fails hard; at runtime we log and degrade to lenient extraction.
+        const validated = KnowledgeSearchResponseSchema.safeParse(result);
+        if (!validated.success) {
+            console.error("[synalux] knowledge_search response failed contract validation — " +
+                "portal and client may have drifted: " +
+                JSON.stringify(validated.error.issues.map(i => ({ path: i.path, code: i.code }))));
+        }
         const count = typeof result.count === "number" ? result.count : 0;
         const results = Array.isArray(result.results) ? result.results : [];
-        return { count, results };
+        const matchMode = validated.success ? validated.data.match_mode : undefined;
+        return { count, results, match_mode: matchMode };
+    }
+    /**
+     * Persist embedding data for an already-saved entry.
+     *
+     * MUST be overridden here. SupabaseStorage.patchLedger writes straight to
+     * Supabase via supabasePatch, which needs a direct SUPABASE_URL — not
+     * configured for paid-tier installs. Inheriting it meant every embedding
+     * write threw, and session_save_ledger's fire-and-forget catch swallowed
+     * the error while still reporting "Embedding generation queued". The
+     * result was 0 of 8,560 rows carrying an embedding and semantic search
+     * silently returning nothing.
+     *
+     * Only the vector is sent. embedding_compressed / embedding_format /
+     * embedding_turbo_radius are local-SQLite columns that do not exist on the
+     * portal schema; forwarding them would fail the whole write for fields the
+     * server has nowhere to put.
+     */
+    async patchLedger(id, data) {
+        const raw = data.embedding;
+        if (raw === undefined || raw === null)
+            return;
+        // ledgerHandlers JSON-stringifies the vector before patching; accept both.
+        let vector = raw;
+        if (typeof raw === "string") {
+            try {
+                vector = JSON.parse(raw);
+            }
+            catch {
+                throw new Error("patchLedger: embedding string is not valid JSON");
+            }
+        }
+        if (!Array.isArray(vector)) {
+            throw new Error("patchLedger: embedding must be an array");
+        }
+        await this.portalPost("/api/v1/prism/memory", {
+            action: "save_embedding",
+            memory_id: id,
+            embedding: vector,
+        });
+    }
+    /**
+     * Rows semantic search cannot find, read through the portal.
+     *
+     * The backfill tool used to reach these via inherited getLedgerEntries —
+     * a direct Supabase read paid-tier installs cannot make (NXDOMAIN), so the
+     * repair tool could never see what needed repairing. The portal endpoint
+     * ignores cursorId (it always returns the oldest missing rows, and rows
+     * gain embeddings as the backfill proceeds, so the frontier advances by
+     * itself); it is accepted here to satisfy the shared signature.
+     */
+    async getEntriesMissingEmbeddings(params) {
+        const result = await this.portalPost("/api/v1/prism/memory", {
+            action: "list_missing_embeddings",
+            limit: params.limit,
+            ...(params.project ? { project: params.project } : {}),
+        });
+        const entries = Array.isArray(result.entries) ? result.entries : [];
+        return entries;
     }
     // ─── Time Travel ─────────────────────────────────────────────
     // Phase 3 Tier B: route memory_history through portal instead of
@@ -397,8 +484,15 @@ export class SynaluxStorage extends SupabaseStorage {
             const inventory = result.inventory;
             const totalActiveEntries = typeof inventory?.ledger_entries === "number" ? inventory.ledger_entries : 0;
             const totalHandoffs = typeof inventory?.active_projects === "number" ? inventory.active_projects : 0;
+            // Hardcoding 0 here certified a 100%-missing-embeddings outage as
+            // "HEALTHY — all clean". Use the portal's real count; if the portal
+            // predates the field, report -1 so healthCheck can say "unknown"
+            // instead of lying in either direction.
+            const missingEmbeddings = typeof inventory?.ledger_missing_embeddings === "number"
+                ? inventory.ledger_missing_embeddings
+                : -1;
             return {
-                missingEmbeddings: 0,
+                missingEmbeddings,
                 activeLedgerSummaries: [],
                 orphanedHandoffs: [],
                 staleRollups: 0,
@@ -411,7 +505,9 @@ export class SynaluxStorage extends SupabaseStorage {
         catch (e) {
             debugLog("[SynaluxStorage] getHealthStats failed: " + (e instanceof Error ? e.message : String(e)));
             return {
-                missingEmbeddings: 0,
+                // Portal unreachable: coverage is UNKNOWN, not zero. -1 makes the
+                // health check say so rather than certify blind.
+                missingEmbeddings: -1,
                 activeLedgerSummaries: [],
                 orphanedHandoffs: [],
                 staleRollups: 0,

package/dist/tools/graphHandlers.js

@@ -57,6 +57,56 @@ 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";
+/**
+ * Header line for knowledge_search results.
+ *
+ * A 'relaxed' match_mode means no entry matched every query term — the portal
+ * widened the search and returned the closest entries. Wording those the same
+ * as an exact hit is how a best-effort guess gets read as a confirmed answer,
+ * so the distinction is stated in the text the agent actually sees.
+ *
+ * Exported so the wording is covered by a test that exercises this function
+ * rather than a copy of it.
+ */
+export function formatKnowledgeHeader(resultCount, matchMode) {
+    if (matchMode === "relaxed") {
+        return `🧠 No exact match. ${resultCount} closest ${resultCount === 1 ? "entry" : "entries"} ` +
+            `(widened search — treat as leads, not confirmed answers):`;
+    }
+    return `🧠 Found ${resultCount} knowledge entries:`;
+}
+/**
+ * Header + per-hit scoring for session_search_memory results.
+ *
+ * Exported so wording is covered by tests that call the shipped functions —
+ * a lesson from the knowledge_search match_mode fix, whose first tests
+ * mirrored the logic and would have passed while the handler regressed.
+ *
+ * Hybrid detection is per-row: portal fusion (weighted RRF, measured 59%
+ * blind hit@1 vs 45% semantic-only) annotates each row with semantic_rank /
+ * lexical_rank. Any row carrying lexical_rank means the lexical arm ran, so
+ * calling the results "semantically similar" would misstate how they were
+ * found — and a lexical-only rescue has NO similarity score at all, which
+ * previously rendered as "N/A similar".
+ */
+export function isHybridSearchResults(results) {
+    return results.some((r) => r?.lexical_rank !== undefined && r?.lexical_rank !== null);
+}
+export function searchResultsHeader(count, hybrid) {
+    return hybrid
+        ? `🧠 Found ${count} matching sessions (hybrid retrieval — semantic meaning + exact terms):`
+        : `🧠 Found ${count} semantically similar sessions:`;
+}
+export function formatHitScore(r) {
+    const sim = typeof r.similarity === "number" ? `${(r.similarity * 100).toFixed(1)}% similar` : null;
+    const sem = r.semantic_rank !== undefined && r.semantic_rank !== null ? `sem#${r.semantic_rank + 1}` : null;
+    const lex = r.lexical_rank !== undefined && r.lexical_rank !== null ? `lex#${r.lexical_rank + 1}` : null;
+    if (sem || lex) {
+        const arms = [sem, lex].filter(Boolean).join(" + ");
+        return sim ? `${sim} (${arms})` : `exact-term match (${arms})`;
+    }
+    return sim ?? "N/A similar";
+}
 export async function knowledgeSearchHandler(args) {
     if (!isKnowledgeSearchArgs(args)) {
         throw new Error("Invalid arguments for knowledge_search");
@@ -136,7 +186,7 @@ export async function knowledgeSearchHandler(args) {
     // Phase 1: Wrap in contentBlocks array for optional trace attachment
     const contentBlocks = [{
             type: "text",
-            text: `🧠 Found ${resultCount} knowledge entries:\n\n${JSON.stringify(data.results, null, 2)}`,
+            text: `${formatKnowledgeHeader(resultCount, data.match_mode)}\n\n${JSON.stringify(data.results, null, 2)}`,
         }];
     // Phase 1: Attach MemoryTrace with strategy="keyword" and timing data
     if (enable_trace) {
@@ -377,6 +427,8 @@ export async function sessionSearchMemoryHandler(args) {
             : Math.min(limit, 20);
         const results = await storage.searchMemory({
             queryEmbedding: JSON.stringify(queryEmbedding),
+            // Portal-backed installs fuse this with lexical search (weighted RRF).
+            queryText: query,
             project: project || null,
             limit: candidateLimit,
             similarityThreshold: similarity_threshold,
@@ -516,9 +568,7 @@ export async function sessionSearchMemoryHandler(args) {
         }
         // Format results with similarity scores + effective importance + ACT-R
         const formatted = results.map((r, i) => {
-            const simScore = typeof r.similarity === "number"
-                ? `${(r.similarity * 100).toFixed(1)}%`
-                : "N/A";
+            const simScore = formatHitScore(r);
             // Dynamic importance decay (uses ACT-R internally when enabled)
             const baseImportance = r.importance ?? 0;
             const effectiveImportance = computeEffectiveImportance(baseImportance, r.last_accessed_at, r.created_at, Boolean(r.is_rollup));
@@ -529,7 +579,7 @@ export async function sessionSearchMemoryHandler(args) {
             const actrStr = r._actr_composite !== undefined
                 ? `  ACT-R: composite=${r._actr_composite.toFixed(3)} (B=${r._actr_Bi?.toFixed(2)}, S=${r._actr_Si?.toFixed(3)})\n`
                 : "";
-            return `[${i + 1}] ${simScore} similar — ${r.session_date || "unknown date"}\n` +
+            return `[${i + 1}] ${simScore} — ${r.session_date || "unknown date"}\n` +
                 `  Project: ${r.project}\n` +
                 `  Summary: ${r.summary}\n` +
                 importanceStr +
@@ -540,7 +590,7 @@ export async function sessionSearchMemoryHandler(args) {
         // Phase 1: content[0] = human-readable results (unchanged from pre-Phase 1)
         const contentBlocks = [{
                 type: "text",
-                text: `🧠 Found ${results.length} semantically similar sessions:\n\n${formatted}`,
+                text: `${searchResultsHeader(results.length, isHybridSearchResults(results))}\n\n${formatted}`,
             }];
         // Phase 1: content[1] = machine-readable MemoryTrace (only when enable_trace=true)
         // topScore is read from results[0].similarity — this is the cosine distance

package/dist/tools/hygieneHandlers.js

@@ -60,22 +60,36 @@ export async function backfillEmbeddingsHandler(args) {
     debugLog(`[backfill_embeddings] ${dry_run ? "DRY RUN: " : ""}` +
         `project=${project || "all"}, limit=${safeLimit}`);
     const storage = await getStorage();
-    // Find entries missing embeddings
-    const params = {
-        "embedding": "is.null",
-        "archived_at": "is.null",
-        user_id: `eq.${PRISM_USER_ID}`,
-        order: "id.asc",
-        limit: String(safeLimit),
-        select: "id,summary,decisions,project",
-    };
-    if (args._cursor_id) {
-        params.id = `gt.${args._cursor_id}`;
+    // Find entries missing embeddings. Prefer the dedicated method: the old
+    // PostgREST-param path below goes through getLedgerEntries, which
+    // SynaluxStorage inherits as a DIRECT Supabase read — paid-tier installs
+    // have no SUPABASE_URL, so that read dies with NXDOMAIN and this tool
+    // could never see what it was supposed to repair.
+    let entries;
+    if (typeof storage.getEntriesMissingEmbeddings === "function") {
+        entries = await storage.getEntriesMissingEmbeddings({
+            limit: safeLimit,
+            ...(project ? { project } : {}),
+            ...(args._cursor_id ? { cursorId: args._cursor_id } : {}),
+        });
     }
-    if (project) {
-        params.project = `eq.${project}`;
+    else {
+        const params = {
+            "embedding": "is.null",
+            "archived_at": "is.null",
+            user_id: `eq.${PRISM_USER_ID}`,
+            order: "id.asc",
+            limit: String(safeLimit),
+            select: "id,summary,decisions,project",
+        };
+        if (args._cursor_id) {
+            params.id = `gt.${args._cursor_id}`;
+        }
+        if (project) {
+            params.project = `eq.${project}`;
+        }
+        entries = await storage.getLedgerEntries(params);
     }
-    const entries = await storage.getLedgerEntries(params);
     if (entries.length === 0) {
         return {
             content: [{

package/dist/tools/ledgerHandlers.js

@@ -627,6 +627,7 @@ export async function sessionSaveHandoffHandler(args, server) {
     // Await the attempt so short-lived CLI/MCP transports cannot exit before the
     // snapshot reaches storage. Failure stays non-fatal because the primary
     // handoff has already been durably saved.
+    let historySnapshotSaved = false;
     if (data.status === "created" || data.status === "updated") {
         const snapshotEntry = {
             project,
@@ -637,10 +638,12 @@ export async function sessionSaveHandoffHandler(args, server) {
             keywords: keywords ?? null,
             key_context: key_context ?? null,
             active_branch: active_branch ?? null,
+            role: effectiveRole,
             version: newVersion,
         };
         try {
-            await storage.saveHistorySnapshot(snapshotEntry);
+            await storage.saveHistorySnapshot(snapshotEntry, active_branch ?? "main");
+            historySnapshotSaved = true;
         }
         catch (err) {
             console.error(`[session_save_handoff] History snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
@@ -800,12 +803,16 @@ export async function sessionSaveHandoffHandler(args, server) {
         console.error("[FactMerger] Module load failed (non-fatal): " + err));
     }
     const metricsBlock = formatInferenceMetrics();
+    const historySnapshotLine = historySnapshotSaved
+        ? `🕘 Versioned history snapshot saved.\n`
+        : `⚠️ Primary handoff saved, but its versioned history snapshot was not saved. Check memory_history before relying on time travel.\n`;
     // Build response text based on whether a CRDT merge occurred
     const responseText = (_saveHandoffGateWarning ? `⚠️ ${_saveHandoffGateWarning}\n\n` : "") +
         (isMerged
             ? `🔄 Auto-merged conflict for "${project}" (v${expected_version} → v${newVersion})\n` +
                 `Strategy: ${JSON.stringify(mergeStrategy)}\n` +
                 (last_summary ? `Summary: ${last_summary}\n` : "") +
+                historySnapshotLine +
                 metricsBlock +
                 `\n🔑 Remember: pass expected_version: ${newVersion} on your next save ` +
                 `to maintain concurrency control.`
@@ -814,6 +821,7 @@ export async function sessionSaveHandoffHandler(args, server) {
                 (last_summary ? `Last summary: ${last_summary}\n` : "") +
                 (open_todos?.length ? `Open TODOs: ${open_todos.length} items\n` : "") +
                 (active_branch ? `Active branch: ${active_branch}\n` : "") +
+                historySnapshotLine +
                 (embeddingQueued
                     ? `📊 Embedding generation queued for semantic search.\n`
                     : `📊 Primary history saved; optional semantic indexing was not queued.\n`) +

package/dist/utils/healthCheck.js

@@ -217,7 +217,21 @@ export function runHealthCheck(stats) {
             severity: stats.missingEmbeddings > 10 ? "error" : "warning", // >10 = critical
             message: `${stats.missingEmbeddings} ledger entries have no embedding vector`,
             count: stats.missingEmbeddings, // how many are affected
-            suggestion: "Run session_health_check(auto_fix: true) to generate missing embeddings automatically",
+            suggestion: "Run session_backfill_embeddings to generate the missing vectors",
+        });
+    }
+    else if (stats.missingEmbeddings < 0) {
+        // -1 = coverage is UNKNOWN (portal unreachable, or a portal that predates
+        // the ledger_missing_embeddings field). Saying nothing here is how a
+        // 100%-missing outage was certified "HEALTHY — all clean": the storage
+        // layer hardcoded 0 and this check had no way to distinguish "verified
+        // zero" from "never looked".
+        issues.push({
+            check: "missing_embeddings",
+            severity: "warning",
+            message: "Embedding coverage could not be verified (portal did not report a count)",
+            count: 0,
+            suggestion: "Update the Synalux portal, or check connectivity, then re-run session_health_check",
         });
     }
     // ── Check 2: Duplicate Entries ─────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.2.9",
+  "version": "20.3.0",
   "mcpName": "io.github.dcostenco/prism-coder",
   "description": "Prism Coder — Cognitive memory + tool-calling intelligence for AI agents. Mind Palace persistent memory (BFCL Gold Certified, 100% Tool-Call Accuracy, 114 Agent Skills, PHI Guard, Tier Enforcement, Prompt-Based Skill Routing, Zero-Search HDC/HRR retrieval, HRR Semantic Drift Detection across BCBA/Coding/AAC domains, HIPAA-hardened local or subscription-gated Synalux storage, SLERP-optimized GRPO alignment) plus the prism-coder 1.7B–32B open-weights LLM fleet.",
   "module": "index.ts",