@exaudeus/memory-mcp 0.1.0

package/dist/config-manager.d.ts

@@ -0,0 +1,49 @@
+import type { MemoryConfig } from './types.js';
+import { type LoadedConfig, type ConfigOrigin } from './config.js';
+import { MarkdownMemoryStore } from './store.js';
+/** Health status for a lobe (matches existing LobeHealth in index.ts) */
+export type LobeHealth = {
+    readonly status: 'healthy';
+} | {
+    readonly status: 'degraded';
+    readonly error: string;
+    readonly since: string;
+    readonly recovery: string[];
+};
+/**
+ * ConfigManager: Hot-reload config on every tool call.
+ *
+ * Design:
+ * - Constructor takes configPath + initial LoadedConfig from startup
+ * - ensureFresh() stats the config file, reloads if mtime changed
+ * - Reload is atomic: both lobeConfigs + stores swap together or not at all
+ * - Graceful degradation: any error keeps old config, logs to stderr
+ * - Observability: all reloads logged with timestamp and lobe count
+ */
+export declare class ConfigManager {
+    private configPath;
+    private configOrigin;
+    private lobeConfigs;
+    private stores;
+    private lobeHealth;
+    private configMtime;
+    protected statFile(path: string): Promise<{
+        mtimeMs: number;
+    }>;
+    constructor(configPath: string, initial: LoadedConfig, initialStores: Map<string, MarkdownMemoryStore>, initialHealth: Map<string, LobeHealth>);
+    /**
+     * Ensure config is fresh. Call at the start of every tool handler.
+     * Stats config file, reloads if mtime changed. Graceful on all errors.
+     */
+    ensureFresh(): Promise<void>;
+    /**
+     * Reload config from file. Atomic: both lobeConfigs and stores swap together.
+     * Graceful: parse failure or store init failure keeps old config/stores.
+     */
+    private reload;
+    getStore(lobe: string): MarkdownMemoryStore | undefined;
+    getLobeNames(): readonly string[];
+    getLobeHealth(lobe: string): LobeHealth | undefined;
+    getConfigOrigin(): ConfigOrigin;
+    getLobeConfig(lobe: string): MemoryConfig | undefined;
+}

package/dist/config-manager.js

