prism-mcp-server 4.0.0 → 4.2.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,48 @@
 
 ---
 
-## What's New in v4.0.0 — Behavioral Memory 🧠
+## What's New in v4.2.0 — Project Repo Registry 🗂️
 
 | 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. |
+| 🗂️ **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** | 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 +92,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 +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>
 
@@ -97,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>
 
@@ -109,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>
 
@@ -130,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>
 
@@ -172,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.
@@ -280,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
@@ -621,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:
@@ -798,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 |
@@ -864,12 +934,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 +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
 
@@ -1113,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)
@@ -1139,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/
@@ -1182,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
@@ -1194,40 +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!)
 
-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. |
 
-### ✅ 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 |
+| 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
 

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) {

package/dist/dashboard/ui.js

@@ -696,6 +696,19 @@ export function renderDashboardHTML(version) {
           </select>
         </div>
 
+        <div class="setting-row">
+          <div>
+            <div class="setting-label">Token Budget</div>
+            <div class="setting-desc">Max tokens for session_load_context (0 = unlimited)</div>
+          </div>
+          <input type="number" id="input-max-tokens"
+            placeholder="0"
+            min="0" max="100000" step="500"
+            style="padding: 0.2rem 0.5rem; background: var(--bg-hover); color: var(--text-primary); border: 1px solid var(--border-color); border-radius: 4px; font-size: 0.85rem; font-family: var(--font-mono); width: 90px; text-align: right;"
+            onchange="saveSetting('max_tokens', this.value)"
+            oninput="clearTimeout(this._t); this._t=setTimeout(()=>saveSetting('max_tokens',this.value),800)" />
+        </div>
+
         <div class="setting-section">Boot Settings <span class="boot-badge">Restart Required</span></div>
 
         <div class="setting-row">
@@ -716,6 +729,26 @@ export function renderDashboardHTML(version) {
           </select>
         </div>
 
+        <div class="setting-row" style="align-items:flex-start">
+          <div>
+            <div class="setting-label">Auto-Load Projects</div>
+            <div class="setting-desc">Select projects to auto-push context on startup</div>
+          </div>
+          <div id="autoload-checkboxes" style="display:flex;flex-direction:column;gap:4px;font-size:0.85rem;font-family:var(--font-mono);max-height:120px;overflow-y:auto;">
+            <span style="color:var(--text-muted);font-size:0.8rem">Loading…</span>
+          </div>
+        </div>
+
+        <div class="setting-row" style="align-items:flex-start">
+          <div>
+            <div class="setting-label">Project Repo Paths</div>
+            <div class="setting-desc">Map each project to its repo directory for save validation</div>
+          </div>
+          <div id="repopath-inputs" style="display:flex;flex-direction:column;gap:6px;font-size:0.85rem;max-height:160px;overflow-y:auto;">
+            <span style="color:var(--text-muted);font-size:0.8rem">Loading…</span>
+          </div>
+        </div>
+
         <div class="setting-section">Agent Identity</div>
 
         <div class="setting-row">
@@ -1278,6 +1311,88 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
     }
 
 
+    // ─── Auto-Load Checkboxes (v4.1) ─────────────────────────────────
+    async function loadAutoloadCheckboxes() {
+      var container = document.getElementById('autoload-checkboxes');
+      if (!container) return;
+      try {
+        var projRes = await fetch('/api/projects');
+        var projData = await projRes.json();
+        var projects = projData.projects || [];
+
+        var settRes = await fetch('/api/settings');
+        var settData = await settRes.json();
+        var saved = (settData.settings || {}).autoload_projects || '';
+        var selected = saved.split(',').map(function(s){ return s.trim(); }).filter(Boolean);
+
+        if (projects.length === 0) {
+          container.innerHTML = '<span style="color:var(--text-muted);font-size:0.8rem">No projects found</span>';
+          return;
+        }
+
+        container.innerHTML = projects.map(function(p) {
+          var checked = selected.indexOf(p) !== -1 ? ' checked' : '';
+          return '<label style="display:flex;align-items:center;gap:6px;cursor:pointer;color:var(--text-primary)">' +
+            '<input type="checkbox" value="' + escapeHtml(p) + '"' + checked +
+            ' onchange="onAutoloadToggle()"' +
+            ' style="accent-color:var(--accent-purple);cursor:pointer" />' +
+            escapeHtml(p) + '</label>';
+        }).join('');
+      } catch(e) {
+        container.innerHTML = '<span style="color:var(--accent-rose);font-size:0.8rem">Failed to load</span>';
+      }
+    }
+
+    function onAutoloadToggle() {
+      var container = document.getElementById('autoload-checkboxes');
+      if (!container) return;
+      var boxes = container.querySelectorAll('input[type=checkbox]');
+      var selected = [];
+      for (var i = 0; i < boxes.length; i++) {
+        if (boxes[i].checked) selected.push(boxes[i].value);
+      }
+      saveBootSetting('autoload_projects', selected.join(','));
+    }
+
+    // ─── Project Repo Paths (v4.2) ─────────────────────────────────
+    async function loadRepoPathInputs() {
+      var container = document.getElementById('repopath-inputs');
+      if (!container) return;
+      try {
+        var projRes = await fetch('/api/projects');
+        var projData = await projRes.json();
+        var projects = projData.projects || [];
+
+        var settRes = await fetch('/api/settings');
+        var settData = await settRes.json();
+        var settings = settData.settings || {};
+
+        if (projects.length === 0) {
+          container.innerHTML = '<span style="color:var(--text-muted);font-size:0.8rem">No projects found</span>';
+          return;
+        }
+
+        container.innerHTML = projects.map(function(p) {
+          var savedPath = settings['repo_path:' + p] || '';
+          return '<div style="display:flex;align-items:center;gap:6px">' +
+            '<span style="min-width:100px;color:var(--text-secondary);font-family:var(--font-mono);font-size:0.8rem;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="' + escapeHtml(p) + '">' + escapeHtml(p) + '</span>' +
+            '<input type="text" value="' + escapeHtml(savedPath) + '"' +
+            ' placeholder="/path/to/repo"' +
+            ' data-project="' + escapeHtml(p) + '"' +
+            ' style="flex:1;min-width:140px;padding:0.2rem 0.4rem;background:var(--bg-primary);color:var(--text-primary);border:1px solid var(--border-glass);border-radius:4px;font-size:0.8rem;font-family:var(--font-mono)"' +
+            ' onchange="saveRepoPath(this.dataset.project, this.value)"' +
+            ' oninput="clearTimeout(this._t); var self=this; this._t=setTimeout(function(){saveRepoPath(self.dataset.project, self.value)},1200)" />' +
+            '</div>';
+        }).join('');
+      } catch(e) {
+        container.innerHTML = '<span style="color:var(--accent-rose);font-size:0.8rem">Failed to load</span>';
+      }
+    }
+
+    async function saveRepoPath(project, path) {
+      await saveSetting('repo_path:' + project, path.trim());
+    }
+
       async function loadSettings() {
       try {
         var res = await fetch('/api/settings');
@@ -1304,6 +1419,11 @@ Example:\n## Dev Rules\n- Always write tests first\n- Use TypeScript strict mode
         // Agent Identity
         if (s.default_role) document.getElementById('select-default-role').value = s.default_role;
         if (s.agent_name) document.getElementById('input-agent-name').value = s.agent_name;
+        if (s.max_tokens) document.getElementById('input-max-tokens').value = s.max_tokens;
+        // Autoload checkboxes are loaded dynamically
+        loadAutoloadCheckboxes();
+        // Repo path inputs are loaded dynamically
+        loadRepoPathInputs();
       } catch(e) { console.warn('Settings load failed:', e); }
     }
 

package/dist/lifecycle.js

@@ -0,0 +1,164 @@
+/**
+ * Server Lifecycle Management
+ * Handles singleton PID locking, graceful shutdown, and SQLite handle cleanup.
+ *
+ * CRITICAL: All logging MUST use console.error() (stderr).
+ * Using console.log() (stdout) will corrupt the MCP JSON-RPC stream.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+import { execSync } from "child_process";
+import { closeConfigStorage } from "./storage/configStorage.js";
+import { getStorage } from "./storage/index.js";
+const PRISM_DIR = path.join(os.homedir(), ".prism-mcp");
+/**
+ * Instance-aware PID file.
+ * Set PRISM_INSTANCE env var to run multiple Prism MCP servers
+ * side-by-side (e.g. "athena-public" and "prism-mcp").
+ * Each instance gets its own PID file to prevent lock conflicts.
+ */
+const INSTANCE_NAME = process.env.PRISM_INSTANCE || "default";
+const PID_FILE = path.join(PRISM_DIR, `server-${INSTANCE_NAME}.pid`);
+function log(msg) {
+    console.error(`[Prism Lifecycle] ${msg}`);
+}
+/**
+ * Checks if a process is an orphan (adopted by init/launchd, PPID=1).
+ * Returns false on Windows (PID logic is different there).
+ */
+function isOrphanProcess(pid) {
+    if (process.platform === "win32") {
+        // Windows doesn't have reliable PPID checks via 'ps'. 
+        // Safer to assume it's NOT an orphan to avoid killing valid instances.
+        return false;
+    }
+    try {
+        // 'ps -o ppid= -p PID' returns just the parent PID
+        const ppid = execSync(`ps -o ppid= -p ${pid}`, { encoding: "utf8" }).trim();
+        return ppid === "1";
+    }
+    catch {
+        // If ps fails (e.g. process gone), assume it's safe to claim
+        return true;
+    }
+}
+/**
+ * Ensures valid server execution state.
+ *
+ * LOGIC:
+ * 1. If --no-lock is passed, skip everything (testing mode).
+ * 2. If PID file exists:
+ *    - If process is dead: Overwrite lock.
+ *    - If process is alive AND is an orphan (PPID=1): Kill it (Zombie), then overwrite.
+ *    - If process is alive AND has a parent: Log warning, allow coexistence (don't kill).
+ */
+export function acquireLock() {
+    if (process.argv.includes("--no-lock")) {
+        log("Lock acquisition skipped (--no-lock flag)");
+        return;
+    }
+    if (!fs.existsSync(PRISM_DIR)) {
+        fs.mkdirSync(PRISM_DIR, { recursive: true });
+    }
+    if (fs.existsSync(PID_FILE)) {
+        try {
+            const oldPid = parseInt(fs.readFileSync(PID_FILE, "utf8").trim(), 10);
+            if (oldPid && oldPid !== process.pid) {
+                let isAlive = false;
+                try {
+                    process.kill(oldPid, 0); // 0 signal checks for existence
+                    isAlive = true;
+                }
+                catch {
+                    isAlive = false;
+                }
+                if (isAlive) {
+                    // Process exists. Is it a zombie?
+                    if (isOrphanProcess(oldPid)) {
+                        log(`Found zombie process (PID ${oldPid}, PPID=1). Terminating...`);
+                        try {
+                            process.kill(oldPid, "SIGTERM");
+                            // Give it 100ms to die, then force kill if needed
+                            setTimeout(() => {
+                                try {
+                                    process.kill(oldPid, "SIGKILL");
+                                }
+                                catch { }
+                            }, 100);
+                        }
+                        catch (e) {
+                            log(`Failed to kill zombie: ${e}`);
+                        }
+                    }
+                    else {
+                        // It has a parent (e.g., another VS Code window or Claude Desktop)
+                        log(`Existing server (PID ${oldPid}) is active and managed. Coexisting...`);
+                        // We do NOT overwrite the PID file here. 
+                        // If we overwrite it, the *active* server will fail to clean up 
+                        // the PID file when it eventually shuts down.
+                        return;
+                    }
+                }
+            }
+        }
+        catch (err) {
+            log(`Warning: Failed to process existing PID file: ${err}`);
+        }
+    }
+    // Claim the lock for this process
+    try {
+        fs.writeFileSync(PID_FILE, process.pid.toString(), "utf8");
+        log(`Acquired singleton lock (PID ${process.pid})`);
+    }
+    catch (err) {
+        log(`Warning: Failed to write PID file: ${err}`);
+    }
+}
+/**
+ * Registers handlers to close SQLite file handles cleanly when the server stops.
+ */
+export function registerShutdownHandlers() {
+    let shuttingDown = false;
+    const shutdown = async (reason) => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        log(`Shutting down gracefully (${reason})...`);
+        try {
+            // 1. Close system settings DB
+            closeConfigStorage();
+            // 2. Close main ledger DB
+            const storage = await getStorage();
+            if (storage && typeof storage.close === "function") {
+                await storage.close();
+            }
+            // 3. Remove PID lockfile (only if WE own it)
+            if (fs.existsSync(PID_FILE)) {
+                try {
+                    const storedPid = parseInt(fs.readFileSync(PID_FILE, "utf8").trim(), 10);
+                    if (storedPid === process.pid) {
+                        fs.unlinkSync(PID_FILE);
+                    }
+                }
+                catch {
+                    // Ignore read errors during shutdown
+                }
+            }
+        }
+        catch (err) {
+            log(`Error during shutdown cleanup: ${err}`);
+        }
+        finally {
+            process.exit(0);
+        }
+    };
+    // OS Signals
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+    process.on("SIGHUP", () => shutdown("SIGHUP"));
+    // MCP Client Disconnect (CRITICAL)
+    process.stdin.on("close", () => {
+        shutdown("CLIENT_DISCONNECTED_STDIN_CLOSED");
+    });
+}

package/dist/server.js

@@ -61,6 +61,7 @@ SubscribeRequestSchema, UnsubscribeRequestSchema, } from "@modelcontextprotocol/
 import { SERVER_CONFIG, SESSION_MEMORY_ENABLED, PRISM_USER_ID, PRISM_ENABLE_HIVEMIND } from "./config.js";
 import { getSyncBus } from "./sync/factory.js";
 import { startDashboardServer } from "./dashboard/server.js";
