mnemon-mcp 1.0.0

package/dist/index-http.js

@@ -0,0 +1,202 @@
+/**
+ * mnemon-mcp: HTTP transport entry point.
+ *
+ * Exposes the same tools as index.ts via StreamableHTTP transport.
+ * Use for remote / multi-server deployments instead of stdio.
+ *
+ * Environment variables:
+ *   MNEMON_PORT       - Listening port (default: 3000)
+ *   MNEMON_AUTH_TOKEN - Bearer token for all requests (optional but recommended)
+ */
+import { createServer } from "node:http";
+import { timingSafeEqual } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { openDatabase } from "./db.js";
+import { createMcpServer, loadExtraStopWords, version } from "./server.js";
+import { createEmbedder } from "./embedder.js";
+import { loadSqliteVec, createVecTable } from "./vector.js";
+// ---------------------------------------------------------------------------
+// Database + config
+// ---------------------------------------------------------------------------
+let db;
+try {
+    db = openDatabase();
+}
+catch (err) {
+    console.error(`[mnemon-mcp http] Failed to open database: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+}
+loadExtraStopWords();
+// Optional: load sqlite-vec extension and create vector table
+const vecAvailable = loadSqliteVec(db);
+let embedder = null;
+try {
+    embedder = createEmbedder();
+    if (embedder && vecAvailable) {
+        createVecTable(db, embedder.dimensions);
+    }
+}
+catch {
+    // Embedder creation is best-effort
+}
+// ---------------------------------------------------------------------------
+// Auth — timing-safe comparison to prevent token extraction via timing attack
+// ---------------------------------------------------------------------------
+const AUTH_TOKEN = process.env["MNEMON_AUTH_TOKEN"];
+const MAX_BODY_BYTES = 1_048_576; // 1 MB
+const CORS_ORIGIN = process.env["MNEMON_CORS_ORIGIN"] ?? "*";
+// ---------------------------------------------------------------------------
+// Rate limiting — simple token bucket per IP
+// ---------------------------------------------------------------------------
+const RATE_LIMIT = parseInt(process.env["MNEMON_RATE_LIMIT"] ?? "100", 10); // requests per window
+const RATE_WINDOW_MS = 60_000; // 1 minute
+const rateBuckets = new Map();
+function isRateLimited(ip) {
+    if (RATE_LIMIT <= 0)
+        return false; // disabled
+    const now = Date.now();
+    const entry = rateBuckets.get(ip);
+    if (!entry || now >= entry.resetAt) {
+        rateBuckets.set(ip, { count: 1, resetAt: now + RATE_WINDOW_MS });
+        return false;
+    }
+    entry.count++;
+    return entry.count > RATE_LIMIT;
+}
+// Periodic cleanup of stale buckets (every 5 minutes)
+setInterval(() => {
+    const now = Date.now();
+    for (const [ip, entry] of rateBuckets) {
+        if (now >= entry.resetAt)
+            rateBuckets.delete(ip);
+    }
+}, 5 * 60_000).unref();
+function isAuthorized(req) {
+    if (!AUTH_TOKEN)
+        return true;
+    const header = req.headers["authorization"] ?? "";
+    const expected = `Bearer ${AUTH_TOKEN}`;
+    if (header.length !== expected.length)
+        return false;
+    return timingSafeEqual(Buffer.from(header), Buffer.from(expected));
+}
+function rejectUnauthorized(res) {
+    res.writeHead(401, { "Content-Type": "application/json", "WWW-Authenticate": 'Bearer realm="mnemon-mcp"' });
+    res.end(JSON.stringify({ error: "Unauthorized" }));
+}
+// ---------------------------------------------------------------------------
+// HTTP server — stateless mode: new transport + server per request
+// ---------------------------------------------------------------------------
+function setCorsHeaders(res) {
+    res.setHeader("Access-Control-Allow-Origin", CORS_ORIGIN);
+    res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+    res.setHeader("Access-Control-Allow-Headers", "Content-Type, Authorization");
+    res.setHeader("Access-Control-Max-Age", "86400");
+}
+async function handleHttpRequest(req, res) {
+    setCorsHeaders(res);
+    // CORS preflight
+    if (req.method === "OPTIONS") {
+        res.writeHead(204);
+        res.end();
+        return;
+    }
+    // Rate limiting
+    // Use socket IP directly — x-forwarded-for is trivially spoofable without a trusted proxy
+    const clientIp = req.socket.remoteAddress ?? "unknown";
+    if (isRateLimited(clientIp)) {
+        res.writeHead(429, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Too many requests. Try again later." }));
+        return;
+    }
+    if (!isAuthorized(req)) {
+        rejectUnauthorized(res);
+        return;
+    }
+    const url = new URL(req.url ?? "/", `http://localhost`);
+    // Health check endpoint
+    if (url.pathname === "/health" && req.method === "GET") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ status: "ok", version }));
+        return;
+    }
+    if (url.pathname !== "/mcp") {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found. Use POST /mcp or GET /health" }));
+        return;
+    }
+    // Body size limit — check header first, then enforce on actual body
+    const contentLength = parseInt(req.headers["content-length"] ?? "0", 10);
+    if (contentLength > MAX_BODY_BYTES) {
+        res.writeHead(413, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: `Request body too large (max ${MAX_BODY_BYTES} bytes)` }));
+        return;
+    }
+    // Enforce body size limit on actual stream (handles chunked transfer encoding).
+    // The data listener runs concurrently with transport.handleRequest — if the body
+    // exceeds the limit, req.destroy() aborts the stream and the transport will fail.
+    let receivedBytes = 0;
+    const onData = (chunk) => {
+        receivedBytes += chunk.length;
+        if (receivedBytes > MAX_BODY_BYTES) {
+            req.removeListener("data", onData);
+            if (!res.headersSent) {
+                res.writeHead(413, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: `Request body too large (max ${MAX_BODY_BYTES} bytes)` }));
+            }
+            req.destroy();
+        }
+    };
+    req.on("data", onData);
+    const transport = new StreamableHTTPServerTransport({});
+    const server = createMcpServer(db, embedder);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    await server.connect(transport);
+    try {
+        await transport.handleRequest(req, res);
+    }
+    finally {
+        req.removeListener("data", onData);
+        await server.close();
+    }
+}
+// ---------------------------------------------------------------------------
+// Start + graceful shutdown
+// ---------------------------------------------------------------------------
+const portRaw = parseInt(process.env["MNEMON_PORT"] ?? "3000", 10);
+if (Number.isNaN(portRaw) || portRaw < 1 || portRaw > 65535) {
+    console.error(`[mnemon-mcp http] Invalid MNEMON_PORT: "${process.env["MNEMON_PORT"]}". Must be 1-65535.`);
+    process.exit(1);
+}
+const PORT = portRaw;
+const httpServer = createServer((req, res) => {
+    handleHttpRequest(req, res).catch((err) => {
+        console.error(`[mnemon-mcp http] Unhandled error: ${err instanceof Error ? err.message : String(err)}`);
+        if (!res.headersSent) {
+            res.writeHead(500, { "Content-Type": "application/json" });
+            res.end(JSON.stringify({ error: "Internal server error" }));
+        }
+    });
+});
+function shutdown() {
+    console.error("[mnemon-mcp http] Shutting down...");
+    httpServer.close(() => {
+        try {
+            db.close();
+        }
+        catch {
+            // Best-effort
+        }
+        process.exit(0);
+    });
+    // Force exit after 5s if graceful shutdown stalls
+    setTimeout(() => process.exit(1), 5000).unref();
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+httpServer.listen(PORT, () => {
+    console.error(`[mnemon-mcp http] v${version} listening on port ${PORT}${AUTH_TOKEN ? " (auth enabled)" : " (no auth — set MNEMON_AUTH_TOKEN for production)"}`);
+    console.error(`[mnemon-mcp http] MCP endpoint: POST http://localhost:${PORT}/mcp`);
+    console.error(`[mnemon-mcp http] Health check: GET http://localhost:${PORT}/health`);
+});
+//# sourceMappingURL=index-http.js.map

package/dist/index-http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-http.js","sourceRoot":"","sources":["../src/index-http.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * mnemon-mcp: MCP server entry point (stdio transport).
+ *
+ * Suitable for Claude Code MCP config.
+ * Database: ~/.mnemon-mcp/memory.db (SQLite + FTS5, WAL mode).
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * mnemon-mcp: MCP server entry point (stdio transport).
+ *
+ * Suitable for Claude Code MCP config.
+ * Database: ~/.mnemon-mcp/memory.db (SQLite + FTS5, WAL mode).
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { openDatabase } from "./db.js";
+import { createMcpServer, loadExtraStopWords } from "./server.js";
+import { createEmbedder } from "./embedder.js";
+import { loadSqliteVec, createVecTable } from "./vector.js";
+let db;
+try {
+    db = openDatabase();
+}
+catch (err) {
+    process.stderr.write(`Failed to open database: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+}
+loadExtraStopWords();
+// Optional: load sqlite-vec extension and create vector table
+const vecAvailable = loadSqliteVec(db);
+// Optional: create embedder from env vars
+let embedder = null;
+try {
+    embedder = createEmbedder();
+    if (embedder && vecAvailable) {
+        createVecTable(db, embedder.dimensions);
+    }
+}
+catch {
+    // Embedder creation is best-effort
+}
+const server = createMcpServer(db, embedder);
+// Graceful shutdown: close DB and checkpoint WAL
+function shutdown() {
+    try {
+        db.close();
+    }
+    catch {
+        // Best-effort on shutdown
+    }
+    process.exit(0);
+}
+process.on("SIGTERM", shutdown);
+process.on("SIGINT", shutdown);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE5D,IAAI,EAAmC,CAAC;AAExC,IAAI,CAAC;IACH,EAAE,GAAG,YAAY,EAAE,CAAC;AACtB,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,4BAA4B,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,kBAAkB,EAAE,CAAC;AAErB,8DAA8D;AAC9D,MAAM,YAAY,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;AAEvC,0CAA0C;AAC1C,IAAI,QAAQ,GAAsC,IAAI,CAAC;AACvD,IAAI,CAAC;IACH,QAAQ,GAAG,cAAc,EAAE,CAAC;IAC5B,IAAI,QAAQ,IAAI,YAAY,EAAE,CAAC;QAC7B,cAAc,CAAC,EAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC;IAC1C,CAAC;AACH,CAAC;AAAC,MAAM,CAAC;IACP,mCAAmC;AACrC,CAAC;AAED,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC;AAE7C,iDAAiD;AACjD,SAAS,QAAQ;IACf,IAAI,CAAC;QACH,EAAE,CAAC,KAAK,EAAE,CAAC;IACb,CAAC;IAAC,MAAM,CAAC;QACP,0BAA0B;IAC5B,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;AAChC,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE/B,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,gBAAgB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared MCP server factory — used by both stdio and HTTP entry points.
+ *
+ * Centralizes tool registration, dispatch, and config loading so that
+ * index.ts and index-http.ts only handle transport-specific concerns.
+ */
+import type Database from "better-sqlite3";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Embedder } from "./embedder.js";
+declare const version: string;
+export { version };
+/** Load extra stop words from config (best-effort, non-fatal). */
+export declare function loadExtraStopWords(): void;
+/** Create an MCP server with all memory tools registered. */
+export declare function createMcpServer(db: Database.Database, embedder?: Embedder | null): Server;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,QAAQ,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AA8CnE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAO9C,QAAA,MAAQ,OAAO,QAAsD,CAAC;AAEtE,OAAO,EAAE,OAAO,EAAE,CAAC;AAEnB,kEAAkE;AAClE,wBAAgB,kBAAkB,IAAI,IAAI,CASzC;AAED,6DAA6D;AAC7D,wBAAgB,eAAe,CAAC,EAAE,EAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,GAAG,MAAM,CAkVzF"}

package/dist/server.js

@@ -0,0 +1,341 @@
+/**
+ * Shared MCP server factory — used by both stdio and HTTP entry points.
+ *
+ * Centralizes tool registration, dispatch, and config loading so that
+ * index.ts and index-http.ts only handle transport-specific concerns.
+ */
+import { createRequire } from "node:module";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ListResourceTemplatesRequestSchema, ReadResourceRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { memoryAdd } from "./tools/memory-add.js";
+import { memorySearch } from "./tools/memory-search.js";
+import { memoryUpdate } from "./tools/memory-update.js";
+import { memoryInspect } from "./tools/memory-inspect.js";
+import { memoryExport } from "./tools/memory-export.js";
+import { memoryDelete } from "./tools/memory-delete.js";
+import { memoryHealth } from "./tools/memory-health.js";
+import { MemoryAddSchema, MemorySearchSchema, MemoryUpdateSchema, MemoryInspectSchema, MemoryExportSchema, MemoryDeleteSchema, MemoryHealthSchema, memoryAddToolSchema, memorySearchToolSchema, memoryUpdateToolSchema, memoryInspectToolSchema, memoryExportToolSchema, memoryDeleteToolSchema, memoryHealthToolSchema, } from "./validation.js";
+import { upsertVec, deleteVec, isVecLoaded } from "./vector.js";
+import { loadConfig } from "./import/config-loader.js";
+import { addExtraStopWords } from "./stop-words.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+export { version };
+/** Load extra stop words from config (best-effort, non-fatal). */
+export function loadExtraStopWords() {
+    try {
+        const config = loadConfig();
+        if (config.extraStopWords.length > 0) {
+            addExtraStopWords(config.extraStopWords);
+        }
+    }
+    catch {
+        // Config loading is best-effort for the MCP server
+    }
+}
+/** Create an MCP server with all memory tools registered. */
+export function createMcpServer(db, embedder) {
+    const server = new Server({ name: "mnemon-mcp", version }, { capabilities: { tools: {}, resources: {}, prompts: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, () => ({
+        tools: [
+            {
+                name: "memory_add",
+                description: "Add a new memory to the persistent store. Supports 4 cognitive layers: episodic (events/sessions), semantic (facts/concepts), procedural (rules/workflows), resource (reference material). Automatically supersedes previous entries from the same source_file.",
+                inputSchema: memoryAddToolSchema,
+            },
+            {
+                name: "memory_search",
+                description: "Full-text search across all memory layers using FTS5. Supports layer/entity/date/scope filtering. Returns scored results with snippets. Superseded entries excluded by default.",
+                inputSchema: memorySearchToolSchema,
+            },
+            {
+                name: "memory_update",
+                description: "Update an existing memory. Use supersede=true to create a versioned replacement (preserves history chain). Use supersede=false (default) to update fields in place.",
+                inputSchema: memoryUpdateToolSchema,
+            },
+            {
+                name: "memory_delete",
+                description: "Permanently delete a memory by ID. Cleans up superseding chain references: re-activates predecessor if one exists.",
+                inputSchema: memoryDeleteToolSchema,
+            },
+            {
+                name: "memory_inspect",
+                description: "Inspect memory details or layer statistics. Without id: returns aggregate stats per layer (total, active, superseded, avg_confidence, top_entities). With id: returns the full memory row and optionally its history chain.",
+                inputSchema: memoryInspectToolSchema,
+            },
+            {
+                name: "memory_export",
+                description: "Export memories to JSON, Markdown, or claude-md (compact LLM-optimized) format. Supports filtering by layer, scope, date range. Returns the exported content as a string.",
+                inputSchema: memoryExportToolSchema,
+            },
+            {
+                name: "memory_health",
+                description: "Diagnostic health report on the memory store. Returns expired entries, orphaned superseding chains, stale/never-accessed memories, low-confidence entries, and per-layer stats. Use cleanup=true to garbage-collect expired entries.",
+                inputSchema: memoryHealthToolSchema,
+            },
+        ],
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            switch (name) {
+                case "memory_add": {
+                    const input = MemoryAddSchema.parse(args);
+                    const result = memoryAdd(db, input);
+                    // Auto-embed if embedder configured and sqlite-vec loaded
+                    if (embedder && isVecLoaded()) {
+                        try {
+                            const textToEmbed = input.title
+                                ? `${input.title}\n\n${input.content}`
+                                : input.content;
+                            const embedding = await embedder.embed(textToEmbed);
+                            upsertVec(db, result.id, embedding);
+                        }
+                        catch {
+                            // Embedding is best-effort — don't fail the add
+                        }
+                    }
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                case "memory_search": {
+                    const input = MemorySearchSchema.parse(args);
+                    const result = await memorySearch(db, input, embedder);
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                case "memory_update": {
+                    const input = MemoryUpdateSchema.parse(args);
+                    const result = memoryUpdate(db, input);
+                    // Re-embed updated or new (superseded) memory
+                    if (embedder && isVecLoaded()) {
+                        try {
+                            const activeId = result.new_id ?? result.updated_id;
+                            const row = db.prepare("SELECT title, content FROM memories WHERE id = ?").get(activeId);
+                            if (row) {
+                                const text = row.title ? `${row.title}\n\n${row.content}` : row.content;
+                                const embedding = await embedder.embed(text);
+                                upsertVec(db, activeId, embedding);
+                            }
+                            // Remove stale vector for superseded entry
+                            if (result.new_id) {
+                                deleteVec(db, result.updated_id);
+                            }
+                        }
+                        catch {
+                            // Best-effort
+                        }
+                    }
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                case "memory_delete": {
+                    const input = MemoryDeleteSchema.parse(args);
+                    const result = memoryDelete(db, input);
+                    // Remove vector for deleted memory
+                    if (isVecLoaded()) {
+                        deleteVec(db, input.id);
+                    }
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                case "memory_inspect": {
+                    const input = MemoryInspectSchema.parse(args);
+                    const result = memoryInspect(db, input);
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                case "memory_export": {
+                    const input = MemoryExportSchema.parse(args);
+                    const result = memoryExport(db, input);
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                case "memory_health": {
+                    const input = MemoryHealthSchema.parse(args ?? {});
+                    const result = memoryHealth(db, input);
+                    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+                }
+                default:
+                    throw new Error(`Unknown tool: ${name}`);
+            }
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // MCP Resources — read-only data endpoints for memory browsing
+    // -----------------------------------------------------------------------
+    server.setRequestHandler(ListResourcesRequestSchema, () => ({
+        resources: [
+            {
+                uri: "memory://stats",
+                name: "Memory Statistics",
+                description: "Aggregate statistics per memory layer: totals, active count, avg confidence/importance, top entities",
+                mimeType: "application/json",
+            },
+            {
+                uri: "memory://recent",
+                name: "Recent Memories",
+                description: "Memories created or updated in the last 24 hours",
+                mimeType: "application/json",
+            },
+        ],
+    }));
+    server.setRequestHandler(ListResourceTemplatesRequestSchema, () => ({
+        resourceTemplates: [
+            {
+                uriTemplate: "memory://layer/{layer}",
+                name: "Memories by Layer",
+                description: "List active memories in a specific layer (episodic, semantic, procedural, resource)",
+                mimeType: "application/json",
+            },
+            {
+                uriTemplate: "memory://entity/{name}",
+                name: "Memories by Entity",
+                description: "List active memories about a specific entity",
+                mimeType: "application/json",
+            },
+        ],
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, (request) => {
+        const { uri } = request.params;
+        if (uri === "memory://stats") {
+            const result = memoryInspect(db, {});
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify(result, null, 2),
+                    }],
+            };
+        }
+        if (uri === "memory://recent") {
+            const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString().replace(/\.\d{3}Z$/, "Z");
+            const rows = db.prepare(`SELECT id, layer, title, content, created_at FROM memories
+         WHERE superseded_by IS NULL AND COALESCE(updated_at, created_at) >= ?
+         ORDER BY COALESCE(updated_at, created_at) DESC LIMIT 50`).all(since);
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify({ since, count: rows.length, memories: rows }, null, 2),
+                    }],
+            };
+        }
+        const VALID_LAYERS = ["episodic", "semantic", "procedural", "resource"];
+        const layerMatch = uri.match(/^memory:\/\/layer\/(\w+)$/);
+        if (layerMatch) {
+            const layer = layerMatch[1];
+            if (!VALID_LAYERS.includes(layer)) {
+                throw new Error(`Invalid layer: "${layer}". Must be one of: ${VALID_LAYERS.join(", ")}`);
+            }
+            const rows = db.prepare(`SELECT id, title, content, entity_name, importance, created_at FROM memories
+         WHERE layer = ? AND superseded_by IS NULL
+         ORDER BY importance DESC, created_at DESC LIMIT 100`).all(layer);
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify({ layer, count: rows.length, memories: rows }, null, 2),
+                    }],
+            };
+        }
+        const entityMatch = uri.match(/^memory:\/\/entity\/(.+)$/);
+        if (entityMatch) {
+            const name = decodeURIComponent(entityMatch[1]);
+            const rows = db.prepare(`SELECT id, layer, title, content, importance, created_at FROM memories
+         WHERE entity_name = ? AND superseded_by IS NULL
+         ORDER BY importance DESC, created_at DESC LIMIT 100`).all(name);
+            return {
+                contents: [{
+                        uri,
+                        mimeType: "application/json",
+                        text: JSON.stringify({ entity_name: name, count: rows.length, memories: rows }, null, 2),
+                    }],
+            };
+        }
+        throw new Error(`Unknown resource URI: ${uri}`);
+    });
+    // -----------------------------------------------------------------------
+    // MCP Prompts — pre-built prompt templates for common memory operations
+    // -----------------------------------------------------------------------
+    server.setRequestHandler(ListPromptsRequestSchema, () => ({
+        prompts: [
+            {
+                name: "recall",
+                description: "Recall everything known about a topic from memory",
+                arguments: [
+                    { name: "topic", description: "What to recall (e.g. 'human design', 'project architecture')", required: true },
+                ],
+            },
+            {
+                name: "context-load",
+                description: "Load relevant context for a task into the conversation",
+                arguments: [
+                    { name: "task", description: "The task you're about to work on", required: true },
+                    { name: "scope", description: "Optional scope filter (e.g. 'mnemon-mcp', 'personal')", required: false },
+                ],
+            },
+            {
+                name: "journal",
+                description: "Create a structured journal/session entry from a summary",
+                arguments: [
+                    { name: "summary", description: "What happened in this session", required: true },
+                ],
+            },
+        ],
+    }));
+    server.setRequestHandler(GetPromptRequestSchema, (request) => {
+        const { name, arguments: args } = request.params;
+        switch (name) {
+            case "recall": {
+                const topic = args?.["topic"] ?? "general";
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: `Search your memory for everything related to: "${topic}"\n\nUse memory_search with different queries and filters to find all relevant information. Try:\n1. FTS search for the topic directly\n2. Search with entity_name if it's about a specific person/concept/project\n3. Search across different layers (episodic for events, semantic for facts, procedural for rules)\n\nSynthesize the results into a comprehensive answer. If memories conflict, note the most recent version.`,
+                            },
+                        },
+                    ],
+                };
+            }
+            case "context-load": {
+                const task = args?.["task"] ?? "current task";
+                const scope = args?.["scope"];
+                const scopeHint = scope ? `\nFilter by scope: "${scope}"` : "";
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: `Load relevant context for this task: "${task}"${scopeHint}\n\nSearch memory for:\n1. Procedural rules and conventions related to this task\n2. Semantic facts about the entities involved\n3. Recent episodic context (sessions, decisions, discussions)\n4. Relevant resources (references, documentation)\n\nPresent the loaded context as a structured briefing.`,
+                            },
+                        },
+                    ],
+                };
+            }
+            case "journal": {
+                const summary = args?.["summary"] ?? "";
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: `Create a journal entry from this session summary:\n\n${summary}\n\nUse memory_add with:\n- layer: "episodic"\n- entity_type: "user"\n- event_at: current ISO timestamp\n- importance: 0.6\n- confidence: 0.9\n\nExtract any new facts, decisions, or preferences mentioned and store them as separate semantic memories.`,
+                            },
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown prompt: ${name}`);
+        }
+    });
+    return server;
+}
+//# sourceMappingURL=server.js.map