sessionmem 1.3.0 → 1.5.0

package/SECURITY.md

@@ -0,0 +1,33 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are provided for the latest published stable release of
+sessionmem. Older releases and prereleases are not supported;
+upgrade to the latest stable release before checking whether an issue persists.
+The main branch receives fixes for the next release but is not a supported
+published version.
+
+## Report a vulnerability privately
+
+Use [GitHub private vulnerability reporting](https://github.com/catfish-1234/sessionmem/security/advisories/new)
+to open a private security advisory. You need a GitHub account. Reports stay
+private while maintainers investigate and coordinate a fix with the reporter.
+Do not disclose vulnerabilities in public issues, pull requests, or discussions.
+
+Include the affected version, operating system and Node.js version, reproduction
+steps or a minimal proof of concept, expected impact, and any suggested mitigation.
+Use synthetic data: do not include real API keys, private session transcripts,
+production memory databases, or other sensitive information.
+
+## Response expectations
+
+Maintainers aim to acknowledge reports within 7 calendar days and provide an
+initial assessment within 14 calendar days. These are best-effort targets for a
+community-maintained project, not guaranteed service levels. If you have not
+heard back after 7 days, follow up in the same private advisory.
+
+For confirmed vulnerabilities, maintainers coordinate remediation, disclosure
+timing, and reporter credit in the private advisory. Fix timing depends on
+severity and complexity; maintainers will share progress and available
+workarounds there. Keep details private until coordinated disclosure.

package/dist/adapters/diagnostics.js

@@ -0,0 +1,109 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { IDEInstaller, isManagedClaudeHook } from "./ide/installer.js";
+import { resolveDbPath } from "../cli/context.js";
+function object(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+export function checkHooks(installation) {
+    const expected = installation.hooks;
+    if (!expected)
+        return "This host uses MCP tools; no lifecycle hooks are required";
+    const config = IDEInstaller.parseJsonc(readFileSync(expected.path, "utf8"));
+    if (config.disableAllHooks === true)
+        throw new Error("Claude Code has disableAllHooks enabled");
+    const hooks = object(config.hooks);
+    for (const spec of expected.entries) {
+        const entries = Array.isArray(hooks[spec.event]) ? hooks[spec.event] : [];
+        const managed = entries.flatMap((value) => {
+            const entry = object(value);
+            return Array.isArray(entry.hooks) ? entry.hooks.filter((value) => isManagedClaudeHook(object(value).command, spec.command)).map((hook) => ({ entry, hook: object(hook) })) : [];
+        });
+        const matches = managed.filter(({ entry, hook }) => {
+            if (entry.matcher !== spec.matcher || entry.async === true)
+                return false;
+            return hook.type === "command" && hook.command === spec.command && hook.async !== true;
+        });
+        if (managed.length !== 1 || matches.length !== 1)
+            throw new Error(`${spec.event} hook is missing, duplicated, or differs from the current definition`);
+    }
+    return `SessionStart, SessionEnd, PostToolUse match current hook definitions (${expected.path})`;
+}
+/** Check the installed launch entry before executing the known local command. */
+export function readMcpLaunch(installation) {
+    const expected = installation.mcp;
+    const content = readFileSync(expected.path, "utf8");
+    let entry;
+    if (expected.format === "toml") {
+        // The Codex installer writes this small TOML section with JSON-compatible
+        // quoted values. Refuse unfamiliar syntax rather than claiming it works.
+        const section = content.match(/^\s*\[mcp_servers\.sessionmem\][^\S\r\n]*\r?\n([\s\S]*?)(?=^\s*\[|$(?![\s\S]))/m)?.[1];
+        if (!section)
+            throw new Error("sessionmem MCP section is missing");
+        if (/^\s*\[mcp_servers\.sessionmem\./m.test(content) || /^\s*(?:env|env_vars|cwd|url)\s*=/m.test(section)) {
+            throw new Error("Custom Codex launch settings require manual verification; doctor supports the installer-generated command and args");
+        }
+        if (/^\s*enabled\s*=\s*false\s*$/m.test(section))
+            throw new Error("sessionmem MCP server is disabled");
+        entry = {
+            command: JSON.parse(section.match(/^\s*command\s*=\s*(.+)$/m)?.[1] ?? "null"),
+            args: JSON.parse(section.match(/^\s*args\s*=\s*(.+)$/m)?.[1] ?? "null"),
+        };
+    }
+    else {
+        const config = IDEInstaller.parseJsonc(content);
+        entry = object(object(config.mcpServers).sessionmem);
+    }
+    if (entry.disabled === true)
+        throw new Error("sessionmem MCP server is disabled");
+    if (entry.type !== undefined && entry.type !== "stdio")
+        throw new Error("sessionmem MCP server must use the local stdio transport");
+    if (entry.command !== expected.command || JSON.stringify(entry.args) !== JSON.stringify(expected.args)) {
+        throw new Error(`sessionmem MCP launch entry differs from the current definition (${expected.path})`);
+    }
+    if (entry.env !== undefined && (entry.env === null || typeof entry.env !== "object" || Array.isArray(entry.env))) {
+        throw new Error("sessionmem MCP environment must be an object");
+    }
+    const env = object(entry.env);
+    if (Object.values(env).some((value) => typeof value !== "string")) {
+        throw new Error("sessionmem MCP environment values must be strings");
+    }
+    return { command: expected.command, args: expected.args, env: env };
+}
+export async function probeMcpWiring(launch, dbPath, version) {
+    if (launch.env?.SESSIONMEM_DB_PATH && resolve(resolveDbPath(launch.env.SESSIONMEM_DB_PATH)) !== resolve(dbPath)) {
+        throw new Error("MCP configuration selects a different SESSIONMEM_DB_PATH; run doctor with that path");
+    }
+    const inherited = Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+    const client = new Client({ name: "sessionmem-doctor", version });
+    const transport = new StdioClientTransport({
+        command: launch.command,
+        args: launch.args,
+        env: { ...inherited, ...launch.env, SESSIONMEM_DB_PATH: dbPath },
+        stderr: "ignore",
+    });
+    try {
+        await client.connect(transport, { timeout: 5000 });
+        const server = client.getServerVersion();
+        if (server?.name !== "sessionmem" || server.version !== version) {
+            throw new Error(`MCP server version does not match sessionmem ${version}`);
+        }
+        const tools = await client.listTools({}, { timeout: 5000 });
+        for (const name of ["stats", "storeMemory", "retrieveMemories"]) {
+            if (!tools.tools.some((tool) => tool.name === name))
+                throw new Error(`MCP tool ${name} is missing`);
+        }
+        const result = await client.callTool({ name: "stats", arguments: {} }, undefined, { timeout: 5000 });
+        const payload = Array.isArray(result.content) ? object(result.content.find((part) => object(part).type === "text")) : {};
+        if (result.isError || typeof payload.text !== "string" || !JSON.parse(payload.text).ok) {
+            throw new Error("MCP stats tool failed");
+        }
+    }
+    finally {
+        await transport.close();
+    }
+}

package/dist/adapters/generic.js

@@ -69,6 +69,7 @@ const TOOL_DEFINITIONS = [
             mode: retrieveMemoriesRequestSchema.shape.mode.describe("'auto' for the standard startup context-load path. 'on-demand' for an explicit mid-session retrieval triggered by a specific task or question."),
             depth: retrieveMemoriesRequestSchema.shape.depth.describe("'default' for standard semantic search. 'deep' for a broader sweep that surfaces less-similar memories — use when the topic is new or unfamiliar."),
             tags: retrieveMemoriesRequestSchema.shape.tags.describe("Optional tag filter. When provided, only return memories that have ALL listed tags."),
+            includeHistory: retrieveMemoriesRequestSchema.shape.includeHistory.describe("Include superseded facts for historical questions. Omit for current facts only."),
         },
     },
     {
@@ -209,18 +210,21 @@ export class GenericMCPAdapter {
     guidanceTargets() {
         return [join(process.cwd(), "AGENTS.md")];
     }
+    installation() {
+        return { mcp: { path: join(process.cwd(), ".mcp.json"), command: "sessionmem", args: ["run"] } };
+    }
     /**
      * Fallback for hosts that aren't specifically detected: register sessionmem
      * in a project-local `.mcp.json` (the de-facto generic MCP config format).
      */
     async install() {
-        const configPath = join(process.cwd(), ".mcp.json");
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
             "run",
         ]);
     }
     async uninstall() {
-        const configPath = join(process.cwd(), ".mcp.json");
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.removeMcpConfig(configPath, "sessionmem");
     }
     async call(_method, _request) {

package/dist/adapters/global/antigravity.js

@@ -11,13 +11,16 @@ import { IDEInstaller } from "../ide/installer.js";
 const ANTIGRAVITY_MCP_CONFIG = [".gemini", "config", "mcp_config.json"];
 export class AntigravityAdapter extends GenericMCPAdapter {
     name = "Antigravity";
+    installation() {
+        return { mcp: { path: join(homedir(), ...ANTIGRAVITY_MCP_CONFIG), command: "sessionmem", args: ["run"] } };
+    }
     // Capabilities inherited from GenericMCPAdapter (tools only).
     /** Antigravity reads AGENTS.md-style guidance from its global config dir. */
     guidanceTargets() {
         return [join(homedir(), ".antigravity", "AGENTS.md")];
     }
     async install() {
-        const configPath = join(homedir(), ...ANTIGRAVITY_MCP_CONFIG);
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
             "run",
         ]);

package/dist/adapters/global/claudeCode.js

@@ -21,15 +21,30 @@ export class ClaudeCodeAdapter extends GenericMCPAdapter {
     settingsPath() {
         return join(homedir(), ".claude", "settings.json");
     }
+    installation() {
+        const isWindows = process.platform === "win32";
+        return {
+            mcp: {
+                path: join(homedir(), ".claude.json"),
+                command: isWindows ? "cmd" : "sessionmem",
+                args: isWindows ? ["/c", "sessionmem", "run"] : ["run"],
+            },
+            hooks: {
+                path: this.settingsPath(),
+                entries: [
+                    { event: "SessionStart", command: SESSIONMEM_HOOK_COMMAND },
+                    { event: "SessionEnd", command: SESSIONMEM_SESSION_END_HOOK_COMMAND },
+                    { event: "PostToolUse", command: SESSIONMEM_POST_TOOL_HOOK_COMMAND, matcher: SESSIONMEM_POST_TOOL_MATCHER },
+                ],
+            },
+        };
+    }
     async install() {
-        const configPath = join(homedir(), ".claude.json");
         // On Windows, the globally-installed `sessionmem` bin is a `.cmd` shim.
         // Claude Code spawns MCP servers WITHOUT a shell, and `.cmd` shims require
         // cmd.exe to execute, so a bare `command: "sessionmem"` fails to start.
         // Route through `cmd /c sessionmem run` so the shim is resolved correctly.
-        const isWindows = process.platform === "win32";
-        const command = isWindows ? "cmd" : "sessionmem";
-        const args = isWindows ? ["/c", "sessionmem", "run"] : ["run"];
+        const { path: configPath, command, args } = this.installation().mcp;
         const mcpOk = await IDEInstaller.injectMcpConfig(configPath, "sessionmem", command, args);
         // Register a SessionStart hook so prior memories are injected automatically
         // at the start of EVERY Claude Code session. This is the deterministic

package/dist/adapters/global/codex.js

@@ -12,6 +12,9 @@ args = ["run"]
 `;
 export class CodexAdapter extends GenericMCPAdapter {
     name = "Codex";
+    installation() {
+        return { mcp: { path: join(homedir(), ".codex", "config.toml"), command: "sessionmem", args: ["run"], format: "toml" } };
+    }
     // Capabilities inherited from GenericMCPAdapter (tools only).
     /** Codex reads AGENTS.md; the global one lives in ~/.codex/AGENTS.md. */
     guidanceTargets() {
@@ -20,21 +23,19 @@ export class CodexAdapter extends GenericMCPAdapter {
     async install() {
         try {
             const { readFileSync, writeFileSync, existsSync, mkdirSync } = await import("fs");
-            const configPath = join(homedir(), ".codex", "config.toml");
+            const configPath = this.installation().mcp.path;
             const existing = existsSync(configPath)
                 ? readFileSync(configPath, "utf-8")
                 : "";
-            // Idempotent: skip if the sessionmem server section already exists.
-            // Anchor on line start so a commented/substring mention doesn't match.
-            if (existing.split("\n").some((line) => line.trimStart().startsWith("[mcp_servers.sessionmem]")))
-                return true;
+            // Replace our section so re-install also repairs stale launch commands.
+            const withoutServer = existing.replace(/^\s*\[mcp_servers\.sessionmem\][^\S\r\n]*\r?\n[\s\S]*?(?=^\s*\[|$(?![\s\S]))/m, "");
             const dir = dirname(configPath);
             if (!existsSync(dir)) {
                 mkdirSync(dir, { recursive: true });
             }
             // Append the TOML block, trimming trailing whitespace to keep a single
             // blank-line separator before our section.
-            const updated = existing.trimEnd() + "\n" + CODEX_MCP_BLOCK;
+            const updated = withoutServer.trimEnd() + "\n" + CODEX_MCP_BLOCK;
             writeFileSync(configPath, updated, "utf-8");
             return true;
         }

package/dist/adapters/global/qcoder.js

@@ -17,13 +17,16 @@ import { IDEInstaller } from "../ide/installer.js";
 // directory spelling, or wire it through the UI-managed store if no file exists.
 export class QCoderAdapter extends GenericMCPAdapter {
     name = "QCoder";
+    installation() {
+        return { mcp: { path: join(homedir(), ".qcoder", "config.json"), command: "sessionmem", args: ["run"] } };
+    }
     // Capabilities inherited from GenericMCPAdapter (tools only).
     /** QCoder reads AGENTS.md-style guidance from its global config dir. */
     guidanceTargets() {
         return [join(homedir(), ".qcoder", "AGENTS.md")];
     }
     async install() {
-        const configPath = join(homedir(), ".qcoder", "config.json");
+        const configPath = this.installation().mcp.path;
         return IDEInstaller.injectMcpConfig(configPath, "sessionmem", "sessionmem", [
             "run",
         ]);

package/dist/adapters/ide/cline.js

@@ -59,6 +59,9 @@ export class ClineAdapter extends GenericMCPAdapter {
         // expects to read.
         return IDEInstaller.injectMcpConfig(this.configPath, "sessionmem", "sessionmem", ["run"], { disabled: false, autoApprove: [] });
     }
+    installation() {
+        return { mcp: { path: this.configPath, command: "sessionmem", args: ["run"] } };
+    }
     async uninstall() {
         return IDEInstaller.removeMcpConfig(this.configPath, "sessionmem");
     }

package/dist/adapters/ide/cursor.js

@@ -21,6 +21,9 @@ export class CursorAdapter extends GenericMCPAdapter {
     get configPath() {
         return join(homedir(), ".cursor", "mcp.json");
     }
+    installation() {
+        return { mcp: { path: this.configPath, command: "sessionmem", args: ["run"] } };
+    }
     async install() {
         return IDEInstaller.injectMcpConfig(this.configPath, "sessionmem", "sessionmem", ["run"]);
     }

package/dist/adapters/ide/installer.js

@@ -35,6 +35,15 @@ export const SESSIONMEM_POST_TOOL_HOOK_COMMAND = _isWindows
 export const SESSIONMEM_POST_TOOL_MATCHER = "Bash|Edit|Write|MultiEdit";
 /** Default Claude Code hook event for the legacy 2-arg hook helpers. */
 const DEFAULT_HOOK_EVENT = "SessionStart";
+/** Recognize our bare/Windows hook forms, including stale command arguments. */
+export function isManagedClaudeHook(value, expected) {
+    if (typeof value !== "string")
+        return false;
+    const normalize = (command) => command.replace(/^cmd \/c /i, "");
+    const base = normalize(expected);
+    const candidate = normalize(value);
+    return candidate === base || candidate.startsWith(`${base} `);
+}
 export class IDEInstaller {
     static parseJsonc(content) {
         // Strip single-line comments (//) that appear outside of string literals.
@@ -201,11 +210,14 @@ export class IDEInstaller {
         const eventEntries = Array.isArray(hooks[eventName])
             ? hooks[eventName]
             : [];
-        // Drop any pre-existing sessionmem entry so re-install stays idempotent and
-        // a stale command form is replaced rather than duplicated. hookEntryHasCommand
-        // only inspects entry.hooks, so it dedupes correctly whether or not the entry
-        // carries a matcher.
-        const filtered = eventEntries.filter((entry) => !this.hookEntryHasCommand(entry, command));
+        // Replace our commands, including stale forms, while preserving user hooks
+        // that share an entry. The fresh entry restores the current matcher/type.
+        const filtered = eventEntries.flatMap((entry) => {
+            if (!entry || !Array.isArray(entry.hooks))
+                return [entry];
+            const remaining = entry.hooks.filter((hook) => !isManagedClaudeHook(hook?.command, command));
+            return remaining.length ? [{ ...entry, hooks: remaining }] : [];
+        });
         filtered.push(matcher !== undefined
             ? { matcher, hooks: [{ type: "command", command }] }
             : { hooks: [{ type: "command", command }] });

package/dist/adapters/ide/windsurf.js

@@ -20,6 +20,9 @@ export class WindsurfAdapter extends GenericMCPAdapter {
     get configPath() {
         return join(homedir(), ".codeium", "windsurf", "mcp_config.json");
     }
+    installation() {
+        return { mcp: { path: this.configPath, command: "sessionmem", args: ["run"] } };
+    }
     async install() {
         return IDEInstaller.injectMcpConfig(this.configPath, "sessionmem", "sessionmem", ["run"]);
     }

package/dist/adapters/installedHosts.js

@@ -0,0 +1,51 @@
+import { accessSync, constants, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { delimiter, join } from "node:path";
+import { AdapterFactory } from "./factory.js";
+// Installed-host detection is deliberately separate from runtime session-env
+// detection. Add a row here when another host has a verified install probe.
+export const INSTALLED_HOSTS = [
+    {
+        adapter: "claude-code",
+        executables: ["claude"],
+        homeExecutables: [".local/bin/claude", ".claude/local/claude"],
+    },
+];
+export function isExecutable(file) {
+    try {
+        if (!statSync(file).isFile())
+            return false;
+        accessSync(file, process.platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function executableCandidates(file) {
+    if (process.platform !== "win32")
+        return [file];
+    const extensions = (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";");
+    return [file, ...extensions.filter(Boolean).map((ext) => file + ext.toLowerCase())];
+}
+export function detectInstalledAdapters(table = INSTALLED_HOSTS) {
+    const pathDirs = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+    return table.filter((host) => {
+        const paths = [
+            ...host.executables.flatMap((name) => pathDirs.map((dir) => join(dir.replace(/^"|"$/g, ""), name))),
+            ...(host.homeExecutables ?? []).map((file) => join(homedir(), file)),
+        ];
+        return paths.some((file) => executableCandidates(file).some(isExecutable));
+    }).map((host) => AdapterFactory.forName(host.adapter));
+}
+/** Explicit flags take precedence over the existing environment override. */
+export function resolveInstallAdapters(options) {
+    const explicit = options?.adapter?.trim() || process.env.SESSIONMEM_ADAPTER?.trim();
+    if (explicit)
+        return { adapters: [AdapterFactory.forName(explicit)], forced: true };
+    const adapters = detectInstalledAdapters();
+    if (adapters.length === 0) {
+        throw new Error("No supported agent host found. Install Claude Code or use sessionmem install --adapter <name>.");
+    }
+    return { adapters, forced: false };
+}

package/dist/cli/commands/dedupe.js

@@ -23,7 +23,7 @@ function cosineSimilarity(a, b) {
 function resolveThreshold(raw) {
     if (raw === undefined)
         return SIMILARITY_THRESHOLD;
-    const parsed = Number.parseFloat(raw);
+    const parsed = Number(raw.trim());
     if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 1) {
         console.error(`Invalid --threshold "${raw}": expected a number greater than 0 and at most 1.`);
         process.exit(1);

package/dist/cli/commands/doctor.js

@@ -0,0 +1,146 @@
+import BetterSqlite3 from "better-sqlite3";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { resolveInstallAdapters } from "../../adapters/installedHosts.js";
+import { checkHooks, readMcpLaunch, probeMcpWiring } from "../../adapters/diagnostics.js";
+import { ADAPTER_NAMES, AdapterFactory } from "../../adapters/factory.js";
+import { createMemoryCoreService } from "../../core/api/memoryCoreService.js";
+import { inspectMigrations } from "../../core/schema/runMigrations.js";
+import { resolveDbPath } from "../context.js";
+const VERSION = createRequire(import.meta.url)("../../../package.json").version;
+/** Exercise real storage, embedding, ranking and injection without retaining data. */
+export async function probeRecall(db) {
+    const id = `sessionmem-doctor-${randomUUID()}`;
+    const content = "Sessionmem doctor canary checks local memory recall.";
+    const service = createMemoryCoreService({ db });
+    // A separate project prevents both ranking collisions and access-count changes
+    // to user memories. Rollback also removes FTS entries and feedback on failure.
+    db.exec("BEGIN IMMEDIATE");
+    try {
+        const stored = await service.call("storeMemory", {
+            projectId: id, sessionId: id, memoryId: id, sourceAdapter: "doctor",
+            kind: "fact", content, importance: 5,
+        });
+        if (!stored.ok)
+            throw new Error(`Canary write failed: ${stored.error.message}`);
+        const recalled = await service.call("retrieveMemories", {
+            projectId: id, query: content, limit: 5, mode: "auto", depth: "default",
+        });
+        if (!recalled.ok)
+            throw new Error(`Canary recall failed: ${recalled.error.message}`);
+        if (!recalled.memories.some((memory) => memory.id === id && memory.content === content)) {
+            throw new Error("Recall did not return the canary memory");
+        }
+    }
+    finally {
+        db.exec("ROLLBACK");
+    }
+}
+export async function doctorCommand(options, overrides = {}) {
+    const results = [];
+    const report = (check, ok, detail, fix) => {
+        results.push({ check, ok, detail, ...(fix ? { fix } : {}) });
+        console.log(`${ok ? "PASS" : "FAIL"} ${check}: ${detail}`);
+        if (fix)
+            console.log(`  Fix: ${fix}`);
+    };
+    const message = (err) => err instanceof Error ? err.message : String(err);
+    let adapters = [];
+    try {
+        adapters = resolveInstallAdapters(options).adapters;
+    }
+    catch (err) {
+        report("Agent hosts", false, message(err), "Install a supported host or select one with sessionmem doctor --adapter <name>");
+    }
+    const dbPath = resolveDbPath(overrides.dbPath);
+    let db;
+    let schemaOk = false;
+    try {
+        try {
+            if (dbPath === ":memory:")
+                throw new Error("No persistent memory store selected (:memory:)");
+            // fileMustExist prevents doctor from hiding a missing store; migrations
+            // are inspected separately and are never applied during diagnosis.
+            db = new BetterSqlite3(dbPath, { fileMustExist: true, timeout: 5000 });
+            const status = db.pragma("quick_check", { simple: true });
+            if (status !== "ok")
+                throw new Error(`SQLite quick_check: ${String(status)}`);
+            db.pragma("foreign_keys = ON");
+            report("Memory store", true, `Exists and opens (${dbPath})`);
+        }
+        catch (err) {
+            db?.close();
+            db = undefined;
+            report("Memory store", false, message(err), "Check the selected database path and directory permissions; initialize a missing store with sessionmem ping");
+        }
+        if (db) {
+            try {
+                const schema = inspectMigrations(db, overrides.migrationsDir);
+                if (schema.unknown.length) {
+                    report("Schema", false, `Unrecognized migrations: ${schema.unknown.join(", ")}`, "Use the sessionmem version that created this database; do not downgrade its schema");
+                }
+                else if (schema.pending.length) {
+                    report("Schema", false, `Pending migrations: ${schema.pending.join(", ")}`, "sessionmem ping");
+                }
+                else {
+                    schemaOk = true;
+                    report("Schema", true, "All bundled migrations are applied");
+                }
+            }
+            catch (err) {
+                report("Schema", false, message(err), "Check the database and bundled schema migrations; sessionmem ping applies pending migrations");
+            }
+        }
+        else {
+            report("Schema", false, "Cannot inspect an unavailable store", "sessionmem ping");
+        }
+        for (const adapter of adapters) {
+            const name = ADAPTER_NAMES.find((name) => AdapterFactory.forName(name).name === adapter.name);
+            const installFix = name ? `sessionmem install --adapter ${name}` : "sessionmem install";
+            const installation = adapter.installation?.();
+            if (!installation) {
+                report(`${adapter.name} hooks`, false, "Adapter has no installation diagnostics", installFix);
+                report(`${adapter.name} adapter wiring`, false, "Adapter has no installation diagnostics", installFix);
+                continue;
+            }
+            try {
+                report(`${adapter.name} hooks`, true, `${checkHooks(installation)}; sessionmem ${VERSION}`);
+            }
+            catch (err) {
+                report(`${adapter.name} hooks`, false, message(err), `Enable hooks in the host settings if disabled, then run ${installFix}`);
+            }
+            try {
+                const launch = readMcpLaunch(installation);
+                if (!schemaOk)
+                    throw new Error("MCP launch probe blocked until the store and schema checks pass");
+                await probeMcpWiring(launch, dbPath, VERSION);
+                report(`${adapter.name} adapter wiring`, true, "Configured MCP command starts, matches this version, and answers stats");
+            }
+            catch (err) {
+                report(`${adapter.name} adapter wiring`, false, message(err), `Ensure sessionmem is on PATH, then run ${installFix}`);
+            }
+        }
+        if (!adapters.length) {
+            report("Hook configuration", false, "No host selected", "sessionmem doctor --adapter <name>");
+            report("Adapter wiring", false, "No host selected", "sessionmem doctor --adapter <name>");
+        }
+        if (db && schemaOk) {
+            try {
+                await probeRecall(db);
+                report("Recall canary", true, "Write and recall succeeded; canary rolled back");
+            }
+            catch (err) {
+                report("Recall canary", false, message(err), "Check database write permissions and errors; run sessionmem doctor again after repair");
+            }
+        }
+        else {
+            report("Recall canary", false, "Blocked until the store and schema checks pass", "sessionmem ping");
+        }
+    }
+    finally {
+        db?.close();
+    }
+    if (results.some((result) => !result.ok))
+        process.exitCode = 1;
+    return results;
+}

package/dist/cli/commands/entities.js

@@ -0,0 +1,27 @@
+import { listProjectKnowledge } from "../../core/storage/knowledgeRepo.js";
+import { createCliContext } from "../context.js";
+export function entitiesCommand(options = {}, ctx) {
+    const context = ctx ?? createCliContext();
+    try {
+        const projectId = options.project ?? context.projectId;
+        const knowledge = listProjectKnowledge(context.db, projectId);
+        if (options.json) {
+            console.log(JSON.stringify({ projectId, ...knowledge }, null, 2));
+            return;
+        }
+        console.log(`Entities for ${projectId}:`);
+        for (const entity of knowledge.entities) {
+            console.log(`  [${entity.kind}] ${entity.name} (memories: ${entity.memoryIds.join(", ")})`);
+        }
+        console.log("Relations:");
+        for (const edge of knowledge.relations) {
+            console.log(`  [${edge.sourceKind}] ${edge.sourceName} --${edge.relation}--> [${edge.targetKind}] ${edge.targetName} (memories: ${edge.memoryIds.join(", ")})`);
+        }
+        if (!knowledge.entities.length)
+            console.log("  No entities captured.");
+    }
+    finally {
+        if (!ctx)
+            context.db.close();
+    }
+}

package/dist/cli/commands/history.js

@@ -0,0 +1,23 @@
+import { listSupersessions } from "../../core/storage/supersessionRepo.js";
+import { createCliContext } from "../context.js";
+export function historyCommand(options = {}, ctx) {
+    const context = ctx ?? createCliContext();
+    try {
+        const projectId = options.project ?? context.projectId;
+        const links = listSupersessions(context.db, projectId);
+        if (options.json) {
+            console.log(JSON.stringify({ projectId, links }, null, 2));
+            return;
+        }
+        console.log(`Supersession links for ${projectId}:`);
+        for (const link of links) {
+            console.log(`  ${link.supersedes} -> ${link.supersededBy} at ${link.supersededAt} (${link.entity} ${link.relation}: ${link.oldValue} -> ${link.newValue}; ${link.reason}; ${link.fullySuperseded ? "superseded" : "partially superseded"})`);
+        }
+        if (!links.length)
+            console.log("  No supersessions captured.");
+    }
+    finally {
+        if (!ctx)
+            context.db.close();
+    }
+}