+import { acquireLock, registerShutdownHandlers } from "./lifecycle.js";
 // ─── v2.3.6 FIX: Use Storage Abstraction for Prompts/Resources ───
 // CRITICAL FIX: Previously imported supabaseRpc/supabaseGet directly,
 // which bypassed the storage abstraction layer and caused the server
@@ -114,43 +115,52 @@ const BASE_TOOLS = [
     BRAVE_ANSWERS_TOOL, // brave_answers — AI-grounded answers
     RESEARCH_PAPER_ANALYSIS_TOOL, // gemini_research_paper_analysis — paper analysis
 ];
-// Session memory tools: only added when SUPABASE_URL + SUPABASE_KEY are set
-// REVIEWER NOTE: v0.4.0 adds 2 new tools here:
-//   - session_compact_ledger (Enhancement #2): auto-rollup of old ledger entries
-//   - session_search_memory (Enhancement #4): semantic search via pgvector embeddings
-const SESSION_MEMORY_TOOLS = [
-    SESSION_SAVE_LEDGER_TOOL, // session_save_ledger — append immutable session log
-    SESSION_SAVE_HANDOFF_TOOL, // session_save_handoff — upsert latest project state (now with OCC)
-    SESSION_LOAD_CONTEXT_TOOL, // session_load_context — progressive context loading
-    KNOWLEDGE_SEARCH_TOOL, // knowledge_search — search accumulated knowledge
-    KNOWLEDGE_FORGET_TOOL, // knowledge_forget — prune bad/old memories
-    SESSION_COMPACT_LEDGER_TOOL, // session_compact_ledger — auto-compact old ledger entries (v0.4.0)
-    SESSION_SEARCH_MEMORY_TOOL, // session_search_memory — semantic search via embeddings (v0.4.0)
-    MEMORY_HISTORY_TOOL, // memory_history — view version timeline (v2.0)
-    MEMORY_CHECKOUT_TOOL, // memory_checkout — revert to past version (v2.0)
-    // ─── v2.0: Visual Memory tools ───
-    SESSION_SAVE_IMAGE_TOOL, // session_save_image — save image to media vault (v2.0)
-    SESSION_VIEW_IMAGE_TOOL, // session_view_image — retrieve image from vault (v2.0)
-    // ─── v2.2.0: Health Check tool ───
-    SESSION_HEALTH_CHECK_TOOL, // session_health_check — brain integrity checker (v2.2.0)
-    // ─── Phase 2: GDPR Memory Deletion tool ───
-    SESSION_FORGET_MEMORY_TOOL, // session_forget_memory — GDPR-compliant memory deletion (Phase 2)
-    // ─── v3.1: TTL Retention tool ───
-    KNOWLEDGE_SET_RETENTION_TOOL, // knowledge_set_retention — set auto-expiry TTL for a project
-    // ─── v4.0: Active Behavioral Memory tools ───
-    SESSION_SAVE_EXPERIENCE_TOOL, // session_save_experience — record typed experience events
-    KNOWLEDGE_UPVOTE_TOOL, // knowledge_upvote — increase entry importance
-    KNOWLEDGE_DOWNVOTE_TOOL, // knowledge_downvote — decrease entry importance
-];
-// Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
-// can enumerate the full capability set. Runtime guards in the CallTool handler
-// still prevent execution without valid Supabase credentials.
-const ALL_TOOLS = [
-    ...BASE_TOOLS,
-    ...SESSION_MEMORY_TOOLS,
-    // v3.0: Agent Hivemind tools — only when PRISM_ENABLE_HIVEMIND=true
-    ...(PRISM_ENABLE_HIVEMIND ? AGENT_REGISTRY_TOOLS : []),
-];
+// ─── v4.1 FIX: Build Session Memory Tools dynamically ────────
+// The session_load_context tool description is dynamically modified
+// to include auto-load project instructions. Tool descriptions are
+// the ONLY mechanism guaranteed by ALL MCP clients (Antigravity,
+// Claude Code, Claude CLI). The `instructions` field and
+// sendLoggingMessage are NOT reliably surfaced by any client.
+//
+// buildSessionMemoryTools() is called inside createServer() AFTER
+// initConfigStorage() has run, so getSettingSync() returns real
+// dashboard config values.
+function buildSessionMemoryTools(autoloadList) {
+    // Dynamically inject auto-load instruction into session_load_context description
+    let loadContextTool = SESSION_LOAD_CONTEXT_TOOL;
+    if (autoloadList.length > 0) {
+        const projectList = autoloadList.join(", ");
+        loadContextTool = {
+            ...SESSION_LOAD_CONTEXT_TOOL,
+            description: SESSION_LOAD_CONTEXT_TOOL.description +
+                `\n\nIMPORTANT: At the start of every conversation, you MUST call this tool for each of these projects: ${projectList}. Do this before any other work. Load level should be "standard" unless the user specifies otherwise.`,
+        };
+    }
+    return [
+        SESSION_SAVE_LEDGER_TOOL, // session_save_ledger — append immutable session log
+        SESSION_SAVE_HANDOFF_TOOL, // session_save_handoff — upsert latest project state (now with OCC)
+        loadContextTool, // session_load_context — progressive context loading (+ auto-load instruction)
+        KNOWLEDGE_SEARCH_TOOL, // knowledge_search — search accumulated knowledge
+        KNOWLEDGE_FORGET_TOOL, // knowledge_forget — prune bad/old memories
+        SESSION_COMPACT_LEDGER_TOOL, // session_compact_ledger — auto-compact old ledger entries (v0.4.0)
+        SESSION_SEARCH_MEMORY_TOOL, // session_search_memory — semantic search via embeddings (v0.4.0)
+        MEMORY_HISTORY_TOOL, // memory_history — view version timeline (v2.0)
+        MEMORY_CHECKOUT_TOOL, // memory_checkout — revert to past version (v2.0)
+        // ─── v2.0: Visual Memory tools ───
+        SESSION_SAVE_IMAGE_TOOL, // session_save_image — save image to media vault (v2.0)
+        SESSION_VIEW_IMAGE_TOOL, // session_view_image — retrieve image from vault (v2.0)
+        // ─── v2.2.0: Health Check tool ───
+        SESSION_HEALTH_CHECK_TOOL, // session_health_check — brain integrity checker (v2.2.0)
+        // ─── Phase 2: GDPR Memory Deletion tool ───
+        SESSION_FORGET_MEMORY_TOOL, // session_forget_memory — GDPR-compliant memory deletion (Phase 2)
+        // ─── v3.1: TTL Retention tool ───
+        KNOWLEDGE_SET_RETENTION_TOOL, // knowledge_set_retention — set auto-expiry TTL for a project
+        // ─── v4.0: Active Behavioral Memory tools ───
+        SESSION_SAVE_EXPERIENCE_TOOL, // session_save_experience — record typed experience events
+        KNOWLEDGE_UPVOTE_TOOL, // knowledge_upvote — increase entry importance
+        KNOWLEDGE_DOWNVOTE_TOOL, // knowledge_downvote — decrease entry importance
+    ];
+}
 // ─── v0.4.0: Resource Subscription Tracking ──────────────────────
 // REVIEWER NOTE: We track which project URIs clients have subscribed
 // to. When sessionSaveHandoffHandler successfully updates a project,
