vplex-memory 2.3.0

package/README.md

@@ -0,0 +1,146 @@
+# vplex-memory
+
+**Persistent cross-session memory for AI coding tools via MCP (Model Context Protocol).**
+
+Works with Claude Code, Cursor, VS Code Copilot, Windsurf, Codex, and any MCP-compatible tool. No VPLEX Desktop required.
+
+## Quick Start
+
+```json
+{
+  "mcpServers": {
+    "vplex-memory": {
+      "command": "npx",
+      "args": ["-y", "vplex-memory@2.3.0"]
+    }
+  }
+}
+```
+
+That's it. Add this to your MCP config and the server handles everything — authentication, project detection, and memory persistence.
+
+## Setup by Tool
+
+### Claude Code
+
+Add to `.mcp.json` in your project root or `~/.claude/settings.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "vplex-memory": {
+      "command": "npx",
+      "args": ["-y", "vplex-memory@2.3.0"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vplex-memory": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "vplex-memory@2.3.0"]
+    }
+  }
+}
+```
+
+### VS Code (Copilot)
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "vplex-memory": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "vplex-memory@2.3.0"]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.windsurf/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vplex-memory": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "vplex-memory@2.3.0"]
+    }
+  }
+}
+```
+
+## Authentication
+
+On first use, the server detects that no session exists and initiates a browser-based auth flow:
+
+1. The MCP server returns an error with a URL and a code: `Open https://vplex-web.vercel.app/auth/cli and enter code: XXXX`
+2. Your AI tool displays this message — open the URL and enter the code
+3. After approval, a session token is saved to `~/.vplex/session.json`
+4. All subsequent tool calls work automatically
+
+The token refreshes automatically. You only need to authenticate once per machine.
+
+## How It Works
+
+- **stdio-only** — no TCP/HTTP listener, no network attack surface
+- **Project-scoped** — memories are grouped by project (hashed from `process.cwd()`)
+- **Persistent** — memories survive across sessions, tools, and devices
+- **Semantic search** — find past decisions by meaning, not just keywords
+- **Zero dependencies** — single `.mjs` file, runs on Node.js 18+
+
+## Available Tools (15)
+
+| Tool | Description |
+|------|-------------|
+| `memory_store` | Store a memory with type, importance, tags, and related files |
+| `memory_search` | Semantic + keyword search across project memories |
+| `memory_list` | List all memories for the current project |
+| `memory_list_projects` | List all projects with stored memories |
+| `memory_modify` | Update, archive, delete, or reactivate memories |
+| `memory_expand` | Get full content of memories by IDs |
+| `memory_session_recap` | Summary of recent activity across sessions |
+| `memory_get_rules` | Retrieve project-specific behavioral rules |
+| `memory_projects` | Manage project documents (briefs, PRDs, plans) |
+| `memory_tasks` | Create, complete, and list project tasks |
+| `memory_start_thinking` | Start a structured thinking sequence |
+| `memory_add_thought` | Add thoughts to a sequence; use "conclusion" to finalize |
+| `memory_export` | Export all memories as JSON (requires Max plan) |
+| `memory_insights` | Discover clusters of related memories (requires Base plan) |
+| `memory_upload_document` | Upload PDF/MD/TXT into searchable memory chunks (requires Base plan) |
+
+## Memory Types
+
+`feature` `code-snippet` `debug` `design` `decision` `rule` `learning` `research` `discussion` `progress` `task` `working-notes` `pattern` `context` `bug` `document-chunk`
+
+## Security
+
+- stdio-only transport — no network listener
+- Auth token stored in `~/.vplex/session.json` with `0600` permissions (Unix)
+- All API calls over HTTPS to `termplex-api.vercel.app`
+- Input validation: length limits, type checks, ID format validation
+- Rate limiting: per-tool fixed window (30 stores/min, 60 searches/min)
+- Content quality gate rejects noise (raw errors, stack traces, install logs)
+
+## Requirements
+
+- Node.js 18+
+- VPLEX account (free tier available at [vplex-web.vercel.app](https://vplex-web.vercel.app))
+
+## License
+
+MIT

package/bin.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./vplex-mcp-server.mjs";

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "vplex-memory",
+  "version": "2.3.0",
+  "description": "VPLEX Memory MCP Server — persistent cross-session memory for AI coding tools",
+  "type": "module",
+  "bin": {
+    "vplex-memory": "bin.js"
+  },
+  "files": [
+    "vplex-mcp-server.mjs",
+    "bin.js",
+    "README.md"
+  ],
+  "keywords": [
+    "mcp",
+    "memory",
+    "ai",
+    "cursor",
+    "claude",
+    "copilot",
+    "model-context-protocol"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xGUCCIFER/VPLEX.git"
+  }
+}

package/vplex-mcp-server.mjs

@@ -0,0 +1,1187 @@
+#!/usr/bin/env node
+/**
+ * VPLEX MCP Server — Secure Memory Bridge for AI CLIs
+ *
+ * Exposes VPLEX Memory system via MCP Protocol (stdio only — no network listener)
+ * Compatible with Claude Code, Cursor, Codex, and other MCP-enabled tools
+ *
+ * Security model:
+ *   - stdio-only: no TCP/HTTP listener, no network attack surface
+ *   - Auth: reads Bearer token from ~/.vplex/session.json (0o600 on Unix)
+ *   - All API calls go to VPLEX backend over HTTPS
+ *   - Input validation: length limits, type checks, ID format validation
+ *   - Rate limiting: per-tool fixed window
+ *   - Error sanitization: no API internals leaked to caller
+ *   - Token cached in-memory with TTL, re-read from disk on expiry
+ *
+ * v2.1 — Security hardened
+ */
+
+import { readFileSync, writeFileSync, statSync, mkdirSync, realpathSync } from "fs";
+import { homedir, platform } from "os";
+import { join, resolve, relative } from "path";
+import { createInterface } from "readline";
+
+const API_URL = "https://termplex-api.vercel.app";
+const WEB_URL = "https://vplex-web.vercel.app";
+const SERVER_NAME = "vplex-memory";
+const SERVER_VERSION = "2.3.0";
+
+// ── Security Constants ──────────────────────────────────────────────
+
+const MAX_CONTENT_LENGTH = 50_000;       // 50KB max memory content
+const MAX_TAG_LENGTH = 100;              // per tag
+const MAX_TAGS = 50;                     // max tags per memory
+const MAX_FILE_PATH_LENGTH = 500;        // related file path limit
+const MAX_FILES = 50;                    // max related files
+const MAX_QUERY_LENGTH = 500;            // search query limit (must match API)
+const MAX_SESSION_NAME_LENGTH = 200;     // session name limit
+const MAX_SEARCH_LIMIT = 50;            // max search results
+const ID_PATTERN = /^[a-f0-9-]{8,64}$/i; // UUID-ish IDs only
+const HASH_PATTERN = /^[a-z0-9]{1,20}$/; // project hash format
+
+// Rate limiting: max calls per tool per window
+const RATE_LIMITS = {
+  memory_store: { max: 30, windowMs: 60_000 },     // 30 stores/min
+  memory_search: { max: 60, windowMs: 60_000 },     // 60 searches/min
+  memory_modify: { max: 20, windowMs: 60_000 },     // 20 modifies/min
+  _default: { max: 120, windowMs: 60_000 },          // 120/min for reads
+};
+
+const rateBuckets = new Map(); // tool -> { count, resetAt }
+
+function checkRateLimit(tool) {
+  const config = RATE_LIMITS[tool] || RATE_LIMITS._default;
+  const now = Date.now();
+  let bucket = rateBuckets.get(tool);
+
+  if (!bucket || now >= bucket.resetAt) {
+    bucket = { count: 0, resetAt: now + config.windowMs };
+    rateBuckets.set(tool, bucket);
+  }
+
+  bucket.count++;
+  if (bucket.count > config.max) {
+    throw new Error(`Rate limit exceeded for ${tool}. Try again in ${Math.ceil((bucket.resetAt - now) / 1000)}s.`);
+  }
+}
+
+// ── Input Validation ────────────────────────────────────────────────
+
+function validateString(val, name, maxLen) {
+  if (typeof val !== "string") throw new Error(`${name} must be a string`);
+  if (val.length === 0) throw new Error(`${name} cannot be empty`);
+  if (val.length > maxLen) throw new Error(`${name} exceeds maximum length of ${maxLen}`);
+  return val;
+}
+
+function validateId(val, name) {
+  if (typeof val !== "string") throw new Error(`${name} must be a string`);
+  if (!ID_PATTERN.test(val)) throw new Error(`${name} has invalid format`);
+  return val;
+}
+
+function validateHash(val, name) {
+  if (typeof val !== "string") throw new Error(`${name} must be a string`);
+  if (!HASH_PATTERN.test(val)) throw new Error(`${name} has invalid format`);
+  return val;
+}
+
+function validateTags(tags) {
+  if (!Array.isArray(tags)) return [];
+  return tags
+    .filter((t) => typeof t === "string" && t.length > 0)
+    .slice(0, MAX_TAGS)
+    .map((t) => t.slice(0, MAX_TAG_LENGTH).replace(/[<>{}]/g, ""));
+}
+
+function validateFiles(files) {
+  if (!Array.isArray(files)) return undefined;
+  return files
+    .filter((f) => typeof f === "string" && f.length > 0)
+    .slice(0, MAX_FILES)
+    .map((f) => f.slice(0, MAX_FILE_PATH_LENGTH));
+}
+
+function validateImportance(val) {
+  if (val === undefined || val === null) return undefined;
+  const n = Number(val);
+  if (isNaN(n)) return undefined;
+  return Math.max(0, Math.min(1, n));
+}
+
+function validateMemoryType(val) {
+  if (!MEMORY_TYPES.includes(val)) throw new Error(`Invalid memory type: ${val}`);
+  return val;
+}
+
+// ── Content Quality Gate ────────────────────────────────────────────
+
+const NOISE_PATTERNS = [
+  // Generic errors / stack traces (not project-specific insights)
+  /^(error|Error|ERROR)[:\s].*?(ENOENT|EACCES|EPERM|ETIMEDOUT|ECONNREFUSED|ECONNRESET|MODULE_NOT_FOUND)/i,
+  // Raw stack traces without analysis
+  /^\s*at\s+[\w.]+\s+\(.*:\d+:\d+\)/m,
+  // npm/pnpm install output
+  /^(added|removed|up to date)\s+\d+\s+packages?\s+in/i,
+  // Git status noise
+  /^(On branch|Your branch is|nothing to commit|Changes not staged)/,
+  // CLI startup/version banners
+  /^(v?\d+\.\d+\.\d+|Welcome to|Starting|Initializing|Loading)\s/i,
+  // Compiler warnings without context
+  /^warning\[?\w*\]?:\s+unused/i,
+  // Raw file listings
+  /^(total\s+\d+|-[rwx-]{9})\s/,
+  // Process exit/signal noise
+  /^(Process exited|Killed|Terminated|Segmentation fault)/i,
+  // Empty-ish content after trimming
+  /^\s*$/,
+];
+
+// Secret patterns — reject content that contains credentials or private keys
+const SECRET_PATTERNS = [
+  { pattern: /-----BEGIN\s+(RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----/, label: "private key" },
+  { pattern: /AKIA[0-9A-Z]{16}/, label: "AWS access key" },
+  { pattern: /ghp_[a-zA-Z0-9]{36}/, label: "GitHub personal access token" },
+  { pattern: /gho_[a-zA-Z0-9]{36}/, label: "GitHub OAuth token" },
+  { pattern: /github_pat_[a-zA-Z0-9]{22}_[a-zA-Z0-9]{59}/, label: "GitHub fine-grained token" },
+  { pattern: /sk-[a-zA-Z0-9]{20,}/, label: "API secret key (OpenAI/Stripe)" },
+  { pattern: /sk-proj-[a-zA-Z0-9_-]{40,}/, label: "OpenAI project key" },
+  { pattern: /xox[bpsar]-[a-zA-Z0-9-]{10,}/, label: "Slack token" },
+  { pattern: /npm_[a-zA-Z0-9]{36}/, label: "npm token" },
+  { pattern: /glpat-[a-zA-Z0-9_-]{20,}/, label: "GitLab token" },
+  { pattern: /eyJ[a-zA-Z0-9_-]{20,}\.eyJ[a-zA-Z0-9_-]{20,}\./, label: "JWT token" },
+];
+
+const MIN_CONTENT_LENGTH = 15; // memories shorter than this are almost always noise
+const MIN_WORD_COUNT = 3;      // at least 3 words for meaningful content
+
+/**
+ * Rejects low-quality or noisy content before it reaches the API.
+ * Returns null if content is acceptable, or an error message explaining rejection.
+ */
+function checkContentQuality(content, type) {
+  const trimmed = content.trim();
+
+  // Too short
+  if (trimmed.length < MIN_CONTENT_LENGTH) {
+    return `Content too short (${trimmed.length} chars). Memories should be complete, descriptive thoughts — not fragments.`;
+  }
+
+  // Too few words
+  const wordCount = trimmed.split(/\s+/).length;
+  if (wordCount < MIN_WORD_COUNT) {
+    return `Content has only ${wordCount} word(s). Write a complete sentence describing the insight, decision, or finding.`;
+  }
+
+  // Secret detection — never store credentials
+  for (const { pattern, label } of SECRET_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return `Content contains what appears to be a ${label}. Storing secrets in memory is a security risk. Remove the credential and store only the insight (e.g., "Auth uses JWT tokens stored in ~/.vplex/session.json").`;
+    }
+  }
+
+  // Noise pattern detection
+  for (const pattern of NOISE_PATTERNS) {
+    if (pattern.test(trimmed)) {
+      return `Content looks like terminal noise, not a project insight. Memories should capture decisions, learnings, or patterns — not raw output. If this IS valuable, rephrase it as an insight (e.g., "Learned that X fails because Y — fix is Z").`;
+    }
+  }
+
+  // Type-content mismatch: "pattern" type should describe actual patterns, not errors
+  if (type === "pattern" && /\b(error|fail|crash|exception|traceback)\b/i.test(trimmed) && !/\b(pattern|always|whenever|every time|consistently)\b/i.test(trimmed)) {
+    return `Type "pattern" is for recurring codebase patterns (e.g., "All stores use create() with devtools"). For errors, use type "debug" instead and describe the root cause + fix.`;
+  }
+
+  // Type "rule" should be prescriptive
+  if (type === "rule" && !/\b(always|never|must|should|shall|don't|do not|prefer|avoid)\b/i.test(trimmed)) {
+    return `Type "rule" should contain a prescriptive guideline (e.g., "Never use .unwrap() in production"). Consider "learning" or "decision" for observations.`;
+  }
+
+  return null; // content is fine
+}
+
+// ── Session & Token Management ──────────────────────────────────────
+
+let cachedToken = null;
+let tokenReadAt = 0;
+const TOKEN_CACHE_MS = 30_000; // re-read from disk every 30s
+const TOKEN_REFRESH_MARGIN_S = 120; // refresh if < 2 min until expiry
+
+// CLI auth flow state
+let cliAuthPending = null; // { sessionId, userCode, verificationUrl, pollInterval, expiresAt }
+
+function getSessionPath() {
+  return join(homedir(), ".vplex", "session.json");
+}
+
+function readSession() {
+  try {
+    const sessionPath = getSessionPath();
+
+    // Verify file permissions on Unix (skip on Windows — no chmod)
+    if (platform() !== "win32") {
+      const stat = statSync(sessionPath);
+      const mode = stat.mode & 0o777;
+      if (mode !== 0o600) {
+        process.stderr.write(`[vplex-mcp] Warning: ${sessionPath} has permissions ${mode.toString(8)}, expected 600\n`);
+      }
+    }
+
+    return JSON.parse(readFileSync(sessionPath, "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+function saveSession(session) {
+  const dir = join(homedir(), ".vplex");
+  try { mkdirSync(dir, { recursive: true }); } catch { /* exists */ }
+  const sessionPath = join(dir, "session.json");
+  writeFileSync(sessionPath, JSON.stringify(session, null, 2), { mode: 0o600 });
+}
+
+function getTokenExpiry(token) {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1], "base64url").toString());
+    return payload.exp || 0;
+  } catch { return 0; }
+}
+
+async function refreshTokenFromAPI(refreshTokenStr) {
+  try {
+    const response = await fetch(`${API_URL}/auth/refresh`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ refresh_token: refreshTokenStr }),
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    if (!data.token) return null;
+    return { token: data.token, refresh_token: data.refresh_token, user: data.user };
+  } catch { return null; }
+}
+
+async function getToken() {
+  const now = Date.now();
+
+  // Return cached token if still fresh
+  if (cachedToken && (now - tokenReadAt) < TOKEN_CACHE_MS) {
+    // Even with cache, check if close to expiry and refresh proactively
+    const exp = getTokenExpiry(cachedToken);
+    if (exp > 0 && (exp - now / 1000) < TOKEN_REFRESH_MARGIN_S) {
+      const session = readSession();
+      if (session?.refresh_token) {
+        const refreshed = await refreshTokenFromAPI(session.refresh_token);
+        if (refreshed) {
+          saveSession({ ...session, token: refreshed.token, refresh_token: refreshed.refresh_token, user: refreshed.user || session.user });
+          cachedToken = refreshed.token;
+          tokenReadAt = Date.now();
+          return cachedToken;
+        }
+      }
+    }
+    return cachedToken;
+  }
+
+  // Read from disk
+  const session = readSession();
+  if (!session?.token || typeof session.token !== "string") {
+    cachedToken = null;
+    return null;
+  }
+
+  // Check if token is expired or close to expiry
+  const exp = getTokenExpiry(session.token);
+  const nowSec = now / 1000;
+
+  if (exp > 0 && (exp - nowSec) < TOKEN_REFRESH_MARGIN_S) {
+    // Token is close to expiry or already expired — try refresh
+    if (session.refresh_token) {
+      const refreshed = await refreshTokenFromAPI(session.refresh_token);
+      if (refreshed) {
+        saveSession({ ...session, token: refreshed.token, refresh_token: refreshed.refresh_token, user: refreshed.user || session.user });
+        cachedToken = refreshed.token;
+        tokenReadAt = Date.now();
+        return cachedToken;
+      }
+    }
+    // Refresh failed — if token is fully expired, return null
+    if (exp > 0 && exp < nowSec) {
+      cachedToken = null;
+      return null;
+    }
+  }
+
+  cachedToken = session.token;
+  tokenReadAt = now;
+  return cachedToken;
+}
+
+// ── CLI Auth Flow (Browser-based) ───────────────────────────────────
+
+async function initCliAuth() {
+  try {
+    const response = await fetch(`${API_URL}/auth/cli/init`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return data;
+  } catch { return null; }
+}
+
+async function pollCliAuth(sessionId) {
+  try {
+    const response = await fetch(`${API_URL}/auth/cli/poll/${sessionId}`);
+    if (!response.ok) return null;
+    return response.json();
+  } catch { return null; }
+}
+
+function startCliAuthPolling(sessionId) {
+  if (cliAuthPending?.pollInterval) {
+    clearInterval(cliAuthPending.pollInterval);
+  }
+
+  const interval = setInterval(async () => {
+    const result = await pollCliAuth(sessionId);
+    if (!result) return;
+
+    if (result.status === "approved" && result.token) {
+      clearInterval(interval);
+      const session = readSession() || {};
+      saveSession({
+        ...session,
+        token: result.token,
+        refresh_token: result.refresh_token,
+      });
+      cachedToken = result.token;
+      tokenReadAt = Date.now();
+      cliAuthPending = null;
+      process.stderr.write("[vplex-mcp] CLI auth approved — token saved.\n");
+    } else if (result.status === "expired") {
+      clearInterval(interval);
+      cliAuthPending = null;
+      process.stderr.write("[vplex-mcp] CLI auth session expired.\n");
+    }
+  }, 2000);
+
+  return interval;
+}
+
+/**
+ * Starts CLI auth flow if no token is available.
+ * Returns an error message with the auth URL and code for the user.
+ */
+async function startCliAuthFlow() {
+  // Don't start if already pending
+  if (cliAuthPending && Date.now() < cliAuthPending.expiresAt) {
+    return `Not authenticated. Open ${cliAuthPending.verificationUrl} and enter code: ${cliAuthPending.userCode}`;
+  }
+
+  const result = await initCliAuth();
+  if (!result?.cli_session_id) {
+    return "Not authenticated. Please log in via VPLEX Desktop App.";
+  }
+
+  const pollInterval = startCliAuthPolling(result.cli_session_id);
+
+  cliAuthPending = {
+    sessionId: result.cli_session_id,
+    userCode: result.user_code,
+    verificationUrl: result.verification_url || `${WEB_URL}/auth/cli`,
+    pollInterval,
+    expiresAt: Date.now() + (result.expires_in || 600) * 1000,
+  };
+
+  return `Not authenticated. Open ${cliAuthPending.verificationUrl} and enter code: ${cliAuthPending.userCode}`;
+}
+
+// ── Project Identification ──────────────────────────────────────────
+
+function hashString(str) {
+  let hash = 0;
+  for (let i = 0; i < str.length; i++) {
+    const char = str.charCodeAt(i);
+    hash = ((hash << 5) - hash) + char;
+    hash |= 0;
+  }
+  return Math.abs(hash).toString(36);
+}
+
+const projectHash = hashString(process.cwd());
+const projectName = process.cwd().replace(/\\/g, "/").split("/").pop() || process.cwd();
+const projectPath = process.cwd();
+
+// ── HTTP Helper ─────────────────────────────────────────────────────
+
+async function apiFetch(path, options = {}) {
+  const token = await getToken();
+  if (!token) {
+    // Start or return existing CLI auth flow message
+    const authMessage = await startCliAuthFlow();
+    throw new Error(authMessage);
+  }
+
+  // Validate path is a safe relative API path (allows %-encoding for query params)
+  if (!/^\/[a-zA-Z0-9/_?&=.%-]+$/.test(path)) {
+    throw new Error("Invalid API path");
+  }
+
+  const url = `${API_URL}${path}`;
+  const headers = {
+    "Content-Type": "application/json",
+    Authorization: `Bearer ${token}`,
+    ...(options.headers || {}),
+  };
+
+  const response = await fetch(url, { ...options, headers });
+  if (!response.ok) {
+    // Sanitize error — don't leak API response body to caller
+    const status = response.status;
+    if (status === 401) throw new Error("Authentication expired. Please re-login in VPLEX.");
+    if (status === 403) throw new Error("Access denied. Check your VPLEX plan.");
+    if (status === 404) throw new Error("Resource not found.");
+    if (status === 429) throw new Error("API rate limit reached. Please wait.");
+    throw new Error(`Request failed (${status}). Please try again.`);
+  }
+  const contentType = response.headers.get("content-type") || "";
+  if (!contentType.includes("application/json")) {
+    throw new Error(`Unexpected response format from API (${contentType || "no content-type"})`);
+  }
+  return response.json();
+}
+
+// ── MCP Tool Definitions ────────────────────────────────────────────
+
+const MEMORY_TYPES = [
+  "feature", "code-snippet", "debug", "design", "decision", "rule",
+  "learning", "research", "discussion", "progress", "task", "working-notes",
+  "pattern", "context", "bug", "document-chunk",
+];
+
+const TOOLS = [
+  {
+    name: "memory_store",
+    description: "Store a memory in VPLEX for cross-session context. Memories persist across all AI tools (VPLEX, Claude Code, Cursor). IMPORTANT: Automatically call this after completing tasks, making decisions, fixing bugs, or learning something new.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "The memory content — what to remember (max 50KB)" },
+        type: { type: "string", enum: MEMORY_TYPES, description: "Memory type" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags for categorization (max 50)" },
+        related_files: { type: "array", items: { type: "string" }, description: "Related file paths (max 50)" },
+        importance_score: { type: "number", description: "Importance 0.0-1.0 (0.9=critical, 0.5=normal, 0.3=minor)" },
+        session_name: { type: "string", description: "Session grouping (e.g. 'sprint-1')" },
+        related_memory_ids: { type: "array", items: { type: "string" }, description: "IDs of related memories" },
+      },
+      required: ["content", "type"],
+    },
+  },
+  {
+    name: "memory_search",
+    description: "Search VPLEX memories for relevant context from previous sessions. Use this BEFORE making code changes to find past decisions, patterns, and bug fixes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query (max 500 chars)" },
+        limit: { type: "number", description: "Max results 1-50 (default 10)" },
+        memory_type: { type: "string", enum: MEMORY_TYPES, description: "Filter by type" },
+        file_path: { type: "string", description: "Filter by related file" },
+        recent_only: { type: "boolean", description: "Only last 30 days" },
+        search_mode: { type: "string", enum: ["fulltext", "keyword", "hybrid"], description: "Search mode (default: hybrid)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "memory_list",
+    description: "List all memories for the current project.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "memory_list_projects",
+    description: "List all projects that have stored memories.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "memory_modify",
+    description: "Update, archive (soft delete), permanently delete, unarchive, or reactivate memories.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["update", "inactivate", "reactivate", "delete", "unarchive"], description: "Action" },
+        memory_id: { type: "string", description: "Memory ID" },
+        content: { type: "string", description: "New content (for update)" },
+        memory_type: { type: "string", enum: MEMORY_TYPES, description: "New type (for update)" },
+        tags: { type: "array", items: { type: "string" }, description: "New tags (for update)" },
+        importance_score: { type: "number", description: "New importance 0-1 (for update)" },
+        related_files: { type: "array", items: { type: "string" }, description: "New related files (for update)" },
+        reason: { type: "string", description: "Reason (required for inactivate)" },
+      },
+      required: ["action", "memory_id"],
+    },
+  },
+  {
+    name: "memory_expand",
+    description: "Get full content of memories by IDs (max 10).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        memory_ids: { type: "array", items: { type: "string" }, description: "Memory IDs (max 10)" },
+      },
+      required: ["memory_ids"],
+    },
+  },
+  {
+    name: "memory_session_recap",
+    description: "Get a summary of recent activity across sessions. Use at the START of each session to resume context.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_hash: { type: "string", description: "Project hash (default: current)" },
+        days_back: { type: "number", description: "Days to look back 1-30 (default 7)" },
+      },
+    },
+  },
+  {
+    name: "memory_get_rules",
+    description: "Get behavioral rules and guardrails for a project.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_hash: { type: "string", description: "Project hash (default: current)" },
+        include_global: { type: "boolean", description: "Include global rules (default true)" },
+      },
+    },
+  },
+  {
+    name: "memory_projects",
+    description: "Manage project documents (briefs, PRDs, plans).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["list_all", "create", "update", "get"], description: "Action" },
+        project_hash: { type: "string", description: "Project hash" },
+        doc_type: { type: "string", enum: ["brief", "prd", "plan"], description: "Doc type (for create)" },
+        content: { type: "string", description: "Content (for create/update)" },
+        doc_id: { type: "string", description: "Doc ID (for update)" },
+      },
+      required: ["action"],
+    },
+  },
+  {
+    name: "memory_tasks",
+    description: "Manage tasks: create, complete, or list.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: { type: "string", enum: ["create", "complete", "get"], description: "Action" },
+        project_hash: { type: "string", description: "Project hash (default: current)" },
+        task_description: { type: "string", description: "Description (for create)" },
+        task_id: { type: "string", description: "Task ID (for complete)" },
+        include_completed: { type: "boolean", description: "Include completed (default false)" },
+      },
+      required: ["action"],
+    },
+  },
+  {
+    name: "memory_start_thinking",
+    description: "Start a structured thinking sequence for complex problems.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal: { type: "string", description: "Problem or goal" },
+        project_hash: { type: "string", description: "Project hash (default: current)" },
+      },
+      required: ["goal"],
+    },
+  },
+  {
+    name: "memory_add_thought",
+    description: "Add a thought to a thinking sequence. Use 'conclusion' to finalize.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        sequence_id: { type: "string", description: "Sequence ID" },
+        thought: { type: "string", description: "Thought content" },
+        thought_type: {
+          type: "string",
+          enum: ["observation", "hypothesis", "question", "reasoning", "analysis", "conclusion", "branch", "general"],
+          description: "Thought type (default: general)",
+        },
+        branch_name: { type: "string", description: "Branch name (for branch type)" },
+      },
+      required: ["sequence_id", "thought"],
+    },
+  },
+  {
+    name: "memory_export",
+    description: "Export all memories for a project as JSON (requires Max plan).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_hash: { type: "string", description: "Project hash (default: current)" },
+      },
+    },
+  },
+  {
+    name: "memory_insights",
+    description: "Discover clusters of related memories and knowledge gaps. Groups semantically similar memories to reveal patterns and consolidation opportunities. Requires Base plan.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        project_hash: { type: "string", description: "Project hash (default: current)" },
+        threshold: { type: "number", description: "Similarity threshold 0.5-0.99 (default: 0.85)" },
+        min_cluster: { type: "number", description: "Minimum cluster size 2-10 (default: 3)" },
+        limit: { type: "number", description: "Max clusters 1-20 (default: 5)" },
+      },
+    },
+  },
+  {
+    name: "memory_upload_document",
+    description: "Upload and process a document (PDF, Markdown, or plain text) into memory chunks. Reads the file from disk and stores each chunk as a searchable memory. Max 4MB. Requires Base plan.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        file_path: { type: "string", description: "Absolute path to the file to upload" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags for all chunks" },
+      },
+      required: ["file_path"],
+    },
+  },
+];
+
+// ── Plan Verification (cached) ──────────────────────────────────────
+
+let mcpAccessCache = null;
+let mcpAccessCheckedAt = 0;
+const MCP_ACCESS_CACHE_MS = 300_000; // cache plan check for 5min
+
+async function checkMcpAccess() {
+  const now = Date.now();
+  if (mcpAccessCache && (now - mcpAccessCheckedAt) < MCP_ACCESS_CACHE_MS) {
+    return mcpAccessCache;
+  }
+
+  try {
+    const features = await apiFetch("/memory/features");
+    if (!features.mcp_access) {
+      mcpAccessCache = {
+        allowed: false,
+        plan: features.plan,
+        error: `MCP access requires Pro plan or higher (current: ${features.plan}).`,
+      };
+    } else {
+      mcpAccessCache = { allowed: true, plan: features.plan };
+    }
+    mcpAccessCheckedAt = now;
+    return mcpAccessCache;
+  } catch {
+    // On network error, allow access (don't block offline usage)
+    return { allowed: true, plan: "unknown" };
+  }
+}
+
+// ── Tool Handlers ───────────────────────────────────────────────────
+
+async function handleToolCall(name, args) {
+  // Rate limit check
+  checkRateLimit(name);
+
+  // Plan access check
+  const access = await checkMcpAccess();
+  if (!access.allowed) {
+    return { content: [{ type: "text", text: access.error }], isError: true };
+  }
+
+  switch (name) {
+    case "memory_store": {
+      const content = validateString(args.content, "content", MAX_CONTENT_LENGTH);
+      const type = validateMemoryType(args.type);
+      const tags = validateTags(args.tags);
+      const related_files = validateFiles(args.related_files);
+      const importance_score = validateImportance(args.importance_score);
+      const session_name = args.session_name ? validateString(args.session_name, "session_name", MAX_SESSION_NAME_LENGTH) : undefined;
+      const related_memory_ids = Array.isArray(args.related_memory_ids)
+        ? args.related_memory_ids.filter((id) => ID_PATTERN.test(id)).slice(0, 20)
+        : undefined;
+
+      // Quality gate — reject noise before it reaches the API
+      const qualityIssue = checkContentQuality(content, type);
+      if (qualityIssue) {
+        return {
+          content: [{
+            type: "text",
+            text: `Memory rejected: ${qualityIssue}\n\nPlease rephrase and try again. Good memories are complete thoughts that will be useful in future sessions.`,
+          }],
+          isError: true,
+        };
+      }
+
+      const memory = await apiFetch("/memory/store", {
+        method: "POST",
+        body: JSON.stringify({
+          content, type, tags, source: "mcp",
+          projectHash, projectName, projectPath,
+          relatedFiles: related_files, importanceScore: importance_score,
+          sessionName: session_name, relatedMemoryIds: related_memory_ids,
+        }),
+      });
+      const dedupNote = memory.deduplicated
+        ? ` [DEDUPLICATED — merged with existing ${memory.id.slice(0, 8)}, tags merged: ${(memory.tags || []).join(", ")}]`
+        : "";
+      return {
+        content: [{
+          type: "text",
+          text: `Stored [${memory.type}] memory (${memory.id.slice(0, 8)})${dedupNote}. Importance: ${memory.importanceScore}. Files: ${(memory.relatedFiles || []).join(", ") || "none"}.`,
+        }],
+      };
+    }
+
+    case "memory_search": {
+      const query = validateString(args.query, "query", MAX_QUERY_LENGTH);
+      const limit = Math.max(1, Math.min(MAX_SEARCH_LIMIT, Number(args.limit) || 10));
+      const memory_type = args.memory_type ? validateMemoryType(args.memory_type) : undefined;
+      const file_path = args.file_path ? validateString(args.file_path, "file_path", MAX_FILE_PATH_LENGTH) : undefined;
+
+      const memories = await apiFetch("/memory/search", {
+        method: "POST",
+        body: JSON.stringify({
+          query, limit, projectHash,
+          memoryType: memory_type, filePath: file_path,
+          recentOnly: !!args.recent_only,
+          searchMode: args.search_mode === "keyword" ? "keyword" : args.search_mode === "fulltext" ? "fulltext" : "hybrid",
+        }),
+      });
+
+      if (memories.length === 0) {
+        return { content: [{ type: "text", text: `No memories found for: "${query}"` }] };
+      }
+
+      const formatted = memories
+        .map((m, i) => {
+          const files = (m.relatedFiles || []).length > 0 ? `\n   Files: ${m.relatedFiles.join(", ")}` : "";
+          const relevance = m.relevance !== undefined ? ` (score: ${Number(m.relevance).toFixed(3)})` : "";
+          return `${i + 1}. [${m.type}]${relevance} ${m.content}\n   ID: ${m.id} | Tags: ${(m.tags || []).join(", ") || "none"}${files}`;
+        })
+        .join("\n\n");
+
+      return { content: [{ type: "text", text: `Found ${memories.length} memories:\n\n${formatted}` }] };
+    }
+
+    case "memory_list": {
+      const memories = await apiFetch(`/memory/project/${projectHash}`);
+      if (memories.length === 0) {
+        return { content: [{ type: "text", text: "No memories for this project." }] };
+      }
+
+      const grouped = memories.reduce((acc, m) => {
+        if (!acc[m.type]) acc[m.type] = [];
+        acc[m.type].push(m);
+        return acc;
+      }, {});
+
+      const sections = Object.entries(grouped)
+        .map(([type, items]) => {
+          const list = items.map((m) => `  - ${m.content}${(m.relatedFiles || []).length ? ` [${m.relatedFiles.length} files]` : ""}`).join("\n");
+          return `${type.toUpperCase()} (${items.length}):\n${list}`;
+        })
+        .join("\n\n");
+
+      return { content: [{ type: "text", text: `Project Memories (${memories.length}):\n\n${sections}` }] };
+    }
+
+    case "memory_list_projects": {
+      const data = await apiFetch("/memory/projects");
+      const projects = data.projects;
+      if (projects.length === 0) {
+        return { content: [{ type: "text", text: "No projects with memories." }] };
+      }
+      const list = projects
+        .map((p) => `- ${p.project_name ?? p.project_hash}: ${p.memory_count} memories`)
+        .join("\n");
+      return { content: [{ type: "text", text: `Projects (${projects.length}):\n\n${list}` }] };
+    }
+
+    case "memory_modify": {
+      const { action } = args;
+      const memory_id = validateId(args.memory_id, "memory_id");
+
+      if (action === "update") {
+        const updates = {};
+        if (args.content !== undefined) updates.content = validateString(args.content, "content", MAX_CONTENT_LENGTH);
+        if (args.memory_type !== undefined) updates.type = validateMemoryType(args.memory_type);
+        if (args.tags !== undefined) updates.tags = validateTags(args.tags);
+        if (args.importance_score !== undefined) updates.importanceScore = validateImportance(args.importance_score);
+        if (args.related_files !== undefined) updates.relatedFiles = validateFiles(args.related_files);
+
+        const result = await apiFetch(`/memory/${memory_id}`, { method: "PATCH", body: JSON.stringify(updates) });
+        return { content: [{ type: "text", text: `Memory ${memory_id.slice(0, 8)} updated. Type: ${result.type}` }] };
+      }
+
+      if (action === "inactivate") {
+        if (!args.reason || typeof args.reason !== "string" || args.reason.trim().length === 0) {
+          return { content: [{ type: "text", text: "Error: reason required for inactivation" }], isError: true };
+        }
+        const reason = validateString(args.reason, "reason", 500);
+        await apiFetch(`/memory/${memory_id}/inactivate`, { method: "POST", body: JSON.stringify({ reason }) });
+        return { content: [{ type: "text", text: `Memory ${memory_id.slice(0, 8)} archived.` }] };
+      }
+
+      if (action === "reactivate") {
+        await apiFetch(`/memory/${memory_id}/reactivate`, { method: "POST" });
+        return { content: [{ type: "text", text: `Memory ${memory_id.slice(0, 8)} reactivated.` }] };
+      }
+
+      if (action === "delete") {
+        await apiFetch(`/memory/${memory_id}`, { method: "DELETE" });
+        return { content: [{ type: "text", text: `Memory ${memory_id.slice(0, 8)} permanently deleted.` }] };
+      }
+
+      if (action === "unarchive") {
+        const result = await apiFetch(`/memory/${memory_id}/unarchive`, { method: "POST" });
+        const swapped = result.swapped ? " (oldest active memory was swapped out to stay within plan limits)" : "";
+        return { content: [{ type: "text", text: `Memory ${memory_id.slice(0, 8)} unarchived.${swapped}` }] };
+      }
+
+      return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+    }
+
+    case "memory_expand": {
+      const ids = (args.memory_ids || []).filter((id) => ID_PATTERN.test(id)).slice(0, 10);
+      if (ids.length === 0) return { content: [{ type: "text", text: "Error: valid memory_ids required" }], isError: true };
+
+      const memories = await apiFetch("/memory/expand", { method: "POST", body: JSON.stringify({ memoryIds: ids }) });
+      if (memories.length === 0) return { content: [{ type: "text", text: "No memories found." }] };
+
+      const formatted = memories
+        .map((m) => `--- ${m.id} [${m.type}] ---\nImportance: ${m.importanceScore} | Status: ${m.status}\nTags: ${(m.tags || []).join(", ") || "none"}\nFiles: ${(m.relatedFiles || []).join(", ") || "none"}\n\n${m.content}`)
+        .join("\n\n");
+
+      return { content: [{ type: "text", text: formatted }] };
+    }
+
+    case "memory_session_recap": {
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+      const daysBack = Math.min(Math.max(Number(args.days_back) || 7, 1), 30);
+
+      const result = await apiFetch("/memory/session-recap", {
+        method: "POST",
+        body: JSON.stringify({ projectHash: hash, daysBack }),
+      });
+
+      if (result.totalMemories === 0) {
+        return { content: [{ type: "text", text: `No activity in the last ${daysBack} days.` }] };
+      }
+
+      const sections = result.projects
+        .map((p) => {
+          const name = p.projectName || p.projectHash || "Global";
+          const list = p.recentMemories
+            .map((m) => `  - [${m.type}] ${m.content.substring(0, 120)}${m.content.length > 120 ? "..." : ""}`)
+            .join("\n");
+          return `${name} (${p.memoryCount}, types: ${p.types.join(", ")}):\n${list}`;
+        })
+        .join("\n\n");
+
+      return { content: [{ type: "text", text: `Recap (${daysBack}d, ${result.totalMemories} memories):\n\n${sections}` }] };
+    }
+
+    case "memory_get_rules": {
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+      const includeGlobal = args.include_global !== false;
+      const result = await apiFetch(`/memory/rules/${hash}?includeGlobal=${includeGlobal}`);
+
+      const fmt = (rules, label) => {
+        if (rules.length === 0) return `${label}: none`;
+        return `${label} (${rules.length}):\n${rules.map((r) => `  - ${r.content}`).join("\n")}`;
+      };
+
+      const text = [
+        fmt(result.projectRules, "Project Rules"),
+        includeGlobal ? fmt(result.globalRules, "Global Rules") : null,
+      ].filter(Boolean).join("\n\n");
+
+      return { content: [{ type: "text", text }] };
+    }
+
+    case "memory_projects": {
+      const { action } = args;
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+
+      if (action === "list_all") {
+        const data = await apiFetch("/memory/projects");
+        if (data.projects.length === 0) return { content: [{ type: "text", text: "No projects." }] };
+        const list = data.projects.map((p) => `- ${p.project_name ?? p.project_hash}: ${p.memory_count} memories`).join("\n");
+        return { content: [{ type: "text", text: `Projects:\n\n${list}` }] };
+      }
+
+      if (action === "get") {
+        const docs = await apiFetch(`/memory/project-docs/${hash}`);
+        if (docs.length === 0) return { content: [{ type: "text", text: "No documents." }] };
+        const formatted = docs.map((d) => `--- ${d.docType.toUpperCase()} (${d.id}) ---\n${d.content}`).join("\n\n");
+        return { content: [{ type: "text", text: formatted }] };
+      }
+
+      if (action === "create") {
+        if (!args.doc_type || !args.content) return { content: [{ type: "text", text: "Error: doc_type and content required" }], isError: true };
+        const content = validateString(args.content, "content", MAX_CONTENT_LENGTH);
+        const doc = await apiFetch("/memory/project-docs", {
+          method: "POST",
+          body: JSON.stringify({ projectHash: hash, docType: args.doc_type, content }),
+        });
+        return { content: [{ type: "text", text: `Doc created: ${doc.id} (${doc.docType})` }] };
+      }
+
+      if (action === "update") {
+        const doc_id = validateId(args.doc_id, "doc_id");
+        const content = validateString(args.content, "content", MAX_CONTENT_LENGTH);
+        await apiFetch(`/memory/project-docs/${doc_id}`, { method: "PATCH", body: JSON.stringify({ content }) });
+        return { content: [{ type: "text", text: `Doc ${doc_id.slice(0, 8)} updated.` }] };
+      }
+
+      return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+    }
+
+    case "memory_tasks": {
+      const { action } = args;
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+
+      if (action === "get") {
+        const qs = args.include_completed ? "?includeCompleted=true" : "";
+        const tasks = await apiFetch(`/memory/tasks/${hash}${qs}`);
+        if (tasks.length === 0) return { content: [{ type: "text", text: "No tasks." }] };
+        const list = tasks.map((t) => `- [${t.isCompleted ? "DONE" : "TODO"}] ${t.content} (${t.id.slice(0, 8)})`).join("\n");
+        return { content: [{ type: "text", text: `Tasks (${tasks.length}):\n\n${list}` }] };
+      }
+
+      if (action === "create") {
+        const desc = validateString(args.task_description, "task_description", MAX_CONTENT_LENGTH);
+        const task = await apiFetch("/memory/tasks", { method: "POST", body: JSON.stringify({ projectHash: hash, description: desc }) });
+        return { content: [{ type: "text", text: `Task created: ${task.id.slice(0, 8)}` }] };
+      }
+
+      if (action === "complete") {
+        const task_id = validateId(args.task_id, "task_id");
+        await apiFetch(`/memory/tasks/${task_id}/complete`, { method: "POST" });
+        return { content: [{ type: "text", text: `Task ${task_id.slice(0, 8)} completed.` }] };
+      }
+
+      return { content: [{ type: "text", text: `Unknown action: ${action}` }], isError: true };
+    }
+
+    case "memory_start_thinking": {
+      const goal = validateString(args.goal, "goal", MAX_CONTENT_LENGTH);
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+      const result = await apiFetch("/memory/thinking", { method: "POST", body: JSON.stringify({ projectHash: hash, goal }) });
+      return {
+        content: [{
+          type: "text",
+          text: `Thinking started: ${result.id}\nGoal: ${result.goal}\n\nUse memory_add_thought with this sequence_id. Use thought_type "conclusion" to finalize.`,
+        }],
+      };
+    }
+
+    case "memory_add_thought": {
+      const sequence_id = validateId(args.sequence_id, "sequence_id");
+      const thought = validateString(args.thought, "thought", MAX_CONTENT_LENGTH);
+      const thought_type = args.thought_type || "general";
+
+      const result = await apiFetch(`/memory/thinking/${sequence_id}/thought`, {
+        method: "POST",
+        body: JSON.stringify({ thought, thoughtType: thought_type, branchName: args.branch_name }),
+      });
+
+      const done = result.status === "completed" ? " [CONCLUDED — stored as decision]" : "";
+      return { content: [{ type: "text", text: `Thought #${result.thoughtCount} (${result.thought.type})${done}` }] };
+    }
+
+    case "memory_export": {
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+      const result = await apiFetch(`/memory/export/${hash}`);
+      if (result.total === 0) {
+        return { content: [{ type: "text", text: "No memories to export." }] };
+      }
+      const summary = result.memories
+        .map((m) => `- [${m.type}] ${m.content.substring(0, 100)}${m.content.length > 100 ? "..." : ""} (${m.archived ? "archived" : "active"})`)
+        .join("\n");
+      return { content: [{ type: "text", text: `Exported ${result.total} memories (${result.project_hash}):\n\n${summary}` }] };
+    }
+
+    case "memory_insights": {
+      const hash = args.project_hash ? validateHash(args.project_hash, "project_hash") : projectHash;
+      const threshold = Math.max(0.5, Math.min(0.99, Number(args.threshold) || 0.85));
+      const minCluster = Math.max(2, Math.min(10, Number(args.min_cluster) || 3));
+      const limit = Math.max(1, Math.min(20, Number(args.limit) || 5));
+
+      const result = await apiFetch("/memory/insights", {
+        method: "POST",
+        body: JSON.stringify({ projectHash: hash, threshold, minCluster, limit }),
+      });
+
+      if (result.totalClusters === 0) {
+        return { content: [{ type: "text", text: "No memory clusters found. Try lowering the threshold or adding more memories." }] };
+      }
+
+      const formatted = result.clusters
+        .map((c, i) => {
+          const previews = c.memberPreviews
+            .map((p, j) => `  ${j + 1}. [${c.memberTypes[j]}] ${p}`)
+            .join("\n");
+          return `Cluster ${i + 1} (${c.clusterSize} memories):\n${previews}`;
+        })
+        .join("\n\n");
+
+      return { content: [{ type: "text", text: `Found ${result.totalClusters} clusters:\n\n${formatted}` }] };
+    }
+
+    case "memory_upload_document": {
+      const filePath = validateString(args.file_path, "file_path", MAX_FILE_PATH_LENGTH);
+
+      // Security: restrict file access to project directory (cwd) to prevent data exfiltration
+      const cwd = process.cwd();
+      const absPath = resolve(filePath);
+      let realPath;
+      try { realPath = realpathSync(absPath); } catch { realPath = absPath; }
+      const normalizedCwd = cwd.replace(/\\/g, "/").toLowerCase();
+      const normalizedReal = realPath.replace(/\\/g, "/").toLowerCase();
+      if (!normalizedReal.startsWith(normalizedCwd + "/") && normalizedReal !== normalizedCwd) {
+        return { content: [{ type: "text", text: `Security: file must be within the project directory (${cwd}). Access to files outside the project is denied to prevent data exfiltration.` }], isError: true };
+      }
+
+      // Read file from disk
+      let fileBuffer;
+      let filename;
+      try {
+        fileBuffer = readFileSync(realPath);
+        filename = realPath.replace(/\\/g, "/").split("/").pop() || "document";
+      } catch (err) {
+        return { content: [{ type: "text", text: `Error reading file: ${err.message}` }], isError: true };
+      }
+
+      // Determine MIME type
+      const ext = filename.split(".").pop()?.toLowerCase();
+      const mimeMap = { pdf: "application/pdf", md: "text/markdown", txt: "text/plain", text: "text/plain" };
+      const mimeType = mimeMap[ext] || "text/plain";
+
+      if (!["pdf", "md", "txt", "text"].includes(ext || "")) {
+        return { content: [{ type: "text", text: `Unsupported file type: .${ext}. Supported: .pdf, .md, .txt` }], isError: true };
+      }
+
+      if (fileBuffer.length > 4 * 1024 * 1024) {
+        return { content: [{ type: "text", text: `File too large (${(fileBuffer.length / 1024 / 1024).toFixed(1)}MB). Maximum: 4MB.` }], isError: true };
+      }
+
+      // Build multipart form data
+      const tags = validateTags(args.tags);
+      const blob = new Blob([fileBuffer], { type: mimeType });
+      const formData = new FormData();
+      formData.append("file", blob, filename);
+      formData.append("projectHash", projectHash);
+      if (tags.length > 0) formData.append("tags", tags.join(","));
+
+      // Send to API (custom headers for multipart)
+      const token = await getToken();
+      if (!token) {
+        const authMessage = await startCliAuthFlow();
+        return { content: [{ type: "text", text: authMessage }], isError: true };
+      }
+
+      const response = await fetch(`${API_URL}/memory/documents/upload`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${token}` },
+        body: formData,
+      });
+
+      if (!response.ok) {
+        const errBody = await response.json().catch(() => ({}));
+        return { content: [{ type: "text", text: `Upload failed (${response.status}): ${errBody.error || "Unknown error"}` }], isError: true };
+      }
+
+      const result = await response.json();
+      return {
+        content: [{
+          type: "text",
+          text: `Document "${result.filename}" processed: ${result.chunkCount} chunks created.\nUpload ID: ${result.uploadId}`,
+        }],
+      };
+    }
+
+    default:
+      return { content: [{ type: "text", text: `Unknown tool: ${name}` }], isError: true };
+  }
+}
+
+// ── MCP JSON-RPC Handler ────────────────────────────────────────────
+
+async function handleRequest(request) {
+  const { method, params, id } = request;
+
+  // Validate JSON-RPC structure
+  if (typeof method !== "string") {
+    return { jsonrpc: "2.0", id: id ?? null, error: { code: -32600, message: "Invalid request: method required" } };
+  }
+
+  try {
+    switch (method) {
+      case "initialize":
+        return {
+          jsonrpc: "2.0", id,
+          result: {
+            protocolVersion: "2024-11-05",
+            capabilities: { tools: {} },
+            serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+          },
+        };
+
+      case "initialized":
+        return null;
+
+      case "tools/list":
+        return { jsonrpc: "2.0", id, result: { tools: TOOLS } };
+
+      case "tools/call": {
+        if (!params || typeof params.name !== "string") {
+          return { jsonrpc: "2.0", id, error: { code: -32602, message: "Invalid params: name required" } };
+        }
+        const result = await handleToolCall(params.name, params.arguments || {});
+        return { jsonrpc: "2.0", id, result };
+      }
+
+      default:
+        return { jsonrpc: "2.0", id, error: { code: -32601, message: `Unknown method: ${method}` } };
+    }
+  } catch (error) {
+    // Sanitize: only return our own error messages, never raw stack traces
+    const safeMessage = error.message || "Internal error";
+    return { jsonrpc: "2.0", id, error: { code: -32603, message: safeMessage } };
+  }
+}
+
+// ── stdio Communication Loop ────────────────────────────────────────
+
+const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+
+rl.on("line", async (line) => {
+  if (!line.trim()) return;
+
+  try {
+    const request = JSON.parse(line);
+    const response = await handleRequest(request);
+    if (response !== null) {
+      // Write to stdout only — stderr is reserved for diagnostics
+      process.stdout.write(JSON.stringify(response) + "\n");
+    }
+  } catch {
+    process.stdout.write(JSON.stringify({
+      jsonrpc: "2.0", id: null,
+      error: { code: -32700, message: "Parse error" },
+    }) + "\n");
+  }
+});
+
+rl.on("close", () => process.exit(0));
+process.on("SIGINT", () => process.exit(0));