prism-mcp-server 5.2.1 → 6.1.8

package/README.md

@@ -10,7 +10,7 @@
 
 **Your AI agent forgets everything between sessions. Prism fixes that.**
 
-One command. Persistent memory. Zero cloud dependencies.
+One command. Persistent memory. Local-first by default. Optional cloud power-ups.
 
 ```bash
 npx -y prism-mcp-server
@@ -18,6 +18,23 @@ npx -y prism-mcp-server
 
 Works with **Claude Desktop · Claude Code · Cursor · Windsurf · Cline · Gemini · Antigravity** — any MCP client.
 
+## 📖 Table of Contents
+
+- [Why Prism?](#why-prism)
+- [Quick Start](#-quick-start)
+- [The Magic Moment](#-the-magic-moment)
+- [Setup Guides](#-setup-guides)
+- [What Makes Prism Different](#-what-makes-prism-different)
+- [Use Cases](#-use-cases)
+- [What's New](#-whats-new)
+- [How Prism Compares](#-how-prism-compares)
+- [Tool Reference](#-tool-reference)
+- [Environment Variables](#environment-variables)
+- [Architecture](#architecture)
+- [Scientific Foundation](#-scientific-foundation)
+- [Product Roadmap](#-product-roadmap)
+- [Limitations](#limitations)
+
 ---
 
 ## Why Prism?
@@ -28,81 +45,9 @@ Every time you start a new conversation with an AI coding assistant, it starts f
 
 ---
 
-## ✨ What Makes Prism Different
-
-### 🧠 Your Agent Learns From Mistakes
-When you correct your agent, Prism tracks it. Corrections accumulate **importance** over time. High-importance lessons auto-surface as warnings in future sessions — and can even sync to your `.cursorrules` file for permanent enforcement. Your agent literally gets smarter the more you use it.
-
-### 🕰️ Time Travel
-Every save creates a versioned snapshot. Made a mistake? `memory_checkout` reverts your agent's memory to any previous state — like `git revert` for your agent's brain. Full version history with optimistic concurrency control.
-
-### 🔮 Mind Palace Dashboard
-A gorgeous glassmorphism UI at `localhost:3000` that lets you see exactly what your agent is thinking:
-
-- **Current State & TODOs** — the exact context injected into the LLM's prompt
-- **Interactive Knowledge Graph** — force-directed neural graph with click-to-filter, node renaming, and surgical keyword deletion *(v5.1)*
-- **Deep Storage Manager** — preview and execute vector purge operations with dry-run safety *(v5.1)*
-- **Session Ledger** — full audit trail of every decision your agent has made
-- **Time Travel Timeline** — browse and revert any historical handoff version
-- **Visual Memory Vault** — browse VLM-captioned screenshots and auto-captured HTML states
-- **Hivemind Radar** — real-time active agent roster with role, task, and heartbeat
-- **Morning Briefing** — AI-synthesized action plan after 4+ hours away
-- **Brain Health** — memory integrity scan with one-click auto-repair
-
-![Mind Palace Dashboard](docs/mind-palace-dashboard.png)
-
-### 🧬 10× Memory Compression
-Powered by a pure TypeScript port of Google's TurboQuant (ICLR 2026), Prism compresses 768-dim embeddings from **3,072 bytes → ~400 bytes** — enabling decades of session history on a standard laptop. No native modules. No vector database required.
-
-### 🐝 Multi-Agent Hivemind
-Multiple agents (dev, QA, PM) can work on the same project with **role-isolated memory**. Agents discover each other automatically, share context in real-time via Telepathy sync, and see a team roster during context loading.
-
-### 🖼️ Visual Memory
-Save UI screenshots, architecture diagrams, and bug states to a searchable vault. Images are auto-captioned by a VLM (Claude Vision / GPT-4V / Gemini) and become semantically searchable across sessions.
-
-### 🔭 Full Observability
-OpenTelemetry spans for every MCP tool call, LLM hop, and background worker. Route to Jaeger, Grafana, or any OTLP collector. Configure in the dashboard — zero code changes.
-
-### 🔒 GDPR Compliant
-Soft/hard delete (Art. 17), full ZIP export (Art. 20), API key redaction, per-project TTL retention, and audit trail. Enterprise-ready out of the box.
-
----
-
-## 🎯 Use Cases
-
-**Long-running feature work** — Save state at end of day, restore full context next morning. No re-explaining.
-
-**Multi-agent collaboration** — Dev, QA, and PM agents share real-time context without stepping on each other's memory.
-
-**Consulting / multi-project** — Switch between client projects with progressive loading: `quick` (~50 tokens), `standard` (~200), or `deep` (~1000+).
-
-**Visual debugging** — Save UI screenshots to searchable memory. Find that CSS bug from last week by description.
-
-**Team onboarding** — New team member's agent loads the full project history instantly.
-
-**Behavior enforcement** — Agent corrections auto-graduate into permanent `.cursorrules` / `.clauderules` rules.
-
-**Offline / air-gapped** — Full SQLite local mode + Ollama LLM adapter. Zero internet dependency.
-
-**Morning Briefings** — After 4+ hours away, Prism auto-synthesizes a 3-bullet action plan from your last sessions.
-
----
-
-## 🆕 What's New in v5.2
-
-- 🧠 **Cognitive Memory** — Ebbinghaus importance decay computes `effective_importance = base × 0.95^days` at retrieval time. Frequently accessed memories stay prominent; neglected ones naturally fade. Tracks `last_accessed_at` per entry.
-- 🎯 **Context-Weighted Retrieval** — New `context_boost` parameter on `session_search_memory` prepends your active project's context to the query before embedding, biasing results toward what matters right now.
-- 🔄 **[Universal History Migration](#migrating-existing-history-claude-gemini-openai)** — Import years of Claude Code, Gemini, and ChatGPT sessions on day one. Strategy Pattern adapters with OOM-safe streaming, content-hash dedup, and `--dry-run` support. Also available via the [Dashboard Import UI](#-mind-palace-dashboard).
-- 🧹 **Smart Consolidation** — Enhanced compaction extracts recurring principles alongside summaries for richer rollups.
-- 🛡️ **SQL Injection Prevention** — 17-column allowlist on `patchLedger()` hardens all dynamic SQL paths.
-- 🧪 **352 Tests** — Zero regressions across 15 suites.
-
-> [Full CHANGELOG →](CHANGELOG.md) · [Architecture Deep Dive →](docs/ARCHITECTURE.md)
-
----
-
 ## 🚀 Quick Start
 
+
 Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.):
 
 ```json
@@ -116,9 +61,47 @@ Add to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`,
 }
 ```
 
