prism-mcp-server 2.3.12 → 2.5.1

package/README.md

@@ -8,13 +8,56 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![Node.js](https://img.shields.io/badge/Node.js-18+-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 
-> **Your AI agent's memory that survives between sessions.** Prism MCP is a Model Context Protocol server that gives Claude Desktop, Cursor, Windsurf, and any MCP client **persistent memory**, **time travel**, **visual context**, **multi-agent sync**, and **multi-engine search** — all running locally with zero cloud dependencies.
+> **Your AI agent's memory that survives between sessions.** Prism MCP is a Model Context Protocol server that gives Claude Desktop, Cursor, Windsurf, and any MCP client **persistent memory**, **time travel**, **visual context**, **multi-agent sync**, **GDPR-compliant deletion**, **memory tracing**, and **LangChain integration** — all running locally with zero cloud dependencies.
 >
-> Built with **SQLite + F32_BLOB vector search**, **optimistic concurrency control**, **MCP Prompts & Resources**, **auto-compaction**, **Gemini-powered Morning Briefings**, and optional **Supabase cloud sync**.
+> Built with **SQLite + F32_BLOB vector search**, **optimistic concurrency control**, **MCP Prompts & Resources**, **auto-compaction**, **Gemini-powered Morning Briefings**, **MemoryTrace explainability**, and optional **Supabase cloud sync**.
+
+## Table of Contents
+
+- [What's New (v2.5.0)](#whats-new-in-v250---enterprise-memory-)
+- [How Prism Compares](#how-prism-compares)
+- [Quick Start](#quick-start-zero-config--local-mode)
+- [Mind Palace Dashboard](#-the-mind-palace-dashboard)
+- [Integration Examples](#integration-examples)
+- [Use Cases](#use-cases)
+- [Architecture](#architecture)
+- [Tool Reference](#tool-reference)
+- [LangChain / LangGraph Integration](#langchain--langgraph-integration)
+- [Environment Variables](#environment-variables)
+- [Progressive Context Loading](#progressive-context-loading)
+- [Time Travel](#time-travel-version-history)
+- [Agent Telepathy](#agent-telepathy-multi-client-sync)
+- [Knowledge Accumulation](#knowledge-accumulation)
+- [GDPR Compliance](#gdpr-compliance)
+- [Observability & Tracing](#observability--tracing)
+- [Supabase Setup](#supabase-setup-cloud-mode)
+- [Project Structure](#project-structure)
+- [Hybrid Search Pipeline](#hybrid-search-pipeline-brave--vertex-ai)
+- [🚀 Roadmap](#-roadmap)
 
 ---
 
-## What's New in v2.3.12 — Stability & Fixes 🛠️
+## What's New in v2.5.0 — Enterprise Memory 🏗️
+
+| 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. |
+
+<details>
+<summary><strong>What's in v2.5.1 — Version Sync & Embedding Safety</strong></summary>
+
+| 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. |
+
+</details>
+
+<details>
+<summary><strong>What's in v2.3.12 — Stability & Fixes</strong></summary>
 
 | Feature | Description |
 |---|---|
@@ -22,6 +65,8 @@
 | 📝 **Debug Logging** | Gated verbose startup logs behind `PRISM_DEBUG_LOGGING` for a cleaner default experience. |
 | ⚡ **Excess Loading Fixes** | Performance improvements to resolve excess loading loops. |
 
+</details>
+
 <details>
 <summary><strong>What's in v2.3.8 — LangGraph Research Agent</strong></summary>
 
@@ -63,6 +108,8 @@
 
 ---
 
+> 💡 **TL;DR:** Prism MCP gives your AI agent persistent memory using a local SQLite database. No cloud accounts, no API keys, and no Postgres/Qdrant containers required. Just `npx -y prism-mcp-server` and you're running.
+
 ## How Prism Compares
 
 | 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) |
@@ -82,6 +129,9 @@
 | **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 |
 | **Language** | TypeScript | TypeScript | Python | Python | Python |
 
@@ -158,7 +208,7 @@ Then add to your MCP config:
 }
 ```
 
-### Restart your MCP client. That's it — all tools are now available.
+**Restart your MCP client. That's it — all tools are now available.**
 
 ---
 
@@ -168,6 +218,8 @@ Prism MCP spins up a lightweight, zero-dependency HTTP server alongside the MCP
 
 Open **`http://localhost:3000`** in your browser to see exactly what your AI agent is thinking:
 
+![Mind Palace Dashboard](docs/mind-palace-dashboard.png)
+
 - **Current State & TODOs** — See the exact context injected into the LLM's prompt
 - **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
@@ -316,32 +368,39 @@ Verification pattern (same for both clients):
 ```mermaid
 graph TB
     Client["AI Client<br/>(Claude Desktop / Cursor / Windsurf)"]
+    LangChain["LangChain / LangGraph<br/>(Python Retrievers)"]
     MCP["Prism MCP Server<br/>(TypeScript)"]
     
     Client -- "MCP Protocol (stdio)" --> MCP
+    LangChain -- "JSON-RPC via MCP Bridge" --> MCP
     
+    MCP --> Tracing["MemoryTrace Engine<br/>Latency + Strategy + Scoring"]
     MCP --> Dashboard["Mind Palace Dashboard<br/>localhost:3000"]
     MCP --> Brave["Brave Search API<br/>Web + Local + AI Answers"]
     MCP --> Gemini["Google Gemini API<br/>Analysis + Briefings"]
     MCP --> Sandbox["QuickJS Sandbox<br/>Code-Mode Templates"]
     MCP --> SyncBus["SyncBus<br/>Agent Telepathy"]
+    MCP --> GDPR["GDPR Engine<br/>Soft/Hard Delete + Audit"]
     
     MCP --> Storage{"Storage Backend"}
     Storage --> SQLite["SQLite (Local)<br/>libSQL + F32_BLOB vectors"]
     Storage --> Supabase["Supabase (Cloud)<br/>PostgreSQL + pgvector"]
     
-    SQLite --> Ledger["session_ledger"]
+    SQLite --> Ledger["session_ledger<br/>(+ deleted_at tombstoning)"]
     SQLite --> Handoffs["session_handoffs"]
     SQLite --> History["history_snapshots<br/>(Time Travel)"]
     SQLite --> Media["media vault<br/>(Visual Memory)"]
     
     style Client fill:#4A90D9,color:#fff
+    style LangChain fill:#1C3D5A,color:#fff
     style MCP fill:#2D3748,color:#fff
+    style Tracing fill:#D69E2E,color:#fff
     style Dashboard fill:#9F7AEA,color:#fff
     style Brave fill:#FB542B,color:#fff
     style Gemini fill:#4285F4,color:#fff
     style Sandbox fill:#805AD5,color:#fff
     style SyncBus fill:#ED64A6,color:#fff
+    style GDPR fill:#E53E3E,color:#fff
     style Storage fill:#2D3748,color:#fff
     style SQLite fill:#38B2AC,color:#fff
     style Supabase fill:#3ECF8E,color:#fff
@@ -390,6 +449,14 @@ graph TB
 |------|---------|----------|---------|
 | `session_health_check` | Scan brain for integrity issues (`fsck`) | `auto_fix` (boolean) | Health report & auto-repairs |
 
+### v2.5 Enterprise Memory Tools
+
+| Tool | Purpose | Key Args | Returns |
+|------|---------|----------|---------|
+| `session_forget_memory` | GDPR-compliant deletion (soft/hard) | `memory_id`, `hard_delete`, `reason` | Deletion confirmation + audit |
+| `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]` |
+
 ### Code Mode Templates (v2.1)
 
 Instead of writing custom JavaScript, pass a `template` name for instant extraction:
@@ -405,7 +472,54 @@ Instead of writing custom JavaScript, pass a `template` name for instant extract
 | `slack_messages` | Slack Web API | `[timestamp] @user: message` |
 | `csv_summary` | CSV text | Column names, row count, sample rows |
 
-**Usage:** `{ "data": "<raw JSON>", "template": "github_issues" }` — no custom code needed.
+**Tool Arguments:** `{ "data": "<raw JSON>", "template": "github_issues" }` — no custom code needed.
+
+---
+
+## LangChain / LangGraph Integration
+
+Prism MCP includes first-class Python adapters for the LangChain ecosystem, located in `examples/langgraph-agent/`:
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| **MCP Bridge** | `mcp_client.py` | JSON-RPC 2.0 client with `call_tool()` and `call_tool_raw()` (preserves `MemoryTrace`) |
+| **Semantic Retriever** | `prism_retriever.py` | `PrismMemoryRetriever(BaseRetriever)` — async-first vector search |
+| **Keyword Retriever** | `prism_retriever.py` | `PrismKnowledgeRetriever(BaseRetriever)` — FTS5 keyword search |
+| **Forget Tool** | `tools.py` | `forget_memory()` — GDPR deletion bridge |
+| **Research Agent** | `agent.py` | 5-node LangGraph agent (plan→search→analyze→decide→answer→save) |
+
+### Hybrid Search with EnsembleRetriever
+
+Combine both retrievers for hybrid (semantic + keyword) search with a single line:
+
+```python
+from langchain.retrievers import EnsembleRetriever
+from prism_retriever import PrismMemoryRetriever, PrismKnowledgeRetriever
+
+retriever = EnsembleRetriever(
+    retrievers=[PrismMemoryRetriever(...), PrismKnowledgeRetriever(...)],
+    weights=[0.7, 0.3],  # 70% semantic, 30% keyword
+)
+```
+
+### MemoryTrace in LangSmith
+
+When `enable_trace=True`, each `Document.metadata["trace"]` contains:
+
+```json
+{
+  "strategy": "vector_cosine_similarity",
+  "latency": { "embedding_ms": 45, "storage_ms": 12, "total_ms": 57 },
+  "result_count": 5,
+  "threshold": 0.7
+}
+```
+
+This metadata flows automatically into LangSmith traces for observability.
+
+### Async Architecture
+
+The retrievers use `_aget_relevant_documents` as the primary path with `asyncio.to_thread()` to wrap the synchronous MCP bridge. This prevents the `RuntimeError: This event loop is already running` crash that plagues most LangGraph deployments.
 
 ---
 
@@ -422,6 +536,7 @@ Instead of writing custom JavaScript, pass a `template` name for instant extract
 | `PRISM_USER_ID` | No | Multi-tenant user isolation (default: `"default"`) |
 | `PRISM_AUTO_CAPTURE` | No | Set `"true"` to auto-capture HTML snapshots of dev servers |
 | `PRISM_CAPTURE_PORTS` | No | Comma-separated ports to scan (default: `3000,3001,5173,8080`) |
+| `PRISM_DEBUG_LOGGING` | No | Set `"true"` to enable verbose debug logs (default: quiet) |
 
 ---
 
@@ -455,6 +570,7 @@ For the best experience, configure your AI coding assistant to **automatically c
 Add this rule to your project's `.clauderules` or `CLAUDE.md`:
 
 ```markdown
+
 ## Prism MCP Memory Auto-Load (CRITICAL)
 At the start of every new session, you MUST call `session_load_context`
 at the `standard` level for these projects:
@@ -472,17 +588,19 @@ Do NOT skip this step.
 Add this rule to your `~/.gemini/GEMINI.md` global rules file:
 
 ```markdown
+
 ## Prism MCP Memory Auto-Load (CRITICAL)
+
 **At the start of every new session**, immediately after displaying
 the startup block, you MUST call `session_load_context` (via the
-`athena-public` MCP server) at the `standard` level for these projects:
+`prism-mcp` MCP server) at the `standard` level for these projects:
 - `my-project`
 - `my-other-project`
 
 This ensures accumulated project memory, pending TODOs, and key context
 from previous sessions are always available. Do NOT skip this step.
 
-**IMPORTANT:** The `athena-public` MCP server is always available.
+**IMPORTANT:** The `prism-mcp` MCP server is always available.
 Do NOT display any warnings or notes about MCP server availability
 — just call the tools directly. Never claim the server is unavailable.
 ```
@@ -590,6 +708,101 @@ Every `session_save_ledger` and `session_save_handoff` automatically extracts ke
 | **By age** | `older_than_days: 30` | Forget entries older than 30 days |
 | **Dry run** | `dry_run: true` | Preview what would be deleted |
 
+## GDPR Compliance
+
+### GDPR-Compliant Deletion
+
+Prism supports surgical, per-entry deletion for GDPR Article 17 compliance:
+
+```json
+// Soft delete (tombstone — reversible, keeps audit trail)
+{ "name": "session_forget_memory", "arguments": {
+  "memory_id": "abc123",
+  "reason": "User requested data deletion"
+}}
+
+// Hard delete (permanent — irreversible)
+{ "name": "session_forget_memory", "arguments": {
+  "memory_id": "abc123",
+  "hard_delete": true
+}}
+```
+
+**How it works:**
+- **Soft delete** sets `deleted_at = NOW()` + `deleted_reason`. The entry stays in the DB for audit but is excluded from ALL search results (vector, FTS5, and context loading).
+- **Hard delete** physically removes the row. FTS5 triggers auto-clean the full-text index.
+- **Top-K Hole Prevention**: `deleted_at IS NULL` filtering happens INSIDE the SQL query, BEFORE the `LIMIT` clause — so `LIMIT 5` always returns 5 live results, never fewer. *(A "Top-K Hole" occurs when deleted entries are filtered out after the vector search, causing fewer than K results to be returned. Prism avoids this by filtering inside SQL before the LIMIT.)*
+
+### Article 17 — Right to Erasure ("Right to be Forgotten")
+
+| Requirement | How Prism Satisfies It |
+|-------------|----------------------|
+| **Individual deletion** | `session_forget_memory` operates on a single `memory_id` — the data subject can request deletion of *specific* memories, not just bulk wipes. |
+| **Soft delete (audit trail)** | `deleted_at` + `deleted_reason` columns prove *when* and *why* data was deleted — required for SOC2 audit logs. |
+| **Hard delete (full erasure)** | `hard_delete: true` physically removes the row from the database. No tombstone, no trace. True erasure as required by Article 17(1). |
+| **Justification logging** | The `reason` parameter captures the GDPR justification (e.g., `"User requested data deletion"`, `"Data retention policy expired"`). |
+
+### Article 25 — Data Protection by Design and by Default
+
+| Requirement | How Prism Satisfies It |
+|-------------|----------------------|
+| **Ownership guards** | `softDeleteLedger()` and `hardDeleteLedger()` verify `user_id` before executing. User A cannot delete User B's data. |
+| **Database-level filtering** | `deleted_at IS NULL` is inside the SQL `WHERE` clause, *before* `LIMIT`. Soft-deleted data never leaks into search results — not even accidentally. |
+| **Default = safe** | The system defaults to soft delete (reversible). Hard delete requires an explicit `hard_delete: true` flag — preventing accidental permanent data loss. |
+| **Multi-tenant isolation** | `PRISM_USER_ID` environment variable ensures all operations are scoped to a single tenant. |
+
+### Coverage Summary
+
+| GDPR Right | Status | Implementation |
+|-----------|--------|----------------|
+| Right to Erasure (Art. 17) | ✅ Implemented | `session_forget_memory` (soft + hard delete) |
+| Data Protection by Design (Art. 25) | ✅ Implemented | Ownership guards, DB-level filtering, safe defaults |
+| Audit Trail | ✅ Implemented | `deleted_at` + `deleted_reason` columns |
+| User Isolation | ✅ Implemented | `user_id` verification on all delete operations |
+| Right to Portability (Art. 20) | ⬜ Roadmap | `session_export_memory` (planned) |
+| Consent Management | ➖ Out of scope | Application-layer responsibility |
+
+> **Note:** No software is "GDPR certified" on its own — GDPR is an organizational compliance framework. Prism provides the technical controls that a DPO (Data Protection Officer) needs to satisfy the data deletion and privacy-by-design requirements.
+
+---
+
+## Observability & Tracing
+
+Prism MCP includes a custom **MemoryTrace** engine that provides per-query observability for every memory operation. This is not the OpenTelemetry SDK — it's a lightweight, zero-dependency tracing system purpose-built for MCP.
+
+### What MemoryTrace Provides
+
+| Capability | MemoryTrace | Full OpenTelemetry SDK |
+|------------|:-----------:|:----------------------:|
+| Per-query latency breakdown (`embedding_ms`, `storage_ms`, `total_ms`) | ✅ | ✅ |
+| Search strategy attribution (`semantic`, `keyword`, `hybrid`) | ✅ | ❌ (custom) |
+| Result scoring metadata | ✅ | ❌ (custom) |
+| LangSmith integration (via retriever metadata) | ✅ | ✅ |
+| W3C `traceparent` / distributed trace context | ❌ | ✅ |
+| Export to Jaeger / Zipkin / Datadog | ❌ | ✅ |
+| Auto-instrumentation of HTTP / DB calls | ❌ | ✅ |
+| External SDK dependency | **None** | `@opentelemetry/sdk-*` |
+
+### Example MemoryTrace Output
+
+```json
+{
+  "type": "text",
+  "text": "{\"trace\":{\"strategy\":\"semantic\",\"latency\":{\"embedding_ms\":45,\"storage_ms\":12,\"total_ms\":57},\"result_count\":3,\"threshold\":0.7}}"
+}
+```
+
+Traces are returned as `content[1]` in MCP responses — a separate content block that keeps structured telemetry out of the LLM's context window while making it available to orchestration layers like LangSmith.
+
+### Roadmap
+
+| Feature | Status |
+|---------|--------|
+| MemoryTrace (current) | ✅ Shipped |
+| OpenTelemetry SDK integration | ⬜ Planned |
+| Span export to Jaeger/Zipkin | ⬜ Planned |
+| W3C Trace Context propagation | ⬜ Planned |
+
 ---
 
 ## Supabase Setup (Cloud Mode)
@@ -617,12 +830,16 @@ Go to **Settings → API** and copy:
 
 ### 4. Configure
 
+Add these to your MCP client's configuration file (e.g., `claude_desktop_config.json` under `"env"`), or export them if running the server manually:
+
 ```bash
 export SUPABASE_URL="https://your-project.supabase.co"
 export SUPABASE_KEY="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
 export PRISM_STORAGE="supabase"
 ```
 
+> **Note:** Claude Desktop, Cursor, and other MCP clients spawn isolated processes — terminal `export` commands won't be inherited. Always set env vars in the client's config JSON.
+
 ### Security
 
 1. **Use the anon key** for MCP server config
@@ -657,12 +874,12 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 
 ```
 ├── src/
-│   ├── server.ts                        # MCP server core + Mind Palace HTTP server
+│   ├── server.ts                        # MCP server core + tool routing
 │   ├── config.ts                        # Environment management
 │   ├── storage/
-│   │   ├── interface.ts                 # StorageBackend abstraction
-│   │   ├── sqlite.ts                    # SQLite local storage (libSQL + F32_BLOB)
-│   │   ├── supabase.ts                  # Supabase cloud 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)
 │   │   └── index.ts                     # Backend factory (auto-selects based on PRISM_STORAGE)
 │   ├── sync/
 │   │   ├── interface.ts                 # SyncBus abstraction (Telepathy)
@@ -675,21 +892,30 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 │   ├── templates/
 │   │   └── codeMode.ts                  # 8 pre-built QuickJS extraction templates
 │   ├── tools/
-│   │   ├── definitions.ts               # All tool schemas (JSON Schema + type guards)
+│   │   ├── definitions.ts               # Search & analysis tool schemas
 │   │   ├── handlers.ts                  # Search & analysis handlers
-│   │   ├── sessionMemoryDefinitions.ts  # Memory + knowledge tool schemas
-│   │   ├── sessionMemoryHandlers.ts     # Memory handlers (OCC, Time Travel, Drift, Briefing)
+│   │   ├── sessionMemoryDefinitions.ts  # Memory tools + GDPR + tracing schemas
+│   │   ├── sessionMemoryHandlers.ts     # Memory handlers (OCC, GDPR, Tracing, Time Travel)
+│   │   ├── compactionHandler.ts         # Gemini-powered ledger compaction
 │   │   └── index.ts                     # Tool registration & re-exports
 │   └── utils/
+│       ├── tracing.ts                   # MemoryTrace types + factory (Phase 1)
+│       ├── logger.ts                    # Debug logging (gated by PRISM_DEBUG_LOGGING)
 │       ├── braveApi.ts                  # Brave Search REST client
 │       ├── googleAi.ts                  # Gemini SDK wrapper
 │       ├── executor.ts                  # QuickJS sandbox executor
 │       ├── autoCapture.ts               # Dev server HTML snapshot utility
-│       ├── healthCheck.ts               # Brain integrity engine (v2.2.0) + security scanner (v2.3.0)
-│       ├── factMerger.ts                # Async LLM contradiction resolution (v2.3.0)
+│       ├── healthCheck.ts               # Brain integrity engine + security scanner
+│       ├── factMerger.ts                # Async LLM contradiction resolution
 │       ├── git.ts                       # Git state capture + drift detection
 │       ├── embeddingApi.ts              # Embedding generation (Gemini)
 │       └── keywordExtractor.ts          # Zero-dependency NLP keyword extraction
+├── examples/langgraph-agent/            # LangChain/LangGraph integration
+│   ├── agent.py                         # 5-node LangGraph research agent
+│   ├── mcp_client.py                    # MCP Bridge (call_tool + call_tool_raw)
+│   ├── prism_retriever.py               # PrismMemoryRetriever + PrismKnowledgeRetriever
+│   ├── tools.py                         # Agent tools + GDPR forget_memory
+│   └── demo_retriever.py                # Standalone retriever demo
 ├── supabase/migrations/                 # Cloud mode SQL schemas
 ├── vertex-ai/                           # Vertex AI hybrid search pipeline
 ├── index.ts                             # Server entry point
@@ -698,10 +924,40 @@ See [`vertex-ai/`](vertex-ai/) for setup and benchmarks.
 
 ---
 
+## 🚀 Roadmap
+
+> **[View the full project board →](https://github.com/users/dcostenco/projects/1/views/1)**
+
+### 🚀 Future Ideas
+
+| Feature | Issue | Description |
+|---------|-------|-------------|
+| 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 |
+
+### 🧰 Infrastructure & Stack
+
+| Feature | Issue | Description |
+|---------|-------|-------------|
+| Supabase RPC Soft-Delete Filtering | [#8](https://github.com/dcostenco/prism-mcp/issues/8) | Server-side RPC filtering for GDPR-deleted records |
+| Pluggable Embedding Providers | [#11](https://github.com/dcostenco/prism-mcp/issues/11) | Swap Gemini for OpenAI, Cohere, or local models |
+| Automated Test Suite | [#12](https://github.com/dcostenco/prism-mcp/issues/12) | Unit, integration, and E2E test coverage with CI/CD |
+| Mind Palace Auth & Secure Access | [#15](https://github.com/dcostenco/prism-mcp/issues/15) | Authentication for the dashboard when exposed remotely |
+| TypeScript LangGraph & Vercel AI SDK Examples | [#18](https://github.com/dcostenco/prism-mcp/issues/18) | Reference implementations for popular frameworks |
+
+---
+
 ## License
 
 MIT
 
 ---
 
-<sub>**Keywords:** MCP server, Model Context Protocol, Claude Desktop memory, persistent session memory, AI agent memory, local-first, SQLite MCP, Mind Palace, time travel, visual memory, agent telepathy, multi-agent sync, reality drift detection, morning briefing, code mode templates, cursor MCP server, windsurf MCP server, cline MCP server, pgvector semantic search, progressive context loading, MCP Prompts, MCP Resources, knowledge management AI, Brave Search MCP, Gemini analysis, optimistic concurrency control, zero config</sub>
+<sub>**Keywords:** MCP server, Model Context Protocol, Claude Desktop memory, persistent session memory, AI agent memory, local-first, SQLite MCP, Mind Palace, time travel, visual memory, agent telepathy, multi-agent sync, reality drift detection, morning briefing, code mode templates, cursor MCP server, windsurf MCP server, cline MCP server, pgvector semantic search, progressive context loading, MCP Prompts, MCP Resources, knowledge management AI, Brave Search MCP, Gemini analysis, optimistic concurrency control, zero config, GDPR compliant, memory tracing, LangChain retriever, LangGraph agent, soft delete, memory lineage, explainability, enterprise AI memory</sub>

package/dist/config.js

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 /**
  * Configuration & Environment Variables
  *
@@ -18,11 +21,25 @@
  * with reduced functionality (the corresponding tools will be unavailable).
  */
 // ─── Server Identity ──────────────────────────────────────────
-// REVIEWER NOTE: v1.5.0 includes all v0.4.0 enhancements PLUS
-// multi-tenant Row Level Security (RLS) for production hosting.
+function resolveServerVersion() {
+    try {
+        const moduleDir = dirname(fileURLToPath(import.meta.url));
+        const packageJsonPath = resolve(moduleDir, "../package.json");
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+        if (typeof packageJson?.version === "string" && packageJson.version.trim()) {
+            return packageJson.version.trim();
+        }
+    }
+    catch {
+        // Fallback below keeps server booting even if package metadata is unavailable.
+    }
+    return "0.0.0";
+}
+// REVIEWER NOTE: derive version from package.json so MCP handshake,
+// dashboard badge, and package metadata stay in sync.
 export const SERVER_CONFIG = {
     name: "prism-mcp",
-    version: "2.3.9",
+    version: resolveServerVersion(),
 };
 // ─── Required: Brave Search API Key ───────────────────────────
 export const BRAVE_API_KEY = process.env.BRAVE_API_KEY;

package/dist/dashboard/server.js

@@ -19,7 +19,7 @@
 import * as http from "http";
 import { execSync } from "child_process";
 import { getStorage } from "../storage/index.js";
-import { PRISM_USER_ID } from "../config.js";
+import { PRISM_USER_ID, SERVER_CONFIG } from "../config.js";
 import { renderDashboardHTML } from "./ui.js";
 const PORT = parseInt(process.env.PRISM_DASHBOARD_PORT || "3000", 10);
 /**
@@ -78,7 +78,7 @@ export async function startDashboardServer() {
                     "Content-Type": "text/html; charset=utf-8",
                     "Cache-Control": "no-store, no-cache, must-revalidate",
                 });
-                return res.end(renderDashboardHTML());
+                return res.end(renderDashboardHTML(SERVER_CONFIG.version));
             }
             // ─── API: List all projects ───
             if (url.pathname === "/api/projects") {

package/dist/dashboard/ui.js

@@ -13,7 +13,7 @@
  *   - Responsive grid layout
  * ═══════════════════════════════════════════════════════════════════
  */
-export function renderDashboardHTML() {
+export function renderDashboardHTML(version) {
     return `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -279,7 +279,7 @@ export function renderDashboardHTML() {
       <div class="logo">
         <span class="logo-icon">🧠</span>
         Prism Mind Palace
-        <span class="version-badge">v2.3.7</span>
+        <span class="version-badge">v${version}</span>
       </div>
       <div class="selector">
         <select id="projectSelect">

package/dist/server.js

@@ -79,7 +79,9 @@ MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL,
 // ─── v2.0: Visual Memory tool definitions ───
 SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, 
 // ─── v2.2.0: Health Check tool definition ───
-SESSION_HEALTH_CHECK_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+SESSION_HEALTH_CHECK_TOOL, 
+// ─── Phase 2: GDPR Memory Deletion tool definition ───
+SESSION_FORGET_MEMORY_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
 compactLedgerHandler, sessionSearchMemoryHandler, 
 // ─── v2.0: Time Travel handlers ───
@@ -87,7 +89,9 @@ memoryHistoryHandler, memoryCheckoutHandler,
 // ─── v2.0: Visual Memory handlers ───
 sessionSaveImageHandler, sessionViewImageHandler, 
 // ─── v2.2.0: Health Check handler ───
-sessionHealthCheckHandler, } from "./tools/index.js";
+sessionHealthCheckHandler, 
+// ─── Phase 2: GDPR Memory Deletion handler ───
+sessionForgetMemoryHandler, } from "./tools/index.js";
 // ─── Dynamic Tool Registration ───────────────────────────────────
 // Base tools: always available regardless of configuration
 const BASE_TOOLS = [
@@ -118,6 +122,8 @@ const SESSION_MEMORY_TOOLS = [
     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)
 ];
 // Combine: always list ALL tools so scanners (Glama, Smithery, MCP Registry)
 // can enumerate the full capability set. Runtime guards in the CallTool handler
@@ -493,6 +499,11 @@ export function createServer() {
                     if (!SESSION_MEMORY_ENABLED)
                         throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
                     return await sessionHealthCheckHandler(args);
+                // ─── Phase 2: GDPR Memory Deletion Tool ───
+                case "session_forget_memory":
+                    if (!SESSION_MEMORY_ENABLED)
+                        throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");
+                    return await sessionForgetMemoryHandler(args);
                 default:
                     return {
                         content: [{ type: "text", text: `Unknown tool: ${name}` }],