prism-mcp-server 3.1.1 → 4.2.0

package/README.md

@@ -14,11 +14,14 @@
 
 ## Table of Contents
 
-- [What's New (v3.1.0)](#whats-new-in-v310---memory-lifecycle-)
+- [What's New (v4.2.0)](#whats-new-in-v420--project-repo-registry-)
+- [Multi-Instance Support](#multi-instance-support)
 - [How Prism Compares](#how-prism-compares)
 - [Quick Start](#quick-start-zero-config--local-mode)
 - [Mind Palace Dashboard](#-the-mind-palace-dashboard)
 - [Integration Examples](#integration-examples)
+- [Claude Code Integration (Hooks)](#claude-code-integration-hooks)
+- [Gemini / Antigravity Integration](#gemini--antigravity-integration)
 - [Use Cases](#use-cases)
 - [Architecture](#architecture)
 - [Tool Reference](#tool-reference)
@@ -39,25 +42,60 @@
 
 ---
 
-## What's New in v3.1.0 — Memory Lifecycle 🔄
+## What's New in v4.2.0 — Project Repo Registry 🗂️
 
 | Feature | Description |
 |---|---|
-| 📊 **Memory Analytics** | New **Memory Analytics** card in the dashboard — 14-day sparkline chart, active sessions count, rollup savings, and average context richness. Powered by `getAnalytics()` on both SQLite and Supabase backends. |
-| ⏳ **Automated Data Retention (TTL)** | Set a per-project data retention policy via `knowledge_set_retention` MCP tool or the dashboard **Lifecycle Controls** card. Entries older than the TTL are soft-deleted (GDPR-compliant `archived_at` tombstone) every 12 hours automatically. Rollups are never expired. Minimum 7 days to prevent accidental mass-delete. |
-| 🗜️ **Smart Auto-Compaction** | After every `session_save_ledger`, Prism runs a background health check and triggers compaction automatically if the brain is degraded or unhealthy — gated by `compaction_auto` setting and debounced per-project to prevent concurrent Gemini calls. **Compact Now** button also available in the dashboard. |
-| 📦 **PKM Export (Obsidian / Logseq)** | Export any project's full memory as a ZIP archive of Markdown files — one file per session with YAML-like frontmatter, TODOs, decisions, files-changed, and `#hashtag` keywords. Includes an `_index.md` with `[[wikilink]]` references. Click **Export ZIP** in the dashboard Lifecycle Controls card. |
-| 🧪 **Expanded Test Suite** | 37 new Vitest tests (95 total) — covers analytics queries, TTL soft-delete idempotency, rollup preservation, `activeCompactions` Set memory-leak prevention, type guards, export Markdown structure, and TTL sweep scheduler contracts. |
+| 🗂️ **Project Repo Paths** | Map each project to its repo directory in the dashboard. `session_save_ledger` validates `files_changed` paths and warns on mismatch — prevents cross-project contamination. |
+| 🔄 **Universal Auto-Load** | Auto-load projects via dynamic tool descriptions — works across all MCP clients (Claude, Cursor, Gemini, Antigravity) without lifecycle hooks. Dashboard is the sole source of truth. |
+| 🏠 **Dashboard-First Config** | Removed `PRISM_AUTOLOAD_PROJECTS` env var override. The Mind Palace dashboard is now the single source of truth for auto-load project configuration. |
+
+<details>
+<summary><strong>What's in v4.1.0 — Auto-Migration & Multi-Instance 🔀</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 🔄 **Auto-Migrations (Supabase)** | Zero-config schema upgrades — pending DDL migrations run automatically on server startup via `prism_apply_ddl` RPC. |
+| 🔀 **Multi-Instance Support** | `PRISM_INSTANCE` env var enables instance-aware PID locks — run multiple Prism servers side-by-side without conflicts. |
+| 🛡️ **Server Lifecycle Management** | Singleton PID lock with graceful shutdown and stale PID recovery. |
+
+</details>
+
+<details>
+<summary><strong>What's in v4.0.0 — Behavioral Memory 🧠</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 🧠 **Behavioral Memory** | `session_save_experience` — log actions, outcomes, corrections with confidence scores. Auto-injects warnings into context so agents learn from mistakes. |
+| 🎯 **Dynamic Roles** | Role auto-resolves from dashboard settings. Set once in Mind Palace, applies everywhere. |
+| 📏 **Token Budget** | `max_tokens` on `session_load_context` — intelligently truncates to fit your budget. |
+| 📉 **Importance Decay** | Stale corrections auto-fade over time to keep context fresh. |
+| 🔧 **Claude Code Hooks** | Simplified SessionStart/Stop hooks that reliably trigger MCP tool calls. |
+
+</details>
+
+<details>
+<summary><strong>What's in v3.1.0 — Memory Lifecycle 🔄</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 📊 **Memory Analytics** | Dashboard sparkline chart, session counts, rollup savings, context richness metrics. |
+| ⏳ **Data Retention (TTL)** | Per-project TTL via `knowledge_set_retention` or dashboard. Auto-expires old entries every 12h. |
+| 🗜️ **Auto-Compaction** | Background health check after saves — auto-compacts when brain is degraded. |
+| 📦 **PKM Export** | Export project memory as ZIP of Markdown files for Obsidian/Logseq. |
+| 🧪 **95 Tests** | Analytics, TTL, rollup, compaction, type guards, and export coverage. |
+
+</details>
 
 <details>
 <summary><strong>What's in v3.0.1 — Agent Identity & Brain Clean-up 🧹</strong></summary>
 
 | Feature | Description |
 |---|---|
-| 🧹 **Brain Health Clean-up** | New **Fix Issues** button in the Mind Palace Dashboard's Brain Health card — detects orphaned handoffs, missing embeddings, and stale rollups, then cleans them up in one click without needing the MCP tool. |
-| 👤 **Agent Identity Settings** | Dashboard Settings → Agent Identity panel lets you set a **Default Role** (`dev`, `qa`, `pm`…) and **Agent Name** (e.g. `Dmitri`). Both values auto-apply as fallbacks in all memory and Hivemind tools — no need to pass them per call. |
-| 📜 **Role-Scoped Skills** | Each agent role can have its own persistent skill/rules document stored in the dashboard (⚙️ Settings → Skills). It is automatically injected into every `session_load_context` response so the agent boots with its rules pre-loaded. |
-| 🔤 **Resource Formatting Fix** | `memory://{project}/handoff` resources now render as formatted plain text (Last Summary, TODOs, Keywords) instead of a raw JSON blob — readable in Claude Desktop's paperclip attach panel. |
+| 🧹 **Brain Health Clean-up** | One-click **Fix Issues** button — detects and cleans orphaned handoffs, missing embeddings, stale rollups. |
+| 👤 **Agent Identity** | Set Default Role and Agent Name in dashboard — auto-applies as fallback in all tools. |
+| 📜 **Role-Scoped Skills** | Per-role persistent rules documents, auto-injected at `session_load_context`. |
+| 🔤 **Resource Formatting** | `memory://` resources render as formatted text instead of raw JSON. |
 
 </details>
 
@@ -66,13 +104,13 @@
 
 | Feature | Description |
 |---|---|
-| 🐝 **Role-Scoped Memory** | Optional `role` parameter on ledger, handoff, and context loading — each agent role (dev, qa, pm, lead, security, ux) gets its own isolated memory lane within a project. Defaults to `'global'` for full backward compatibility. |
-| 👥 **Agent Registry** | New `agent_register`, `agent_heartbeat`, `agent_list_team` tools — agents announce their presence, pulse their status, and discover who else is working on the team. Stale agents are auto-pruned after 30 minutes. |
-| 🎯 **Team Roster Injection** | When loading context with a role, Prism automatically injects a "Team Roster" showing active teammates, their roles, current tasks, and last heartbeat — true multi-agent awareness without extra tool calls. |
-| ⚙️ **Dashboard Settings** | New Settings modal with runtime toggles (auto-capture, theme, context depth) backed by a persistent `system_settings` key-value store. Environment variables override DB settings for safety. |
-| 📡 **Hivemind Radar** | New dashboard widget showing active agents, their roles (with icons), current tasks, and heartbeat timestamps — a real-time team coordination dashboard. |
-| 🔒 **Conditional Tool Registration** | `PRISM_ENABLE_HIVEMIND` env var gates Hivemind tools — users who don't need multi-agent features keep the same lean tool count as v2.x. |
-| ✅ **Test Suite** | 58 tests across 4 suites (storage, tools, dashboard, load) with Vitest — includes concurrent write stress tests, role isolation verification, and 0.2ms/write performance benchmarks. |
+| 🐝 **Role-Scoped Memory** | Optional `role` param — each role gets isolated memory within a project. |
+| 👥 **Agent Registry** | `agent_register`, `agent_heartbeat`, `agent_list_team` — multi-agent discovery. |
+| 🎯 **Team Roster** | Auto-injected teammate awareness during context loading. |
+| ⚙️ **Dashboard Settings** | Runtime toggles backed by persistent key-value store. |
+| 📡 **Hivemind Radar** | Dashboard widget showing active agents, roles, and heartbeats. |
+| 🔒 **Conditional Tools** | `PRISM_ENABLE_HIVEMIND` gates multi-agent tools. |
+| ✅ **58 Tests** | Storage, tools, dashboard, concurrent writes, role isolation. |
 
 </details>
 
@@ -82,10 +120,10 @@
 
 | Feature | Description |
 |---|---|
-| 🔍 **Memory Tracing (Phase 1)** | Every search now returns a structured `MemoryTrace` with latency breakdown (`embedding_ms`, `storage_ms`, `total_ms`), search strategy, and scoring metadata — surfaced as a separate `content[1]` block for LangSmith integration. |
-| 🛡️ **GDPR Memory Deletion (Phase 2)** | New `session_forget_memory` tool with soft-delete (tombstoning via `deleted_at`) and hard-delete. Ownership guards prevent cross-user deletion. `deleted_reason` column captures GDPR Article 17 justification. Top-K Hole solved by filtering inside SQL, not post-query (ensures we always return exactly K results, rather than returning fewer because deleted items were filtered out after the vector search). |
-| 🔗 **LangChain Integration (Phase 3)** | `PrismMemoryRetriever` and `PrismKnowledgeRetriever` — async-first `BaseRetriever` subclasses that wrap Prism MCP's traced search endpoints. Trace metadata flows automatically into `Document.metadata["trace"]` for LangSmith visibility. |
-| 🧩 **LangGraph Research Agent** | Full example in `examples/langgraph-agent/` — a 5-node agentic research loop with MCP bridge, persistent memory, and `EnsembleRetriever` hybrid search. |
+| 🔍 **Memory Tracing** | `MemoryTrace` with latency breakdown and scoring metadata for LangSmith. |
+| 🛡️ **GDPR Deletion** | `session_forget_memory` with soft/hard delete and Article 17 justification. |
+| 🔗 **LangChain Integration** | `PrismMemoryRetriever` / `PrismKnowledgeRetriever` BaseRetriever adapters. |
+| 🧩 **LangGraph Agent** | 5-node research agent example with MCP bridge and hybrid search. |
 
 </details>
 
@@ -94,8 +132,8 @@
 
 | Feature | Description |
 |---|---|
-| 🔄 **Dynamic Versioning** | Server version is now derived from `package.json` at startup — MCP handshake, dashboard badge, and npm metadata always stay in sync. Falls back to `0.0.0` if unreadable. |
-| 🛡️ **Embedding Dimension Validation** | `generateEmbedding()` now validates the returned vector is exactly 768 dimensions at runtime, catching model regressions before storing bad vectors. Removed `as any` cast in favor of proper `EmbedContentRequest` typing. |
+| 🔄 **Dynamic Versioning** | Version derived from `package.json` — MCP handshake, dashboard, and npm stay in sync. |
+| 🛡️ **Embedding Validation** | Validates 768-dimension vectors at runtime to catch model regressions. |
 
 </details>
 
@@ -115,11 +153,11 @@
 
 | Feature | Description |
 |---|---|
-| 🤖 **LangGraph Research Agent** | New `examples/langgraph-agent/` — a 5-node agentic research agent (plan→search→analyze→decide→answer→save) with autonomous looping, MCP integration, and persistent memory. |
-| 🧠 **Agentic Memory** | `save_session` node persists research findings to a ledger — the agent doesn't just answer and forget. Routes to Prism's `session_save_ledger` in MCP-connected mode. |
-| 🔌 **MCP Client Bridge** | Raw JSON-RPC 2.0 client (`mcp_client.py`) for Python 3.9+ — dynamically discovers and wraps Prism MCP tools as LangChain `StructuredTool` objects. |
-| 🔧 **Storage Abstraction Fix** | Resource/Prompt handlers now route through `getStorage()` instead of calling Supabase directly — eliminates EOF crashes when reading `memory://` resources. |
-| 🛡️ **Error Boundaries** | Resource handlers catch errors gracefully and return proper MCP error responses (`isError: true`) instead of crashing the server process. |
+| 🤖 **LangGraph Agent** | 5-node research agent with autonomous looping, MCP integration, persistent memory. |
+| 🧠 **Agentic Memory** | `save_session` node persists findings to ledger — agents don't just answer and forget. |
+| 🔌 **MCP Client Bridge** | JSON-RPC 2.0 client wraps Prism tools as LangChain `StructuredTool` objects. |
+| 🔧 **Storage Fix** | Resource/Prompt handlers route through `getStorage()` — eliminates EOF crashes. |
+| 🛡️ **Error Boundaries** | Graceful error handling with proper MCP error responses. |
 
 </details>
 
@@ -157,25 +195,29 @@
 
 | Feature | **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) |
 |---|---|---|---|---|---|
-| **Pricing** | ✅ Free & open source (MIT) | ✅ Free & open source (MIT) | Freemium (free 10K memories; paid Pro) | ✅ Free & open source | Freemium (OSS core free; paid Pro) |
-| **Storage** | SQLite (local) + Supabase (cloud) | JSON file | Postgres + Qdrant (hosted or self-hosted) | Qdrant + S3/MinIO | Markdown files |
-| **Zero Config** | ✅ `npx -y prism-mcp-server` | ✅ | ❌ Requires Qdrant/Postgres | ✅ `uvx mnemory` | ✅ `pip install basic-memory` |
-| **Semantic Search** | ✅ F32_BLOB vectors + FTS5 | ❌ | ✅ pgvector | ✅ Qdrant vectors | ❌ Text search only |
-| **Knowledge Graph** | ✅ Neural Graph (Vis.js dashboard) | ✅ Entity/Relation model | ❌ | ✅ Relationship graph | ✅ Markdown links |
-| **Time Travel** | ✅ `memory_history` / `memory_checkout` | ❌ | ❌ | ❌ | ❌ |
-| **Fact Merging** | ✅ Async Gemini (fire-and-forget) | ❌ | ✅ Built-in | ✅ Contradiction resolution | ❌ |
-| **Security Scan** | ✅ Prompt injection detection | ❌ | ❌ | ✅ Anti-injection in fsck | ❌ |
-| **Health Check** | ✅ `session_health_check` (fsck) | ❌ | ❌ | ✅ 3-phase fsck | ❌ |
-| **Visual Dashboard** | ✅ Mind Palace (localhost:3000) | ❌ | ✅ Cloud dashboard | ✅ Management UI | ❌ |
-| **Multi-Agent Sync** | ✅ Real-time cross-client | ❌ | ❌ | ❌ Per-user isolation | ❌ |
-| **Visual Memory** | ✅ Screenshot vault + auto-capture | ❌ | ❌ | ✅ Artifact store | ❌ |
+| **Pricing** | ✅ Free / MIT | ✅ Free / MIT | Freemium | ✅ Free / OSS | Freemium |
+| **Storage** | SQLite + Supabase | JSON file | Postgres + Qdrant | Qdrant + S3 | Markdown files |
+| **Zero Config** | ✅ npx one-liner | ✅ | ❌ Qdrant/Postgres | ✅ uvx | ✅ pip |
+| **Behavioral Memory** | ✅ Importance tracking | ❌ | ❌ | ❌ | ❌ |
+| **Dynamic Roles** | ✅ Dashboard auto-resolve | ❌ | ❌ | ❌ | ❌ |
+| **Token Budget** | ✅ max_tokens param | ❌ | ❌ | ❌ | ❌ |
+| **Importance Decay** | ✅ Auto-fade stale data | ❌ | ❌ | ❌ | ❌ |
+| **Semantic Search** | ✅ Vectors + FTS5 | ❌ | ✅ pgvector | ✅ Qdrant | ❌ Text only |
+| **Knowledge Graph** | ✅ Neural Graph | ✅ Entity model | ❌ | ✅ Graph | ✅ MD links |
+| **Time Travel** | ✅ History + checkout | ❌ | ❌ | ❌ | ❌ |
+| **Fact Merging** | ✅ Gemini async | ❌ | ✅ Built-in | ✅ Contradiction | ❌ |
+| **Security Scan** | ✅ Injection detection | ❌ | ❌ | ✅ Anti-injection | ❌ |
+| **Health Check** | ✅ fsck tool | ❌ | ❌ | ✅ 3-phase fsck | ❌ |
+| **Visual Dashboard** | ✅ Mind Palace | ❌ | ✅ Cloud UI | ✅ Mgmt UI | ❌ |
+| **Multi-Agent Sync** | ✅ Real-time | ❌ | ❌ | ❌ Per-user | ❌ |
+| **Visual Memory** | ✅ Screenshot vault | ❌ | ❌ | ✅ Artifacts | ❌ |
 | **Auto-Compaction** | ✅ Gemini rollups | ❌ | ❌ | ❌ | ❌ |
 | **Morning Briefing** | ✅ Gemini synthesis | ❌ | ❌ | ❌ | ❌ |
 | **OCC (Concurrency)** | ✅ Version-based | ❌ | ❌ | ❌ | ❌ |
-| **GDPR Compliance** | ✅ Soft/hard delete + audit trail | ❌ | ❌ | ❌ | ❌ |
-| **Memory Tracing** | ✅ MemoryTrace with latency breakdown | ❌ | ❌ | ❌ | ❌ |
-| **LangChain Native** | ✅ BaseRetriever adapters | ❌ | ❌ | ❌ | ❌ |
-| **MCP Native** | ✅ stdio (Claude Desktop, Cursor) | ✅ stdio | ❌ Python SDK / REST | ✅ HTTP + MCP | ✅ stdio |
+| **GDPR Compliance** | ✅ Soft/hard delete | ❌ | ❌ | ❌ | ❌ |
+| **Memory Tracing** | ✅ Latency breakdown | ❌ | ❌ | ❌ | ❌ |
+| **LangChain** | ✅ BaseRetriever | ❌ | ❌ | ❌ | ❌ |
+| **MCP Native** | ✅ stdio | ✅ stdio | ❌ Python SDK | ✅ HTTP + MCP | ✅ stdio |
 | **Language** | TypeScript | TypeScript | Python | Python | Python |
 
 > **When to choose Prism MCP:** You want MCP-native memory with zero infrastructure overhead, progressive context loading, and enterprise features (OCC, compaction, time travel, security scanning) that work directly in Claude Desktop — without running Qdrant, Postgres, or cloud services.
@@ -265,6 +307,7 @@ Open **`http://localhost:3000`** in your browser to see exactly what your AI age
 
 - **Current State & TODOs** — See the exact context injected into the LLM's prompt
 - **Agent Identity Chip** — Header shows your active role + name (e.g. `🛠️ dev · Antigravity`); click to open Settings
+- **Project Repo Paths** — Map each project to its repo directory for save validation
 - **Brain Health 🩺** — Memory integrity status at a glance; **🧹 Fix Issues** button auto-cleans orphaned handoffs in one click
 - **Git Drift Detection** — Alerts you if you've modified code outside the agent's view
 - **Morning Briefing** — AI-synthesized action plan from your last sessions
@@ -363,36 +406,124 @@ Add to your Continue `config.json` or Cline MCP settings:
 
 ---
 
-## Claude Code + Gemini Startup Compatibility
+## Claude Code Integration (Hooks)
 
-If you want consistent behavior across clients, treat startup in two phases:
+Claude Code supports **lifecycle hooks** in `~/.claude/settings.json` that fire automatically at session start and end. Use these to auto-hydrate and persist Prism memory without manual prompting.
 
-1. **Server availability**: ensure `prism-mcp` is enabled in MCP config so tools are available.
-2. **Context hydration**: explicitly call `session_load_context` at session start.
+### SessionStart Hook
 
-Recommended startup call:
+Automatically loads context when a new session begins:
 
 ```json
 {
-  "projectName": "<your-project>",
-  "level": "standard"
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json; print(json.dumps({'continue': True, 'suppressOutput': False, 'systemMessage': 'You MUST call mcp__prism-mcp__session_load_context twice before responding to the user: first with project=my-project level=standard, then with project=my-other-project level=standard. Do not skip this.'}))\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
 }
 ```
 
-Important distinction:
+### Stop Hook
+
+Automatically saves session memory when a session ends:
+
+```json
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 -c \"import json; print(json.dumps({'continue': True, 'suppressOutput': False, 'systemMessage': 'MANDATORY END WORKFLOW: 1) Call mcp__prism-mcp__session_save_ledger with project and summary. 2) Call mcp__prism-mcp__session_save_handoff with expected_version set to the loaded version.'}))\"",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### How the Hooks Work
+
+The hook `command` runs a Python one-liner that returns a JSON object to Claude Code:
+
+| Field | Purpose |
+|---|---|
+| `continue: true` | Tell Claude Code to proceed (don't abort the session) |
+| `suppressOutput: false` | Show the hook result to the agent |
+| `systemMessage` | Instruction injected as a system message — the agent follows it |
+
+The agent receives the `systemMessage` as an instruction and executes the tool calls. The server resolves the agent's **role** and **name** automatically from the dashboard — no need to specify them in the hook.
+
+### Role Resolution — No Hardcoding Needed
+
+Prism resolves the agent role dynamically using a priority chain:
+
+```
+explicit tool argument  →  dashboard setting  →  "global" (default)
+```
+
+1. **Explicit arg wins** — if `role` is passed in the tool call, it's used directly.
+2. **Dashboard fallback** — if `role` is omitted, the server calls `getSetting("default_role")` and uses whatever role you configured in the **Mind Palace Dashboard ⚙️ Settings → Agent Identity**.
+3. **Final default** — if no dashboard setting exists, falls back to `"global"`.
+
+Change your role once in the dashboard, and it automatically applies to every session — CLI, extension, and all MCP clients.
+
+### Verification
+
+If hydration ran successfully, the agent's output will include:
+- A `[👤 AGENT IDENTITY]` block showing your dashboard-configured role and name
+- `PRISM_CONTEXT_LOADED` marker text
+
+If the marker is missing, the hook did not fire or the MCP server is not connected.
+
+---
+
+## Gemini / Antigravity Integration
+
+Gemini-based clients (like Antigravity) use `GEMINI.md` global rules or user rules for startup behavior. The server resolves the role from the dashboard automatically.
+
+### Global Rules (`~/.gemini/GEMINI.md`)
+
+```markdown
+## Prism MCP Memory Auto-Load (CRITICAL)
+At the start of every new session, call `mcp__prism-mcp__session_load_context`
+for these projects:
+- `my-project` (level=standard)
+- `my-other-project` (level=standard)
+
+After both succeed, print PRISM_CONTEXT_LOADED.
+```
+
+### User Rules (Antigravity Settings)
 
-- Auto-loading `prism-mcp` makes the server available.
-- It does **not** guarantee memory context is auto-hydrated unless your client runtime/hook invokes `session_load_context`.
+If your Gemini client supports user rules, add the same instructions there. The key points:
 
-Client notes:
+1. **Call `session_load_context` as a tool** — not `read_resource`. Only the tool returns the `[👤 AGENT IDENTITY]` block.
+2. **Verify** — confirm the response includes `version` and `last_summary`.
 
-- **Gemini runtimes** may support native startup execution depending on configuration.
-- **Claude Code** should use a local `SessionStart` hook in `~/.claude/settings.json` for deterministic startup context loading.
+### Session End
 
-Verification pattern (same for both clients):
+At the end of each session, save state:
 
-- Print a startup marker after successful `session_load_context` (for example, `PRISM_CONTEXT_LOADED`).
-- If the marker is missing, startup hydration did not run.
+```markdown
+## Session End Protocol
+1) Call `mcp__prism-mcp__session_save_ledger` with project and summary.
+2) Call `mcp__prism-mcp__session_save_handoff` with expected_version from the loaded version.
+```
 
 ---
 
@@ -518,6 +649,47 @@ The tool and dashboard button both call the same repair logic — the dashboard
 | `session_search_memory` | Semantic search with `enable_trace` | `query`, `enable_trace` | Results + `MemoryTrace` in `content[1]` |
 | `knowledge_search` | Knowledge search with `enable_trace` | `query`, `enable_trace` | Results + `MemoryTrace` in `content[1]` |
 
+### v4.0 Behavioral Memory Tools
+
+| Tool | Purpose | Key Args |
+|------|---------|----------|
+| `session_save_experience` | Record behavioral events with importance tracking | `project`, `event_type`, `context`, `action`, `outcome` |
+
+**Dynamic Roles (v4.0):** `role` is now *optional* on all tools. Set your **Default Role** once in the dashboard (⚙️ Settings → Agent Identity) and it auto-applies everywhere — no need to pass it per call.
+
+**Token Budget (v4.0):** Set a default in the dashboard (⚙️ Settings → Token Budget) or pass `max_tokens` per call to override:
+
+```json
+{ "name": "session_load_context", "arguments": {
+    "project": "my-app", "level": "standard", "max_tokens": 2000
+}}
+```
+
+> 💡 Set Token Budget to `0` in the dashboard for unlimited (default). Per-call `max_tokens` always takes priority.
+
+**Recording experiences:**
+
+```json
+{ "name": "session_save_experience", "arguments": {
+    "project": "my-app",
+    "event_type": "correction",
+    "context": "User asked to add a database migration",
+    "action": "Ran ALTER TABLE directly in production",
+    "outcome": "Data was corrupted",
+    "correction": "Always create a migration file and test in staging first",
+    "confidence_score": 95
+}}
+```
+
+**Event types:** `correction` (user corrected the agent), `success` (task went well), `failure` (task failed), `learning` (new knowledge acquired).
+
+**How behavioral memory works:**
+1. Agent records experiences via `session_save_experience`
+2. Prism assigns an **importance score** based on event type + confidence
+3. Stale entries **auto-decay** in importance over time
+4. On `session_load_context`, high-importance corrections auto-surface as `[⚠️ BEHAVIORAL WARNINGS]`
+5. Agent sees warnings and avoids repeating past mistakes
+
 ### Code Mode Templates (v2.1)
 
 Instead of writing custom JavaScript, pass a `template` name for instant extraction:
@@ -695,6 +867,7 @@ The retrievers use `_aget_relevant_documents` as the primary path with `asyncio.
 | `BRAVE_API_KEY` | No | Brave Search Pro API key (enables web/local search tools) |
 | `PRISM_STORAGE` | No | `"local"` (default) or `"supabase"` — **requires restart** |
 | `PRISM_ENABLE_HIVEMIND` | No | Set `"true"` to enable multi-agent Hivemind tools — **requires restart** |
+| `PRISM_INSTANCE` | No | Instance name for PID lock isolation (e.g. `"athena"`, `"prism-dev"`). Enables [multi-instance support](#multi-instance-support). Default: `"default"` |
 | `GOOGLE_API_KEY` | No | Google AI / Gemini — enables paper analysis, Morning Briefings, compaction |
 | `BRAVE_ANSWERS_API_KEY` | No | Separate Brave Answers key for AI-grounded answers |
 | `SUPABASE_URL` | If cloud mode | Supabase project URL |
@@ -761,50 +934,28 @@ The agent boots up knowing exactly what to do — zero prompting needed.
 
 ### Auto-Load on Session Start (Recommended)
 
-For the best experience, configure your AI coding assistant to **automatically call `session_load_context`** at the start of every new session. This ensures your agent always boots with full project memory — no manual prompting needed.
+For the best experience, ensure your agent boots with full project memory on every new session. There are three approaches — use whichever fits your workflow:
 
-<details>
-<summary><strong>Claude Code (.clauderules / CLAUDE.md)</strong></summary>
-
-Add this rule to your project's `.clauderules` or `CLAUDE.md`:
-
-```markdown
+#### Option A: Dashboard Setting (Easiest)
 
-## Prism MCP Memory Auto-Load (CRITICAL)
-At the start of every new session, you MUST call `session_load_context`
-at the `standard` level for these projects:
-- `my-project`
-- `my-other-project`
+Open the **Mind Palace Dashboard** (⚙️ Settings) and type your project names into the **Auto-Load Projects** field under Boot Settings:
 
-Do NOT skip this step.
+```
+prism-mcp, my-app
 ```
 
-</details>
-
-<details>
-<summary><strong>Gemini / Antigravity (GEMINI.md)</strong></summary>
-
-Add this rule to your `~/.gemini/GEMINI.md` global rules file:
+That's it. Restart your AI client and Prism auto-pushes context for each listed project on next boot.
 
-```markdown
+#### Option B: Client-Side Hooks / Rules
 
-## Prism MCP Memory Auto-Load (CRITICAL)
+For clients that support lifecycle hooks or startup rules, instruct the AI to **call `session_load_context` as a tool** at session start:
 
-**At the start of every new session**, immediately after displaying
-the startup block, you MUST call `session_load_context` (via the
-`prism-mcp` MCP server) at the `standard` level for these projects:
-- `my-project`
-- `my-other-project`
+- **[Claude Code Integration (Hooks)](#claude-code-integration-hooks)** — `SessionStart` and `Stop` hook JSON samples for `~/.claude/settings.json`
+- **[Gemini / Antigravity Integration](#gemini--antigravity-integration)** — global rules for `~/.gemini/GEMINI.md` or user rules
 
-This ensures accumulated project memory, pending TODOs, and key context
-from previous sessions are always available. Do NOT skip this step.
+> **You can use both approaches together.** The dashboard auto-load (A) injects project names into the `session_load_context` tool description — works universally across all MCP clients. Client-side hooks (B) give the AI full structured access to the context response (including version numbers for OCC).
 
-**IMPORTANT:** The `prism-mcp` MCP server is always available.
-Do NOT display any warnings or notes about MCP server availability
-— just call the tools directly. Never claim the server is unavailable.
-```
-
-</details>
+> **Key principle:** Never hardcode a `role` in your hooks or rules. Set your role once in the **Mind Palace Dashboard ⚙️ Settings → Agent Identity**, and Prism automatically resolves it for every tool call across all clients. See [Role Resolution](#role-resolution--no-hardcoding-needed).
 
 > **Tip:** Replace `my-project` with your actual project identifiers. You can list as many projects as you need — each one gets its own independent memory timeline.
 
@@ -1017,9 +1168,12 @@ Traces are returned as `content[1]` in MCP responses — a separate content bloc
 
 ### 2. Apply Migrations
 
-In the SQL Editor, run:
+In the SQL Editor, run the **bootstrap migration** first:
 1. [`supabase/migrations/015_session_memory.sql`](supabase/migrations/015_session_memory.sql)
 2. [`supabase/migrations/016_knowledge_accumulation.sql`](supabase/migrations/016_knowledge_accumulation.sql)
+3. [`supabase/migrations/027_auto_migration_infra.sql`](supabase/migrations/027_auto_migration_infra.sql) — **enables auto-migrations** (see below)
+
+> **After applying migration 027**, all future schema changes are applied automatically on server startup — no manual SQL required.
 
 ### 3. Get Credentials
 
@@ -1047,6 +1201,70 @@ export PRISM_STORAGE="supabase"
 
 </details>
 
+### Auto-Migrations (Supabase Cloud)
+
+Prism includes a zero-config auto-migration system for Supabase. Once the bootstrap migration (`027_auto_migration_infra.sql`) is applied, all future schema changes are applied automatically on server startup.
+
+**How it works:**
+
+1. On startup, the migration runner checks each entry in `MIGRATIONS[]` (defined in `supabaseMigrations.ts`)
+2. For each migration, it calls `prism_apply_ddl(version, name, sql)` — a `SECURITY DEFINER` RPC function
+3. The function checks `prism_schema_versions` — if the version is already recorded, it's silently skipped (idempotent)
+4. If not applied, it executes the DDL and records the version number
+
+**Graceful degradation:** If `prism_apply_ddl()` doesn't exist (you haven't applied migration 027 yet), the runner logs a warning and continues — the server still starts, but newer schema features may not be available.
+
+**Adding new migrations** — just append to the `MIGRATIONS[]` array in `src/storage/supabaseMigrations.ts`:
+
+```typescript
+{
+  version: 28,
+  name: "my_new_feature",
+  sql: `ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS my_col TEXT;`,
+}
+```
+
+All SQL must be idempotent (`IF NOT EXISTS` / `IF EXISTS` guards).
+
+---
+
+## Multi-Instance Support
+
+Run multiple Prism MCP servers side-by-side on the same machine without PID lock conflicts. This is useful when you have different MCP configurations (e.g., one for web search + memory, another for memory-only) running in different clients simultaneously.
+
+### Configuration
+
+Set `PRISM_INSTANCE` to a unique name per server instance:
+
+```json
+{
+  "mcpServers": {
+    "prism-search": {
+      "command": "node",
+      "args": ["/path/to/prism/dist/server.js"],
+      "env": {
+        "PRISM_INSTANCE": "prism-search",
+        "BRAVE_API_KEY": "your-key"
+      }
+    },
+    "prism-memory": {
+      "command": "node",
+      "args": ["/path/to/prism/dist/server.js"],
+      "env": {
+        "PRISM_INSTANCE": "prism-memory"
+      }
+    }
+  }
+}
+```
+
+### How it works
+
+- Each instance gets its own PID file: `/tmp/prism-{PRISM_INSTANCE}.pid`
+- Default instance name is `"default"` (backward compatible)
+- Instances share the same SQLite database and Supabase backend — only the process lock is isolated
+- Graceful shutdown cleans up the instance's PID file
+
 ---
 
 ## Hybrid Search Pipeline (Brave + Vertex AI)
@@ -1073,12 +1291,13 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 
 ```
 ├── src/
-│   ├── server.ts                        # MCP server core + tool routing
+│   ├── server.ts                        # MCP server core + tool routing + lifecycle
 │   ├── config.ts                        # Environment management
 │   ├── storage/
 │   │   ├── interface.ts                 # StorageBackend abstraction (+ GDPR delete methods)
 │   │   ├── sqlite.ts                    # SQLite local storage (libSQL + F32_BLOB + deleted_at migration)
 │   │   ├── supabase.ts                  # Supabase cloud storage (+ soft/hard delete)
+│   │   ├── supabaseMigrations.ts        # Auto-migration runner for Supabase DDL
 │   │   ├── configStorage.ts             # Boot config micro-DB (~/.prism-mcp/prism-config.db)
 │   │   └── index.ts                     # Backend factory (auto-selects based on PRISM_STORAGE)
 │   ├── sync/
@@ -1116,7 +1335,8 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 │   ├── prism_retriever.py               # PrismMemoryRetriever + PrismKnowledgeRetriever
 │   ├── tools.py                         # Agent tools + GDPR forget_memory
 │   └── demo_retriever.py                # Standalone retriever demo
-├── supabase/migrations/                 # Cloud mode SQL schemas
+├── supabase/migrations/                 # Cloud mode SQL schemas + auto-migration bootstrap
+│   └── 027_auto_migration_infra.sql     # prism_apply_ddl() RPC + schema version tracking
 ├── vertex-ai/                           # Vertex AI hybrid search pipeline
 ├── index.ts                             # Server entry point
 └── package.json
@@ -1128,28 +1348,41 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 
 > **[View the full project board →](https://github.com/users/dcostenco/projects/1/views/1)**
 
-### ✅ v3.0.1 — Agent Identity & Brain Clean-up (Shipped!)
+### ✅ v4.2 — Project Repo Registry (Shipped!)
+
+| Feature | Description |
+|---|---|
+| 🗂️ **Project Repo Paths** | Dashboard UI to map projects to repo directories + `session_save_ledger` path validation. |
+| 🔄 **Universal Auto-Load** | Dynamic tool descriptions replace env var — dashboard is sole source of truth. |
+| 🏠 **Dashboard-First Config** | Removed `PRISM_AUTOLOAD_PROJECTS` env var override. |
+
+### ✅ v4.1 — Auto-Migration & Multi-Instance (Shipped!)
+
+See [What's in v4.1.0](#whats-in-v410--auto-migration--multi-instance-) above.
+
+### ✅ v4.0 — Behavioral Memory (Shipped!)
+
+See [What's in v4.0.0](#whats-in-v400--behavioral-memory-) above.
+
+### ✅ v3.1 — Memory Lifecycle (Shipped!)
 
-See [What's New in v3.0.1](#whats-new-in-v301---agent-identity--brain-clean-up-) above.
+See [What's in v3.1.0](#whats-in-v310--memory-lifecycle-) above.
 
 ### ✅ v3.0 — Agent Hivemind (Shipped!)
 
-See [What's New in v3.0.0 — Agent Hivemind](#whats-new-in-v300---agent-hivemind-) above.
+See [What's in v3.0.0](#whats-in-v300--agent-hivemind-) above.
 
 ### 🚀 Future Ideas
 
 | Feature | Issue | Description |
 |---------|-------|-------------|
-| **Role-Scoped Skills & Rules** | — | Each agent role (`dev`, `qa`, `pm`, etc.) gets its own persistent skill/rules document. Preloaded automatically at session start via `session_load_context`. Skills editable and uploadable from the Mind Palace Dashboard (⚙️ → Skills tab per role). Stored in `configStorage` per-role key — backend already exists. |
-| OpenTelemetry SDK Integration | [#6](https://github.com/dcostenco/prism-mcp/issues/6) | W3C-compliant tracing with Jaeger/Zipkin export |
-| GDPR Right to Portability | [#7](https://github.com/dcostenco/prism-mcp/issues/7) | `session_export_memory` tool for Art. 20 compliance |
-| Multi-agent CRDT Conflict Resolution | [#9](https://github.com/dcostenco/prism-mcp/issues/9) | Conflict-free replicated data types for concurrent agent edits |
-| Memory Analytics Dashboard | [#10](https://github.com/dcostenco/prism-mcp/issues/10) | Usage trends, token costs, and memory health metrics |
-| Pluggable LLM Providers | [#13](https://github.com/dcostenco/prism-mcp/issues/13) | Anthropic, OpenAI, Ollama provider adapters |
-| VLM / OCR for Visual Memory | [#14](https://github.com/dcostenco/prism-mcp/issues/14) | Auto-extract text and insights from stored images |
-| Automated Data Retention (TTL) | [#16](https://github.com/dcostenco/prism-mcp/issues/16) | Time-based memory expiration policies |
-| Obsidian / Logseq Export Bridge | [#17](https://github.com/dcostenco/prism-mcp/issues/17) | Export memory to Markdown knowledge bases |
-| Interactive Knowledge Graph Editor | [#19](https://github.com/dcostenco/prism-mcp/issues/19) | Visual graph editor inside the Mind Palace dashboard |
+| Insight Graduation | — | `knowledge_upvote` / `knowledge_downvote` — importance ≥ 7 promotes to rule |
+| OpenTelemetry | [#6](https://github.com/dcostenco/prism-mcp/issues/6) | W3C tracing with Jaeger/Zipkin export |
+| GDPR Portability | [#7](https://github.com/dcostenco/prism-mcp/issues/7) | `session_export_memory` for Art. 20 |
+| CRDT Conflict Resolution | [#9](https://github.com/dcostenco/prism-mcp/issues/9) | Conflict-free types for concurrent edits |
+| Pluggable LLM Providers | [#13](https://github.com/dcostenco/prism-mcp/issues/13) | Anthropic, OpenAI, Ollama adapters |
+| VLM / OCR for Images | [#14](https://github.com/dcostenco/prism-mcp/issues/14) | Auto-extract text from stored images |
+| Knowledge Graph Editor | [#19](https://github.com/dcostenco/prism-mcp/issues/19) | Visual graph editor in Mind Palace |
 
 ### 🧰 Infrastructure & Stack