-**That's it.** Restart your client. All 30+ tools are available. Dashboard at `http://localhost:3000`.
+> **Note on Windows/Restricted Shells:** If your MCP client complains that `npx` is not found, use the absolute path to your node binary (e.g. `C:\Program Files\nodejs\npx.cmd`) or install globally with caution.
+
+**That's it.** Restart your client. All tools are available. Dashboard at `http://localhost:3000`. *(Note: The MCP server automatically starts this UI on port 3000 when connected. If you have a Next.js/React app running, port 3000 might already be in use.)*
+
+### Capability Matrix
 
-> **Optional API keys:** `GOOGLE_API_KEY` for semantic search + Morning Briefings, `BRAVE_API_KEY` for web search. See [Environment Variables](#environment-variables).
+| Feature | Local (Offline) | Cloud (API Key) |
+|:--------|:---:|:---:|
+| Session memory & handoffs | ✅ | ✅ |
+| Keyword search (FTS5) | ✅ | ✅ |
+| Time travel & versioning | ✅ | ✅ |
+| Mind Palace Dashboard | ✅ | ✅ |
+| GDPR export (JSON/Markdown/Vault) | ✅ | ✅ |
+| Semantic vector search | ❌ | ✅ `GOOGLE_API_KEY` |
+| Morning Briefings | ❌ | ✅ `GOOGLE_API_KEY` |
+| Auto-compaction | ❌ | ✅ `GOOGLE_API_KEY` |
+| Web Scholar research | ❌ | ✅ `BRAVE_API_KEY` + `FIRECRAWL_API_KEY` |
+| VLM image captioning | ❌ | ✅ Provider key |
+
+> 🔑 The core Mind Palace works **100% offline** with zero API keys. Cloud keys unlock intelligence features. See [Environment Variables](#environment-variables).
+
+---
+
+## ✨ The Magic Moment
+
+> **Session 1** (Monday evening):
+> ```
+> You: "Analyze this auth architecture and plan the OAuth migration."
+> Agent: *deep analysis, decisions, TODO list*
+> Agent: session_save_ledger → session_save_handoff ✅
+> ```
+>
+> **Session 2** (Tuesday morning — new conversation, new context window):
+> ```
+> Agent: session_load_context → "Welcome back! Yesterday we decided to use PKCE
+>        flow with refresh tokens. 3 TODOs remain: migrate the user table,
+>        update the middleware, and write integration tests."
+> You: "Pick up where we left off."
+> ```
+>
+> **Your agent remembers everything.** No re-uploading files. No re-explaining decisions.
 
 ---
 
@@ -200,18 +183,21 @@ Add to your Continue `config.json` or Cline MCP settings:
 
 </details>
 
+### Migration
+
 <details>
 <summary><strong>Migrating Existing History (Claude, Gemini, OpenAI)</strong></summary>
 
-Prism can ingest months of historical sessions from other tools to give your Mind Palace a massive head start.
+Prism can ingest months of historical sessions from other tools to give your Mind Palace a massive head start. Import via the **CLI** or directly from the [Mind Palace Dashboard](#-mind-palace-dashboard) Import tab (file picker + manual path + dry-run toggle).
 
-### Supported Formats
+#### Supported Formats
 * **Claude Code** (`.jsonl` logs) — Automatically handles streaming chunk deduplication and `requestId` normalization.
 * **Gemini** (JSON history arrays) — Supports large-file streaming for 100MB+ exports.
 * **OpenAI** (JSON chat completion history) — Normalizes disparate tool-call structures into the unified Ledger schema.
 
-### How to Run
-Use the `universal-import` command:
+#### How to Run
+
+**Option 1 — CLI:**
 
 ```bash
 # Ingest Claude Code history
@@ -221,151 +207,34 @@ npx -y prism-mcp-server universal-import --format claude --path ~/path/to/claude
 npx -y prism-mcp-server universal-import --format gemini --path ./gemini_history.json --dry-run
 ```
 
-### Key Features
+**Option 2 — Dashboard:** Open `localhost:3000`, navigate to the **Import** tab, select the format and file, and click Import. Supports dry-run preview. See the [dashboard screenshot](#-mind-palace-dashboard) above.
+
+#### Key Features
 * **OOM-Safe Streaming:** Processes massive log files line-by-line using `stream-json`.
+* **Idempotent Dedup:** Content-hash prevents duplicate imports on re-run (`skipCount` reported).
 * **Chronological Integrity:** Uses timestamp fallbacks and `requestId` sorting to ensure your memory timeline is accurate.
 * **Smart Context Mapping:** Extracts `cwd`, `gitBranch`, and tool usage patterns into searchable metadata.
 
 </details>
 
 <details>
-<summary><strong>Claude Code — Lifecycle Hooks (Auto-Load & Auto-Save)</strong></summary>
-
-Claude Code supports `SessionStart` and `Stop` hooks that force the agent to load/save Prism context automatically.
-
-### 1. Create the Hook Script
-
-Save as `~/.claude/mcp_autoload_hook.py`:
-
-```python
-#!/usr/bin/env python3
-import json, sys
-
-def main():
-    print(json.dumps({
-        "continue": True,
-        "suppressOutput": True,
-        "systemMessage": (
-            "## First Action\n"
-            "Call `mcp__prism-mcp__session_load_context(project='my-project', level='deep')` "
-            "before responding to the user. Do not generate any text before calling this tool."
-        )
-    }))
-
-if __name__ == "__main__":
-    main()
-```
-
-### 2. Configure `settings.json`
-
-```json
-{
-  "hooks": {
-    "SessionStart": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 /Users/you/.claude/mcp_autoload_hook.py",
-            "timeout": 10
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": "*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "python3 -c \"import json; print(json.dumps({'continue': True, 'suppressOutput': True, '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.'}))\""
-          }
-        ]
-      }
-    ]
-  },
-  "permissions": {
-    "allow": [
-      "mcp__prism-mcp__session_load_context",
-      "mcp__prism-mcp__session_save_ledger",
-      "mcp__prism-mcp__session_save_handoff",
-      "mcp__prism-mcp__knowledge_search",
-      "mcp__prism-mcp__session_search_memory"
-    ]
-  }
-}
-```
-
-### Troubleshooting
-
-- **Hook not firing?** Check `timeout` — if your script takes too long, Claude ignores it.
-- **"Tool not available"?** This is a hallucination. Ensure `permissions.allow` exactly matches the double-underscore format.
-
-</details>
-
-<details>
-<summary><strong>Gemini / Antigravity — Auto-Load Rules (Battle-Tested)</strong></summary>
+<summary><strong>Claude Code — Lifecycle Autoload (.clauderules)</strong></summary>
 
-Gemini-based agents (including Google's Antigravity IDE) require a fundamentally different approach to auto-load. This guide was refined over **14 iterations** of real-world prompt engineering.
-
-### The Core Problem
-
-When given verbose instructions with many constraints, Gemini models hallucinate that MCP tools "don't exist" or "aren't available" — even when they are. This is adversarial reasoning triggered by long rule lists, not a configuration issue.
-
-### The 2-Line Rule (Proven Fix)
-
-Create `~/.gemini/GEMINI.md`:
+Claude Code naturally picks up MCP tools by adding them to your workspace `.clauderules`. Simply add:
 
 ```markdown
-## First Action
-Call `mcp_prism-mcp_session_load_context(project="my-project", level="deep")` before responding.
+Always start the conversation by calling `mcp__prism-mcp__session_load_context(project='my-project', level='deep')`.
+When wrapping up, always call `mcp__prism-mcp__session_save_ledger` and `mcp__prism-mcp__session_save_handoff`.
 ```
 
-**Why this works:**
-- Gemini uses **single underscores** for MCP tools (`mcp_prism-mcp_...`) vs Claude's **double underscores** (`mcp__prism-mcp__...`)
-- Keeping the instruction to 2 lines avoids triggering the model's adversarial "tool not found" reasoning
-- Framing as a positive "First Action" directive outperforms negative constraint lists
+> **Format Note:** Claude automatically wraps MCP tools with double underscores (`mcp__prism-mcp__...`), while most other clients use single underscores (`mcp_prism-mcp_...`). Prism's backend natively handles both formats seamlessly.
 
-### Antigravity UI Caveat
-
-Antigravity **does not visually render MCP tool output blocks** in the chat UI. The tool executes successfully, but the user sees nothing. Fix this by adding an echo rule:
-
-```markdown
-## Echo Context
-After loading context, include in your text reply:
-- Agent identity (role + name)
-- Last session summary
-- Open TODOs
-- Session version number
-```
-
-This ensures the user sees their project context even though the raw MCP output is invisible.
-
-### Session End Workflow
-
-Tell the agent: *"Wrap up the session."* It should execute:
-
-1. `session_save_ledger` — append immutable work log (summary, decisions, files changed)
-2. `session_save_handoff` — upsert project state with `expected_version` for OCC
-
-> **Tip:** Include the session-end instructions in your `GEMINI.md` or ask the agent to save when you're done.
-
-### Key Findings from 14 Iterations
-
-| Iteration | What We Tried | Result |
-|-----------|---------------|--------|
-| 1–6 | Verbose "Banned Behaviors" blocks, negative constraints | ❌ Model hallucinated tools were unavailable |
-| 7–9 | `always_on` trigger rules, multi-file configs | ❌ Redundant configs caused race conditions |
-| 10–11 | Emergency-style `🚨 MANDATORY` headers | ⚠️ Inconsistent — worked sometimes |
-| 12–13 | Positive-only framing, progressively shorter | ⚠️ Better but still intermittent |
-| 14 | **2-line "First Action" directive** | ✅ Reliable across sessions |
+</details>
 
-### Platform Gotchas
+<details id="antigravity-auto-load">
+<summary><strong>Gemini / Antigravity — Prompt Auto-Load</strong></summary>
 
-- **`replace_file_content` silently fails** on `~/.gemini/GEMINI.md` in some environments — use `write_to_file` with overwrite instead
-- **Multiple GEMINI.md locations** can conflict: global (`~/.gemini/`), workspace, and User Rules in the Antigravity UI. Keep them synchronized
-- **Camoufox/browser tools** called at startup spawn visible black windows — never call browser tools during greeting handlers
+See the [Gemini Setup Guide](docs/SETUP_GEMINI.md) for the proven three-layer prompt architecture to ensure reliable session auto-loading.
 
 </details>
 
@@ -383,7 +252,7 @@ To sync memory across machines or teams:
       "env": {
         "PRISM_STORAGE": "supabase",
         "SUPABASE_URL": "https://your-project.supabase.co",
-        "SUPABASE_KEY": "your-supabase-anon-key"
+        "SUPABASE_KEY": "your-supabase-anon-or-service-key"
       }
     }
   }
@@ -392,6 +261,8 @@ To sync memory across machines or teams:
 
 See the **Supabase Setup** section below for schema migration instructions.
 
+> **Anon key vs. service role key:** The anon key works for personal use (Supabase RLS policies apply). Use the service role key for team deployments where multiple users share the same Supabase project — it bypasses RLS and allows Prism to manage all rows regardless of auth context. Never expose the service role key client-side.
+
 </details>
 
 <details>
@@ -421,35 +292,201 @@ Then add to your MCP config:
 
 </details>
 
+### Common Installation Pitfalls
+
+> **❌ Don't use `npm install -g`:**
+> Hardcoding the binary path (e.g. `/opt/homebrew/Cellar/node/23.x/bin/prism-mcp-server`) is tied to a specific Node.js version — when Node updates, the path silently breaks.
+>
+> **✅ Always use `npx` instead:**
+> ```json
+> {
+>   "mcpServers": {
+>     "prism-mcp": {
+>       "command": "npx",
+>       "args": ["-y", "prism-mcp-server"]
+>     }
+>   }
+> }
+> ```
+> `npx` resolves the correct binary automatically, always fetches the latest version, and works identically on macOS, Linux, and Windows. Already installed globally? Run `npm uninstall -g prism-mcp-server` first.
+
+> **❓ Seeing warnings about missing API keys on startup?**
+> That's expected and not an error. `BRAVE_API_KEY` / `GOOGLE_API_KEY` warnings are informational only — core session memory works with zero keys. See [Environment Variables](#environment-variables) for what each key unlocks.
+
 ---
 
-## How Prism Compares
-
-**Prism MCP** vs [MCP Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) · [Mem0](https://github.com/mem0ai/mem0) · [Mnemory](https://github.com/fpytloun/mnemory) · [Basic Memory](https://github.com/basicmachines-co/basic-memory)
-
-**Only Prism has all of these:**
-- ✅ Zero config — one `npx` command, no Qdrant/Postgres containers
-- ✅ Time Travel — versioned snapshots with `memory_checkout`
-- ✅ Behavioral memory — importance tracking, auto-decay, mistake learning
-- ✅ Visual dashboard — Mind Palace at localhost:3000
-- ✅ Multi-agent sync — role-isolated Hivemind with real-time Telepathy
-- ✅ Visual memory — VLM-captioned screenshot vault
-- ✅ Token budgeting — `max_tokens` param on context loading
-- ✅ 10× vector compression — TurboQuant, no external vector DB
-- ✅ GDPR compliance — soft/hard delete, ZIP export, TTL retention
-- ✅ OpenTelemetry — full span tracing to Jaeger/Grafana
-- ✅ LangChain adapters — `BaseRetriever` integration + LangGraph examples
-- ✅ Morning Briefings — AI-synthesized action plans after breaks
-- ✅ Auto-compaction — Gemini-powered rollups to prevent unbounded growth
-- ✅ IDE rules sync — graduated insights → `.cursorrules` / `.clauderules`
-- ✅ Air-gapped mode — SQLite + Ollama, zero internet needed
-
-> **TL;DR:** Prism is the only MCP memory server with time travel, behavioral learning, visual memory, multi-agent sync, and 10× compression — all from a single `npx` command.
+## ✨ What Makes Prism Different
+
+
+### 🧠 Your Agent Learns From Mistakes
+When you correct your agent, Prism tracks it. Corrections accumulate **importance** over time. High-importance lessons auto-surface as warnings in future sessions — and can even sync to your `.cursorrules` file for permanent enforcement. Your agent literally gets smarter the more you use it.
+
+### 🕰️ Time Travel
+Every save creates a versioned snapshot. Made a mistake? `memory_checkout` reverts your agent's memory to any previous state — like `git revert` for your agent's brain. Full version history with optimistic concurrency control.
+
+### 🔮 Mind Palace Dashboard
+A gorgeous glassmorphism UI at `localhost:3000` that lets you see exactly what your agent is thinking:
+
+- **Current State & TODOs** — the exact context injected into the LLM's prompt
+- **Interactive Knowledge Graph** — force-directed neural graph with click-to-filter, node renaming, and surgical keyword deletion
+- **Deep Storage Manager** — preview and execute vector purge operations with dry-run safety
+- **Session Ledger** — full audit trail of every decision your agent has made
+- **Time Travel Timeline** — browse and revert any historical handoff version
+- **Visual Memory Vault** — browse VLM-captioned screenshots and auto-captured HTML states
+- **Hivemind Radar** — real-time active agent roster with role, task, and heartbeat
+- **Morning Briefing** — AI-synthesized action plan after 4+ hours away
+- **Brain Health** — memory integrity scan with one-click auto-repair
+
+![Mind Palace Dashboard](docs/mind-palace-dashboard.png)
+
+### 🧬 10× Memory Compression
+Powered by a pure TypeScript port of Google's TurboQuant (inspired by Google's ICLR research), Prism compresses 768-dim embeddings from **3,072 bytes → ~400 bytes** — enabling decades of session history on a standard laptop. No native modules. No vector database required.
+
+### 🐝 Multi-Agent Hivemind
+Multiple agents (dev, QA, PM) can work on the same project with **role-isolated memory**. Agents discover each other automatically, share context in real-time via Telepathy sync, and see a team roster during context loading.
+
+### 🖼️ Visual Memory
+Save UI screenshots, architecture diagrams, and bug states to a searchable vault. Images are auto-captioned by a VLM (Claude Vision / GPT-4V / Gemini) and become semantically searchable across sessions.
+
+### 🔭 Full Observability
+OpenTelemetry spans for every MCP tool call, LLM hop, and background worker. Route to Jaeger, Grafana, or any OTLP collector. Configure in the dashboard — zero code changes.
+
+### 🌐 Autonomous Web Scholar
+Prism researches while you sleep. A background pipeline searches the web, scrapes articles, synthesizes findings via LLM, and injects results directly into your semantic memory — fully searchable on your next session. Brave Search → Firecrawl scrape → LLM synthesis → Prism ledger. Task-aware, Hivemind-integrated, and zero-config when API keys are missing (falls back to Yahoo + Readability).
+
+### 🔒 GDPR Compliant
+Soft/hard delete (Art. 17), full export in JSON, Markdown, or Obsidian vault `.zip` (Art. 20), API key redaction, per-project TTL retention, and audit trail. Enterprise-ready out of the box.
+
+---
+
+## 🎯 Use Cases
+
+**Long-running feature work** — Save state at end of day, restore full context next morning. No re-explaining.
+
+**Multi-agent collaboration** — Dev, QA, and PM agents share real-time context without stepping on each other's memory.
+
+**Consulting / multi-project** — Switch between client projects with progressive loading: `quick` (~50 tokens), `standard` (~200), or `deep` (~1000+).
+
+**Visual debugging** — Save UI screenshots to searchable memory. Find that CSS bug from last week by description.
+
+**Team onboarding** — New team member's agent loads the full project history instantly.
+
+**Behavior enforcement** — Agent corrections auto-graduate into permanent `.cursorrules` / `.clauderules` rules.
+
+**Offline / air-gapped** — Full SQLite local mode + Ollama LLM adapter. Zero internet dependency.
+
+**Morning Briefings** — After 4+ hours away, Prism auto-synthesizes a 3-bullet action plan from your last sessions.
+
+---
+
+## 🆕 What's New
+
+### v6.1 — Prism-Port, Cognitive Load & Semantic Search ✅
+> **Current stable release (v6.1.8).** Data sovereignty meets active memory intelligence.
+
+- 📦 **Prism-Port Vault Export** — New `vault` format for `session_export_memory`. Generates a `.zip` of interlinked Markdown files with YAML frontmatter, `[[Wikilinks]]`, and auto-generated `Keywords/` backlink indices. Drop into Obsidian or Logseq for instant knowledge graph.
+- 🏛️ **Dashboard Export Vault Button** — "🏛️ Export Vault" button in the Mind Palace UI exports the full Prism-Port vault ZIP directly from the browser. Both `/api/export` and `/api/export/vault` now use the unified `buildVaultDirectory` path — same rich format as the MCP tool.
+- 🏥 **Dashboard Health Cleanup** — The "Fix Issues" button now repairs missing embeddings directly from the Mind Palace UI.
+- 🧠 **Smart Memory Merge UI** — Dynamically merge duplicate knowledge nodes right from the Graph Editor. "Knowledge Gardening" made effortless.
+- ✨ **Semantic Search Highlighting** — Native RegEx mapping that visually wraps the exact reason a vector result was retrieved during a search.
+- 📊 **Deep Purge Visualization** — A zero-overhead "Memory Density" analytic providing instant signal-to-noise ratio visibility (Graduated ideas vs raw concepts).
+- 🛡️ **Context-Boosted Search** — Biases semantic queries by intelligently interleaving your current project workspace.
+
+#### v6.1.8 — Type Guard Hardening (Production Safety)
+- 🛡️ **Missing Guard Added** — `isSessionCompactLedgerArgs` was absent; an LLM passing `{threshold: "many"}` would reach the handler as a string. Added full validation for all four optional fields.
+- ✅ **Array Field Validation** — `isSessionSaveLedgerArgs` now guards `todos`, `files_changed`, and `decisions` with `Array.isArray` checks — prevents a hallucinated `{todos: "string"}` from bypassing the type system.
+- 🔖 **Enum Literal Guard** — `isSessionExportMemoryArgs` now rejects any `format` value outside `'json' | 'markdown' | 'vault'` at the boundary instead of propagating to the handler.
+- 🔢 **Numeric Field Guards** — `isSessionIntuitiveRecallArgs` now validates `limit` and `threshold` as numbers, blocking string coercion (`{limit: "many"}`).
+- 🧹 **Legacy Guard Migration** — `isMemoryHistoryArgs`, `isMemoryCheckoutArgs`, and `isSessionSaveImageArgs` migrated to the consistent `Record<string, unknown>` pattern; `isMemoryHistoryArgs` also gains a previously missing `limit` number check.
+
+#### v6.1.7 — Dashboard Toggle Persistence
+- 🔄 **Rollback on Save Failure** — `saveSetting()` now returns `Promise<boolean>`; UI toggles (Hivemind, Auto-Capture) roll back their optimistic state if the server request fails.
+- 🚫 **Cache-Busting** — `loadSettings()` appends `?t=<timestamp>` to bypass stale browser/service-worker caches.
+- 🔔 **HTTP Error Detection** — Explicit 4xx/5xx catching in `saveSetting()` surfaces failed saves as user-visible toast notifications.
+
+#### v6.1.6 — Type Guard Audit (Round 1)
+- 🛡️ **11 Type Guards Hardened** — Audited and refactored all MCP tool argument guards to include explicit `typeof` validation for optional fields, preventing LLM-hallucinated payloads from causing runtime type coercion errors.
+
+#### v6.1.5 — SQLite Deep Storage TTL
+- 🧪 **Comprehensive Edge-Case Test Suite** — 425 tests across 20 files covering CRDT merges, TurboQuant mathematical invariants, prototype pollution guards, and SQLite retention TTL boundary conditions.
+- 🔒 **Prototype Pollution Guards** — CRDT merge pipeline hardened against `__proto__` / `constructor` injection via `Object.create(null)` scratchpads.
+- 🗜️ **`maintenance_vacuum` Tool** — New tool to reclaim SQLite disk space after large purge operations.
+
+#### v6.1.4 — Production Hardening
+- 🔒 **Embedding Binary Strip** — Both `embedding` (raw float32) and `embedding_compressed` (TurboQuant binary blob) are now stripped from all export formats, preventing ~400 bytes of raw binary per entry from appearing in vault/JSON exports.
+- 🔗 **Vault Wikilink Fix** — Keyword backlink paths now use vault-relative `Ledger/filename.md` instead of `../Ledger/filename.md` — ensuring correct internal link resolution in Obsidian and Logseq.
+- 🖼️ **Visual Memory Key Fix** — Export correctly reads `filename` and `timestamp` (the keys written by `session_save_image`), resolving a mismatch that produced `"Unknown"` values in the vault visual memory index.
+- 🛡️ **OOM Guard on Large Exports** — `getLedgerEntries` in the export handler now has a 10,000-entry ceiling with explicit `ORDER BY created_at ASC`, preventing unbounded heap allocation on high-volume projects.
+- ⚡ **O(1) Filename Dedup** — Vault filename collision resolution upgraded from O(n²) loop to O(1) `Map<string, number>` counter. Important for projects with many same-day sessions.
+- 🔧 **TurboQuant Guard** — `bits` parameter now validated to `[2, 6]` range at construction time, preventing accidental multi-second Lloyd-Max initialization at higher bit depths.
+
+![Prism v6 Features](docs/v6_cognitive_load_dashboard.png)
+
+<details>
+<summary><strong>Earlier releases (v5.x and below)</strong></summary>
+
+#### v5.5 — Architectural Hardening
+- 🛡️ **Transactional Migrations** — SQLite DDL rebuilds are wrapped in explicit `BEGIN/COMMIT` blocks.
+- 🛑 **Graceful Shutdown Registry** — `BackgroundTaskRegistry` uses a 5-second `Promise.race()` to await flushes.
+- 🕰️ **Thundering Herd Prevention** — Maintenance scheduler migrated from `setInterval` to state-aware `setTimeout`.
+- 🚀 **Zero-Thrashing SDM Scans** — `Int32Array` scratchpad allocations hoisted outside the hot decode loop.
+
+#### v5.4 — Convergent Intelligence
+- 🔄 **CRDT Handoff Merging** — Multi-agent saves no longer reject on version conflict. Custom OR-Map engine auto-merges concurrent edits.
+- ⏰ **Background Purge Scheduler** — Fully automated storage maintenance TTL sweep, Ebbinghaus decay, auto-compaction.
+- 🌐 **Autonomous Web Scholar** — Agent-driven research pipeline. Brave Search → Firecrawl scrape → LLM synthesis.
+- **v5.3** — Hivemind Health Watchdog (state machine, loop detection, Telepathy alert injection)
+- **v5.2** — Cognitive Memory (Ebbinghaus decay, context-weighted retrieval), Universal History Migration, Smart Consolidation
+- **v5.1** — Knowledge Graph Editor, Deep Storage purge
+- **v5.0** — TurboQuant 10× embedding compression, three-tier search architecture
+- **v4.x** — OpenTelemetry, VLM multimodal memory, LLM adapters, Behavioral memory, Hivemind
+
+</details>
+
+> [Full CHANGELOG →](CHANGELOG.md) · [Architecture Deep Dive →](docs/ARCHITECTURE.md)
+
+---
+
+## 🆚 How Prism Compares
+
+| Capability | **Prism MCP** | [MCP Memory](https://github.com/modelcontextprotocol/servers/tree/main/src/memory) | [Mem0](https://github.com/mem0ai/mem0) | [Mnemory](https://github.com/fpytloun/mnemory) | [Basic Memory](https://github.com/basicmachines-co/basic-memory) |
+|:-----------|:---:|:---:|:---:|:---:|:---:|
+| Zero-config (`npx` one-liner) | ✅ | ✅ | ❌ Docker | ✅ | ✅ |
+| Time travel (version revert) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Behavioral memory (mistake learning) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Visual dashboard | ✅ | ❌ | ✅ Web | ❌ | ❌ |
+| Multi-agent Hivemind | ✅ | ❌ | ❌ | ❌ | ❌ |
+| CRDT conflict-free merging | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Autonomous research (Web Scholar) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Visual memory (VLM screenshots) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| 10× vector compression | ✅ | ❌ | ❌ (Qdrant) | ❌ | ❌ |
+| Obsidian/Logseq vault export | ✅ | ❌ | ❌ | ❌ | ✅ |
+| Token budgeting | ✅ | ❌ | ❌ | ❌ | ❌ |
+| GDPR compliance (Art. 17 + 20) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| OpenTelemetry tracing | ✅ | ❌ | ❌ | ❌ | ❌ |
+| IDE rules sync (`.cursorrules`) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Air-gapped mode (Ollama) | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Morning Briefings | ✅ | ❌ | ❌ | ❌ | ❌ |
+| Auto-compaction | ✅ | ❌ | ❌ | ❌ | ❌ |
+
+> **TL;DR:** Prism is the only MCP memory server with time travel, behavioral learning, autonomous research, CRDT multi-agent sync, and 10× compression — all from a single `npx` command.
 
 ---
 
 ## 🔧 Tool Reference
 
+Prism ships 30+ tools, but **90% of your workflow uses just three:**
+
+> **🎯 The Big Three**
+>
+> | Tool | When | What it does |
+> |------|------|--------------|
+> | `session_load_context` | ▶️ Start of session | Loads your agent’s brain from last time |
+> | `session_save_ledger` | ⏹️ End of session | Records what was accomplished |
+> | `knowledge_search` | 🔍 Anytime | Finds past decisions, context, and learnings |
+>
+> *Everything else is a power-up. Start with these three and you’re 90% there.*
+
 <details>
 <summary><strong>Session Memory & Knowledge (12 tools)</strong></summary>
 
@@ -464,7 +501,7 @@ Then add to your MCP config:
 | `session_search_memory` | Vector similarity search across all sessions |
 | `session_compact_ledger` | Auto-compact old entries via Gemini summarization |
 | `session_forget_memory` | GDPR-compliant deletion (soft/hard + Art. 17 reason) |
-| `session_export_memory` | Full ZIP export (JSON + Markdown) for portability |
+| `session_export_memory` | Full export (JSON, Markdown, or Obsidian vault `.zip` with `[[Wikilinks]]`) |
 | `session_health_check` | Brain integrity scan + auto-repair (`fsck`) |
 | `deep_storage_purge` | Reclaim ~90% vector storage (v5.1) |
 
@@ -531,6 +568,7 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | Variable | Required | Description |
 |----------|----------|-------------|
 | `BRAVE_API_KEY` | No | Brave Search Pro API key |
+| `FIRECRAWL_API_KEY` | No | Firecrawl API key — required for Web Scholar |
 | `PRISM_STORAGE` | No | `"local"` (default) or `"supabase"` — restart required |
 | `PRISM_ENABLE_HIVEMIND` | No | `"true"` to enable multi-agent tools — restart required |
 | `PRISM_INSTANCE` | No | Instance name for multi-server PID isolation |
@@ -539,10 +577,16 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | `SUPABASE_URL` | If cloud | Supabase project URL |
 | `SUPABASE_KEY` | If cloud | Supabase anon/service key |
 | `PRISM_USER_ID` | No | Multi-tenant user isolation (default: `"default"`) |
-| `PRISM_AUTO_CAPTURE` | No | `"true"` to auto-snapshot dev servers |
+| `PRISM_AUTO_CAPTURE` | No | `"true"` to auto-snapshot dev server UI states (HTML/DOM) for visual memory |
 | `PRISM_CAPTURE_PORTS` | No | Comma-separated ports (default: `3000,3001,5173,8080`) |
 | `PRISM_DEBUG_LOGGING` | No | `"true"` for verbose logs |
 | `PRISM_DASHBOARD_PORT` | No | Dashboard port (default: `3000`) |
+| `PRISM_SCHEDULER_ENABLED` | No | `"false"` to disable background maintenance (default: enabled) |
+| `PRISM_SCHEDULER_INTERVAL_MS` | No | Maintenance interval in ms (default: `43200000` = 12h) |
+| `PRISM_SCHOLAR_ENABLED` | No | `"true"` to enable Web Scholar pipeline |
+| `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`) |
 
 </details>
 
@@ -550,183 +594,118 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 
 ## Architecture
 
-<details>
-<summary><strong>Three-Tier Memory Architecture</strong></summary>
+Prism is a **stdio-based MCP server** that manages persistent agent memory. Here's how the pieces fit together:
 
 ```
-searchMemory() flow:
-
-  Tier 0: FTS5 keywords     → Full-text search (knowledge_search)
-  Tier 1: float32 (3072B)   → sqlite-vec cosine similarity (native)
-  Tier 2: turbo4  (400B)    → JS asymmetricCosineSimilarity (fallback)
-
-  → Tier 1 success → return results
-  → Tier 1 fail    → Tier 2 success → return results
-                   → Tier 2 fail    → return []
+┌──────────────────────────────────────────────────────────┐
+│  MCP Client (Claude Desktop / Cursor / Antigravity)      │
+│                    ↕ stdio (JSON-RPC)                    │
+├──────────────────────────────────────────────────────────┤
+│  Prism MCP Server                                        │
+│                                                          │
+│  ┌──────────────┐  ┌──────────────┐  ┌────────────────┐  │
+│  │  30+ Tools   │  │  Lifecycle   │  │   Dashboard    │  │
+│  │  (handlers)  │  │  (PID lock,  │  │  (HTTP :3000)  │  │
+│  │              │  │   shutdown)  │  │                │  │
+│  └──────┬───────┘  └──────────────┘  └────────────────┘  │
+│         ↕                                                │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │  Storage Engine                                    │  │
+│  │  Local: SQLite + FTS5 + TurboQuant vectors         │  │
+│  │  Cloud: Supabase + pgvector                        │  │
+│  └────────────────────────────────────────────────────┘  │
+│         ↕                                                │
+│  ┌────────────────────────────────────────────────────┐  │
+│  │  Background Workers                                │  │
+│  │  • Scheduler (TTL, decay, compaction, purge)       │  │
+│  │  • Web Scholar (Brave → Firecrawl → LLM → Ledger)  │  │
+│  │  • Hivemind heartbeats & Telepathy broadcasts      │  │
+│  │  • OpenTelemetry span export                       │  │
+│  └────────────────────────────────────────────────────┘  │
+└──────────────────────────────────────────────────────────┘
 ```
 
-Every `session_save_ledger` call generates both tiers automatically:
-1. Gemini generates float32 embedding (3,072 bytes)
-2. TurboQuant compresses to turbo4 blob (~400 bytes)
-3. Single atomic write stores both to the database
+### Startup Sequence
 
-| Metric | Before v5.0 | After v5.0 |
-|--------|------------|------------|
-| Storage per embedding | 3,072 bytes | ~400 bytes |
-| Compression ratio | 1:1 | ~7.7:1 (4-bit) |
-| Entries per GB | ~330K | ~2.5M |
+1. **Acquire PID lock** — prevents duplicate instances per `PRISM_INSTANCE`
+2. **Initialize config** — SQLite settings cache (`prism-config.db`)
+3. **Register 30+ MCP tools** — session, knowledge, search, behavioral, hivemind
+4. **Connect stdio transport** — MCP handshake with the client (~60ms total)
+5. **Async post-connect** — storage warmup, dashboard launch, scheduler start (non-blocking)
 
-</details>
+### Storage Layers
 
-<details>
-<summary><strong>Progressive Context Loading</strong></summary>
+| Layer | Technology | Purpose |
+|-------|-----------|---------|
+| **Session Ledger** | SQLite (append-only) | Immutable audit trail of all agent work |
+| **Handoff State** | SQLite (upsert, versioned) | Live project context with OCC + CRDT merging |
+| **Keyword Search** | FTS5 virtual tables | Zero-dependency full-text search |
+| **Semantic Search** | TurboQuant compressed vectors | 10× compressed 768-dim embeddings, three-tier retrieval |
+| **Cloud Sync** | Supabase + pgvector | Optional multi-device/team sync |
 
-| Level | What You Get | Size | When to Use |
-|-------|-------------|------|-------------|
-| **quick** | Open TODOs + keywords | ~50 tokens | Fast check-in |
-| **standard** | + summary + recent decisions + Git drift | ~200 tokens | **Recommended** |
-| **deep** | + full logs (last 5 sessions) + cross-project knowledge | ~1000+ tokens | After a long break |
+### Auto-Load Architecture
 
-</details>
-
-<details>
-<summary><strong>Role Resolution</strong></summary>
-
-Prism resolves agent roles using a priority chain:
-
-```
-explicit tool argument  →  dashboard setting  →  "global" (default)
-```
+Each MCP client has its own mechanism for ensuring Prism context loads on session start. See the platform-specific [Setup Guides](#-setup-guides) above for detailed instructions:
 
-Set your role once in the Mind Palace Dashboard (⚙️ Settings → Agent Identity) and it auto-applies to every session.
+- **Claude Code** — Lifecycle hooks (`SessionStart` / `Stop`)
+- **Gemini / Antigravity** — Three-layer architecture (User Rules + AGENTS.md + Startup Skill)
+- **Cursor / Windsurf / VS Code** — System prompt instructions
 
-Available roles: `dev`, `qa`, `pm`, `lead`, `security`, `ux`, `global`, or any custom string.
-
-</details>
-
-<details>
-<summary><strong>Project Structure</strong></summary>
-
-```
-src/
-├── server.ts                  # MCP server core + tool routing
-├── config.ts                  # Environment management
-├── storage/
-│   ├── interface.ts           # StorageBackend abstraction
-│   ├── sqlite.ts              # SQLite local (libSQL + F32_BLOB)
-│   ├── supabase.ts            # Supabase cloud storage
-│   └── configStorage.ts       # Boot config micro-DB
-├── dashboard/
-│   ├── server.ts              # Dashboard HTTP server
-│   └── ui.ts                  # Mind Palace glassmorphism UI
-├── tools/
-│   ├── definitions.ts         # Search & analysis schemas
-│   ├── handlers.ts            # Search & analysis handlers
-│   ├── sessionMemoryDefinitions.ts
-│   └── sessionMemoryHandlers.ts
-└── utils/
-    ├── telemetry.ts           # OTel singleton
-    ├── turboquant.ts          # TurboQuant math core
-    ├── universalImporter.ts   # Universal migration orchestrator
-    ├── migration/             # Format-specific adapters (Claude/Gemini/OpenAI)
-    ├── imageCaptioner.ts      # VLM auto-caption pipeline
-    └── llm/adapters/          # Gemini, OpenAI, Anthropic, Ollama
-```
-
-</details>
-
-<details>
-<summary><strong>Supabase Setup</strong></summary>
-
-1. Create a Supabase project at [supabase.com](https://supabase.com)
-2. Run the migration SQL files from `supabase/migrations/` in order
-3. Set `PRISM_STORAGE=supabase`, `SUPABASE_URL`, and `SUPABASE_KEY` in your MCP config
-4. Prism auto-applies pending DDL migrations on startup via `prism_apply_ddl` RPC
-
-</details>
-
-<details>
-<summary><strong>LangChain / LangGraph Integration</strong></summary>
-
-Prism includes Python adapters in `examples/langgraph-agent/`:
-
-```python
-from langchain.retrievers import EnsembleRetriever
-from prism_retriever import PrismMemoryRetriever, PrismKnowledgeRetriever
-
-# Hybrid search: 70% semantic, 30% keyword
-retriever = EnsembleRetriever(
-    retrievers=[PrismMemoryRetriever(...), PrismKnowledgeRetriever(...)],
-    weights=[0.7, 0.3],
-)
-```
-
-Includes a full 5-node LangGraph research agent with MCP bridge and persistent memory.
-
-</details>
+All platforms benefit from the **server-side fallback** (v5.2.1): if `session_load_context` hasn't been called within 10 seconds, Prism auto-pushes context via `sendLoggingMessage`.
 
 ---
 
-## Research Roadmap
+## 🧬 Scientific Foundation
 
 Prism is evolving from smart session logging toward a **cognitive memory architecture** — grounded in real research, not marketing.
 
 | Phase | Feature | Inspired By | Status |
 |-------|---------|-------------|--------|
+| **v5.0** | TurboQuant 10× Compression — 4-bit quantized 768-dim vectors in <500 bytes | Vector quantization (product/residual PQ) | ✅ Shipped |
+| **v5.0** | Three-Tier Search — native → TurboQuant → FTS5 keyword fallback | Cascaded retrieval architectures | ✅ Shipped |
 | **v5.2** | Smart Consolidation — extract principles, not just summaries | Neuroscience sleep consolidation | ✅ Shipped |
 | **v5.2** | Ebbinghaus Importance Decay — memories fade unless reinforced | Ebbinghaus forgetting curve | ✅ Shipped |
 | **v5.2** | Context-Weighted Retrieval — current work biases what surfaces | Contextual memory in cognitive science | ✅ Shipped |
-| **v6.x** | Superposed Memory (SDM) — O(1) retrieval via correlation | Kanerva's Sparse Distributed Memory (1988) | 🔬 Research |
-| **v6.x** | Affect-Tagged Memory — sentiment shapes what gets recalled | Affect-modulated retrieval (neuroscience) | 🔬 Research |
-| **v7+** | Zero-Search Retrieval — no index, no ANN, just ask the vector | Holographic Reduced Representations | 🔭 Horizon |
-
-> Informed by LeCun's "Why AI Systems Don't Learn" (Dupoux, LeCun, Malik — March 2026) and Kanerva's SDM.
-
----
-
-## Version History
-
-<details>
-<summary><strong>Previous releases (v3.0 — v5.0)</strong></summary>
-
-- **v5.1** — Knowledge Graph Editor, Deep Storage purge
-- **v5.0** — TurboQuant 10× embedding compression, three-tier search architecture
-- **v4.6** — OpenTelemetry distributed tracing (Jaeger, Grafana)
-- **v4.5** — VLM multimodal memory + GDPR Art. 20 ZIP export
-- **v4.4** — Pluggable LLM adapters (OpenAI, Anthropic, Gemini, Ollama)
-- **v4.3** — Knowledge Sync Rules (behavioral insights → IDE rules)
-- **v4.2** — Project repo registry + universal auto-load
-- **v4.1** — Auto-migration + multi-instance support
-- **v4.0** — Behavioral memory (corrections, importance, auto-decay)
-- **v3.1** — Memory lifecycle (TTL, auto-compaction, PKM export)
-- **v3.0** — Agent Hivemind (role-scoped memory, Telepathy sync)
-
-See [CHANGELOG.md](CHANGELOG.md) for full details.
-
-</details>
+| **v5.4** | CRDT Handoff Merging — conflict-free multi-agent state via OR-Map engine | CRDTs (Shapiro et al., 2011) | ✅ Shipped |
+| **v5.4** | Autonomous Web Scholar — background research pipeline with LLM synthesis | Autonomous research agents | ✅ Shipped |
+| **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.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 and visual decay | Implicit associative memory | 🔬 In Progress |
+| **v7.x** | Affect-Tagged Memory — sentiment shapes what gets recalled | Affect-modulated retrieval (neuroscience) | 🔭 Horizon |
+| **v8+** | Zero-Search Retrieval — no index, no ANN, just ask the vector | Holographic Reduced Representations | 🔭 Horizon |
+
+> Informed by LeCun's "Why AI Systems Don't Learn" (Dupoux, LeCun, Malik) and Kanerva's SDM.
 
 ---
 
-## 🚀 Roadmap
+## 📦 Product Roadmap
 
 > **[Full ROADMAP.md →](ROADMAP.md)**
 
-**Next (v5.3):**
-- 🔄 CRDT Handoff Merging — conflict-free concurrent multi-agent edits
-- ⏰ Background Purge Scheduler — automated storage reclamation
-- 📱 Mind Palace Mobile PWA — offline-first responsive dashboard
-- 🌐 Autonomous Web Scholar — agent-driven research pipeline
+### v6.2: The "Synthesize & Prune" Phase
+The v6.1 series (through v6.1.8) shipped Prism-Port vault export, Intuitive Recall, full type guard hardening, and dashboard toggle persistence. The v6.2 phase aims to turn collected data into proactive intelligence, moving the dashboard from a passive storage viewer into an active, self-organizing Mind Palace.
+
+1. 🕸️ **Automated Edge Synthesis (The "Dream" Procedure):** A background routine that runs on the graph payload to find semantically similar but disconnected nodes via Cosine Similarity. It highlights potential ghostly edges in the UI, empowering the system to autonomously suggest new mental models instead of waiting for the user to connect the dots manually.
+2. 🗓️ **Temporal Decay Heatmaps (Visualizing the Ebbinghaus Curve):** A UI overlay toggle where un-accessed nodes dynamically desaturate or physically "fade" while Graduated nodes (Score >= 7) stay vibrant longer. This makes the "Deep Purge" decision-making visceral: if the graph looks gray, trigger a learning session or a cleanup.
+3. 📝 **Active Recall Prompt Generation (Knowledge Activation):** A "Test Me" utility in the `nodeEditorPanel`. Using a node's semantic neighbors, the dashboard generates synthetic quizzes to ensure context retention, pushing the product away from pure "storage" into genuine "active learning" capabilities.
 
 ---
 
-## ⚠️ Limitations
+## Limitations
 
 - **LLM-dependent features require an API key.** Semantic search, Morning Briefings, auto-compaction, and VLM captioning need a `GOOGLE_API_KEY` (Gemini) or equivalent provider key. Without one, Prism falls back to keyword-only search (FTS5).
-- **Auto-load is model-dependent.** Session auto-loading relies on the LLM following system prompt instructions. Some models (especially Gemini) intermittently hallucinate that MCP tools are "unavailable." See the [Gemini/Antigravity setup guide](#gemini--antigravity--auto-load-rules-battle-tested) for workarounds.
+- **Auto-load is model- and client-dependent.** Session auto-loading relies on both the LLM following system prompt instructions *and* the MCP client completing tool registration before the model's first turn. Prism provides platform-specific [Setup Guides](#-setup-guides) and a server-side fallback (v5.2.1) that auto-pushes context after 10 seconds.
+- **MCP client race conditions.** Some MCP clients may not finish tool enumeration before the model generates its first response, causing transient `unknown_tool` errors. This is a client-side timing issue — Prism's server completes the MCP handshake in ~60ms. Workaround: the server-side auto-push fallback and the startup skill's retry logic.
 - **No real-time sync without Supabase.** Local SQLite mode is single-machine only. Multi-device or team sync requires a Supabase backend.
-- **Embedding quality varies by provider.** Gemini `text-embedding-004` and OpenAI `text-embedding-3-small` produce high-quality 768-dim vectors. Ollama embeddings (e.g., `nomic-embed-text`) are usable but may reduce retrieval accuracy.
+- **Embedding quality varies by provider.** Gemini `text-embedding-004` and OpenAI `text-embedding-3-small` produce high-quality 768-dim vectors. Prism passes `dimensions: 768` via the Matryoshka API for OpenAI models (native output is 1536-dim; this truncation is lossless and outperforms ada-002 at full 1536 dims). Ollama embeddings (e.g., `nomic-embed-text`) are usable but may reduce retrieval accuracy.
 - **Dashboard is HTTP-only.** The Mind Palace dashboard at `localhost:3000` does not support HTTPS. For remote access, use a reverse proxy (nginx/Caddy) or SSH tunnel. Basic auth is available via `PRISM_DASHBOARD_USER` / `PRISM_DASHBOARD_PASS`.
-- **Migration is one-way.** Universal History Migration imports sessions *into* Prism but does not export back to Claude/Gemini/OpenAI formats. Use `session_export_memory` for portable JSON/Markdown export.
+- **Long-lived clients can accumulate zombie processes.** MCP clients that run for extended periods (e.g., Claude CLI) may leave orphaned Prism server processes. The lifecycle manager detects true orphans (PPID=1) but allows coexistence for active parent processes. Use `PRISM_INSTANCE` to isolate instances across clients.
+- **Migration is one-way.** Universal History Migration imports sessions *into* Prism but does not export back to Claude/Gemini/OpenAI formats. Use `session_export_memory` for portable JSON/Markdown export, or the `vault` format for Obsidian/Logseq-compatible `.zip` archives.
+- **Export ceiling at 10,000 ledger entries.** The `session_export_memory` tool and the dashboard export button cap vault/JSON exports at 10,000 entries per project as an OOM guard. Projects exceeding this limit should use per-project exports and time-based filtering to stay within the ceiling. This limit does not affect search or context loading.
 - **No Windows CI testing.** Prism is developed and tested on macOS/Linux. It should work on Windows via Node.js, but edge cases (file paths, PID locks) may surface.
 
 ---