@@ -0,0 +1,126 @@
+// ConfigManager: Handles config hot-reload with stat-based freshness checking
+//
+// Encapsulates config state (lobeConfigs, configOrigin, stores, lobeHealth, mtime).
+// Provides ensureFresh() method that stats the config file and reloads if changed.
+// All tool handlers call ensureFresh() at entry to validate config is current.
+import { stat } from 'fs/promises';
+import { getLobeConfigs } from './config.js';
+import { MarkdownMemoryStore } from './store.js';
+/**
+ * ConfigManager: Hot-reload config on every tool call.
+ *
+ * Design:
+ * - Constructor takes configPath + initial LoadedConfig from startup
+ * - ensureFresh() stats the config file, reloads if mtime changed
+ * - Reload is atomic: both lobeConfigs + stores swap together or not at all
+ * - Graceful degradation: any error keeps old config, logs to stderr
+ * - Observability: all reloads logged with timestamp and lobe count
+ */
+export class ConfigManager {
+    // Dependency injection for testing: allow tests to override stat function
+    async statFile(path) {
+        return stat(path);
+    }
+    constructor(configPath, initial, initialStores, initialHealth) {
+        this.configPath = configPath;
+        this.configOrigin = initial.origin;
+        this.lobeConfigs = initial.configs;
+        this.stores = initialStores;
+        this.lobeHealth = initialHealth;
+        this.configMtime = Date.now(); // Initial mtime (will be updated on first stat)
+    }
+    /**
+     * Ensure config is fresh. Call at the start of every tool handler.
+     * Stats config file, reloads if mtime changed. Graceful on all errors.
+     */
+    async ensureFresh() {
+        // Only reload file-based configs (env-var configs can't change at runtime)
+        if (this.configOrigin.source !== 'file') {
+            return;
+        }
+        try {
+            const stats = await this.statFile(this.configPath);
+            if (stats.mtimeMs > this.configMtime) {
+                await this.reload(stats.mtimeMs);
+            }
+        }
+        catch (error) {
+            // Any stat error (ENOENT, EACCES, EIO, etc.) → keep old config
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[memory-mcp] Config stat failed: ${message}. Keeping current config.\n`);
+        }
+    }
+    /**
+     * Reload config from file. Atomic: both lobeConfigs and stores swap together.
+     * Graceful: parse failure or store init failure keeps old config/stores.
+     */
+    async reload(newMtime) {
+        try {
+            const newConfig = getLobeConfigs();
+            // If parse failed, getLobeConfigs falls through to env/default.
+            // For file-based reload, we want to detect parse failure and keep old.
+            // Check: if origin changed from 'file' to 'env'/'default', parse failed.
+            if (newConfig.origin.source !== 'file') {
+                process.stderr.write(`[memory-mcp] Config reload failed (parse error). Keeping current config.\n`);
+                return;
+            }
+            // Initialize new stores
+            const newStores = new Map();
+            const newHealth = new Map();
+            for (const [name, config] of newConfig.configs) {
+                try {
+                    const store = new MarkdownMemoryStore(config);
+                    await store.init();
+                    newStores.set(name, store);
+                    newHealth.set(name, { status: 'healthy' });
+                }
+                catch (error) {
+                    // Store init failed → mark as degraded, continue with others
+                    const message = error instanceof Error ? error.message : String(error);
+                    process.stderr.write(`[memory-mcp] Lobe "${name}" init failed during reload: ${message}. Marked as degraded.\n`);
+                    newHealth.set(name, {
+                        status: 'degraded',
+                        error: message,
+                        since: new Date().toISOString(),
+                        recovery: [
+                            `Verify the repo root exists: ${config.repoRoot}`,
+                            'Check file permissions on the memory directory.',
+                            'If the repo was moved, update memory-config.json.',
+                        ],
+                    });
+                }
+            }
+            // Atomic swap
+            this.configOrigin = newConfig.origin;
+            this.lobeConfigs = newConfig.configs;
+            this.stores = newStores;
+            this.lobeHealth = newHealth;
+            this.configMtime = newMtime;
+            const lobeCount = newConfig.configs.size;
+            const degradedCount = Array.from(newHealth.values()).filter(h => h.status === 'degraded').length;
+            const timestamp = new Date().toISOString();
+            process.stderr.write(`[memory-mcp] [${timestamp}] Config reloaded: ${lobeCount} lobe(s)${degradedCount > 0 ? `, ${degradedCount} degraded` : ''}\n`);
+        }
+        catch (error) {
+            // Reload failed entirely → keep old config
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[memory-mcp] Config reload failed: ${message}. Keeping current config.\n`);
+        }
+    }
+    // Accessors
+    getStore(lobe) {
+        return this.stores.get(lobe);
+    }
+    getLobeNames() {
+        return Array.from(this.lobeConfigs.keys());
+    }
+    getLobeHealth(lobe) {
+        return this.lobeHealth.get(lobe);
+    }
+    getConfigOrigin() {
+        return this.configOrigin;
+    }
+    getLobeConfig(lobe) {
+        return this.lobeConfigs.get(lobe);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,32 @@
+import type { MemoryConfig, BehaviorConfig } from './types.js';
+/** How the config was loaded — discriminated union so configFilePath
+ *  only exists when source is 'file' (illegal states unrepresentable) */
+export type ConfigOrigin = {
+    readonly source: 'file';
+    readonly path: string;
+} | {
+    readonly source: 'env';
+} | {
+    readonly source: 'default';
+};
+/** Result of loading lobe configs */
+export interface LoadedConfig {
+    readonly configs: ReadonlyMap<string, MemoryConfig>;
+    readonly origin: ConfigOrigin;
+    /** Resolved behavior config — present when a "behavior" block was found in memory-config.json */
+    readonly behavior?: BehaviorConfig;
+}
+interface MemoryConfigFileBehavior {
+    staleDaysStandard?: number;
+    staleDaysPreferences?: number;
+    maxStaleInBriefing?: number;
+    maxDedupSuggestions?: number;
+    maxConflictPairs?: number;
+}
+/** Parse and validate a behavior config block, falling back to defaults for each field.
+ *  Warns to stderr for unknown keys (likely typos) and out-of-range values.
+ *  Exported for testing — validates and clamps all fields. */
+export declare function parseBehaviorConfig(raw?: MemoryConfigFileBehavior): BehaviorConfig;
+/** Load lobe configs with priority: memory-config.json -> env vars -> single-repo default */
+export declare function getLobeConfigs(): LoadedConfig;
+export {};

package/dist/config.js

@@ -0,0 +1,162 @@
+// Configuration loading for the memory MCP server.
+//
+// Priority: memory-config.json → env vars → single-repo default
+// Graceful degradation: each source falls through to the next on failure.
+import { readFileSync } from 'fs';
+import { execFileSync } from 'child_process';
+import path from 'path';
+import os from 'os';
+import { DEFAULT_STORAGE_BUDGET_BYTES } from './types.js';
+import { DEFAULT_STALE_DAYS_STANDARD, DEFAULT_STALE_DAYS_PREFERENCES, DEFAULT_MAX_STALE_IN_BRIEFING, DEFAULT_MAX_DEDUP_SUGGESTIONS, DEFAULT_MAX_CONFLICT_PAIRS, } from './thresholds.js';
+/** Validate and clamp a numeric threshold to a given range.
+ *  Returns the default if the value is missing, NaN, or out of range. */
+function clampThreshold(value, defaultValue, min, max) {
+    if (value === undefined || value === null)
+        return defaultValue;
+    const n = Number(value);
+    if (isNaN(n) || n < min || n > max) {
+        process.stderr.write(`[memory-mcp] Behavior threshold out of range [${min}, ${max}]: ${value} — using default ${defaultValue}\n`);
+        return defaultValue;
+    }
+    return Math.round(n); // integer thresholds only
+}
+/** Known behavior config keys — used to warn on typos/unknown fields at startup. */
+const KNOWN_BEHAVIOR_KEYS = new Set([
+    'staleDaysStandard', 'staleDaysPreferences',
+    'maxStaleInBriefing', 'maxDedupSuggestions', 'maxConflictPairs',
+]);
+/** Parse and validate a behavior config block, falling back to defaults for each field.
+ *  Warns to stderr for unknown keys (likely typos) and out-of-range values.
+ *  Exported for testing — validates and clamps all fields. */
+export function parseBehaviorConfig(raw) {
+    if (!raw)
+        return {};
+    // Warn on unrecognized keys so typos don't silently produce defaults
+    for (const key of Object.keys(raw)) {
+        if (!KNOWN_BEHAVIOR_KEYS.has(key)) {
+            process.stderr.write(`[memory-mcp] Unknown behavior config key "${key}" — ignored. ` +
+                `Valid keys: ${Array.from(KNOWN_BEHAVIOR_KEYS).join(', ')}\n`);
+        }
+    }
+    return {
+        staleDaysStandard: clampThreshold(raw.staleDaysStandard, DEFAULT_STALE_DAYS_STANDARD, 1, 365),
+        staleDaysPreferences: clampThreshold(raw.staleDaysPreferences, DEFAULT_STALE_DAYS_PREFERENCES, 1, 730),
+        maxStaleInBriefing: clampThreshold(raw.maxStaleInBriefing, DEFAULT_MAX_STALE_IN_BRIEFING, 1, 20),
+        maxDedupSuggestions: clampThreshold(raw.maxDedupSuggestions, DEFAULT_MAX_DEDUP_SUGGESTIONS, 1, 10),
+        maxConflictPairs: clampThreshold(raw.maxConflictPairs, DEFAULT_MAX_CONFLICT_PAIRS, 1, 5),
+    };
+}
+function resolveRoot(root) {
+    return root
+        .replace(/^\$HOME\b/, process.env.HOME ?? '')
+        .replace(/^~/, process.env.HOME ?? '');
+}
+/**
+ * Resolve the memory storage directory for a workspace.
+ *
+ * Priority:
+ * 1. Explicit memoryDir config -> use it (relative to repoRoot, or absolute)
+ * 2. Git repo detected -> `<git-common-dir>/memory/` — shared across all worktrees
+ * 3. Fallback -> `~/.memory-mcp/<workspaceName>/` (central, no git pollution)
+ *
+ * Uses `git rev-parse --git-common-dir` which always resolves to the main
+ * .git/ directory regardless of whether you're in a linked worktree or
+ * submodule. This ensures all worktrees of the same repo share one memory.
+ */
+function resolveMemoryPath(repoRoot, workspaceName, explicitMemoryDir) {
+    if (explicitMemoryDir) {
+        if (path.isAbsolute(explicitMemoryDir)) {
+            return explicitMemoryDir;
+        }
+        return path.join(repoRoot, explicitMemoryDir);
+    }
+    // Use git to find the common .git directory (shared across worktrees)
+    try {
+        const result = execFileSync('git', ['rev-parse', '--git-common-dir'], { cwd: repoRoot, encoding: 'utf-8', timeout: 5000 }).trim();
+        const gitCommonDir = path.resolve(repoRoot, result);
+        return path.join(gitCommonDir, 'memory');
+    }
+    catch {
+        // Not a git repo or git not available — fall through to central store
+    }
+    return path.join(os.homedir(), '.memory-mcp', workspaceName);
+}
+/** Load lobe configs with priority: memory-config.json -> env vars -> single-repo default */
+export function getLobeConfigs() {
+    const configs = new Map();
+    // 1. Try loading from memory-config.json (highest priority)
+    const configPath = path.resolve(new URL('.', import.meta.url).pathname, '..', 'memory-config.json');
+    try {
+        const raw = readFileSync(configPath, 'utf-8');
+        const external = JSON.parse(raw);
+        if (!external.lobes || typeof external.lobes !== 'object') {
+            process.stderr.write(`[memory-mcp] Invalid memory-config.json: missing "lobes" object\n`);
+        }
+        else {
+            // Parse global behavior config once — applies to all lobes
+            const behavior = parseBehaviorConfig(external.behavior);
+            for (const [name, config] of Object.entries(external.lobes)) {
+                if (!config.root) {
+                    process.stderr.write(`[memory-mcp] Skipping lobe "${name}": missing "root" field\n`);
+                    continue;
+                }
+                const repoRoot = resolveRoot(config.root);
+                configs.set(name, {
+                    repoRoot,
+                    memoryPath: resolveMemoryPath(repoRoot, name, config.memoryDir),
+                    storageBudgetBytes: (config.budgetMB ?? 2) * 1024 * 1024,
+                    behavior,
+                });
+            }
+            if (configs.size > 0) {
+                process.stderr.write(`[memory-mcp] Loaded ${configs.size} lobe(s) from memory-config.json\n`);
+                // Pass resolved behavior at the top-level so diagnostics can surface active values
+                const resolvedBehavior = external.behavior ? parseBehaviorConfig(external.behavior) : undefined;
+                return { configs, origin: { source: 'file', path: configPath }, behavior: resolvedBehavior };
+            }
+        }
+    }
+    catch (error) {
+        // ENOENT = config file doesn't exist, which is expected — silently fall through
+        const isFileNotFound = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+        if (!isFileNotFound) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[memory-mcp] Failed to parse memory-config.json: ${message}\n`);
+        }
+    }
+    // 2. Try env var multi-repo mode
+    const workspacesJson = process.env.MEMORY_MCP_WORKSPACES;
+    if (workspacesJson) {
+        const explicitDir = process.env.MEMORY_MCP_DIR;
+        const storageBudget = parseInt(process.env.MEMORY_MCP_BUDGET ?? '', 10) || DEFAULT_STORAGE_BUDGET_BYTES;
+        try {
+            const parsed = JSON.parse(workspacesJson);
+            for (const [name, rawRoot] of Object.entries(parsed)) {
+                const repoRoot = resolveRoot(rawRoot);
+                configs.set(name, {
+                    repoRoot,
+                    memoryPath: resolveMemoryPath(repoRoot, name, explicitDir),
+                    storageBudgetBytes: storageBudget,
+                });
+            }
+            if (configs.size > 0) {
+                process.stderr.write(`[memory-mcp] Loaded ${configs.size} lobe(s) from MEMORY_MCP_WORKSPACES env var\n`);
+                return { configs, origin: { source: 'env' } };
+            }
+        }
+        catch (e) {
+            process.stderr.write(`[memory-mcp] Failed to parse MEMORY_MCP_WORKSPACES: ${e}\n`);
+        }
+    }
+    // 3. Fall back to single-repo default
+    const repoRoot = process.env.MEMORY_MCP_REPO_ROOT ?? process.cwd();
+    const explicitDir = process.env.MEMORY_MCP_DIR;
+    const storageBudget = parseInt(process.env.MEMORY_MCP_BUDGET ?? '', 10) || DEFAULT_STORAGE_BUDGET_BYTES;
+    configs.set('default', {
+        repoRoot,
+        memoryPath: resolveMemoryPath(repoRoot, 'default', explicitDir),
+        storageBudgetBytes: storageBudget,
+    });
+    process.stderr.write(`[memory-mcp] Using single-lobe default mode (cwd: ${repoRoot})\n`);
+    return { configs, origin: { source: 'default' } };
+}

package/dist/crash-journal.d.ts

@@ -0,0 +1,38 @@
+/** A single crash report */
+export interface CrashReport {
+    readonly timestamp: string;
+    readonly pid: number;
+    readonly error: string;
+    readonly stack?: string;
+    readonly type: CrashType;
+    readonly context: CrashContext;
+    readonly recovery: string[];
+    readonly serverUptime: number;
+}
+export type CrashType = 'uncaught-exception' | 'unhandled-rejection' | 'startup-failure' | 'lobe-init-failure' | 'transport-error' | 'unknown';
+/** What the server was doing when it crashed */
+export interface CrashContext {
+    readonly phase: 'startup' | 'running' | 'migration' | 'shutdown';
+    readonly lastToolCall?: string;
+    readonly activeLobe?: string;
+    readonly configSource?: string;
+    readonly lobeCount?: number;
+}
+/** Reset the start time (called on startup) */
+export declare function markServerStarted(): void;
+/** Write a crash report to disk. Synchronous — must work even in dying process. */
+export declare function writeCrashReport(report: CrashReport): Promise<string>;
+/** Synchronous version for use in process exit handlers where async isn't reliable */
+export declare function writeCrashReportSync(report: CrashReport): string | null;
+/** Build a CrashReport from an error */
+export declare function buildCrashReport(error: unknown, type: CrashType, context: CrashContext): CrashReport;
+/** Read the most recent crash report (if any) */
+export declare function readLatestCrash(): Promise<CrashReport | null>;
+/** Read all crash reports, newest first */
+export declare function readCrashHistory(limit?: number): Promise<CrashReport[]>;
+/** Clear the latest crash indicator (call after successfully showing it to user) */
+export declare function clearLatestCrash(): Promise<void>;
+/** Format a crash report for display in an MCP tool response */
+export declare function formatCrashReport(report: CrashReport): string;
+/** Format a short crash summary for briefing inclusion */
+export declare function formatCrashSummary(report: CrashReport): string;

package/dist/crash-journal.js

@@ -0,0 +1,198 @@
+// Crash journal: persistent, human-readable record of MCP server failures.
+//
+// Design principles:
+//   - Errors are data: crashes become structured records, not silent deaths
+//   - Observability as a constraint: every failure is visible on next startup
+//   - Fail fast with meaningful messages: journal then die, don't zombie
+//
+// Location: ~/.memory-mcp/crashes/
+//   crash-<timestamp>.json  — one file per crash (no write conflicts)
+//   LATEST.json             — symlink/copy of most recent crash (fast access)
+import { promises as fs } from 'fs';
+import path from 'path';
+import os from 'os';
+const CRASH_DIR = path.join(os.homedir(), '.memory-mcp', 'crashes');
+const LATEST_FILE = path.join(CRASH_DIR, 'LATEST.json');
+const MAX_CRASH_FILES = 20; // keep last 20 crash reports
+let serverStartTime = Date.now();
+/** Reset the start time (called on startup) */
+export function markServerStarted() {
+    serverStartTime = Date.now();
+}
+/** Write a crash report to disk. Synchronous — must work even in dying process. */
+export async function writeCrashReport(report) {
+    await fs.mkdir(CRASH_DIR, { recursive: true });
+    const filename = `crash-${report.timestamp.replace(/[:.]/g, '-')}.json`;
+    const filepath = path.join(CRASH_DIR, filename);
+    const content = JSON.stringify(report, null, 2);
+    await fs.writeFile(filepath, content, 'utf-8');
+    await fs.writeFile(LATEST_FILE, content, 'utf-8');
+    // Prune old crash files (keep newest MAX_CRASH_FILES)
+    try {
+        const files = (await fs.readdir(CRASH_DIR))
+            .filter(f => f.startsWith('crash-') && f.endsWith('.json'))
+            .sort()
+            .reverse();
+        for (const old of files.slice(MAX_CRASH_FILES)) {
+            await fs.unlink(path.join(CRASH_DIR, old)).catch(() => { });
+        }
+    }
+    catch { /* pruning is best-effort */ }
+    return filepath;
+}
+/** Synchronous version for use in process exit handlers where async isn't reliable */
+export function writeCrashReportSync(report) {
+    const { mkdirSync, writeFileSync } = require('fs');
+    try {
+        mkdirSync(CRASH_DIR, { recursive: true });
+        const filename = `crash-${report.timestamp.replace(/[:.]/g, '-')}.json`;
+        const filepath = path.join(CRASH_DIR, filename);
+        const content = JSON.stringify(report, null, 2);
+        writeFileSync(filepath, content, 'utf-8');
+        writeFileSync(LATEST_FILE, content, 'utf-8');
+        return filepath;
+    }
+    catch {
+        return null;
+    }
+}
+/** Build a CrashReport from an error */
+export function buildCrashReport(error, type, context) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+    const recovery = generateRecoverySteps(type, message, context);
+    return {
+        timestamp: new Date().toISOString(),
+        pid: process.pid,
+        error: message,
+        stack,
+        type,
+        context,
+        recovery,
+        serverUptime: Math.round((Date.now() - serverStartTime) / 1000),
+    };
+}
+/** Generate human-readable recovery instructions based on crash type */
+function generateRecoverySteps(type, message, context) {
+    const steps = [];
+    // Common first step
+    steps.push('Toggle the memory MCP off and on in Firebender to restart the server.');
+    switch (type) {
+        case 'startup-failure':
+            if (message.includes('memory-config.json')) {
+                steps.push('Check memory-config.json for syntax errors (invalid JSON).');
+                steps.push('Verify all "root" paths in lobe definitions exist on disk.');
+            }
+            if (message.includes('ENOENT') || message.includes('not found')) {
+                steps.push(`Verify the path exists: check if the directory referenced in the error is accessible.`);
+            }
+            steps.push('Try running: node /path/to/memory-mcp/dist/index.js directly to see stderr output.');
+            break;
+        case 'lobe-init-failure':
+            steps.push(`The lobe "${context.activeLobe}" failed to initialize.`);
+            steps.push('Check that the repo root exists and is accessible.');
+            steps.push('Verify git is installed if the repo uses .git/memory/ storage.');
+            steps.push('Other lobes may still work — the server continues in degraded mode.');
+            break;
+        case 'uncaught-exception':
+        case 'unhandled-rejection':
+            steps.push('This is likely a bug in the memory MCP server.');
+            steps.push('If reproducible, note what tool call triggered it and report the issue.');
+            if (message.includes('ENOSPC')) {
+                steps.push('Disk is full — free space and restart.');
+            }
+            if (message.includes('EACCES') || message.includes('EPERM')) {
+                steps.push('Permission error — check file permissions on ~/.memory-mcp/ and the repo .git/memory/ directories.');
+            }
+            break;
+        case 'transport-error':
+            steps.push('The communication channel between Firebender and the MCP broke.');
+            steps.push('This usually happens when the IDE restarts or the MCP is toggled.');
+            steps.push('Simply toggle the MCP off and on — this is expected behavior.');
+            break;
+        default:
+            steps.push('Check the stack trace for details.');
+    }
+    return steps;
+}
+/** Read the most recent crash report (if any) */
+export async function readLatestCrash() {
+    try {
+        const content = await fs.readFile(LATEST_FILE, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/** Read all crash reports, newest first */
+export async function readCrashHistory(limit = 10) {
+    try {
+        const files = (await fs.readdir(CRASH_DIR))
+            .filter(f => f.startsWith('crash-') && f.endsWith('.json'))
+            .sort()
+            .reverse()
+            .slice(0, limit);
+        const reports = [];
+        for (const file of files) {
+            try {
+                const content = await fs.readFile(path.join(CRASH_DIR, file), 'utf-8');
+                reports.push(JSON.parse(content));
+            }
+            catch { /* skip corrupt files */ }
+        }
+        return reports;
+    }
+    catch {
+        return [];
+    }
+}
+/** Clear the latest crash indicator (call after successfully showing it to user) */
+export async function clearLatestCrash() {
+    try {
+        await fs.unlink(LATEST_FILE);
+    }
+    catch { /* already gone */ }
+}
+/** Format a crash report for display in an MCP tool response */
+export function formatCrashReport(report) {
+    const lines = [
+        `## ⚠ Memory MCP Crash Report`,
+        ``,
+        `**When:** ${report.timestamp}`,
+        `**Type:** ${report.type}`,
+        `**Phase:** ${report.context.phase}`,
+        `**Uptime:** ${report.serverUptime}s before crash`,
+        `**Error:** ${report.error}`,
+    ];
+    if (report.context.lastToolCall) {
+        lines.push(`**Last tool call:** ${report.context.lastToolCall}`);
+    }
+    if (report.context.activeLobe) {
+        lines.push(`**Affected lobe:** ${report.context.activeLobe}`);
+    }
+    lines.push('');
+    lines.push('### Recovery Steps');
+    for (const step of report.recovery) {
+        lines.push(`- ${step}`);
+    }
+    if (report.stack) {
+        lines.push('');
+        lines.push('### Stack Trace');
+        lines.push('```');
+        // Truncate very long stacks
+        const stackLines = report.stack.split('\n').slice(0, 10);
+        lines.push(stackLines.join('\n'));
+        if (report.stack.split('\n').length > 10) {
+            lines.push('... (truncated)');
+        }
+        lines.push('```');
+    }
+    return lines.join('\n');
+}
+/** Format a short crash summary for briefing inclusion */
+export function formatCrashSummary(report) {
+    const age = Math.round((Date.now() - new Date(report.timestamp).getTime()) / 1000 / 60);
+    const ageStr = age < 60 ? `${age}m ago` : `${Math.round(age / 60)}h ago`;
+    return `[!] Server crashed ${ageStr}: ${report.type} — ${report.error.substring(0, 100)}`;
+}