@xultrax-web/agent-memory-mcp 0.6.0

package/dist/index.js

@@ -0,0 +1,1245 @@
+#!/usr/bin/env node
+/**
+ * agent-memory-mcp
+ *
+ * File-based persistent memory for any MCP client. Markdown files with
+ * YAML frontmatter, indexed by a simple MEMORY.md file. Inspired by
+ * Claude Code's built-in memory pattern, made available to Cursor,
+ * Cline, Continue, and any other MCP-compatible tool.
+ *
+ * Storage resolution (first match wins):
+ *   1. AGENT_MEMORY_DIR env var (absolute path)
+ *   2. AGENT_MEMORY_SCOPE=global  → ~/.agent-memory/
+ *   3. default                    → ./.agent-memory/  (per-project)
+ *
+ * Three usage modes share the same binary:
+ *   1. MCP server (stdio)    · default when invoked with no args
+ *   2. CLI                   · agent-memory <save|search|get|list|delete>
+ *   3. Bulk import           · agent-memory import-claude-code
+ *
+ * The tools are intentionally minimal. The whole point is that the
+ * storage is plain markdown — users can grep, edit, commit, and
+ * inspect it without going through the server.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import Fuse from "fuse.js";
+import matter from "gray-matter";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+// -------------------------------------------------------------
+// Storage location resolution
+// -------------------------------------------------------------
+function resolveStorageDir() {
+    const explicit = process.env.AGENT_MEMORY_DIR;
+    if (explicit)
+        return resolve(explicit);
+    if (process.env.AGENT_MEMORY_SCOPE === "global") {
+        return join(homedir(), ".agent-memory");
+    }
+    return resolve(process.cwd(), ".agent-memory");
+}
+const MEMORY_DIR = resolveStorageDir();
+const INDEX_FILE = join(MEMORY_DIR, "MEMORY.md");
+const TRASH_DIR = join(MEMORY_DIR, ".trash");
+const LOCK_FILE = join(MEMORY_DIR, ".lock");
+const EVENT_LOG = join(MEMORY_DIR, ".events.jsonl");
+const SCHEMA_VERSION = 1;
+const LOG_LEVEL_ORDER = { debug: 0, info: 1, warn: 2, error: 3 };
+const CURRENT_LOG_LEVEL = process.env.AGENT_MEMORY_LOG?.toLowerCase() ?? "info";
+function log(level, message, fields) {
+    if (LOG_LEVEL_ORDER[level] < LOG_LEVEL_ORDER[CURRENT_LOG_LEVEL])
+        return;
+    const ts = new Date().toISOString();
+    const fieldStr = fields ? " " + JSON.stringify(fields) : "";
+    process.stderr.write(`${ts} [${level}] ${message}${fieldStr}\n`);
+}
+// -------------------------------------------------------------
+// Color · ANSI for TTY, respects NO_COLOR / FORCE_COLOR
+// -------------------------------------------------------------
+const ANSI = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    bold: "\x1b[1m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    magenta: "\x1b[35m",
+};
+function useColor() {
+    if (process.env.NO_COLOR)
+        return false;
+    if (process.env.FORCE_COLOR)
+        return true;
+    return Boolean(process.stderr.isTTY);
+}
+function c(code, text) {
+    return useColor() ? `${code}${text}${ANSI.reset}` : text;
+}
+function logEvent(action, fields) {
+    try {
+        ensureStorage();
+        const record = { ts: new Date().toISOString(), action, ...fields };
+        // Append is safe across processes on POSIX + Windows for small lines
+        // (writev guarantees atomicity below pipe buffer size). For larger
+        // future events we could move to the lock-wrapped pattern.
+        writeFileSync(EVENT_LOG, JSON.stringify(record) + "\n", { flag: "a", encoding: "utf8" });
+    }
+    catch (err) {
+        // Never let event-log failure break the main operation
+        log("warn", "event log write failed", {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    }
+}
+function readEventLog(opts) {
+    if (!existsSync(EVENT_LOG))
+        return [];
+    const lines = readFileSync(EVENT_LOG, "utf8").split(/\r?\n/).filter(Boolean);
+    let records = [];
+    for (const line of lines) {
+        try {
+            records.push(JSON.parse(line));
+        }
+        catch {
+            // Skip malformed lines silently — log file may have been
+            // hand-edited or truncated mid-write
+        }
+    }
+    if (opts.action)
+        records = records.filter((r) => r.action === opts.action);
+    if (opts.tail)
+        records = records.slice(-opts.tail);
+    return records;
+}
+function ensureStorage() {
+    if (!existsSync(MEMORY_DIR))
+        mkdirSync(MEMORY_DIR, { recursive: true });
+    if (!existsSync(INDEX_FILE)) {
+        writeFileSync(INDEX_FILE, "# Memory Index\n\n_Auto-managed by agent-memory-mcp. Hand-edits to entries are preserved._\n\n", "utf8");
+    }
+}
+function ensureTrash() {
+    if (!existsSync(TRASH_DIR))
+        mkdirSync(TRASH_DIR, { recursive: true });
+}
+function ensureLockTarget() {
+    ensureStorage();
+    // proper-lockfile needs the target file to exist before locking
+    if (!existsSync(LOCK_FILE))
+        writeFileSync(LOCK_FILE, "", "utf8");
+}
+// -------------------------------------------------------------
+// Reliability primitives
+// -------------------------------------------------------------
+//
+// Every mutation goes through these two helpers:
+//   atomicWriteFile · tmp-file + rename, so power-loss never leaves
+//                     a half-written file on disk
+//   withLock        · proper-lockfile around any write transaction,
+//                     so MCP server + concurrent CLI invocations
+//                     don't corrupt the index
+function atomicWriteFile(filePath, content) {
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    writeFileSync(tmpPath, content, "utf8");
+    renameSync(tmpPath, filePath);
+}
+function withLock(fn) {
+    ensureLockTarget();
+    // proper-lockfile's sync API doesn't support retries — a collision
+    // throws immediately. For a single-process MCP server + occasional
+    // CLI invocations that's fine; the rare contention case surfaces
+    // as a clear error instead of silently corrupting data. The stale
+    // timeout means a crashed process's lock gets auto-cleaned.
+    const release = lockfile.lockSync(LOCK_FILE, { stale: 10_000 });
+    try {
+        return fn();
+    }
+    finally {
+        release();
+    }
+}
+// -------------------------------------------------------------
+// Types & validation
+// -------------------------------------------------------------
+const VALID_TYPES = new Set(["user", "feedback", "project", "reference"]);
+// Slug rules: lowercase a-z + digits + hyphen + underscore, start with
+// a letter or digit, 1-80 chars. Underscores are allowed because Claude
+// Code's memory tree uses them; we want frictionless import.
+const SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,80}$/;
+function memoryFilePath(name) {
+    return join(MEMORY_DIR, `${name}.md`);
+}
+function readMemory(name) {
+    const fp = memoryFilePath(name);
+    if (!existsSync(fp))
+        return null;
+    const raw = readFileSync(fp, "utf8");
+    const parsed = matter(raw);
+    const fm = parsed.data;
+    return {
+        name: fm.name ?? name,
+        description: fm.description ?? "",
+        type: fm.type ?? "project",
+        body: parsed.content.trim(),
+        filePath: fp,
+    };
+}
+function listMemoryFiles() {
+    if (!existsSync(MEMORY_DIR))
+        return [];
+    return readdirSync(MEMORY_DIR)
+        .filter((f) => f.endsWith(".md") && f !== "MEMORY.md")
+        .map((f) => f.replace(/\.md$/, ""));
+}
+// -------------------------------------------------------------
+// Index management
+// -------------------------------------------------------------
+const INDEX_ENTRY_PATTERN = /^- \[([^\]]+)\]\(([^)]+)\) — (.+)$/;
+function readIndex() {
+    if (!existsSync(INDEX_FILE))
+        return new Map();
+    const lines = readFileSync(INDEX_FILE, "utf8").split(/\r?\n/);
+    const entries = new Map();
+    for (const line of lines) {
+        const m = INDEX_ENTRY_PATTERN.exec(line.trim());
+        if (m)
+            entries.set(m[1], line.trim());
+    }
+    return entries;
+}
+function writeIndex(entries) {
+    const header = "# Memory Index\n\n_Auto-managed by agent-memory-mcp. Hand-edits to entries are preserved._\n\n";
+    const sorted = Array.from(entries.values()).sort();
+    atomicWriteFile(INDEX_FILE, header + sorted.join("\n") + "\n");
+}
+// Unlocked variants · safe to call only from inside a withLock block.
+function upsertIndexEntryUnlocked(name, description) {
+    const entries = readIndex();
+    entries.set(name, `- [${name}](${name}.md) — ${description}`);
+    writeIndex(entries);
+}
+function removeIndexEntryUnlocked(name) {
+    const entries = readIndex();
+    entries.delete(name);
+    writeIndex(entries);
+}
+// -------------------------------------------------------------
+// Tool handlers
+// -------------------------------------------------------------
+function toolSaveMemory(args) {
+    const name = String(args.name ?? "").trim();
+    const description = String(args.description ?? "").trim();
+    const type = String(args.type ?? "project").trim();
+    const content = String(args.content ?? "").trim();
+    if (!SLUG_PATTERN.test(name)) {
+        throw new Error(`Invalid name "${name}". Use lowercase (a-z, 0-9, hyphen, underscore), 1-80 chars, must start with letter or digit.`);
+    }
+    if (!VALID_TYPES.has(type)) {
+        throw new Error(`Invalid type "${type}". Must be one of: ${Array.from(VALID_TYPES).join(", ")}.`);
+    }
+    if (!description)
+        throw new Error("description is required");
+    if (!content)
+        throw new Error("content is required");
+    ensureStorage();
+    const frontmatter = `---\n` +
+        `name: ${name}\n` +
+        `description: ${JSON.stringify(description)}\n` +
+        `type: ${type}\n` +
+        `schema: ${SCHEMA_VERSION}\n` +
+        `---\n\n`;
+    const fp = memoryFilePath(name);
+    const isUpdate = existsSync(fp);
+    return withLock(() => {
+        atomicWriteFile(fp, frontmatter + content + "\n");
+        upsertIndexEntryUnlocked(name, description);
+        logEvent("save", { name, type, update: isUpdate, bytes: content.length });
+        log("debug", "save_memory", { name, type, update: isUpdate });
+        return `${isUpdate ? "Updated" : "Saved"} memory "${name}" (${type}) at ${fp}`;
+    });
+}
+function toolGetMemory(args) {
+    const name = String(args.name ?? "").trim();
+    const mem = readMemory(name);
+    if (!mem)
+        return `Memory "${name}" not found.`;
+    return [
+        `# ${mem.name}`,
+        `type: ${mem.type}`,
+        `description: ${mem.description}`,
+        "",
+        mem.body,
+    ].join("\n");
+}
+function toolListMemories(args) {
+    const typeFilter = args.type ? String(args.type) : null;
+    const offset = args.offset ? Math.max(0, Number(args.offset)) : 0;
+    const limit = args.limit ? Math.max(1, Number(args.limit)) : 50;
+    const names = listMemoryFiles();
+    const all = names
+        .map((n) => readMemory(n))
+        .filter((m) => m !== null)
+        .filter((m) => !typeFilter || m.type === typeFilter)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    if (all.length === 0) {
+        return typeFilter
+            ? `No memories of type "${typeFilter}".`
+            : "No memories yet. Use save_memory to create one.";
+    }
+    const page = all.slice(offset, offset + limit);
+    const lines = [];
+    const showing = offset === 0 && page.length === all.length
+        ? `Found ${all.length} memor${all.length === 1 ? "y" : "ies"}:`
+        : `Showing ${offset + 1}-${offset + page.length} of ${all.length}:`;
+    lines.push(showing);
+    lines.push("");
+    for (const m of page) {
+        lines.push(`  ${m.name}  [${m.type}]`);
+        lines.push(`    ${m.description}`);
+    }
+    if (offset + page.length < all.length) {
+        const nextOffset = offset + page.length;
+        lines.push("");
+        lines.push(`  ... ${all.length - nextOffset} more. Use offset=${nextOffset} to continue.`);
+    }
+    return lines.join("\n");
+}
+// -------------------------------------------------------------
+// Fuzzy search · Fuse.js with field weighting + snippets
+// -------------------------------------------------------------
+//
+// Why Fuse over BM25 / Lunr: memory documents are small (1-10KB)
+// and queries are short (3-5 words). Fuse gives typo tolerance,
+// word-order tolerance, and partial-match support out of the box,
+// with field weighting that approximates TF-IDF on this data size.
+// BM25 would be over-engineering at this scale.
+//
+// Field weights (name×3 > description×2 > body×1) match the
+// natural intuition: a hit in the slug or summary is more
+// meaningful than a single hit in 5KB of prose.
+function buildFuse(memories) {
+    return new Fuse(memories, {
+        includeScore: true,
+        includeMatches: true,
+        threshold: 0.4, // 0=exact, 1=anything; 0.4 is forgiving without going noisy
+        ignoreLocation: true,
+        minMatchCharLength: 2,
+        keys: [
+            { name: "name", weight: 3 },
+            { name: "description", weight: 2 },
+            { name: "body", weight: 1 },
+        ],
+    });
+}
+function extractFuseSnippet(memory, matches) {
+    // Prefer a body-field snippet so the operator sees context, not the
+    // memory's own description (which is already in the summary line).
+    const bodyMatch = matches.find((m) => m.key === "body");
+    if (!bodyMatch || !bodyMatch.indices?.length)
+        return null;
+    const text = memory.body;
+    const [start, end] = bodyMatch.indices[0];
+    const ctxStart = Math.max(0, start - 40);
+    const ctxEnd = Math.min(text.length, end + 1 + 40);
+    let snippet = text.slice(ctxStart, ctxEnd).replace(/\s+/g, " ").trim();
+    if (ctxStart > 0)
+        snippet = "... " + snippet;
+    if (ctxEnd < text.length)
+        snippet = snippet + " ...";
+    return snippet;
+}
+function toolSearchMemories(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        throw new Error("query is required");
+    const limit = args.limit ? Math.max(1, Number(args.limit)) : 10;
+    const names = listMemoryFiles();
+    const memories = names.map((n) => readMemory(n)).filter((m) => m !== null);
+    if (memories.length === 0)
+        return "No memories to search.";
+    const fuse = buildFuse(memories);
+    const results = fuse.search(query, { limit });
+    if (results.length === 0) {
+        return `No memories matched "${query}". (Fuzzy threshold 0.4; try a shorter or simpler query.)`;
+    }
+    const lines = [];
+    lines.push(`Found ${results.length} match${results.length === 1 ? "" : "es"} for "${query}":`);
+    lines.push("");
+    for (const r of results) {
+        const m = r.item;
+        // Fuse score: 0 = perfect, 1 = no match. Invert + scale for human display.
+        const relevance = Math.round((1 - (r.score ?? 0)) * 100);
+        lines.push(`  ${c(ANSI.bold, m.name)}  [${m.type}]  ${c(ANSI.dim, `· relevance ${relevance}%`)}`);
+        lines.push(`    ${m.description}`);
+        const snippet = extractFuseSnippet(m, r.matches ?? []);
+        if (snippet)
+            lines.push(`    ${c(ANSI.dim, snippet)}`);
+    }
+    return lines.join("\n");
+}
+// -------------------------------------------------------------
+// Relevant memories · for LLM consumption (full content)
+// -------------------------------------------------------------
+//
+// Where search_memories returns human-readable matches with snippets,
+// relevant_memories returns the FULL memory bodies. The intended
+// caller is an LLM asking "what do I know about X?" so it can pull
+// just-in-time context without a second round trip.
+//
+// Default max=5 keeps the context window cost bounded.
+function toolRelevantMemories(args) {
+    const query = String(args.query ?? "").trim();
+    if (!query)
+        throw new Error("query is required");
+    const max = args.max ? Math.max(1, Math.min(20, Number(args.max))) : 5;
+    const names = listMemoryFiles();
+    const memories = names.map((n) => readMemory(n)).filter((m) => m !== null);
+    if (memories.length === 0)
+        return "No memories available.";
+    const fuse = buildFuse(memories);
+    const results = fuse.search(query, { limit: max });
+    if (results.length === 0) {
+        return `No memories relevant to "${query}".`;
+    }
+    // Emit each memory as a markdown section so the LLM can ingest
+    // multiple memories in one shot without further parsing.
+    const sections = [];
+    sections.push(`# Memories relevant to "${query}"\n`);
+    for (const r of results) {
+        const m = r.item;
+        const relevance = Math.round((1 - (r.score ?? 0)) * 100);
+        sections.push(`## ${m.name} · [${m.type}] · relevance ${relevance}%`);
+        sections.push(`> ${m.description}`);
+        sections.push("");
+        sections.push(m.body);
+        sections.push("");
+        sections.push("---");
+    }
+    return sections.join("\n");
+}
+function toolDeleteMemory(args) {
+    const name = String(args.name ?? "").trim();
+    if (!SLUG_PATTERN.test(name))
+        throw new Error(`Invalid name "${name}".`);
+    const fp = memoryFilePath(name);
+    if (!existsSync(fp))
+        return `Memory "${name}" not found.`;
+    return withLock(() => {
+        ensureTrash();
+        // Trash filename: <unix-ms>-<name>.md so restore can pick the
+        // most recent version and the operator can see when it was binned.
+        const ts = Date.now();
+        const trashPath = join(TRASH_DIR, `${ts}-${name}.md`);
+        renameSync(fp, trashPath);
+        removeIndexEntryUnlocked(name);
+        logEvent("delete", { name, trash: `${ts}-${name}.md` });
+        log("debug", "delete_memory", { name });
+        return `Moved "${name}" to trash. Restore with: agent-memory restore ${name}`;
+    });
+}
+function toolRestoreMemory(args) {
+    const name = String(args.name ?? "").trim();
+    if (!SLUG_PATTERN.test(name))
+        throw new Error(`Invalid name "${name}".`);
+    ensureTrash();
+    // Most recent trash entry wins (timestamp prefix sorts lexically).
+    const matches = readdirSync(TRASH_DIR)
+        .filter((f) => f.endsWith(`-${name}.md`))
+        .sort()
+        .reverse();
+    if (matches.length === 0)
+        return `No trashed memory named "${name}" found.`;
+    return withLock(() => {
+        const trashPath = join(TRASH_DIR, matches[0]);
+        const fp = memoryFilePath(name);
+        if (existsSync(fp)) {
+            throw new Error(`Cannot restore: "${name}" already exists in the active store. ` +
+                `Delete it first (it'll get its own trash entry) then restore.`);
+        }
+        renameSync(trashPath, fp);
+        // Re-add to index using the restored file's frontmatter description.
+        const mem = readMemory(name);
+        if (mem)
+            upsertIndexEntryUnlocked(name, mem.description);
+        const binnedAt = new Date(Number(matches[0].split("-")[0])).toISOString();
+        logEvent("restore", { name, binnedAt });
+        log("debug", "restore_memory", { name });
+        return `Restored "${name}" from trash (was binned ${binnedAt}).`;
+    });
+}
+function runDoctor(rebuildIndex) {
+    ensureStorage();
+    const diskFiles = listMemoryFiles();
+    const indexEntries = readIndex();
+    const indexNames = Array.from(indexEntries.keys());
+    const orphans = diskFiles.filter((n) => !indexEntries.has(n));
+    const dangling = indexNames.filter((n) => !diskFiles.includes(n));
+    const unreadable = [];
+    const invalidType = [];
+    for (const name of diskFiles) {
+        try {
+            const mem = readMemory(name);
+            if (!mem) {
+                unreadable.push(name);
+            }
+            else if (!VALID_TYPES.has(mem.type)) {
+                invalidType.push(`${name} (type="${mem.type}")`);
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            unreadable.push(`${name} (${msg.split("\n")[0]})`);
+        }
+    }
+    let rebuilt = false;
+    if (rebuildIndex && (orphans.length > 0 || dangling.length > 0)) {
+        withLock(() => {
+            const newEntries = new Map();
+            for (const name of diskFiles) {
+                const mem = readMemory(name);
+                if (mem) {
+                    newEntries.set(name, `- [${name}](${name}.md) — ${mem.description}`);
+                }
+            }
+            writeIndex(newEntries);
+        });
+        rebuilt = true;
+    }
+    return {
+        storageDir: MEMORY_DIR,
+        diskFiles,
+        indexEntries: indexNames,
+        orphans,
+        dangling,
+        unreadable,
+        invalidType,
+        rebuilt,
+    };
+}
+function formatDoctorReport(r, rebuildRequested) {
+    const lines = [];
+    lines.push(`agent-memory doctor`);
+    lines.push(`storage : ${r.storageDir}`);
+    lines.push(`on disk : ${r.diskFiles.length} memor${r.diskFiles.length === 1 ? "y" : "ies"}`);
+    lines.push(`indexed : ${r.indexEntries.length}`);
+    lines.push("");
+    const issueCount = r.orphans.length + r.dangling.length + r.unreadable.length + r.invalidType.length;
+    if (issueCount === 0) {
+        lines.push("OK · no issues found");
+        return lines.join("\n");
+    }
+    lines.push(`Found ${issueCount} issue${issueCount === 1 ? "" : "s"}:`);
+    for (const o of r.orphans)
+        lines.push(`  orphan   · ${o}.md exists on disk but not in MEMORY.md`);
+    for (const d of r.dangling)
+        lines.push(`  dangling · ${d} indexed but file missing`);
+    for (const u of r.unreadable)
+        lines.push(`  bad      · ${u}`);
+    for (const v of r.invalidType)
+        lines.push(`  type     · ${v}`);
+    lines.push("");
+    if (r.rebuilt) {
+        lines.push(`Fixed · rebuilt MEMORY.md from disk (${r.diskFiles.length} entries).`);
+        lines.push(`Note · unreadable / invalid-type files were NOT removed. Inspect and fix by hand.`);
+    }
+    else if (!rebuildRequested) {
+        lines.push("Re-run with --rebuild-index to reconstruct MEMORY.md from disk.");
+    }
+    return lines.join("\n");
+}
+function toolDoctor(args) {
+    const rebuild = Boolean(args["rebuild-index"]);
+    const report = runDoctor(rebuild);
+    return formatDoctorReport(report, rebuild);
+}
+// -------------------------------------------------------------
+// Stats · operator dashboard
+// -------------------------------------------------------------
+function toolStats(_args) {
+    ensureStorage();
+    const diskFiles = listMemoryFiles();
+    const memories = diskFiles.map((n) => readMemory(n)).filter((m) => m !== null);
+    const byType = {};
+    for (const t of VALID_TYPES)
+        byType[t] = 0;
+    for (const m of memories)
+        byType[m.type] = (byType[m.type] ?? 0) + 1;
+    // File sizes via stat on each file (read body length doesn't include
+    // frontmatter bytes — stat gives the on-disk truth).
+    let totalBytes = 0;
+    let largestBytes = 0;
+    let largestName = "";
+    for (const n of diskFiles) {
+        const fp = memoryFilePath(n);
+        try {
+            const stats = readFileSync(fp, "utf8").length;
+            totalBytes += stats;
+            if (stats > largestBytes) {
+                largestBytes = stats;
+                largestName = n;
+            }
+        }
+        catch {
+            // skip unreadable
+        }
+    }
+    // Oldest/newest by file mtime would need a stat call; use the
+    // index ordering as a proxy (alphabetical) for simplicity. Real
+    // mtime-based age would need `statSync` which adds an N read.
+    // Skipping that for v0.4; defer to a `--detailed` flag if asked.
+    const events = readEventLog({});
+    const trashCount = existsSync(TRASH_DIR)
+        ? readdirSync(TRASH_DIR).filter((f) => f.endsWith(".md")).length
+        : 0;
+    const lines = [];
+    lines.push(c(ANSI.bold, "agent-memory stats"));
+    lines.push(c(ANSI.dim, `storage : ${MEMORY_DIR}`));
+    lines.push("");
+    lines.push(c(ANSI.bold, `memories: ${memories.length} total`));
+    for (const t of ["user", "feedback", "project", "reference"]) {
+        const count = byType[t] ?? 0;
+        const bar = count > 0 ? "█".repeat(Math.min(count, 40)) : "";
+        lines.push(`  ${t.padEnd(10)} ${String(count).padStart(4)}  ${c(ANSI.cyan, bar)}`);
+    }
+    lines.push("");
+    lines.push(c(ANSI.bold, "storage:"));
+    lines.push(`  total size  ${fmtBytes(totalBytes)}`);
+    lines.push(`  avg size    ${memories.length > 0 ? fmtBytes(totalBytes / memories.length) : "—"}`);
+    if (largestName) {
+        lines.push(`  largest     ${fmtBytes(largestBytes)}  (${largestName})`);
+    }
+    lines.push("");
+    lines.push(c(ANSI.bold, "audit:"));
+    lines.push(`  events logged   ${events.length}`);
+    lines.push(`  items in trash  ${trashCount}`);
+    if (events.length > 0) {
+        lines.push(`  last event      ${events[events.length - 1].ts} (${events[events.length - 1].action})`);
+    }
+    return lines.join("\n");
+}
+function fmtBytes(n) {
+    if (n < 1024)
+        return `${Math.round(n)} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / (1024 * 1024)).toFixed(2)} MB`;
+}
+// -------------------------------------------------------------
+// Log browser · paginated audit-trail view
+// -------------------------------------------------------------
+function toolLogEvents(args) {
+    const tail = args.tail ? Number(args.tail) : 20;
+    const action = args.action ? String(args.action) : undefined;
+    const events = readEventLog({ tail, action });
+    if (events.length === 0) {
+        return action ? `No events of action "${action}" in the log.` : "No events logged yet.";
+    }
+    const lines = [];
+    lines.push(c(ANSI.bold, `Last ${events.length} event${events.length === 1 ? "" : "s"}${action ? ` (action=${action})` : ""}:`));
+    lines.push("");
+    for (const e of events) {
+        const { ts, action: a, ...rest } = e;
+        const tsStr = c(ANSI.dim, String(ts)
+            .replace("T", " ")
+            .replace(/\.\d+Z$/, "Z"));
+        const actionStr = c(actionColor(String(a)), String(a).padEnd(7));
+        const fields = Object.entries(rest)
+            .map(([k, v]) => `${c(ANSI.dim, k + "=")}${String(v)}`)
+            .join("  ");
+        lines.push(`  ${tsStr}  ${actionStr}  ${fields}`);
+    }
+    return lines.join("\n");
+}
+function actionColor(action) {
+    if (action === "save")
+        return ANSI.green;
+    if (action === "delete")
+        return ANSI.yellow;
+    if (action === "restore")
+        return ANSI.cyan;
+    return ANSI.dim;
+}
+// -------------------------------------------------------------
+// Server wiring
+// -------------------------------------------------------------
+const server = new Server({ name: "agent-memory", version: "0.2.0" }, { capabilities: { tools: {}, resources: {} } });
+// -------------------------------------------------------------
+// Resource URI scheme
+// -------------------------------------------------------------
+//
+//   agent-memory://index              → the MEMORY.md index
+//   agent-memory://memory/{name}      → an individual memory file
+//
+// Clients (Cursor, Claude Desktop, etc.) can pin the index as
+// always-visible context. Per-memory URIs are exposed so a client
+// can pin specific memories the user marks as "always relevant"
+// (e.g. their user profile memory, the project's prime directive).
+const URI_INDEX = "agent-memory://index";
+const URI_MEMORY_PREFIX = "agent-memory://memory/";
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    ensureStorage();
+    const memories = listMemoryFiles()
+        .map((n) => readMemory(n))
+        .filter((m) => m !== null)
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        resources: [
+            {
+                uri: URI_INDEX,
+                name: "Memory index",
+                description: "Auto-managed index of every stored memory. Pin this as always-visible context so the assistant sees what's known before deciding what to look up.",
+                mimeType: "text/markdown",
+            },
+            ...memories.map((m) => ({
+                uri: `${URI_MEMORY_PREFIX}${m.name}`,
+                name: m.name,
+                description: `[${m.type}] ${m.description}`,
+                mimeType: "text/markdown",
+            })),
+        ],
+    };
+});
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri;
+    ensureStorage();
+    if (uri === URI_INDEX) {
+        const text = readFileSync(INDEX_FILE, "utf8");
+        return { contents: [{ uri, mimeType: "text/markdown", text }] };
+    }
+    if (uri.startsWith(URI_MEMORY_PREFIX)) {
+        const name = uri.slice(URI_MEMORY_PREFIX.length);
+        // Defense in depth: strict slug validation prevents path traversal
+        // even though the URI parser should already reject "../" segments.
+        if (!SLUG_PATTERN.test(name)) {
+            throw new Error(`Invalid memory name in URI: "${name}"`);
+        }
+        const fp = memoryFilePath(name);
+        if (!existsSync(fp)) {
+            throw new Error(`Resource not found: ${uri}`);
+        }
+        const text = readFileSync(fp, "utf8");
+        return { contents: [{ uri, mimeType: "text/markdown", text }] };
+    }
+    throw new Error(`Unknown resource URI: ${uri}. Supported: ${URI_INDEX}, ${URI_MEMORY_PREFIX}{name}`);
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "save_memory",
+            description: "Save (or update) a memory. Memories are markdown files with YAML frontmatter, " +
+                "stored at the resolved memory dir. Use a short kebab-case name; the description " +
+                "is what's shown in the index and used for search ranking.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: {
+                        type: "string",
+                        description: "Short kebab-case slug, 1-80 chars (e.g. 'user-prefers-tabs')",
+                    },
+                    description: {
+                        type: "string",
+                        description: "One-line summary, shown in the index and ranked highly in search",
+                    },
+                    type: {
+                        type: "string",
+                        enum: ["user", "feedback", "project", "reference"],
+                        description: "Memory type: user (about the person), feedback (rules to follow), project (state/context), reference (external pointers)",
+                    },
+                    content: {
+                        type: "string",
+                        description: "Markdown body. For feedback/project, include **Why:** and **How to apply:** lines.",
+                    },
+                },
+                required: ["name", "description", "type", "content"],
+            },
+        },
+        {
+            name: "search_memories",
+            description: "Fuzzy search across name, description, and body. Tolerates typos, word-order shifts, and partial matches. Returns top matches with relevance scores (0-100) and body-context snippets. Use this for human-readable browsing.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "What to look for. Fuzzy match (typo-tolerant).",
+                    },
+                    limit: { type: "number", description: "Max results to return (default 10)." },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "relevant_memories",
+            description: "Find memories relevant to a query and return their FULL content (not summaries). Designed for LLM ingestion — call this when the assistant needs context on a topic and the memory index alone isn't specific enough. Returns up to `max` memories as a markdown document.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "The topic the assistant needs context on." },
+                    max: {
+                        type: "number",
+                        description: "Max memories to include (default 5, capped at 20).",
+                    },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "get_memory",
+            description: "Fetch a single memory by name.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The memory's name slug" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "list_memories",
+            description: "List stored memories, optionally filtered by type. Paginated.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    type: {
+                        type: "string",
+                        enum: ["user", "feedback", "project", "reference"],
+                        description: "Optional filter — only list memories of this type",
+                    },
+                    offset: { type: "number", description: "Skip this many results (default 0)." },
+                    limit: { type: "number", description: "Max results per page (default 50)." },
+                },
+            },
+        },
+        {
+            name: "delete_memory",
+            description: "Move a memory to .trash/ (soft delete). The file is removed from the index but recoverable via restore_memory until you manually empty .trash/.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The memory's name slug" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "restore_memory",
+            description: "Restore a memory from .trash/ back into the active store. Picks the most recent trash entry for the name.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    name: { type: "string", description: "The memory's name slug" },
+                },
+                required: ["name"],
+            },
+        },
+        {
+            name: "doctor",
+            description: "Check storage integrity. Reports orphan files (on disk but not indexed), dangling index entries (no file), unreadable files, and invalid types. Pass rebuild-index=true to reconstruct MEMORY.md from disk.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    "rebuild-index": {
+                        type: "boolean",
+                        description: "If true, rewrite MEMORY.md to match what's on disk.",
+                    },
+                },
+            },
+        },
+        {
+            name: "stats",
+            description: "Dashboard of memory-store state: counts per type, total size, largest memory, audit-log size, trash count.",
+            inputSchema: { type: "object", properties: {} },
+        },
+        {
+            name: "log_events",
+            description: "Read recent entries from the audit event log (.events.jsonl). Returns the last N events, optionally filtered by action.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    tail: { type: "number", description: "How many recent events to return (default 20)" },
+                    action: {
+                        type: "string",
+                        description: "Filter by action (save | delete | restore)",
+                    },
+                },
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case "save_memory":
+                result = toolSaveMemory(args);
+                break;
+            case "search_memories":
+                result = toolSearchMemories(args);
+                break;
+            case "relevant_memories":
+                result = toolRelevantMemories(args);
+                break;
+            case "get_memory":
+                result = toolGetMemory(args);
+                break;
+            case "list_memories":
+                result = toolListMemories(args);
+                break;
+            case "delete_memory":
+                result = toolDeleteMemory(args);
+                break;
+            case "restore_memory":
+                result = toolRestoreMemory(args);
+                break;
+            case "doctor":
+                result = toolDoctor(args);
+                break;
+            case "stats":
+                result = toolStats(args);
+                break;
+            case "log_events":
+                result = toolLogEvents(args);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// -------------------------------------------------------------
+// CLI mode
+// -------------------------------------------------------------
+//
+// When invoked with no arguments, the entry point starts the MCP
+// stdio server (as MCP clients expect). When invoked with a known
+// subcommand as argv[2], it runs CLI mode and exits — making the
+// same binary usable from shell scripts, cron, git hooks, etc.
+const CLI_COMMANDS = new Set([
+    "save",
+    "search",
+    "relevant",
+    "get",
+    "list",
+    "delete",
+    "restore",
+    "doctor",
+    "stats",
+    "log",
+    "import-claude-code",
+    "help",
+    "--help",
+    "-h",
+    "--version",
+    "-v",
+]);
+function parseFlags(argv) {
+    const flags = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith("--")) {
+            const eq = arg.indexOf("=");
+            if (eq >= 0) {
+                flags[arg.slice(2, eq)] = arg.slice(eq + 1);
+            }
+            else if (i + 1 < argv.length && !argv[i + 1].startsWith("--")) {
+                flags[arg.slice(2)] = argv[i + 1];
+                i++;
+            }
+            else {
+                flags[arg.slice(2)] = true;
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { flags, positional };
+}
+function readStdin() {
+    return new Promise((resolve) => {
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (chunk) => (data += chunk));
+        process.stdin.on("end", () => resolve(data));
+    });
+}
+async function cliMain(command, rest) {
+    if (command === "help" || command === "--help" || command === "-h") {
+        printHelp();
+        return 0;
+    }
+    if (command === "--version" || command === "-v") {
+        process.stdout.write("agent-memory-mcp 0.2.0\n");
+        return 0;
+    }
+    ensureStorage();
+    const { flags, positional } = parseFlags(rest);
+    try {
+        switch (command) {
+            case "save": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory save <name> --type <t> --description <d> [--content <c> | --content-file <path> | --stdin]");
+                let content = String(flags.content ?? "");
+                if (flags["content-file"]) {
+                    content = readFileSync(String(flags["content-file"]), "utf8");
+                }
+                else if (flags.stdin) {
+                    content = await readStdin();
+                }
+                const result = toolSaveMemory({
+                    name,
+                    type: String(flags.type ?? "project"),
+                    description: String(flags.description ?? ""),
+                    content,
+                });
+                process.stdout.write(result + "\n");
+                return 0;
+            }
+            case "search": {
+                const query = positional[0];
+                if (!query)
+                    throw new Error("Usage: agent-memory search <query> [--limit N]");
+                process.stdout.write(toolSearchMemories({
+                    query,
+                    limit: flags.limit ? Number(flags.limit) : undefined,
+                }) + "\n");
+                return 0;
+            }
+            case "relevant": {
+                const query = positional[0];
+                if (!query)
+                    throw new Error("Usage: agent-memory relevant <query> [--max N]");
+                process.stdout.write(toolRelevantMemories({
+                    query,
+                    max: flags.max ? Number(flags.max) : undefined,
+                }) + "\n");
+                return 0;
+            }
+            case "get": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory get <name>");
+                process.stdout.write(toolGetMemory({ name }) + "\n");
+                return 0;
+            }
+            case "list": {
+                process.stdout.write(toolListMemories({
+                    type: flags.type,
+                    offset: flags.offset ? Number(flags.offset) : undefined,
+                    limit: flags.limit ? Number(flags.limit) : undefined,
+                }) + "\n");
+                return 0;
+            }
+            case "delete": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory delete <name>");
+                process.stdout.write(toolDeleteMemory({ name }) + "\n");
+                return 0;
+            }
+            case "restore": {
+                const name = positional[0];
+                if (!name)
+                    throw new Error("Usage: agent-memory restore <name>");
+                process.stdout.write(toolRestoreMemory({ name }) + "\n");
+                return 0;
+            }
+            case "doctor": {
+                process.stdout.write(toolDoctor({ "rebuild-index": Boolean(flags["rebuild-index"]) }) + "\n");
+                return 0;
+            }
+            case "stats": {
+                process.stdout.write(toolStats({}) + "\n");
+                return 0;
+            }
+            case "log": {
+                process.stdout.write(toolLogEvents({
+                    tail: flags.tail ? Number(flags.tail) : undefined,
+                    action: flags.action ? String(flags.action) : undefined,
+                }) + "\n");
+                return 0;
+            }
+            case "import-claude-code": {
+                return importClaudeCode({
+                    source: flags.source ? String(flags.source) : undefined,
+                    project: flags.project ? String(flags.project) : undefined,
+                    overwrite: Boolean(flags.overwrite),
+                    dryRun: Boolean(flags["dry-run"]),
+                });
+            }
+            default:
+                throw new Error(`Unknown command: ${command}. Try 'agent-memory help'.`);
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`error: ${message}\n`);
+        return 1;
+    }
+}
+function printHelp() {
+    process.stdout.write(`agent-memory-mcp · markdown memory for AI agents
+
+USAGE
+  agent-memory <command> [args]            CLI mode
+  agent-memory-mcp                         MCP server mode (default when no args)
+
+COMMANDS
+  save <name> --type <t> --description <d> --content <c>
+                                           Save or update a memory.
+                                           Type: user | feedback | project | reference
+                                           Content sources: --content "..." | --content-file <path> | --stdin
+  search <query> [--limit N]               Fuzzy search (typo-tolerant), top N (default 10)
+  relevant <query> [--max N]               Top N matches as full markdown for LLM ingestion
+  get <name>                               Print one memory's full contents
+  list [--type <t>] [--offset N] [--limit N]
+                                           List memories (paginated, default limit 50)
+  delete <name>                            Soft-delete: move to .trash/, removable later
+  restore <name>                           Restore the most recent trash entry for <name>
+  doctor [--rebuild-index]                 Check storage integrity (orphans, dangling
+                                           index entries, unreadable files). With
+                                           --rebuild-index, regenerates MEMORY.md from disk.
+  stats                                    Dashboard: counts per type, sizes, audit/trash counts.
+  log [--tail N] [--action save|delete|restore]
+                                           Recent audit-log entries.
+  import-claude-code [--source <path>] [--project <pat>] [--overwrite] [--dry-run]
+                                           Walk ~/.claude/projects/*/memory/ and
+                                           import each memory into the current store.
+                                           --project filters by substring match.
+  help                                     Show this help
+  --version                                Print version
+
+STORAGE
+  Memories live in ./.agent-memory/ (per-project, default).
+  Set AGENT_MEMORY_SCOPE=global for ~/.agent-memory/.
+  Set AGENT_MEMORY_DIR=/path for any custom location.
+
+CURRENT STORE
+  ${MEMORY_DIR}
+
+DOCS
+  https://github.com/xultrax-web/agent-memory-mcp
+`);
+}
+function importClaudeCode(opts) {
+    const source = opts.source ?? join(homedir(), ".claude", "projects");
+    if (!existsSync(source)) {
+        process.stderr.write(`error: Claude Code projects dir not found: ${source}\n`);
+        return 1;
+    }
+    const projectDirs = readdirSync(source).filter((d) => {
+        const memDir = join(source, d, "memory");
+        return existsSync(memDir);
+    });
+    if (projectDirs.length === 0) {
+        process.stderr.write(`no Claude Code projects with memory found at ${source}\n`);
+        return 1;
+    }
+    const filtered = opts.project
+        ? projectDirs.filter((d) => d.toLowerCase().includes(opts.project.toLowerCase()))
+        : projectDirs;
+    if (filtered.length === 0) {
+        process.stderr.write(`no projects matched filter "${opts.project}". Available: ${projectDirs.join(", ")}\n`);
+        return 1;
+    }
+    let imported = 0;
+    let skipped = 0;
+    let errors = 0;
+    for (const projectDir of filtered) {
+        const memDir = join(source, projectDir, "memory");
+        process.stdout.write(`\n[${projectDir}]\n`);
+        const files = readdirSync(memDir).filter((f) => f.endsWith(".md") && f !== "MEMORY.md");
+        for (const file of files) {
+            const fp = join(memDir, file);
+            const raw = readFileSync(fp, "utf8");
+            // Tolerate malformed frontmatter — fall back to filename + raw content.
+            let parsedData = {};
+            let parsedContent = raw;
+            try {
+                const parsed = matter(raw);
+                parsedData = parsed.data;
+                parsedContent = parsed.content;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stdout.write(`  warn  ${file} · frontmatter parse failed (${msg.split("\n")[0]}); importing as-is\n`);
+            }
+            // The slug comes from the filename — Claude Code's `name` field is
+            // a human-readable title, not a slug. We lowercase to enforce our
+            // case rule. Special chars rejected downstream by SLUG_PATTERN.
+            const name = file.replace(/\.md$/, "").toLowerCase();
+            const metadata = parsedData.metadata ?? {};
+            const type = String(parsedData.type ?? metadata.type ?? "project");
+            const description = String(parsedData.description ?? parsedData.name ?? "(imported from Claude Code)");
+            const content = parsedContent.trim();
+            if (!SLUG_PATTERN.test(name)) {
+                process.stdout.write(`  skip  ${file} · slug "${name}" has unsupported characters\n`);
+                skipped++;
+                continue;
+            }
+            if (!VALID_TYPES.has(type)) {
+                process.stdout.write(`  skip  ${name} · invalid type "${type}"\n`);
+                skipped++;
+                continue;
+            }
+            if (!opts.overwrite && existsSync(memoryFilePath(name))) {
+                process.stdout.write(`  skip  ${name} · already exists (use --overwrite to replace)\n`);
+                skipped++;
+                continue;
+            }
+            if (opts.dryRun) {
+                process.stdout.write(`  would import  ${name} [${type}]\n`);
+                imported++;
+                continue;
+            }
+            try {
+                toolSaveMemory({ name, type, description, content });
+                process.stdout.write(`  imported  ${name} [${type}]\n`);
+                imported++;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                process.stdout.write(`  error  ${name} · ${msg}\n`);
+                errors++;
+            }
+        }
+    }
+    process.stdout.write(`\n${opts.dryRun ? "dry run" : "import"} complete · imported=${imported} skipped=${skipped} errors=${errors}\n`);
+    if (opts.dryRun) {
+        process.stdout.write(`(re-run without --dry-run to actually save)\n`);
+    }
+    return errors > 0 ? 1 : 0;
+}
+// -------------------------------------------------------------
+// Boot · dispatch CLI vs MCP server based on argv
+// -------------------------------------------------------------
+async function main() {
+    const command = process.argv[2];
+    if (command && CLI_COMMANDS.has(command)) {
+        const exitCode = await cliMain(command, process.argv.slice(3));
+        process.exit(exitCode);
+    }
+    ensureStorage();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`agent-memory-mcp · storage: ${MEMORY_DIR}\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});