prism-mcp-server 5.2.1 → 5.5.0

package/README.md

@@ -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)
+- [Setup Guides](#-setup-guides)
+- [What Makes Prism Different](#-what-makes-prism-different)
+- [Use Cases](#-use-cases)
+- [What's New](#-whats-new)
+- [Autonomous Web Scholar](#-autonomous-web-scholar)
+- [How Prism Compares](#how-prism-compares)
+- [Tool Reference](#-tool-reference)
+- [Environment Variables](#environment-variables)
+- [Architecture](#architecture)
+- [Research Roadmap](#research-roadmap)
+- [Roadmap](#-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
@@ -118,7 +63,7 @@ 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`.
 
-> **Optional API keys:** `GOOGLE_API_KEY` for semantic search + Morning Briefings, `BRAVE_API_KEY` for web search. See [Environment Variables](#environment-variables).
+> 🔑 **API Key Requirements:** Need semantic search, Morning Briefings, or auto-compaction? Provide a `GOOGLE_API_KEY` (Gemini) or equivalent. Want Web Scholar to search the live internet? Provide a `BRAVE_API_KEY`. Without keys, Prism still works but falls back to local keyword search (FTS5). See [Environment Variables](#environment-variables).
 
 ---
 
@@ -200,10 +145,12 @@ 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
 * **Claude Code** (`.jsonl` logs) — Automatically handles streaming chunk deduplication and `requestId` normalization.
@@ -211,7 +158,8 @@ Prism can ingest months of historical sessions from other tools to give your Min
 * **OpenAI** (JSON chat completion history) — Normalizes disparate tool-call structures into the unified Ledger schema.
 
 ### How to Run
-Use the `universal-import` command:
+
+**Option 1 — CLI:**
 
 ```bash
 # Ingest Claude Code history
@@ -221,8 +169,11 @@ 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
 ```
 
+**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.
 
@@ -304,43 +255,76 @@ if __name__ == "__main__":
 
 </details>
 
-<details>
-<summary><strong>Gemini / Antigravity — Auto-Load Rules (Battle-Tested)</strong></summary>
+<details id="antigravity-auto-load">
+<summary><strong>Gemini / Antigravity — Three-Layer Auto-Load (Battle-Tested ✅)</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.
+Gemini-based agents (including Google's Antigravity IDE) use a **three-layer architecture** for reliable auto-load, proven over **14+ iterations** of prompt engineering (March 2026).
 
-### The Core Problem
+### Architecture
 
-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.
+| Layer | File | Purpose |
+|-------|------|---------|
+| **1. User Rules** | `~/.gemini/GEMINI.md` | Slim ~10-line directive injected verbatim into system prompt |
+| **2. Cross-Tool Rules** | `~/.gemini/AGENTS.md` | Reinforcement for multi-client setups (Antigravity + Cursor) |
+| **3. Skill** | `.agent/skills/prism-startup/SKILL.md` | Full startup procedure with greeting detection and context echo |
+| **Server Fallback** | Built into `server.ts` (v5.2.1) | Deferred auto-push via `sendLoggingMessage` if model doesn't comply within 10s |
 
-### The 2-Line Rule (Proven Fix)
+### Layer 1: User Rules
 
 Create `~/.gemini/GEMINI.md`:
 
 ```markdown
-## First Action
-Call `mcp_prism-mcp_session_load_context(project="my-project", level="deep")` before responding.
-```
+# Startup — MANDATORY
 
-**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
+Your first action in every conversation is a tool call. Zero text before it.
 
-### Antigravity UI Caveat
+Tool: mcp_prism-mcp_session_load_context
+Args: project="my-project", level="deep"
+
+After success: echo agent identity, last summary, open TODOs, session version.
+If the call fails: say "Prism load failed — retrying" and try ONE more time.
+```
+
+### Layer 2: Cross-Tool Reinforcement
 
-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:
+Create `~/.gemini/AGENTS.md`:
 
 ```markdown
-## Echo Context
-After loading context, include in your text reply:
-- Agent identity (role + name)
-- Last session summary
-- Open TODOs
-- Session version number
+# Session Memory
+Every conversation starts with: mcp_prism-mcp_session_load_context(project="my-project", level="deep")
+Echo result: agent identity, TODOs, session version.
 ```
 
-This ensures the user sees their project context even though the raw MCP output is invisible.
+### Layer 3: Prism Startup Skill
+
+Create `.agent/skills/prism-startup/SKILL.md` (or `.agents/skills/`) in your project or global config. This is a structured skill file that Antigravity loads with higher priority than plain rules. It includes:
+
+- Greeting detection (fires on "hi", "hello", etc.)
+- Full tool call instructions with error handling
+- Context echo template (agent identity, TODOs, version)
+- Startup block display
+
+### Server-Side Fallback (v5.2.1)
+
+If the model ignores all three layers, Prism's server pushes context automatically:
+
+1. After storage warmup, a 10-second timer starts
+2. If `session_load_context` hasn't been called by then, the server pushes context via `sendLoggingMessage`
+3. If the client already called the tool, the push is silently skipped (zero impact on Claude CLI)
+
+This ensures context is always available, even with non-compliant models.
+
+### Why This Architecture Works
+
+- **Gemini uses single underscores** for MCP tools (`mcp_prism-mcp_...`) vs Claude's double underscores
+- **Slim rules** (~10 lines) avoid triggering adversarial "tool not found" reasoning
+- **Skills have dedicated 3-level loading** in Antigravity — higher compliance than plain rules
+- **Server fallback** catches the remaining edge cases without affecting well-behaved clients
+- **Positive "First Action" framing** outperforms negative constraint lists
+
+### 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. All three layers instruct the agent to **echo context in its text reply**.
 
 ### Session End Workflow
 
@@ -349,17 +333,7 @@ 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 |
+> **Tip:** Include session-end instructions in your `GEMINI.md` or ask the agent to save when you're done.
 
 ### Platform Gotchas
 
@@ -423,6 +397,101 @@ Then add to your MCP config:
 
 ---
 
+## ✨ 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.
+
+## 🌐 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. [Details below →](#-autonomous-web-scholar)
+
+### 🔒 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
+
+### v5.5 — Architectural Hardening ✅
+> **Current stable release.** Zero-dependency, production-grade reliability improvements.
+
+- 🛡️ **Transactional Migrations** — SQLite DDL rebuilds are wrapped in explicit `BEGIN/COMMIT` blocks. A crash mid-migration can no longer corrupt your schema or lose handoff state.
+- 🛑 **Graceful Shutdown Registry** — `BackgroundTaskRegistry` uses a 5-second `Promise.race()` to await all in-flight flushes (embeddings, SDM writes, OTel spans) before the process exits. No more orphaned I/O.
+- 🕰️ **Thundering Herd Prevention** — Maintenance scheduler migrated from `setInterval` to a state-aware recursive `setTimeout`. Expensive compaction routines can never stack on top of each other.
+- 🚀 **Zero-Thrashing SDM Scans** — `Int32Array` scratchpad allocations hoisted outside the hot decode loop. Eliminates V8 GC pressure on large semantic memory banks.
+- 🧪 **368 Tests** — Zero regressions across 17 test suites.
+
+### v5.4 — Convergent Intelligence
+- 🔄 **CRDT Handoff Merging** — Multi-agent saves no longer reject on version conflict. Custom OR-Map engine auto-merges concurrent edits (Add-Wins for arrays, LWW for scalars).
+- ⏰ **Background Purge Scheduler** — Fully automated storage maintenance: TTL sweep, Ebbinghaus importance decay, auto-compaction, and deep storage purge on a configurable interval.
+- 🌐 **[Autonomous Web Scholar](#-autonomous-web-scholar)** — Agent-driven research pipeline. Brave Search → Firecrawl scrape → LLM synthesis → Prism ledger. Task-aware and Hivemind-integrated.
+- 🐝 **Scholar ↔ Hivemind Integration** — Scholar registers on the Radar, emits heartbeats, and broadcasts Telepathy alerts on completion.
+
+<details>
+<summary><strong>Earlier releases (v5.3 and below)</strong></summary>
+
+- **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
 
 **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)
@@ -433,9 +502,12 @@ Then add to your MCP config:
 - ✅ 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
+- ✅ CRDT merging — conflict-free concurrent multi-agent edits
+- ✅ Autonomous research — Web Scholar pipeline runs while you sleep
 - ✅ Visual memory — VLM-captioned screenshot vault
 - ✅ Token budgeting — `max_tokens` param on context loading
 - ✅ 10× vector compression — TurboQuant, no external vector DB
+- ✅ Automated maintenance — background scheduler handles TTL, decay, compaction, purge
 - ✅ GDPR compliance — soft/hard delete, ZIP export, TTL retention
 - ✅ OpenTelemetry — full span tracing to Jaeger/Grafana
 - ✅ LangChain adapters — `BaseRetriever` integration + LangGraph examples
@@ -444,7 +516,7 @@ Then add to your MCP config:
 - ✅ 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.
+> **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.
 
 ---
 
@@ -531,6 +603,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 |
@@ -543,6 +616,12 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 | `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,118 +629,136 @@ Requires `PRISM_ENABLE_HIVEMIND=true`.
 
 ## Architecture
 
-<details>
-<summary><strong>Three-Tier Memory Architecture</strong></summary>
+| Layer | File | Purpose |
+|-------|------|---------|
+| **1. User Rules** | `~/.gemini/GEMINI.md` | Slim ~10-line directive injected verbatim into system prompt |
+| **2. Cross-Tool Rules** | `~/.gemini/AGENTS.md` | Reinforcement for multi-client setups (Antigravity + Cursor) |
+| **3. Skill** | `.agent/skills/prism-startup/SKILL.md` | Full startup procedure with greeting detection and context echo |
+| **Server Fallback** | Built into `server.ts` (v5.2.1) | Deferred auto-push via `sendLoggingMessage` if model doesn't comply within 10s |
+
+### Layer 1: User Rules
+
+Create `~/.gemini/GEMINI.md`:
+
+```markdown
+# Startup — MANDATORY
+
+Your first action in every conversation is a tool call. Zero text before it.
+
+Tool: mcp_prism-mcp_session_load_context
+Args: project="my-project", level="deep"
 
+After success: echo agent identity, last summary, open TODOs, session version.
+If the call fails: say "Prism load failed — retrying" and try ONE more time.
 ```
-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)
+### Layer 2: Cross-Tool Reinforcement
 
-  → Tier 1 success → return results
-  → Tier 1 fail    → Tier 2 success → return results
-                   → Tier 2 fail    → return []
+Create `~/.gemini/AGENTS.md`:
+
+```markdown
+# Session Memory
+Every conversation starts with: mcp_prism-mcp_session_load_context(project="my-project", level="deep")
+Echo result: agent identity, TODOs, session version.
 ```
 
-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
+### Layer 3: Prism Startup Skill
 
-| 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 |
+Create `.agent/skills/prism-startup/SKILL.md` (or `.agents/skills/`) in your project or global config. This is a structured skill file that Antigravity loads with higher priority than plain rules. It includes:
 
-</details>
+- Greeting detection (fires on "hi", "hello", etc.)
+- Full tool call instructions with error handling
+- Context echo template (agent identity, TODOs, version)
+- Startup block display
 
-<details>
-<summary><strong>Progressive Context Loading</strong></summary>
+### Server-Side Fallback (v5.2.1)
 
-| 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 |
+If the model ignores all three layers, Prism's server pushes context automatically:
 
-</details>
+1. After storage warmup, a 10-second timer starts
+2. If `session_load_context` hasn't been called by then, the server pushes context via `sendLoggingMessage`
+3. If the client already called the tool, the push is silently skipped (zero impact on Claude CLI)
 
-<details>
-<summary><strong>Role Resolution</strong></summary>
+This ensures context is always available, even with non-compliant models.
 
-Prism resolves agent roles using a priority chain:
+### Why This Architecture Works
 
-```
-explicit tool argument  →  dashboard setting  →  "global" (default)
-```
+- **Gemini uses single underscores** for MCP tools (`mcp_prism-mcp_...`) vs Claude's double underscores
+- **Slim rules** (~10 lines) avoid triggering adversarial "tool not found" reasoning
+- **Skills have dedicated 3-level loading** in Antigravity — higher compliance than plain rules
+- **Server fallback** catches the remaining edge cases without affecting well-behaved clients
+- **Positive "First Action" framing** outperforms negative constraint lists
 
-Set your role once in the Mind Palace Dashboard (⚙️ Settings → Agent Identity) and it auto-applies to every session.
+### Antigravity UI Caveat
 
-Available roles: `dev`, `qa`, `pm`, `lead`, `security`, `ux`, `global`, or any custom string.
+Antigravity **does not visually render MCP tool output blocks** in the chat UI. The tool executes successfully, but the user sees nothing. All three layers instruct the agent to **echo context in its text reply**.
 
-</details>
+### Session End Workflow
 
-<details>
-<summary><strong>Project Structure</strong></summary>
+Tell the agent: *"Wrap up the session."* It should execute:
 
-```
-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
-```
+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 session-end instructions in your `GEMINI.md` or ask the agent to save when you're done.
+
+### Platform Gotchas
+
+- **`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
 
 </details>
 
 <details>
-<summary><strong>Supabase Setup</strong></summary>
+<summary><strong>Supabase Cloud Sync</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
+To sync memory across machines or teams:
+
+```json
+{
+  "mcpServers": {
+    "prism-mcp": {
+      "command": "npx",
+      "args": ["-y", "prism-mcp-server"],
+      "env": {
+        "PRISM_STORAGE": "supabase",
+        "SUPABASE_URL": "https://your-project.supabase.co",
+        "SUPABASE_KEY": "your-supabase-anon-key"
+      }
+    }
+  }
+}
+```
+
+See the **Supabase Setup** section below for schema migration instructions.
 
 </details>
 
 <details>
-<summary><strong>LangChain / LangGraph Integration</strong></summary>
-
-Prism includes Python adapters in `examples/langgraph-agent/`:
+<summary><strong>Clone & Build (Full Control)</strong></summary>
 
-```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],
-)
+```bash
+git clone https://github.com/dcostenco/prism-mcp.git
+cd prism-mcp && npm install && npm run build
 ```
 
-Includes a full 5-node LangGraph research agent with MCP bridge and persistent memory.
+Then add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "prism-mcp": {
+      "command": "node",
+      "args": ["/path/to/prism-mcp/dist/server.js"],
+      "env": {
+        "BRAVE_API_KEY": "your-key",
+        "GOOGLE_API_KEY": "your-gemini-key"
+      }
+    }
+  }
+}
+```
 
 </details>
 
@@ -676,53 +773,34 @@ Prism is evolving from smart session logging toward a **cognitive memory archite
 | **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 |
+| **v5.5** | SDM Decoder Foundation — pre-allocated typed-array hot loop, zero GC thrash | Kanerva's Sparse Distributed Memory (1988) | ✅ Shipped |
+| **v5.6** | Full Superposed Memory (SDM) — O(1) key-value retrieval via Hamming correlation | Kanerva's SDM | 🔬 In Progress |
+| **v5.6** | Intuitive Recall — proactive surface of relevant past decisions without explicit search | Predictive memory (cognitive science) | 🔬 In Progress |
+| **v6.x** | Affect-Tagged Memory — sentiment shapes what gets recalled | Affect-modulated retrieval (neuroscience) | 🔭 Horizon |
 | **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>
-
----
-
-## 🚀 Roadmap
+## 📅 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
+**Shipped — v5.5:**
+- 🛡️ Transactional migrations, graceful shutdown registry, thundering herd prevention, SDM decoder GC optimization
+
+**Next — v5.6:**
+- 🧠 **Full Superposed Memory (SDM)** — O(1) semantic retrieval via Hamming correlation, no ANN index needed
+- 🔮 **Intuitive Recall** — proactive surfacing of relevant past context without explicit `session_search_memory` calls
+- 📊 **Radar 2.0** — richer Hivemind dashboard with agent task graphs and dependency visualization
 
 ---
 
 ## ⚠️ 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-dependent.** Session auto-loading relies on the LLM following system prompt instructions. Gemini/Antigravity uses a [three-layer architecture](#antigravity-auto-load) (User Rules + AGENTS.md + Startup Skill) with a v5.2.1 server-side fallback that auto-pushes context if the model doesn't comply within 10 seconds.
 - **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.
 - **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`.