prism-mcp-server 3.0.0 → 3.1.0

package/README.md

@@ -14,7 +14,7 @@
 
 ## Table of Contents
 
-- [What's New (v3.0.0)](#whats-new-in-v300---agent-hivemind-)
+- [What's New (v3.1.0)](#whats-new-in-v310---memory-lifecycle-)
 - [How Prism Compares](#how-prism-compares)
 - [Quick Start](#quick-start-zero-config--local-mode)
 - [Mind Palace Dashboard](#-the-mind-palace-dashboard)
@@ -22,6 +22,7 @@
 - [Use Cases](#use-cases)
 - [Architecture](#architecture)
 - [Tool Reference](#tool-reference)
+- [Agent Hivemind — Role Usage](#agent-hivemind--role-usage)
 - [LangChain / LangGraph Integration](#langchain--langgraph-integration)
 - [Environment Variables](#environment-variables)
 - [Boot Settings (Restart Required)](#-boot-settings-restart-required)
@@ -38,7 +39,30 @@
 
 ---
 
-## What's New in v3.0.0 — Agent Hivemind 🐝
+## What's New in v3.1.0 — Memory Lifecycle 🔄
+
+| 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. |
+
+<details>
+<summary><strong>What's in v3.0.1 — Agent Identity & Brain Clean-up 🧹</strong></summary>
+
+| Feature | Description |
+|---|---|
+| 🧹 **Brain Health Clean-up** | New **Fix Issues** button in the Mind Palace Dashboard's Brain Health card — detects orphaned handoffs, missing embeddings, and stale rollups, then cleans them up in one click without needing the MCP tool. |
+| 👤 **Agent Identity Settings** | Dashboard Settings → Agent Identity panel lets you set a **Default Role** (`dev`, `qa`, `pm`…) and **Agent Name** (e.g. `Dmitri`). Both values auto-apply as fallbacks in all memory and Hivemind tools — no need to pass them per call. |
+| 📜 **Role-Scoped Skills** | Each agent role can have its own persistent skill/rules document stored in the dashboard (⚙️ Settings → Skills). It is automatically injected into every `session_load_context` response so the agent boots with its rules pre-loaded. |
+| 🔤 **Resource Formatting Fix** | `memory://{project}/handoff` resources now render as formatted plain text (Last Summary, TODOs, Keywords) instead of a raw JSON blob — readable in Claude Desktop's paperclip attach panel. |
+
+</details>
+
+<details>
+<summary><strong>What's in v3.0.0 — Agent Hivemind 🐝</strong></summary>
 
 | Feature | Description |
 |---|---|
@@ -50,6 +74,9 @@
 | 🔒 **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. |
 
+</details>
+
+
 <details>
 <summary><strong>What's in v2.5.0 — Enterprise Memory 🏗️</strong></summary>
 
@@ -102,7 +129,7 @@
 | Feature | Description |
 |---|---|
 | 🩺 **Brain Health Check** | `session_health_check` — like Unix `fsck` for your agent's memory. Detects missing embeddings, duplicate entries, orphaned handoffs, and stale rollups. Use `auto_fix: true` to repair automatically. |
-| 📊 **Mind Palace Health** | Brain health indicator on the Mind Palace Dashboard — see your memory integrity at a glance. |
+| 📊 **Mind Palace Health** | Brain health indicator on the Mind Palace Dashboard — see your memory integrity at a glance. **🧹 Fix Issues** button auto-deletes orphaned handoffs in one click. |
 
 </details>
 
@@ -237,11 +264,15 @@ Open **`http://localhost:3000`** in your browser to see exactly what your AI age
 ![Mind Palace Dashboard](docs/mind-palace-dashboard.png)
 
 - **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
+- **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
 - **Time Travel Timeline** — Browse historical handoff states and revert any version
 - **Visual Memory Vault** — Browse UI screenshots and auto-captured HTML states
 - **Session Ledger** — Full audit trail of every decision your agent has made
+- **Neural Graph** — Force-directed visualization of project ↔ keyword associations
+- **Hivemind Radar** — Real-time active agent roster with role, task, and heartbeat
 
 The dashboard auto-discovers all your projects and updates in real time.
 
@@ -450,6 +481,12 @@ graph TB
 | `session_search_memory` | Vector similarity search across all sessions |
 | `session_compact_ledger` | Auto-compact old ledger entries via Gemini-powered summarization |
 
+### v3.1 Lifecycle Tools
+
+| Tool | Purpose |
+|------|---------|
+| `knowledge_set_retention` | Set a per-project TTL retention policy (0 = disabled, min 7 days). Immediately expires overdue entries. |
+
 ### v2.0 Advanced Memory Tools
 
 | Tool | Purpose |
@@ -463,7 +500,15 @@ graph TB
 
 | Tool | Purpose | Key Args | Returns |
 |------|---------|----------|---------|
-| `session_health_check` | Scan brain for integrity issues (`fsck`) | `auto_fix` (boolean) | Health report & auto-repairs |
+| `session_health_check` | Scan brain for integrity issues (`fsck`) | `project`, `auto_fix` (boolean) | Health report & auto-repairs |
+
+The **Mind Palace Dashboard** also shows a live **Brain Health 🩺** card for every project:
+
+- **Status indicator** — `✅ Healthy` or `⚠️ Issues detected` with entry/handoff/rollup counts
+- **🧹 Fix Issues button** — appears automatically when issues are detected; click to clean up orphaned handoffs and stale rollups in one click, no MCP tool call required
+- **No issues found** — shown in green when memory integrity is confirmed
+
+The tool and dashboard button both call the same repair logic — the dashboard button is simply a zero-friction shortcut for common maintenance.
 
 ### v2.5 Enterprise Memory Tools
 
@@ -492,6 +537,110 @@ Instead of writing custom JavaScript, pass a `template` name for instant extract
 
 ---
 
+## Agent Hivemind — Role Usage
+
+Role-scoped memory lets multiple agents work on the same project without stepping on each other's memory. Each role gets its own isolated memory lane. Defaults to `global` for full backward compatibility.
+
+### Available Roles
+
+| Role | Use for |
+|------|---------|
+| `dev` | Development agent |
+| `qa` | Testing / QA agent |
+| `pm` | Product management |
+| `lead` | Tech lead / orchestrator |
+| `security` | Security review |
+| `ux` | Design / UX |
+| `global` | Default — shared, no isolation |
+
+Custom role strings are also supported (e.g. `"docs"`, `"ml"`).
+
+### Using Roles with Memory Tools
+
+Just add `"role"` to any of the core memory tools:
+
+```json
+// Save a ledger entry as the "dev" agent
+{ "name": "session_save_ledger", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "conversation_id": "abc123",
+  "summary": "Fixed the auth race condition"
+}}
+
+// Load context scoped to your role
+// Also injects a Team Roster showing active teammates
+{ "name": "session_load_context", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "level": "standard"
+}}
+
+// Save handoff as the "qa" agent
+{ "name": "session_save_handoff", "arguments": {
+  "project": "my-app",
+  "role": "qa",
+  "last_summary": "Ran regression suite — 2 failures in auth module"
+}}
+```
+
+### Hivemind Coordination Tools
+
+> **Requires:** `PRISM_ENABLE_HIVEMIND=true` (Boot Setting — restart required)
+
+```json
+// Announce yourself to the team at session start
+{ "name": "agent_register", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "agent_name": "Dev Agent #1",
+  "current_task": "Refactoring auth module"
+}}
+
+// Pulse every ~5 min to stay visible (agents pruned after 30 min)
+{ "name": "agent_heartbeat", "arguments": {
+  "project": "my-app",
+  "role": "dev",
+  "current_task": "Now writing tests"
+}}
+
+// See everyone on the team
+{ "name": "agent_list_team", "arguments": {
+  "project": "my-app"
+}}
+```
+
+### How Role Isolation Works
+
+- `session_load_context` with `role: "dev"` only sees entries saved with `role: "dev"`
+- The `global` role is a shared pool — anything saved without a role goes here
+- When loading *with* a role, Prism auto-injects a **Team Roster** block listing active teammates, roles, and tasks — no extra tool call needed
+- The Hivemind Radar widget in the Mind Palace dashboard shows agent activity in real time
+
+### Setting Your Agent Identity
+
+The easiest way to configure your role and name is via the **Mind Palace Dashboard ⚙️ Settings → Agent Identity**:
+
+- **Default Role** — dropdown to select `dev`, `qa`, `pm`, `lead`, `security`, `ux`, or `global`
+- **Agent Name** — free text for your display name (e.g. `Dmitri`, `Dev Alex`, `QA Bot`)
+
+Once set, **all memory and Hivemind tools automatically use these values** as fallbacks — no need to pass `role` or `agent_name` in every tool call.
+
+> **Priority order:** explicit tool arg → dashboard setting → `"global"` (default)
+
+**Alternative — hardcode in your startup rules** (if you prefer prompt-level config):
+
+```markdown
+## Prism MCP Memory Auto-Load (CRITICAL)
+At the start of every new session, call session_load_context with:
+- project: "my-app", role: "dev"
+- project: "my-other-project", role: "dev"
+```
+
+> **Tip:** For true multi-agent setups, each AI instance has its own Mind Palace dashboard — set a different identity per agent there rather than managing it in prompts.
+
+---
+
 ## LangChain / LangGraph Integration
 
 Prism MCP includes first-class Python adapters for the LangChain ecosystem, located in `examples/langgraph-agent/`:
@@ -979,14 +1128,19 @@ 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!)
+
+See [What's New in v3.0.1](#whats-new-in-v301---agent-identity--brain-clean-up-) above.
+
 ### ✅ v3.0 — Agent Hivemind (Shipped!)
 
-See [What's New in v3.0.0](#whats-new-in-v300---agent-hivemind-) above.
+See [What's New in v3.0.0 — Agent Hivemind](#whats-new-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 |

package/dist/dashboard/server.js

@@ -21,6 +21,8 @@ import { exec } from "child_process";
 import { getStorage } from "../storage/index.js";
 import { PRISM_USER_ID, SERVER_CONFIG } from "../config.js";
 import { renderDashboardHTML } from "./ui.js";
+import { getAllSettings, setSetting, getSetting } from "../storage/configStorage.js";
+import { compactLedgerHandler } from "../tools/compactionHandler.js";
 const PORT = parseInt(process.env.PRISM_DASHBOARD_PORT || "3000", 10);
 /** Read HTTP request body as string */
 function readBody(req) {
@@ -73,9 +75,24 @@ async function killPortHolder(port) {
     });
 }
 export async function startDashboardServer() {
-    // Clean up any zombie dashboard process from a previous session
-    await killPortHolder(PORT);
-    const storage = await getStorage();
+    // Fire-and-forget port cleanup — don't block server start.
+    // Previously awaiting this added 300ms+ delay from lsof + setTimeout,
+    // starving the MCP stdio transport during the init handshake.
+    killPortHolder(PORT).catch(() => { });
+    // Lazy storage accessor — returns null if storage isn't ready yet.
+    // API routes gracefully degrade with 503 instead of blocking startup.
+    let _storage = null;
+    const getStorageSafe = async () => {
+        if (_storage)
+            return _storage;
+        try {
+            _storage = await getStorage();
+            return _storage;
+        }
+        catch {
+            return null;
+        }
+    };
     const httpServer = http.createServer(async (req, res) => {
         // CORS headers for local dev
         res.setHeader("Access-Control-Allow-Origin", "*");
@@ -97,7 +114,12 @@ export async function startDashboardServer() {
             }
             // ─── API: List all projects ───
             if (url.pathname === "/api/projects") {
-                const projects = await storage.listProjects();
+                const s = await getStorageSafe();
+                if (!s) {
+                    res.writeHead(503, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                }
+                const projects = await s.listProjects();
                 res.writeHead(200, { "Content-Type": "application/json" });
                 return res.end(JSON.stringify({ projects }));
             }
@@ -108,15 +130,20 @@ export async function startDashboardServer() {
                     res.writeHead(400, { "Content-Type": "application/json" });
                     return res.end(JSON.stringify({ error: "Missing ?name= parameter" }));
                 }
-                const context = await storage.loadContext(projectName, "deep", PRISM_USER_ID);
-                const ledger = await storage.getLedgerEntries({
+                const s = await getStorageSafe();
+                if (!s) {
+                    res.writeHead(503, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                }
+                const context = await s.loadContext(projectName, "deep", PRISM_USER_ID);
+                const ledger = await s.getLedgerEntries({
                     project: `eq.${projectName}`,
                     order: "created_at.desc",
                     limit: "20",
                 });
                 let history = [];
                 try {
-                    history = await storage.getHistory(projectName, PRISM_USER_ID, 10);
+                    history = await s.getHistory(projectName, PRISM_USER_ID, 10);
                 }
                 catch {
                     // History may not exist for all projects
@@ -125,10 +152,15 @@ export async function startDashboardServer() {
                 return res.end(JSON.stringify({ context, ledger, history }));
             }
             // ─── API: Brain Health Check (v2.2.0) ───
-            if (url.pathname === "/api/health") {
+            if (url.pathname === "/api/health" && req.method === "GET") {
                 try {
                     const { runHealthCheck } = await import("../utils/healthCheck.js");
-                    const stats = await storage.getHealthStats(PRISM_USER_ID);
+                    const s = await getStorageSafe();
+                    if (!s) {
+                        res.writeHead(503, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                    }
+                    const stats = await s.getHealthStats(PRISM_USER_ID);
                     const report = runHealthCheck(stats);
                     res.writeHead(200, { "Content-Type": "application/json" });
                     return res.end(JSON.stringify(report));
@@ -146,11 +178,93 @@ export async function startDashboardServer() {
                     }));
                 }
             }
+            // ─── API: Brain Health Cleanup (v3.1) ───
+            // Deletes orphaned handoffs (handoffs with no backing ledger entries).
+            if (url.pathname === "/api/health/cleanup" && req.method === "POST") {
+                try {
+                    const { runHealthCheck } = await import("../utils/healthCheck.js");
+                    const s = await getStorageSafe();
+                    if (!s) {
+                        res.writeHead(503, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                    }
+                    const stats = await s.getHealthStats(PRISM_USER_ID);
+                    const report = runHealthCheck(stats);
+                    // Collect orphaned handoff projects from the health issues
+                    const orphaned = stats.orphanedHandoffs || [];
+                    const cleaned = [];
+                    for (const { project } of orphaned) {
+                        try {
+                            await s.deleteHandoff(project, PRISM_USER_ID);
+                            cleaned.push(project);
+                            console.error(`[Dashboard] Cleaned up orphaned handoff: ${project}`);
+                        }
+                        catch (delErr) {
+                            console.error(`[Dashboard] Failed to delete handoff for ${project}:`, delErr);
+                        }
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({
+                        ok: true,
+                        cleaned,
+                        count: cleaned.length,
+                        message: cleaned.length > 0
+                            ? `Cleaned up ${cleaned.length} orphaned handoff(s): ${cleaned.join(", ")}`
+                            : "No orphaned handoffs to clean up.",
+                    }));
+                }
+                catch (err) {
+                    console.error("[Dashboard] Health cleanup error:", err);
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ ok: false, error: "Cleanup failed" }));
+                }
+            }
+            // ─── API: Role-Scoped Skills (v3.1) ───
+            // GET /api/skills → { skills: { dev: "...", qa: "..." } }
+            if (url.pathname === "/api/skills" && req.method === "GET") {
+                const all = await getAllSettings();
+                const skills = {};
+                for (const [k, v] of Object.entries(all)) {
+                    if (k.startsWith("skill:") && v) {
+                        skills[k.replace("skill:", "")] = v;
+                    }
+                }
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ skills }));
+            }
+            // POST /api/skills → { role, content } saves skill:<role>
+            if (url.pathname === "/api/skills" && req.method === "POST") {
+                const body = await new Promise(resolve => {
+                    let data = "";
+                    req.on("data", c => data += c);
+                    req.on("end", () => resolve(data));
+                });
+                const { role, content } = JSON.parse(body || "{}");
+                if (!role) {
+                    res.writeHead(400);
+                    return res.end(JSON.stringify({ error: "role required" }));
+                }
+                await setSetting(`skill:${role}`, content || "");
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ ok: true, role }));
+            }
+            // DELETE /api/skills/:role → clears skill:<role>
+            if (url.pathname.startsWith("/api/skills/") && req.method === "DELETE") {
+                const role = url.pathname.replace("/api/skills/", "");
+                await setSetting(`skill:${role}`, "");
+                res.writeHead(200, { "Content-Type": "application/json" });
+                return res.end(JSON.stringify({ ok: true, role }));
+            }
             // ─── API: Knowledge Graph Data (v2.3.0) ───
             if (url.pathname === "/api/graph") {
                 // Fetch recent ledger entries to build the graph
                 // We look at the last 100 entries to keep the graph relevant but performant
-                const entries = await storage.getLedgerEntries({
+                const s = await getStorageSafe();
+                if (!s) {
+                    res.writeHead(503, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                }
+                const entries = await s.getLedgerEntries({
                     limit: "100",
                     order: "created_at.desc",
                     select: "project,keywords",
@@ -216,7 +330,12 @@ export async function startDashboardServer() {
                     return res.end(JSON.stringify({ error: "Missing ?project= parameter" }));
                 }
                 try {
-                    const team = await storage.listTeam(projectName, PRISM_USER_ID);
+                    const s = await getStorageSafe();
+                    if (!s) {
+                        res.writeHead(503, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                    }
+                    const team = await s.listTeam(projectName, PRISM_USER_ID);
                     res.writeHead(200, { "Content-Type": "application/json" });
                     return res.end(JSON.stringify({ team }));
                 }
@@ -257,6 +376,167 @@ export async function startDashboardServer() {
                     return res.end(JSON.stringify({ error: "Invalid JSON body" }));
                 }
             }
+            // ─── API: Memory Analytics (v3.1) ────────────────────
+            if (url.pathname === "/api/analytics" && req.method === "GET") {
+                const projectName = url.searchParams.get("project");
+                if (!projectName) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Missing ?project= parameter" }));
+                }
+                try {
+                    const s = await getStorageSafe();
+                    if (!s) {
+                        res.writeHead(503, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                    }
+                    const analytics = await s.getAnalytics(projectName, PRISM_USER_ID);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify(analytics));
+                }
+                catch (err) {
+                    console.error("[Dashboard] Analytics error:", err);
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({
+                        totalEntries: 0, totalRollups: 0, rollupSavings: 0,
+                        avgSummaryLength: 0, sessionsByDay: [],
+                    }));
+                }
+            }
+            // ─── API: Retention (TTL) Settings (v3.1) ──────────────
+            // GET /api/retention?project= → current TTL setting
+            // POST /api/retention → { project, ttl_days } → saves + runs sweep
+            if (url.pathname === "/api/retention") {
+                if (req.method === "GET") {
+                    const projectName = url.searchParams.get("project");
+                    if (!projectName) {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Missing ?project= parameter" }));
+                    }
+                    const ttlRaw = await getSetting(`ttl:${projectName}`, "0");
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ project: projectName, ttl_days: parseInt(ttlRaw, 10) || 0 }));
+                }
+                if (req.method === "POST") {
+                    const body = await readBody(req);
+                    const { project, ttl_days } = JSON.parse(body || "{}");
+                    if (!project || ttl_days === undefined) {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "project and ttl_days required" }));
+                    }
+                    if (ttl_days > 0 && ttl_days < 7) {
+                        res.writeHead(400, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Minimum TTL is 7 days" }));
+                    }
+                    await setSetting(`ttl:${project}`, String(ttl_days));
+                    let expired = 0;
+                    if (ttl_days > 0) {
+                        const s = await getStorageSafe();
+                        if (!s) {
+                            res.writeHead(503, { "Content-Type": "application/json" });
+                            return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                        }
+                        const result = await s.expireByTTL(project, ttl_days, PRISM_USER_ID);
+                        expired = result.expired;
+                    }
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ ok: true, project, ttl_days, expired }));
+                }
+            }
+            // ─── API: Compact Now (v3.1 — Dashboard button) ──────────
+            if (url.pathname === "/api/compact" && req.method === "POST") {
+                const body = await readBody(req);
+                const { project } = JSON.parse(body || "{}");
+                if (!project) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "project required" }));
+                }
+                try {
+                    const result = await compactLedgerHandler({ project });
+                    res.writeHead(200, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ ok: true, result }));
+                }
+                catch (err) {
+                    console.error("[Dashboard] Compact error:", err);
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ ok: false, error: "Compaction failed" }));
+                }
+            }
+            // ─── API: PKM Export — Obsidian/Logseq ZIP (v3.1) ──────
+            if (url.pathname === "/api/export" && req.method === "GET") {
+                const projectName = url.searchParams.get("project");
+                if (!projectName) {
+                    res.writeHead(400, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Missing ?project= parameter" }));
+                }
+                try {
+                    // Lazy-import fflate to keep startup fast
+                    const { strToU8, zipSync } = await import("fflate");
+                    // Fetch all active ledger entries for this project
+                    const s = await getStorageSafe();
+                    if (!s) {
+                        res.writeHead(503, { "Content-Type": "application/json" });
+                        return res.end(JSON.stringify({ error: "Storage initializing..." }));
+                    }
+                    const entries = await s.getLedgerEntries({
+                        project: `eq.${projectName}`,
+                        order: "created_at.asc",
+                        limit: "1000",
+                    });
+                    const files = {};
+                    // One MD file per session
+                    for (const entry of entries) {
+                        const date = entry.created_at?.slice(0, 10) ?? "unknown";
+                        const id = entry.id?.slice(0, 8) ?? "xxxxxxxx";
+                        const filename = `${projectName}/${date}-${id}.md`;
+                        const todos = Array.isArray(entry.todos) ? entry.todos : [];
+                        const decisions = Array.isArray(entry.decisions) ? entry.decisions : [];
+                        const files_changed = Array.isArray(entry.files_changed) ? entry.files_changed : [];
+                        const tags = (Array.isArray(entry.keywords) ? entry.keywords : []).slice(0, 10);
+                        const content = [
+                            `# Session: ${date}`,
+                            ``,
+                            `**Project:** ${projectName}`,
+                            `**Date:** ${date}`,
+                            `**Role:** ${entry.role || "global"}`,
+                            tags.length ? `**Tags:** ${tags.map(t => `#${t.replace(/\s+/g, "_")}`).join(" ")}` : "",
+                            ``,
+                            `## Summary`,
+                            ``,
+                            entry.summary,
+                            ``,
+                            todos.length ? `## TODOs\n\n${todos.map(t => `- [ ] ${t}`).join("\n")}` : "",
+                            decisions.length ? `## Decisions\n\n${decisions.map(d => `- ${d}`).join("\n")}` : "",
+                            files_changed.length ? `## Files Changed\n\n${files_changed.map(f => `- \`${f}\``).join("\n")}` : "",
+                        ].filter(Boolean).join("\n");
+                        files[filename] = strToU8(content);
+                    }
+                    // Index file linking all sessions
+                    const indexLines = [
+                        `# ${projectName} — Session Index`,
+                        ``,
+                        `> Exported from Prism MCP on ${new Date().toISOString().slice(0, 10)}`,
+                        ``,
+                        ...entries.map(e => {
+                            const d = e.created_at?.slice(0, 10) ?? "unknown";
+                            const i = e.id?.slice(0, 8) ?? "xxxxxxxx";
+                            return `- [[${projectName}/${d}-${i}]]`;
+                        }),
+                    ];
+                    files[`${projectName}/_index.md`] = strToU8(indexLines.join("\n"));
+                    const zipped = zipSync(files, { level: 6 });
+                    res.writeHead(200, {
+                        "Content-Type": "application/zip",
+                        "Content-Disposition": `attachment; filename="prism-export-${projectName}-${Date.now()}.zip"`,
+                        "Content-Length": String(zipped.byteLength),
+                    });
+                    return res.end(Buffer.from(zipped));
+                }
+                catch (err) {
+                    console.error("[Dashboard] PKM export error:", err);
+                    res.writeHead(500, { "Content-Type": "application/json" });
+                    return res.end(JSON.stringify({ error: "Export failed" }));
+                }
+            }
             // ─── 404 ───
             res.writeHead(404, { "Content-Type": "text/plain" });
             res.end("Not found");
