prism-mcp-server 4.0.0 → 4.3.0

package/README.md

@@ -14,7 +14,8 @@
 
 ## Table of Contents
 
-- [What's New (v4.0.0)](#whats-new-in-v400--behavioral-memory-)
+- [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)
@@ -41,26 +42,56 @@
 
 ---
 
-## What's New in v4.0.0 — Behavioral Memory 🧠
+## What's New in v4.3.0 — The Bridge 🌉
+
+> **🧠 Active Behavioral Memory & IDE Sync**
+> Prism doesn't just log what happened—it learns. When an agent is corrected, the memory gains "Importance". Once an insight graduates (Importance >= 7), Prism can automatically sync it directly to your `.cursorrules` or `.clauderules` file, turning dynamic behavioral learnings into permanent, zero-token IDE enforcement.
+
+<details>
+<summary><strong>What's in v4.2.0 — Project Repo Registry 🗂️</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 🗂️ **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>
+
+<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 |
 |---|---|
-| 🧠 **Active Behavioral Memory** | New `session_save_experience` tool — agents log actions, outcomes, corrections, and confidence scores. Prism tracks importance, applies decay over time, and injects behavioral warnings into context loading so agents learn from past mistakes. |
-| 🎯 **Dynamic Role Resolution** | Role parameter is now fully optional across all tools. The server auto-resolves from dashboard settings via `getSetting("default_role")` — set your role once in the Mind Palace Dashboard, and it applies everywhere. No more hardcoding `role: "global"`. |
-| 📏 **Token Budget** | New `max_tokens` parameter on `session_load_context` — set a token budget and the response is intelligently truncated to fit. Uses a 1 token ≈ 4 chars heuristic. |
-| 📉 **Importance Decay** | Stale behavioral experiences automatically decay over time — older corrections fade in importance to keep context fresh and relevant. |
-| 🔧 **Claude Code Hooks** | Refined SessionStart/Stop hook samples that reliably trigger MCP tool calls. Simplified from multi-step workflows to single imperative instructions. |
+| 🧠 **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** | 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. |
+| 📊 **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>
 
@@ -69,10 +100,10 @@
 
 | 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>
 
@@ -81,13 +112,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>
 
@@ -97,10 +128,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>
 
@@ -109,8 +140,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>
 
@@ -130,11 +161,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>
 
@@ -172,25 +203,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.
@@ -280,6 +315,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
@@ -621,6 +657,82 @@ 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
+
+### v4.2 Knowledge Sync Rules — "The Bridge"
+
+Bridges **v4.0 Behavioral Memory** (graduated insights) with **v4.2 Project Registry** (repo paths) to physically write agent learnings into your project's IDE rules file.
+
+| Feature | Without Sync Rules | With `knowledge_sync_rules` |
+|---------|-------------------|----------------------------|
+| **Insight Visibility** | Only in Prism context injection | Persisted as static IDE context (`.cursorrules` / `.clauderules`) |
+| **Cross-Session** | Loaded per-session via tool call | Always-on — IDE reads rules file on every prompt |
+| **Agent Learning Loop** | Behavioral warnings during context load | Rules enforced even without Prism connected |
+| **Idempotency** | N/A | Sentinel markers ensure safe re-runs |
+| **User Control** | View in dashboard | User-maintained rules preserved; only sentinel block updated |
+
+**Syncing graduated insights:**
+
+```json
+{ "name": "knowledge_sync_rules", "arguments": {
+    "project": "my-app",
+    "target_file": ".cursorrules",
+    "dry_run": true
+}}
+```
+
+**How it works:**
+1. Fetches graduated insights (`importance >= 7`) from the ledger
+2. Formats them as markdown rules inside `<!-- PRISM:AUTO-RULES:START/END -->` sentinel markers
+3. Idempotently writes them into the target file at the project's configured `repo_path`
+
+| Tool | Purpose | Key Args |
+|------|---------|----------|
+| `knowledge_sync_rules` | Sync graduated insights to IDE rules file | `project`, `target_file`, `dry_run` |
+| `knowledge_upvote` | Increase entry importance (+1) | `id` |
+| `knowledge_downvote` | Decrease entry importance (-1) | `id` |
+
+> 💡 **Prerequisite:** Set a `repo_path` for your project in the Mind Palace dashboard (⚙️ Settings → Project Repo Paths) before syncing.
+
 ### Code Mode Templates (v2.1)
 
 Instead of writing custom JavaScript, pass a `template` name for instant extraction:
@@ -798,6 +910,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 |
@@ -864,12 +977,27 @@ 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:
+
+#### Option A: Dashboard Setting (Easiest)
+
+Open the **Mind Palace Dashboard** (⚙️ Settings) and type your project names into the **Auto-Load Projects** field under Boot Settings:
+
+```
+prism-mcp, my-app
+```
+
+That's it. Restart your AI client and Prism auto-pushes context for each listed project on next boot.
+
+#### Option B: Client-Side Hooks / Rules
+
+For clients that support lifecycle hooks or startup rules, instruct the AI to **call `session_load_context` as a tool** at session start:
 
-See the full setup guides for each client:
 - **[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
 
+> **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).
+
 > **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.
@@ -1083,9 +1211,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
 
@@ -1113,6 +1244,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)
@@ -1139,12 +1334,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/
@@ -1182,7 +1378,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
@@ -1194,40 +1391,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 + Knowledge Sync Rules (Shipped!)
 
