om-memory-system 3.5.0 → 3.6.0-next.38

package/README.md

@@ -17,6 +17,10 @@ It runs inside [OpenCode](https://opencode.ai) and the
 Both share one memory per project, so a note written in one is available in
 the other. Everything is stored locally on your machine.
 
+Claude Code is also supported, through a plugin of hooks. It needs a global
+install and your own external API for capture. See the
+[Claude Code adapter](docs/claude-code-adapter.md) guide.
+
 ## What it does
 
 - **Remembers automatically.** After each piece of work, a background model
@@ -43,6 +47,8 @@ You need one of:
 
 - **OpenCode** 1.18.29 or later (v1 plugin API) or OpenCode v2
 - **Pi coding agent**
+- **Claude Code**, through a plugin of hooks. Capture needs your own external API. See
+  the [Claude Code adapter](docs/claude-code-adapter.md) guide for setup.
 
 Nothing else is required. OMMS brings its own database. On first use it
 downloads a small embedding model (the part that makes memories searchable),
@@ -142,22 +148,24 @@ backup first. See [Updating and upgrading](docs/upgrading.md) and
 
 ## Documentation
 
-| Read this                                                  | To learn about                                                   |
-| ---------------------------------------------------------- | ---------------------------------------------------------------- |
-| [Using memory day to day](docs/using-memory.md)            | How capture and recall work, the `memory` tool, the user profile |
-| [Configuration](docs/configuration.md)                     | Settings, choosing the model, embeddings, troubleshooting        |
-| [Web UI](docs/web-ui.md)                                   | The memory explorer, opening it on a network safely              |
-| [Settings page](docs/web-ui-settings.md)                   | Every card and control on the web Settings page                  |
-| [Moving projects](docs/moving-projects.md)                 | Nested repositories, moved folders, backup and restore           |
-| [Updating and upgrading](docs/upgrading.md)                | Updates, pinning a version, older stores                         |
-| [OpenCode adapter](docs/opencode-adapter.md)               | How the OpenCode plugin hooks in                                 |
-| [Pi adapter](docs/pi-adapter.md)                           | How the Pi extension hooks in                                    |
-| [OpenCode history import](docs/opencode-history-import.md) | Importing past OpenCode sessions                                 |
-| [Pi history import](docs/pi-history-import.md)             | Importing past Pi sessions, moving machines                      |
-| [CLI reference](docs/cli.md)                               | The `om-memory-system` terminal command                          |
-| [Migrating from opencode-mem](docs/omms-migration.md)      | What changes when upgrading from the original plugin             |
-| [For developers](docs/developers.md)                       | Building, testing, the public `tags` export, architecture        |
-| [Contributing](CONTRIBUTING.md)                            | How to set up, test, and send a pull request                     |
+| Read this                                                        | To learn about                                                   |
+| ---------------------------------------------------------------- | ---------------------------------------------------------------- |
+| [Using memory day to day](docs/using-memory.md)                  | How capture and recall work, the `memory` tool, the user profile |
+| [Configuration](docs/configuration.md)                           | Settings, choosing the model, embeddings, troubleshooting        |
+| [Web UI](docs/web-ui.md)                                         | The memory explorer, opening it on a network safely              |
+| [Settings page](docs/web-ui-settings.md)                         | Every card and control on the web Settings page                  |
+| [Moving projects](docs/moving-projects.md)                       | Nested repositories, moved folders, backup and restore           |
+| [Updating and upgrading](docs/upgrading.md)                      | Updates, pinning a version, older stores                         |
+| [OpenCode adapter](docs/opencode-adapter.md)                     | How the OpenCode plugin hooks in                                 |
+| [Pi adapter](docs/pi-adapter.md)                                 | How the Pi extension hooks in                                    |
+| [Claude Code adapter](docs/claude-code-adapter.md)               | Installing the Claude Code plugin, hooks, the `memory` command   |
+| [OpenCode history import](docs/opencode-history-import.md)       | Importing past OpenCode sessions                                 |
+| [Pi history import](docs/pi-history-import.md)                   | Importing past Pi sessions, moving machines                      |
+| [Claude Code history import](docs/claude-code-history-import.md) | Importing past Claude Code transcripts                           |
+| [CLI reference](docs/cli.md)                                     | The `om-memory-system` terminal command                          |
+| [Migrating from opencode-mem](docs/omms-migration.md)            | What changes when upgrading from the original plugin             |
+| [For developers](docs/developers.md)                             | Building, testing, the public `tags` export, architecture        |
+| [Contributing](CONTRIBUTING.md)                                  | How to set up, test, and send a pull request                     |
 
 ## About this fork
 

package/dist/adapters/claude-code/hook-client.d.ts

@@ -0,0 +1,73 @@
+export declare const CLAUDE_HOOK_EVENTS: readonly ["session-start", "user-prompt-submit", "stop"];
+export type ClaudeHookEvent = (typeof CLAUDE_HOOK_EVENTS)[number];
+/** Claude Code caps added context at 10,000 characters; keep a margin. */
+export declare const CLAUDE_CONTEXT_LIMIT = 9500;
+/**
+ * Copy of `RETRIEVAL_SECTION_TAG` in `src/core/retrieval.ts`. That module loads
+ * the store, so the hook keeps its own copy; a test checks the two match.
+ */
+export declare const RETRIEVAL_TAG = "omms-retrieval";
+export interface HookServerSettings {
+    enabled: boolean;
+    baseUrl: string;
+    basicAuth?: {
+        username: string;
+        password: string;
+    };
+}
+interface SpawnedChild {
+    unref(): void;
+    on(event: "error", listener: (error: Error) => void): unknown;
+}
+type SpawnFn = (command: string, args: string[], options: {
+    detached: true;
+    stdio: "ignore";
+    cwd: string;
+    windowsHide: true;
+}) => SpawnedChild;
+/** A readable byte stream such as `process.stdin`. */
+export interface HookInputStream {
+    on(event: "data", listener: (chunk: Buffer | string) => void): unknown;
+    on(event: "end" | "error", listener: (arg?: unknown) => void): unknown;
+    removeAllListeners(): unknown;
+    pause(): unknown;
+    destroy?(): unknown;
+}
+export interface ClaudeHookOptions {
+    stdin?: HookInputStream;
+    writeStdout?: (text: string) => void;
+    fetch?: typeof fetch;
+    spawn?: SpawnFn;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (message: string, data: Record<string, unknown>) => void | Promise<void>;
+    readToken?: () => Promise<string>;
+    resolveRuntime?: () => Promise<string | null>;
+    loadSettings?: () => Promise<HookServerSettings>;
+    /** The `om-memory-system` script that `web` is run from. */
+    cliScript?: string;
+    inputTimeoutMs?: number;
+    maxInputBytes?: number;
+    /** Overrides the event's request budget. */
+    requestTimeoutMs?: number;
+}
+export type ClaudeHookCode = "ok" | "bad-event" | "no-input" | "bad-input" | "server-disabled" | "server-unreachable" | "start-timeout" | "timeout" | "network-error" | "bad-response" | "error" | `http-${number}`;
+export interface ClaudeHookResult {
+    code: ClaudeHookCode;
+    spawned: boolean;
+    inputBytes: number;
+    outputBytes: number;
+}
+/** Read stdin up to a time and size limit. Late, oversized, or broken input is no input. */
+export declare function readHookInput(stream: HookInputStream, limits: {
+    timeoutMs: number;
+    maxBytes: number;
+}): Promise<{
+    text: string | null;
+    bytes: number;
+}>;
+/** Cut text to the limit. When it ends with the retrieval tag, keep that closing tag. */
+export declare function truncateContext(text: string, limit?: number): string;
+/** Run one hook event. Never throws; the result says what happened. */
+export declare function runClaudeHook(event: ClaudeHookEvent, options?: ClaudeHookOptions): Promise<ClaudeHookResult>;
+export {};

package/dist/adapters/claude-code/hook-client.js

@@ -0,0 +1,285 @@
+import { spawn as nodeSpawn } from "node:child_process";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+import { AUTH_HEADER } from "../../services/auth-token.js";
+// Claude Code hook client: read the hook input, find or start the OMMS web
+// app, send one request, print the added context, and log one metadata line.
+// It loads no store, embedding model, or engine; the web app does that work.
+export const CLAUDE_HOOK_EVENTS = ["session-start", "user-prompt-submit", "stop"];
+/** Claude Code caps added context at 10,000 characters; keep a margin. */
+export const CLAUDE_CONTEXT_LIMIT = 9_500;
+/**
+ * Copy of `RETRIEVAL_SECTION_TAG` in `src/core/retrieval.ts`. That module loads
+ * the store, so the hook keeps its own copy; a test checks the two match.
+ */
+export const RETRIEVAL_TAG = "omms-retrieval";
+const INPUT_TIMEOUT_MS = 2_000;
+const MAX_INPUT_BYTES = 1024 * 1024;
+const HEALTH_PROBE_MS = 1_000;
+const POLL_INTERVAL_MS = 250;
+const BUDGETS = {
+    "session-start": { startMs: 15_000, requestMs: 3_000 },
+    "user-prompt-submit": { startMs: 5_000, requestMs: 3_000 },
+    stop: { startMs: 30_000, requestMs: 5_000 },
+};
+const HOOK_EVENT_NAMES = {
+    "session-start": "SessionStart",
+    "user-prompt-submit": "UserPromptSubmit",
+    stop: "Stop",
+};
+/** Read stdin up to a time and size limit. Late, oversized, or broken input is no input. */
+export function readHookInput(stream, limits) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let bytes = 0;
+        let settled = false;
+        const finish = (complete) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            stream.removeAllListeners();
+            stream.pause();
+            // Let the process exit even though the writer has not closed stdin.
+            if (!complete)
+                stream.destroy?.();
+            const text = complete && bytes <= limits.maxBytes ? Buffer.concat(chunks).toString() : null;
+            resolve({ text, bytes });
+        };
+        const timer = setTimeout(() => finish(false), limits.timeoutMs);
+        stream.on("data", (chunk) => {
+            const buffer = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
+            bytes += buffer.length;
+            if (bytes > limits.maxBytes)
+                return finish(false);
+            chunks.push(buffer);
+        });
+        stream.on("end", () => finish(true));
+        stream.on("error", () => finish(false));
+    });
+}
+/** Cut text to the limit. When it ends with the retrieval tag, keep that closing tag. */
+export function truncateContext(text, limit = CLAUDE_CONTEXT_LIMIT) {
+    if (text.length <= limit)
+        return text;
+    const close = `</${RETRIEVAL_TAG}>`;
+    const suffix = text.trimEnd().endsWith(close) ? `\n${close}` : "";
+    let head = text.slice(0, limit - suffix.length);
+    // Do not leave half of a surrogate pair at the cut.
+    if (/[\uD800-\uDBFF]$/.test(head))
+        head = head.slice(0, -1);
+    return head + suffix;
+}
+function parseInput(text, event) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const input = value;
+    if (typeof input.session_id !== "string" || typeof input.cwd !== "string")
+        return null;
+    if (event === "stop" && typeof input.transcript_path !== "string")
+        return null;
+    return input;
+}
+function requestFor(event, input) {
+    const optional = (key) => (input[key] === undefined ? {} : { [key]: input[key] });
+    if (event === "stop")
+        return {
+            path: "/api/claude/capture",
+            body: {
+                session_id: input.session_id,
+                transcript_path: input.transcript_path,
+                cwd: input.cwd,
+                ...optional("last_assistant_message"),
+                ...optional("stop_hook_active"),
+            },
+        };
+    return {
+        path: "/api/claude/retrieve",
+        body: {
+            event,
+            session_id: input.session_id,
+            cwd: input.cwd,
+            ...optional("transcript_path"),
+            ...optional(event === "session-start" ? "source" : "prompt"),
+        },
+    };
+}
+function productionDefaults() {
+    return {
+        stdin: process.stdin,
+        writeStdout: (text) => process.stdout.write(text),
+        fetch: globalThis.fetch,
+        spawn: nodeSpawn,
+        now: () => Date.now(),
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        // The shared logger only uses the file system; load it lazily anyway.
+        log: async (message, data) => (await import("../../services/logger.js")).log(message, data),
+        readToken: async () => (await import("../../services/auth-token.js")).getOrCreateAuthToken(),
+        resolveRuntime: async () => (await import("../../services/web-autostart.js")).resolveWebRuntime(),
+        loadSettings: loadWebSettings,
+        // From dist/adapters/claude-code/ to the CLI entry point.
+        cliScript: fileURLToPath(new URL("../../cli/index.js", import.meta.url)),
+    };
+}
+/** Port, bind address, and auth as `om-memory-system web` reads them (global config from home). */
+async function loadWebSettings() {
+    const config = await import("../../config.js");
+    config.initConfig(homedir());
+    const { CONFIG } = config;
+    const { webServerUrl } = await import("../../services/web-api-auth.js");
+    const settings = {
+        enabled: CONFIG.webServerEnabled,
+        baseUrl: webServerUrl(CONFIG.webServerHost, CONFIG.webServerPort),
+    };
+    const password = (CONFIG.webServerAuthPassword ?? "").trim();
+    if (password) {
+        const { WebAuth } = await import("../../services/web-auth.js");
+        const { username } = new WebAuth({
+            password,
+            username: CONFIG.webServerAuthUsername,
+        }).getConfig();
+        settings.basicAuth = { username, password };
+    }
+    return settings;
+}
+/** Run one hook event. Never throws; the result says what happened. */
+export async function runClaudeHook(event, options = {}) {
+    const deps = { ...productionDefaults(), ...options };
+    const started = deps.now();
+    const result = { code: "ok", spawned: false, inputBytes: 0, outputBytes: 0 };
+    try {
+        result.code = await runSteps(event, deps, result);
+    }
+    catch {
+        result.code = "error";
+    }
+    try {
+        await deps.log("Claude Code hook", {
+            event,
+            code: result.code,
+            elapsedMs: deps.now() - started,
+            spawned: result.spawned,
+            inputBytes: result.inputBytes,
+            outputBytes: result.outputBytes,
+        });
+    }
+    catch {
+        /* A failed log line must not break the hook. */
+    }
+    return result;
+}
+async function runSteps(event, deps, result) {
+    const raw = await readHookInput(deps.stdin, {
+        timeoutMs: deps.inputTimeoutMs ?? INPUT_TIMEOUT_MS,
+        maxBytes: deps.maxInputBytes ?? MAX_INPUT_BYTES,
+    });
+    result.inputBytes = raw.bytes;
+    if (!raw.text?.trim())
+        return "no-input";
+    const input = parseInput(raw.text, event);
+    if (!input)
+        return "bad-input";
+    const settings = await deps.loadSettings();
+    if (!settings.enabled)
+        return "server-disabled";
+    const budget = BUDGETS[event];
+    const ready = await ensureServer(settings.baseUrl, budget.startMs, deps, result);
+    if (ready !== "ok")
+        return ready;
+    const headers = {
+        "content-type": "application/json",
+        [AUTH_HEADER]: await deps.readToken(),
+    };
+    if (settings.basicAuth) {
+        const { username, password } = settings.basicAuth;
+        headers.authorization = `Basic ${Buffer.from(`${username}:${password}`).toString("base64")}`;
+    }
+    const { path, body } = requestFor(event, input);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deps.requestTimeoutMs ?? budget.requestMs);
+    let response;
+    try {
+        response = await deps.fetch(`${settings.baseUrl}${path}`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: controller.signal,
+        });
+    }
+    catch {
+        return controller.signal.aborted ? "timeout" : "network-error";
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok)
+        return `http-${response.status}`;
+    if (event === "stop")
+        return "ok";
+    const reply = (await response.json().catch(() => null));
+    if (typeof reply?.additionalContext !== "string")
+        return "bad-response";
+    if (!reply.additionalContext)
+        return "ok";
+    const output = `${JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: HOOK_EVENT_NAMES[event],
+            additionalContext: truncateContext(reply.additionalContext),
+        },
+    })}\n`;
+    deps.writeStdout(output);
+    result.outputBytes = Buffer.byteLength(output);
+    return "ok";
+}
+async function isHealthy(baseUrl, timeoutMs, deps) {
+    try {
+        const response = await deps.fetch(`${baseUrl}/api/health`, {
+            method: "GET",
+            signal: AbortSignal.timeout(Math.max(1, timeoutMs)),
+        });
+        if (!response.ok)
+            return false;
+        // Same envelope check as WebServer.checkServerAvailable: another local
+        // service on the port must not count as OMMS.
+        const body = (await response.json());
+        return body.success === true && body.status === "ok";
+    }
+    catch {
+        return false;
+    }
+}
+/** Use a running web app, or start `om-memory-system web` and wait for it within the budget. */
+async function ensureServer(baseUrl, budgetMs, deps, result) {
+    const started = deps.now();
+    const remaining = () => budgetMs - (deps.now() - started);
+    if (await isHealthy(baseUrl, Math.min(HEALTH_PROBE_MS, remaining()), deps))
+        return "ok";
+    const runtime = await deps.resolveRuntime();
+    if (!runtime)
+        return "server-unreachable";
+    const child = deps.spawn(runtime, [deps.cliScript, "web"], {
+        detached: true,
+        stdio: "ignore",
+        cwd: homedir(),
+        windowsHide: true,
+    });
+    // A missing runtime reports through this event; polling then runs out.
+    child.on("error", () => undefined);
+    child.unref();
+    result.spawned = true;
+    while (remaining() > 0) {
+        await deps.sleep(Math.min(POLL_INTERVAL_MS, remaining()));
+        if (remaining() <= 0)
+            break;
+        if (await isHealthy(baseUrl, Math.min(HEALTH_PROBE_MS, remaining()), deps))
+            return "ok";
+    }
+    return "start-timeout";
+}