@@ -280,4 +560,31 @@ export async function startDashboardServer() {
     httpServer.listen(PORT, () => {
         console.error(`[Prism] 🧠 Mind Palace Dashboard → http://localhost:${PORT}`);
     });
+    // ─── v3.1: TTL Sweep — runs at startup + every 12 hours ───────────
+    async function runTtlSweep() {
+        try {
+            const allSettings = await getAllSettings();
+            for (const [key, val] of Object.entries(allSettings)) {
+                if (!key.startsWith("ttl:"))
+                    continue;
+                const project = key.replace("ttl:", "");
+                const ttlDays = parseInt(val, 10);
+                if (!ttlDays || ttlDays <= 0)
+                    continue;
+                const s = await getStorageSafe();
+                if (!s)
+                    continue;
+                const result = await s.expireByTTL(project, ttlDays, PRISM_USER_ID);
+                if (result.expired > 0) {
+                    console.error(`[Dashboard] TTL sweep: expired ${result.expired} entries for "${project}" (ttl=${ttlDays}d)`);
+                }
+            }
+        }
+        catch (err) {
+            console.error("[Dashboard] TTL sweep error (non-fatal):", err);
+        }
+    }
+    // Run immediately on startup, then every 12 hours
+    runTtlSweep().catch(() => { });
+    setInterval(() => { runTtlSweep().catch(() => { }); }, 12 * 60 * 60 * 1000);
 }