-See [What's New in v3.0.1](#whats-new-in-v301---agent-identity--brain-clean-up-) above.
+| 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. |
+| 🌉 **Knowledge Sync Rules** | `knowledge_sync_rules` — auto-sync graduated insights to `.cursorrules` / `.clauderules` with idempotent sentinel markers. |
 
-### ✅ v3.0 — Agent Hivemind (Shipped!)
+### ✅ v4.1 — Auto-Migration & Multi-Instance (Shipped!)
 
-See [What's New in v3.0.0 — Agent Hivemind](#whats-new-in-v300---agent-hivemind-) above.
+See [What's in v4.1.0](#whats-in-v410--auto-migration--multi-instance-) above.
 
-### 🔜 v4.0 — Active Behavioral Memory (In Development)
+### ✅ v4.0 — Behavioral Memory (Shipped!)
 
-Evolves Prism from passive session logging to an **experience learning engine** that shapes agent behavior over time.
+See [What's in v4.0.0](#whats-in-v400--behavioral-memory-) above.
 
-| Feature | Description |
-|---------|-------------|
-| **Structured Event Types** | Typed experience events (`correction`, `success`, `failure`, `learning`) with `confidence_score` (1-100) — agents don't just log, they learn |
-| **Token-Budgeted Context Loading** | `max_tokens` param on `session_load_context` — guarantees constant cost regardless of DB size (1 token ≈ 4 chars heuristic) |
-| **`session_save_experience` Tool** | Dedicated tool for behavioral data: context → action → outcome → correction. Auto-extracts keywords, seeds importance |
-| **Insight Graduation System** | `knowledge_upvote` / `knowledge_downvote` tools. Importance ≥ 7 → graduated rule. 30-day decay prevents bloat |
-| **Behavioral Warnings** | High-importance corrections auto-surface as `[⚠️ BEHAVIORAL WARNINGS]` in `session_load_context` — agents proactively avoid past mistakes |
+### ✅ v3.1 — Memory Lifecycle (Shipped!)
+
+See [What's in v3.1.0](#whats-in-v310--memory-lifecycle-) above.
+
+### ✅ v3.0 — Agent Hivemind (Shipped!)
+
+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 |
+| 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
 

package/dist/config.js

@@ -114,6 +114,14 @@ export const PRISM_DEBUG_LOGGING = process.env.PRISM_DEBUG_LOGGING === "true";
 // doesn't increase tool count.
 // Set PRISM_ENABLE_HIVEMIND=true to unlock the Agent Registry tools.
 export const PRISM_ENABLE_HIVEMIND = process.env.PRISM_ENABLE_HIVEMIND === "true";
+// ─── v4.1: Auto-Load Projects ────────────────────────────────
+// Auto-load is configured exclusively via the Mind Palace dashboard
+// ("Auto-Load Projects" checkboxes in Settings). The setting is stored
+// in prism-config.db and read at startup via getSettingSync().
+//
+// The PRISM_AUTOLOAD_PROJECTS env var has been removed — the dashboard
+// is the single source of truth. This prevents mismatches between
+// env var and dashboard values causing duplicate project loads.
 if (PRISM_AUTO_CAPTURE) {
     // Use console.error instead of debugLog here to prevent circular dependency
     if (PRISM_DEBUG_LOGGING) {