package/dist/adapters/claude-code/hook-command.d.ts

@@ -0,0 +1,6 @@
+import { type ClaudeHookOptions } from "./hook-client.js";
+/**
+ * `om-memory-system claude-hook <event>`. Always returns 0: a hook must never
+ * block or break a Claude Code session, whatever goes wrong.
+ */
+export declare function runClaudeHookCommand(argv: string[], io?: ClaudeHookOptions): Promise<number>;

package/dist/adapters/claude-code/hook-command.js

@@ -0,0 +1,25 @@
+import { CLAUDE_HOOK_EVENTS, runClaudeHook, } from "./hook-client.js";
+function isHookEvent(value) {
+    return CLAUDE_HOOK_EVENTS.includes(value ?? "");
+}
+/**
+ * `om-memory-system claude-hook <event>`. Always returns 0: a hook must never
+ * block or break a Claude Code session, whatever goes wrong.
+ */
+export async function runClaudeHookCommand(argv, io = {}) {
+    try {
+        const [event] = argv;
+        if (isHookEvent(event)) {
+            await runClaudeHook(event, io);
+            return 0;
+        }
+        // Only a known name reaches the log; argv is not trusted text.
+        const log = io.log ??
+            (async (message, data) => (await import("../../services/logger.js")).log(message, data));
+        await log("Claude Code hook", { event: "unknown", code: "bad-event" });
+    }
+    catch {
+        /* Exit 0 on every failure. */
+    }
+    return 0;
+}