@@ -194,6 +204,35 @@ export function notifyResourceUpdate(project, server) {
  *                with subscribe support for live refresh
  */
 export function createServer() {
+    // ─── v4.1 FIX: Auto-Load via Dynamic Tool Descriptions ────────
+    // Read auto-load projects EXCLUSIVELY from dashboard config
+    // (available after initConfigStorage() in startServer).
+    //
+    // ARCHITECTURE DECISION: We inject the auto-load instruction into
+    // the session_load_context TOOL DESCRIPTION, not into `instructions`
+    // or `sendLoggingMessage`. Tool descriptions are the ONLY mechanism
+    // guaranteed by ALL MCP clients (Antigravity, Claude Code, Claude CLI).
+    //
+    // 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 settings causing duplicate project loads.
+    const dashboardAutoload = getSettingSync("autoload_projects", "");
+    const autoloadList = dashboardAutoload
+        .split(",").map(p => p.trim()).filter(Boolean);
+    if (autoloadList.length > 0) {
+        console.error(`[Prism] Auto-load projects (dashboard): ${autoloadList.join(', ')}`);
+    }
+    // Build the dynamic tool list with auto-load instruction injected
+    const SESSION_MEMORY_TOOLS = buildSessionMemoryTools(autoloadList);
+    // Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
+    // can enumerate the full capability set. Runtime guards in the CallTool handler
+    // still prevent execution without valid Supabase credentials.
+    const ALL_TOOLS = [
+        ...BASE_TOOLS,
+        ...SESSION_MEMORY_TOOLS,
+        // v3.0: Agent Hivemind tools — only when PRISM_ENABLE_HIVEMIND=true
+        ...(PRISM_ENABLE_HIVEMIND ? AGENT_REGISTRY_TOOLS : []),
+    ];
     const server = new Server({
         name: SERVER_CONFIG.name,
         version: SERVER_CONFIG.version,
@@ -201,21 +240,13 @@ export function createServer() {
         capabilities: {
             tools: {},
             // ─── v0.4.0: Prompt capability (Enhancement #1) ───
-            // REVIEWER NOTE: Declaring `prompts: {}` tells Claude Desktop
-            // that we support the prompts/list and prompts/get methods.
-            // This enables the /resume_session slash command in the UI.
-            // Only enabled when Supabase is configured (prompts need
-            // session data to be useful).
             ...(SESSION_MEMORY_ENABLED ? { prompts: {} } : {}),
             // ─── v0.4.0: Resource capability (Enhancement #3) ───
-            // REVIEWER NOTE: Setting subscribe: true tells Claude Desktop
-            // that we support resource subscriptions. When a user attaches
-            // memory://project/handoff and the LLM later updates it,
-            // we push an update notification so the attached context
-            // is silently refreshed. Without subscribe:true, the
-            // paperclipped context would become stale.
             ...(SESSION_MEMORY_ENABLED ? { resources: { subscribe: true } } : {}),
         },
+        // Supplementary signal — not all clients support this field.
+        // Primary mechanism is the dynamic tool description above.
+        instructions: `Prism MCP — The Mind Palace for AI Agents. This server provides persistent session memory, knowledge search, and context management tools. Use session_load_context to recover previous work state, session_save_ledger to log completed work, and session_save_handoff to preserve state for the next session.`,
     });
     // ── Handler: Initialize ──
     // NOTE: The SDK's built-in _oninitialize() handles the Initialize request.
@@ -666,7 +697,7 @@ export function createSandboxServer() {
     });
     // Register all tool listings unconditionally
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: [...BASE_TOOLS, ...SESSION_MEMORY_TOOLS, ...AGENT_REGISTRY_TOOLS],
+        tools: [...BASE_TOOLS, ...buildSessionMemoryTools([]), ...AGENT_REGISTRY_TOOLS],
     }));
     // Register prompts listing so scanners see resume_session
     server.setRequestHandler(ListPromptsRequestSchema, async () => ({
@@ -715,6 +746,9 @@ export function createSandboxServer() {
  * responses to stdout. Log messages go to stderr.
  */
 export async function startServer() {
+    // MUST BE FIRST: Kill any zombie processes and acquire the singleton PID lock
+    // before touching SQLite. This prevents lock contention on prism-config.db.
+    acquireLock();
     // Pre-warm the config settings cache BEFORE connecting the MCP transport.
     // This ensures getSettingSync() returns real values (agent_name, default_role)
     // during the Initialize handshake — zero extra latency for resource reads.
@@ -723,6 +757,10 @@ export async function startServer() {
     const server = createServer();
     const transport = new StdioServerTransport();
     await server.connect(transport);
+    // Register graceful shutdown handlers (SIGTERM, SIGINT, SIGHUP, stdin close).
+    // The stdin close handler is critical — when MCP clients disconnect, they
+    // often just close the pipe without sending a signal, leaving zombie processes.
+    registerShutdownHandlers();
     // Pre-warm storage AFTER connecting — fired async so we never block the
     // stdio handshake. Supabase REST initialization can take 500ms–5s; blocking
     // on it before server.connect() was the root cause of the 1m 56s CLI delay.
@@ -740,6 +778,18 @@ export async function startServer() {
         ]).catch(err => {
             console.error(`[Prism] Storage pre-warm failed (non-fatal): ${err}`);
         });
+        // ─── v4.1: Auto-Load is handled via dynamic tool descriptions ──
+        // The session_load_context tool description is dynamically modified
+        // in createServer() → buildSessionMemoryTools() to include the
+        // auto-load projects list. This is the ONLY universally reliable
+        // mechanism — tool descriptions are surfaced by ALL MCP clients.
+        //
+        // Previous approaches that FAILED:
+        //   - sendLoggingMessage: goes to debug logs, not AI conversation
+        //   - instructions field: not supported by Claude Code or Claude CLI
+        //
+        // No runtime code needed here — the instruction is baked into the
+        // tool schema returned by ListTools.
     }
     // ─── v2.0 Step 6: Initialize SyncBus (Telepathy) ───
     // Fire-and-forget — SyncBus is non-critical for startup.

package/dist/storage/configStorage.js

@@ -102,17 +102,36 @@ export async function getSetting(key, defaultValue = "") {
 export async function setSetting(key, value) {
     await initConfigStorage();
     const client = getClient();
-    await client.execute({
-        sql: `
-      INSERT INTO system_settings (key, value, updated_at) 
-      VALUES (?, ?, CURRENT_TIMESTAMP)
-      ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
-    `,
-        args: [key, value],
-    });
-    // Keep the cache in sync so getSettingSync() reflects the new value immediately.
-    if (settingsCache) {
-        settingsCache[key] = value;
+    // Retry with exponential backoff for SQLITE_BUSY (concurrent writes).
+    // The dashboard and load tests can fire many parallel setting saves.
+    const MAX_RETRIES = 5;
+    const BASE_DELAY_MS = 20;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+        try {
+            await client.execute({
+                sql: `
+          INSERT INTO system_settings (key, value, updated_at) 
+          VALUES (?, ?, CURRENT_TIMESTAMP)
+          ON CONFLICT(key) DO UPDATE SET value = excluded.value, updated_at = CURRENT_TIMESTAMP
+        `,
+                args: [key, value],
+            });
+            // Keep the cache in sync so getSettingSync() reflects the new value immediately.
+            if (settingsCache) {
+                settingsCache[key] = value;
+            }
+            return; // Success — exit
+        }
+        catch (err) {
+            const isBusy = err?.code === "SQLITE_BUSY" || err?.rawCode === 5;
+            if (isBusy && attempt < MAX_RETRIES) {
+                // Exponential backoff + jitter
+                const delay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * 10;
+                await new Promise(r => setTimeout(r, delay));
+                continue;
+            }
+            throw err; // Not SQLITE_BUSY or retries exhausted
+        }
     }
 }
 export async function getAllSettings() {
@@ -129,3 +148,17 @@ export async function getAllSettings() {
     }
     return settings;
 }
+/**
+ * Closes the config SQLite client to release the file handle on prism-config.db.
+ * Called by the lifecycle module during graceful shutdown.
+ */
+export function closeConfigStorage() {
+    if (configClient) {
+        try {
+            configClient.close();
+        }
+        catch (e) {
+            console.error(`[ConfigStorage] Error closing db:`, e);
+        }
+    }
+}

package/dist/storage/supabase.js

@@ -15,10 +15,18 @@
 import { supabasePost, supabaseGet, supabaseRpc, supabasePatch, supabaseDelete, } from "../utils/supabaseApi.js";
 import { debugLog } from "../utils/logger.js";
 import { getSetting as cfgGet, setSetting as cfgSet, getAllSettings as cfgGetAll } from "./configStorage.js";
+import { runAutoMigrations } from "./supabaseMigrations.js";
 export class SupabaseStorage {
     // ─── Lifecycle ─────────────────────────────────────────────
     async initialize() {
         debugLog("[SupabaseStorage] Initialized (REST API, stateless)");
+        // Auto-apply pending schema migrations (non-fatal)
+        try {
+            await runAutoMigrations();
+        }
+        catch (err) {
+            console.error("[SupabaseStorage] Auto-migration failed. Server will continue, but some tools may be unstable.", err instanceof Error ? err.message : err);
+        }
     }
     async close() {
         debugLog("[SupabaseStorage] Closed (no-op for REST)");

package/dist/storage/supabaseMigrations.js

@@ -0,0 +1,110 @@
+/**
+ * Supabase Auto-Migration Runner (v4.1)
+ *
+ * On server startup, this module checks the `prism_schema_versions` table
+ * and applies any pending DDL migrations via the `prism_apply_ddl` RPC.
+ *
+ * ═══════════════════════════════════════════════════════════════════
+ * HOW IT WORKS:
+ *   1. For each migration in MIGRATIONS[], call prism_apply_ddl(version, name, sql)
+ *   2. The Postgres function checks if the version is already applied (idempotent)
+ *   3. If not applied, it EXECUTE's the SQL and records the version
+ *
+ * GRACEFUL DEGRADATION:
+ *   If prism_apply_ddl doesn't exist (PGRST202), the runner logs a
+ *   warning and skips — the server still starts, but v4+ tools may
+ *   fail against an old schema.
+ *
+ * SECURITY NOTE:
+ *   prism_apply_ddl is SECURITY DEFINER (runs as postgres owner).
+ *   The prism_schema_versions table has RLS: only service_role can write.
+ * ═══════════════════════════════════════════════════════════════════
+ */
+import { supabaseRpc } from "../utils/supabaseApi.js";
+/**
+ * All Supabase DDL migrations.
+ *
+ * IMPORTANT: Only add migrations for schema changes that Supabase
+ * users need. SQLite handles its own schema in sqlite.ts.
+ *
+ * Each `sql` string is passed to Postgres EXECUTE — it runs as a
+ * single transaction. Use IF NOT EXISTS / IF EXISTS guards generously.
+ */
+export const MIGRATIONS = [
+    {
+        version: 26,
+        name: "active_behavioral_memory",
+        sql: `
+      -- v4.0: Active Behavioral Memory columns
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS event_type TEXT NOT NULL DEFAULT 'session';
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS confidence_score INTEGER DEFAULT NULL;
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS importance INTEGER NOT NULL DEFAULT 0;
+
+      -- Soft-delete / archival columns
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMPTZ DEFAULT NULL;
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS archived_at TIMESTAMPTZ DEFAULT NULL;
+      ALTER TABLE session_ledger ADD COLUMN IF NOT EXISTS deleted_reason TEXT DEFAULT NULL;
+
+      -- Indexes
+      CREATE INDEX IF NOT EXISTS idx_ledger_event_type ON session_ledger(event_type);
+      CREATE INDEX IF NOT EXISTS idx_ledger_importance ON session_ledger(importance DESC);
+
+      -- Partial index for high-priority warnings
+      CREATE INDEX IF NOT EXISTS idx_ledger_behavioral_warnings
+        ON session_ledger(project, user_id, role, importance DESC)
+        WHERE event_type = 'correction' AND importance >= 3
+          AND deleted_at IS NULL AND archived_at IS NULL;
+    `,
+    },
+    // Future migrations go here (version 28+)
+];
+/**
+ * Current schema version — derived from the MIGRATIONS array.
+ * Automatically updates when new migrations are added.
+ * Used for logging and diagnostics.
+ */
+export const CURRENT_SCHEMA_VERSION = MIGRATIONS.length > 0 ? MIGRATIONS[MIGRATIONS.length - 1].version : 27;
+// ─── Runner ──────────────────────────────────────────────────────
+/**
+ * Run all pending auto-migrations on Supabase startup.
+ *
+ * Called from SupabaseStorage.initialize(). Non-fatal: if the
+ * migration infrastructure (027) hasn't been applied, the runner
+ * logs a warning and returns silently.
+ */
+export async function runAutoMigrations() {
+    if (MIGRATIONS.length === 0) {
+        return; // Nothing to apply
+    }
+    console.error(`[Prism Auto-Migration] Schema v${CURRENT_SCHEMA_VERSION} — checking ${MIGRATIONS.length} migration(s)…`);
+    for (const migration of MIGRATIONS) {
+        try {
+            const result = await supabaseRpc("prism_apply_ddl", {
+                p_version: migration.version,
+                p_name: migration.name,
+                p_sql: migration.sql,
+            });
+            // Parse the JSON result from the RPC
+            const data = (typeof result === "string" ? JSON.parse(result) : result);
+            if (data?.status === "applied") {
+                console.error(`[Prism Auto-Migration] ✅ Applied migration ${migration.version}: ${migration.name}`);
+            }
+            else if (data?.status === "already_applied") {
+                // Silent skip — expected for idempotent restarts
+            }
+        }
+        catch (err) {
+            const errMsg = err instanceof Error ? err.message : String(err);
+            // PGRST202 = function not found → migration infra (027) not applied yet
+            if (errMsg.includes("PGRST202") || errMsg.includes("Could not find the function")) {
+                console.error("[Prism Auto-Migration] ⚠️  prism_apply_ddl() not found. " +
+                    "Apply migration 027_auto_migration_infra.sql to enable auto-migrations.\n" +
+                    "  Run: supabase db push  (or apply the SQL in the Supabase Dashboard SQL Editor)");
+                return; // Stop — no point trying further migrations
+            }
+            // Any other error: log and throw to surface the problem
+            console.error(`[Prism Auto-Migration] ❌ Migration ${migration.version} (${migration.name}) failed: ${errMsg}`);
+            throw err;
+        }
+    }
+}

package/dist/tools/sessionMemoryHandlers.js

@@ -55,6 +55,23 @@ export async function sessionSaveLedgerHandler(args) {
     }
     const { project, conversation_id, summary, todos, files_changed, decisions, role } = args;
     const storage = await getStorage();
+    // ─── Repo path mismatch validation (v4.2) ───
+    let repoPathWarning = "";
+    if (files_changed && files_changed.length > 0) {
+        try {
+            const configuredPath = await getSetting(`repo_path:${project}`, "");
+            if (configuredPath && configuredPath.trim()) {
+                const normalizedPath = configuredPath.trim().replace(/\\/g, "/").replace(/\/+$/, ""); // normalize + strip trailing slash
+                const mismatched = files_changed.filter((f) => !f.replace(/\\/g, "/").startsWith(normalizedPath));
+                if (mismatched.length === files_changed.length) {
+                    repoPathWarning = `\n\n⚠️ Project mismatch: none of the files_changed paths match repo_path "${normalizedPath}" ` +
+                        `configured for project "${project}". Consider saving under the correct project.`;
+                    debugLog(`[session_save_ledger] Repo path mismatch for "${project}": expected prefix "${normalizedPath}"`);
+                }
+            }
+        }
+        catch { /* getSetting non-fatal */ }
+    }
     debugLog(`[session_save_ledger] Saving ledger entry for project="${project}"`);
     // Auto-extract keywords from summary + decisions for knowledge accumulation
     const combinedText = [summary, ...(decisions || [])].join(" ");
@@ -130,6 +147,7 @@ export async function sessionSaveLedgerHandler(args) {
                     (files_changed?.length ? `Files changed: ${files_changed.length}\n` : "") +
                     (decisions?.length ? `Decisions: ${decisions.length}\n` : "") +
                     (GOOGLE_API_KEY ? `📊 Embedding generation queued for semantic search.\n` : "") +
+                    repoPathWarning +
                     `\nRaw response: ${JSON.stringify(result)}`,
             }],
         isError: false,
@@ -360,7 +378,8 @@ export async function sessionLoadContextHandler(args) {
         throw new Error("Invalid arguments for session_load_context");
     }
     const { project, level = "standard", role } = args;
-    const maxTokens = args.max_tokens; // v4.0
+    const maxTokens = args.max_tokens
+        || parseInt(await getSetting("max_tokens", "0"), 10) || undefined; // v4.0: arg > dashboard setting > none
     const agentName = await getSetting("agent_name", "");
     const validLevels = ["quick", "standard", "deep"];
     if (!validLevels.includes(level)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "4.0.0",
+  "version": "4.2.0",
   "mcpName": "io.github.dcostenco/prism-mcp",
   "description": "The Mind Palace for AI Agents — local-first MCP server with persistent memory (SQLite/Supabase), visual dashboard, time travel, multi-agent sync, Morning Briefings, reality drift detection, code mode templates, semantic vector search, and Brave Search + Gemini analysis. Zero-config local mode.",
   "module": "index.ts",