package/dist/cli/index.js

@@ -5,26 +5,32 @@ import { historyImportUsage, importNeedsModel, parseHistoryImportArgs, } from ".
 const COMMANDS = {
     "import-opencode-history": "opencode",
     "import-pi-history": "pi",
+    "import-claude-history": "claude-code",
 };
 const usage = `Usage: om-memory-system <command> [options]
 
 Commands:
   import-opencode-history   Import OpenCode history into omms
   import-pi-history         Import Pi history into omms
+  import-claude-history     Import Claude Code history into omms
   web                       Start the web app in the foreground
   web install|uninstall|status  Manage the web app login item
+  memory <mode> [options]   Search, add, list, or forget memories (run with --help)
+  claude-hook <event>       Run a Claude Code hook (used by the Claude Code plugin)
 
 Options:
   --version, -v             Print the installed version
 
 Import commands take the same options; run one with --help to see them.
 Inside a session, /memory-import-opencode-history and /memory-import-pi-history
-use that session's model instead of an API key.`;
+use that session's model instead of an API key. import-claude-history always
+uses the external API or --provider, --api-url, and --api-key-env.`;
 export function parseImportArgs(argv) {
     const [command, ...rest] = argv;
     const host = command ? COMMANDS[command] : undefined;
-    if (!host)
-        throw new Error("Expected import-opencode-history or import-pi-history; use --help");
+    if (!host) {
+        throw new Error("Expected import-opencode-history, import-pi-history, or import-claude-history; use --help");
+    }
     const args = parseHistoryImportArgs(rest, { host, surface: "cli" });
     if (!args.help && args.errors.length > 0)
         throw new Error(args.errors.join("; "));
@@ -40,6 +46,16 @@ export async function runCli(argv) {
         console.log(usage);
         return 0;
     }
+    if (argv[0] === "claude-hook") {
+        const { runClaudeHookCommand } = await import("../adapters/claude-code/hook-command.js");
+        await runClaudeHookCommand(argv.slice(1));
+        // An idle fetch connection could keep the hook alive past its Claude Code timeout.
+        process.exit(0);
+    }
+    if (argv[0] === "memory") {
+        const { runMemoryCommand } = await import("./memory-command.js");
+        return await runMemoryCommand(argv.slice(1));
+    }
     if (argv[0] === "web") {
         try {
             const { runWebCommand } = await import("./web-command.js");

package/dist/cli/memory-command.d.ts

@@ -0,0 +1,24 @@
+import type { MemoryOperationArgs } from "../core/memory-operations.js";
+/**
+ * `om-memory-system memory <mode>`: the shared `memory` tool operations from a
+ * terminal, for hosts without an in-process tool (Claude Code). Parsing and
+ * usage stay free of engine imports so `--help` is fast; config, storage and
+ * embeddings load with dynamic `import()` only when an operation runs.
+ */
+export interface MemoryCommandIO {
+    /** Working directory used when `--directory` is not given. */
+    cwd?: string;
+    stdout?: (text: string) => void;
+    stderr?: (text: string) => void;
+}
+export declare const memoryCommandUsage: string;
+interface ParsedMemoryCommand {
+    help: boolean;
+    args: MemoryOperationArgs;
+    directory?: string;
+}
+/** Parse `<mode> [options]` into memory tool arguments. Throws on bad input. */
+export declare function parseMemoryCommandArgs(argv: string[]): ParsedMemoryCommand;
+/** Run `om-memory-system memory ...` and return the process exit code. */
+export declare function runMemoryCommand(argv: string[], io?: MemoryCommandIO): Promise<number>;
+export {};