@ephemushroom/opencode-claude-mem 0.7.0 → 0.7.1

package/dist/sidebar-model.d.ts

@@ -1,7 +1,10 @@
+import { type CaptureStatus } from './capture-status';
 export declare const POLL_INTERVAL_MS = 5000;
 export declare const OBSERVATION_TYPE_ICONS: Record<string, string>;
 export interface MemSidebarView {
     readonly healthy: boolean;
+    /** What this package's server part reported; null when it is not loaded. */
+    readonly capture: CaptureStatus | null;
     readonly project: string;
     /** `project` when counts come from the Worker database; `all` for the global fallback. */
     readonly scope: 'project' | 'all';
@@ -65,7 +68,7 @@ export declare function bulletRow(icon: string, iconColor: unknown, value: strin
 export declare function expandedRows(view: MemSidebarView, theme: Theme, onSelect?: RecentItemHandler): ViewNode[];
 export declare function buildMemNodes(view: MemSidebarView, theme: Theme, collapsed: boolean, onToggle: () => void, onSelect?: RecentItemHandler): ViewNode[];
 export declare function viewKey(view: MemSidebarView): string;
-export declare function readMemView(project: string, collapsed: boolean): Promise<MemSidebarView>;
+export declare function readMemView(project: string, collapsed: boolean, directory?: string): Promise<MemSidebarView>;
 export interface MemDetail {
     readonly title: string;
     readonly message: string;

package/dist/tui.js

@@ -1,12 +1,82 @@
 // @bun
-// src/worker-client.ts
-import { existsSync, readFileSync } from "fs";
+// src/capture-status.ts
+import { createHash, randomUUID } from "crypto";
+import { join, resolve } from "path";
+import {
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "fs";
 import { homedir } from "os";
-import { join } from "path";
+function cacheDirectory(env = process.env, home = homedir()) {
+  return join(env["XDG_CACHE_HOME"]?.trim() || join(home, ".cache"), "opencode-claude-mem");
+}
+function statusKey(directory) {
+  let resolved = resolve(directory);
+  try {
+    resolved = realpathSync(directory);
+  } catch {}
+  return createHash("sha256").update(resolved).digest("hex").slice(0, 16);
+}
+function isAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function parseStatus(file) {
+  try {
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
+    if (typeof parsed !== "object" || parsed === null) {
+      return null;
+    }
+    const { state, message, pid } = parsed;
+    return (state === "ok" || state === "problem") && typeof message === "string" && typeof pid === "number" && Number.isInteger(pid) && pid > 0 ? { state, message, pid } : null;
+  } catch {
+    return null;
+  }
+}
+function readCaptureStatus(directory, dir = cacheDirectory()) {
+  const folder = join(dir, "status");
+  const prefix = `${statusKey(directory)}.`;
+  let names = [];
+  try {
+    names = readdirSync(folder).filter((name) => name.startsWith(prefix) && name.endsWith(".json"));
+  } catch {
+    return null;
+  }
+  let best = null;
+  for (const name of names) {
+    const file = join(folder, name);
+    const parsed = parseStatus(file);
+    if (!parsed || !isAlive(parsed.pid)) {
+      rmSync(file, { force: true });
+    } else {
+      const own = parsed.pid === process.pid;
+      const at = statSync(file, { throwIfNoEntry: false })?.mtimeMs ?? 0;
+      if (!best || own && !best.own || own === best.own && at > best.at) {
+        best = { status: { state: parsed.state, message: parsed.message }, own, at };
+      }
+    }
+  }
+  return best?.status ?? null;
+}
+
+// src/worker-client.ts
+import { existsSync, readFileSync as readFileSync2 } from "fs";
+import { join as join2, resolve as resolve2, win32 } from "path";
+import { createHash as createHash2 } from "crypto";
+import { homedir as homedir2 } from "os";
 var DEFAULT_WORKER_HOST = "127.0.0.1";
-var DEFAULT_WORKER_PORT = 37777;
-var SETTINGS_FILE = join(homedir(), ".claude-mem", "settings.json");
-var LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1", "[::1]"]);
+var WORKER_PORT_BASE = 37700;
+var TOKEN_HEADER = "x-claude-mem-token";
 var PROJECT_COUNTS_SQL = `SELECT
   (SELECT COUNT(*) FROM observations
     WHERE project = ?1 COLLATE NOCASE OR merged_into_project = ?1 COLLATE NOCASE) AS observations,
@@ -36,25 +106,62 @@ function parseSettings(rawSettings) {
     return {};
   }
   try {
-    const parsed = JSON.parse(rawSettings);
-    return isRecord(parsed) ? parsed : {};
+    const parsed = JSON.parse(rawSettings.replace(/^\uFEFF/, ""));
+    if (!isRecord(parsed)) {
+      return {};
+    }
+    const nested = parsed["env"];
+    const source = isRecord(nested) && Object.keys(nested).some((key) => key.startsWith("CLAUDE_MEM_")) ? nested : parsed;
+    return Object.fromEntries(Object.entries(source).map(([key, value]) => [
+      key,
+      typeof value === "number" || typeof value === "boolean" ? String(value) : value
+    ]));
   } catch {
     return {};
   }
 }
-function parseWorkerEndpoint(env, rawSettings) {
+function dataDirectory(env, home) {
+  const dir = readString(env["CLAUDE_MEM_DATA_DIR"]) ?? join2(home, ".claude-mem");
+  return dir.replace(/^~(?=$|[\\/])/, home);
+}
+function defaultWorkerPort(dataDir, platform = process.platform, uid = typeof process.getuid === "function" ? process.getuid() : null) {
+  if (uid !== null) {
+    return WORKER_PORT_BASE + (uid % 100 + 100) % 100;
+  }
+  const normalized = platform === "win32" ? win32.resolve(dataDir).toLowerCase() : resolve2(dataDir);
+  const digest = createHash2("sha256").update(normalized, "utf8").digest();
+  return WORKER_PORT_BASE + digest.readUInt32BE(0) % 100;
+}
+function parseWorkerEndpoint(env, rawSettings, fallbackPort = defaultWorkerPort(dataDirectory(env, homedir2()))) {
   const settings = parseSettings(rawSettings);
-  const host = readString(env["CLAUDE_MEM_WORKER_HOST"]) ?? readString(settings["CLAUDE_MEM_WORKER_HOST"]) ?? DEFAULT_WORKER_HOST;
-  const port = readPort(env["CLAUDE_MEM_WORKER_PORT"]) ?? readPort(settings["CLAUDE_MEM_WORKER_PORT"]) ?? DEFAULT_WORKER_PORT;
+  const configured = readString(env["CLAUDE_MEM_WORKER_HOST"]) ?? readString(settings["CLAUDE_MEM_WORKER_HOST"]) ?? DEFAULT_WORKER_HOST;
+  const host = configured === "localhost" ? DEFAULT_WORKER_HOST : configured;
+  const port = readPort(env["CLAUDE_MEM_WORKER_PORT"]) ?? readPort(settings["CLAUDE_MEM_WORKER_PORT"]) ?? fallbackPort;
   return { host, port };
 }
+function isLoopbackHost(host) {
+  const name = host.toLowerCase().replace(/^\[|\]$/g, "");
+  return name === "localhost" || name.endsWith(".localhost") || name === "::1" || /^127(?:\.\d{1,3}){1,3}$/.test(name);
+}
+function workerUrl(endpoint) {
+  const host = endpoint.host.includes(":") && !endpoint.host.startsWith("[") ? `[${endpoint.host}]` : endpoint.host;
+  return `http://${host}:${endpoint.port}`;
+}
+function tokenHeaders(baseUrl, rawSettings) {
+  const token = readString(parseSettings(rawSettings)["CLAUDE_MEM_LOCAL_API_TOKEN"]);
+  try {
+    return token && isLoopbackHost(new URL(baseUrl).hostname) ? { [TOKEN_HEADER]: token } : {};
+  } catch {
+    return {};
+  }
+}
 function resolveDatabasePath(env, rawSettings, home) {
-  if (!LOOPBACK_HOSTS.has(parseWorkerEndpoint(env, rawSettings).host)) {
+  if (!isLoopbackHost(parseWorkerEndpoint(env, rawSettings).host)) {
     return null;
   }
   const settings = parseSettings(rawSettings);
-  const dir = readString(env["CLAUDE_MEM_DATA_DIR"]) ?? readString(settings["CLAUDE_MEM_DATA_DIR"]) ?? join(home, ".claude-mem");
-  return join(dir.replace(/^~(?=$|[\\/])/, home), "claude-mem.db");
+  const dir = readString(env["CLAUDE_MEM_DATA_DIR"]) ?? readString(settings["CLAUDE_MEM_DATA_DIR"]) ?? join2(home, ".claude-mem");
+  return join2(dir.replace(/^~(?=$|[\\/])/, home), "claude-mem.db");
 }
 function readCount(value) {
   return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
@@ -88,27 +195,45 @@ function readEpoch(item) {
 }
 function readSettingsRaw() {
   try {
-    return readFileSync(SETTINGS_FILE, "utf8");
+    return readFileSync2(join2(dataDirectory(process.env, homedir2()), "settings.json"), "utf8");
   } catch {
     return null;
   }
 }
+function readWorkerSetting(key) {
+  return readString(process.env[key]) ?? readString(parseSettings(readSettingsRaw())[key]);
+}
+function getWorkerEndpoint() {
+  return parseWorkerEndpoint(process.env, readSettingsRaw());
+}
 function getWorkerBaseUrl() {
-  const endpoint = parseWorkerEndpoint(process.env, readSettingsRaw());
-  return `http://${endpoint.host}:${endpoint.port}`;
+  return workerUrl(getWorkerEndpoint());
+}
+function workerHeaders(baseUrl = getWorkerBaseUrl()) {
+  return tokenHeaders(baseUrl, readSettingsRaw());
 }
 
 class WorkerClient {
   static BASE_URL = getWorkerBaseUrl();
-  static DATABASE_PATH = resolveDatabasePath(process.env, readSettingsRaw(), homedir());
+  static SUPPORTED = !readWorkerSetting("CLAUDE_MEM_WORKER_URL");
+  static DATABASE_PATH = resolveDatabasePath(process.env, readSettingsRaw(), homedir2());
+  static get(path) {
+    if (!this.SUPPORTED) {
+      return Promise.reject(new Error("CLAUDE_MEM_WORKER_URL is not supported"));
+    }
+    return fetch(`${this.BASE_URL}${path}`, {
+      headers: workerHeaders(this.BASE_URL),
+      redirect: "error"
+    });
+  }
   static getProjectCounts(project) {
-    return this.DATABASE_PATH ? readProjectCounts(this.DATABASE_PATH, project) : Promise.resolve(null);
+    return this.DATABASE_PATH && this.SUPPORTED ? readProjectCounts(this.DATABASE_PATH, project) : Promise.resolve(null);
   }
   static async getStats() {
     try {
       const [statsRes, processingRes] = await Promise.all([
-        fetch(`${this.BASE_URL}/api/stats`),
-        fetch(`${this.BASE_URL}/api/processing-status`)
+        this.get(`/api/stats`),
+        this.get(`/api/processing-status`)
       ]);
       if (!statsRes.ok) {
         return null;
@@ -123,7 +248,7 @@ class WorkerClient {
   static async getRecentSummaries(project, limit) {
     try {
       const params = new URLSearchParams({ project, limit: String(limit) });
-      const response = await fetch(`${this.BASE_URL}/api/summaries?${params.toString()}`);
+      const response = await this.get(`/api/summaries?${params.toString()}`);
       if (!response.ok) {
         return [];
       }
@@ -145,7 +270,7 @@ class WorkerClient {
   static async getRecentObservations(project, limit) {
     try {
       const params = new URLSearchParams({ project, limit: String(limit) });
-      const response = await fetch(`${this.BASE_URL}/api/observations?${params.toString()}`);
+      const response = await this.get(`/api/observations?${params.toString()}`);
       if (!response.ok) {
         return [];
       }
@@ -168,7 +293,7 @@ class WorkerClient {
   static async getDetail(kind, id) {
     try {
       const path = kind === "observation" ? "observation" : "session";
-      const response = await fetch(`${this.BASE_URL}/api/${path}/${id}`);
+      const response = await this.get(`/api/${path}/${id}`);
       if (!response.ok) {
         return null;
       }
@@ -252,6 +377,9 @@ function summaryLine(view) {
   if (!view.healthy) {
     return { label: "(offline)", tone: "err" };
   }
+  if (view.capture?.state === "problem") {
+    return { label: "(capture off)", tone: "err" };
+  }
   if (view.isProcessing || (view.queueDepth ?? 0) > 0) {
     return { label: `(queue ${view.queueDepth ?? 0})`, tone: "warn" };
   }
@@ -279,11 +407,21 @@ function recentRow(icon, iconColor, title, age, theme, onSelect) {
   ]);
 }
 function expandedRows(view, theme, onSelect) {
+  const notice = view.capture?.message ? [
+    box({ flexDirection: "row", gap: 1 }, [
+      text({ fg: theme.warning, flexShrink: 0 }, "!"),
+      text({
+        fg: view.capture.state === "problem" ? theme.error : theme.warning,
+        wrapMode: "word"
+      }, view.capture.message)
+    ])
+  ] : [];
   if (!view.healthy) {
-    return [bulletRow("\u2022", theme.error, "worker offline", theme)];
+    return [bulletRow("\u2022", theme.error, "worker offline", theme), ...notice];
   }
   const counts = `obs ${formatCount(view.observations)} \xB7 sum ${formatCount(view.summaries)} \xB7 ses ${formatCount(view.sessions)}`;
   const rows = [
+    ...notice,
     bulletRow("\u2022", theme.success, view.scope === "all" ? `all \xB7 ${counts}` : counts, theme)
   ];
   if (view.scope === "project") {
@@ -330,14 +468,16 @@ function viewKey(view) {
 function readCount2(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
-async function readMemView(project, collapsed) {
+async function readMemView(project, collapsed, directory = "") {
   const [stats, counts] = await Promise.all([
     WorkerClient.getStats(),
     WorkerClient.getProjectCounts(project)
   ]);
+  const capture = directory ? readCaptureStatus(directory) : null;
   if (!stats) {
     return {
       healthy: false,
+      capture,
       project,
       scope: "all",
       totalObservations: null,
@@ -358,6 +498,7 @@ async function readMemView(project, collapsed) {
   const totalObservations = readCount2(stats.database?.observations);
   return {
     healthy: true,
+    capture,
     project,
     scope: counts ? "project" : "all",
     totalObservations,
@@ -428,8 +569,9 @@ var tuiModule = {
         }
       ];
     };
-    const project = projectNameFromDirectory(String(api.state?.path?.directory ?? ""));
-    const initialView = await readMemView(project, true);
+    const directory = String(api.state?.path?.directory ?? "");
+    const project = projectNameFromDirectory(directory);
+    const initialView = await readMemView(project, true, directory);
     const [collapsed, setCollapsed] = signal(true);
     const [view, setView] = signal(initialView);
     let currentKey = viewKey(initialView);
@@ -437,7 +579,7 @@ var tuiModule = {
     let inFlight = false;
     let timer = null;
     const refresh = async () => {
-      const nextView = await readMemView(project, collapsed());
+      const nextView = await readMemView(project, collapsed(), directory);
       const nextKey = viewKey(nextView);
       if (nextKey !== currentKey) {
         currentKey = nextKey;

package/dist/worker-client.d.ts

@@ -7,7 +7,26 @@ export interface ProjectCounts {
     readonly summaries: number;
     readonly sessions: number;
 }
-export declare function parseWorkerEndpoint(env: Record<string, string | undefined>, rawSettings: string | null): WorkerEndpoint;
+type JsonRecord = Record<string, unknown>;
+export declare function isRecord(value: unknown): value is JsonRecord;
+/** claude-mem's data directory, which holds its settings.json: the environment, else ~/.claude-mem. */
+export declare function dataDirectory(env: Record<string, string | undefined>, home: string): string;
+/**
+ * The port a Worker uses when none is configured: 37700 plus the user id's last two
+ * digits, or on Windows (no user id) a number derived from the data directory.
+ */
+export declare function defaultWorkerPort(dataDir: string, platform?: NodeJS.Platform, uid?: number | null): number;
+export declare function parseWorkerEndpoint(env: Record<string, string | undefined>, rawSettings: string | null, fallbackPort?: number): WorkerEndpoint;
+/** True for this machine: localhost, *.localhost, ::1 and 127.0.0.0/8. */
+export declare function isLoopbackHost(host: string): boolean;
+/** An IPv6 host needs brackets inside a URL. */
+export declare function workerUrl(endpoint: WorkerEndpoint): string;
+/**
+ * The header a Worker with `CLAUDE_MEM_LOCAL_API_TOKEN` requires on everything but its
+ * health check. The token is read from the settings file only, and is sent only to a
+ * Worker on this machine.
+ */
+export declare function tokenHeaders(baseUrl: string, rawSettings: string | null): Record<string, string>;
 /**
  * The Worker's SQLite database: CLAUDE_MEM_DATA_DIR from env, then settings, then
  * ~/.claude-mem. Null when the Worker is not on this machine, because a local file would
@@ -16,10 +35,17 @@ export declare function parseWorkerEndpoint(env: Record<string, string | undefin
 export declare function resolveDatabasePath(env: Record<string, string | undefined>, rawSettings: string | null, home: string): string | null;
 /** Read-only per-project counts; null on a missing, locked or unexpected database. */
 export declare function readProjectCounts(path: string, project: string): Promise<ProjectCounts | null>;
+/** A claude-mem setting: the environment first, then the data directory's settings.json. */
+export declare function readWorkerSetting(key: string): string | null;
+export declare function getWorkerEndpoint(): WorkerEndpoint;
 export declare function getWorkerBaseUrl(): string;
+/** Headers for a request to `baseUrl`: the local token when that Worker needs one. */
+export declare function workerHeaders(baseUrl?: string): Record<string, string>;
 export declare class WorkerClient {
     private static readonly BASE_URL;
+    private static readonly SUPPORTED;
     private static readonly DATABASE_PATH;
+    private static get;
     /**
      * Per-project counts, read from the Worker's database in read-only mode. The Worker's
      * HTTP API only reports global totals. Null when the database is remote, missing,
@@ -64,3 +90,4 @@ export declare class WorkerClient {
      */
     static getDetail(kind: 'summary' | 'observation', id: number): Promise<Record<string, unknown> | null>;
 }
+export {};

package/dist/worker-start.d.ts

@@ -0,0 +1,46 @@
+export type WorkerState = 
+/** `version` is null when the Worker answered without a readable version. */
+{
+    readonly status: 'running';
+    readonly version: string | null;
+}
+/** No launcher: claude-mem is not installed on this machine. */
+ | {
+    readonly status: 'missing';
+}
+/** Not running, and this machine is told not to start it (or it runs elsewhere). */
+ | {
+    readonly status: 'disabled';
+}
+/** The launcher ran, and the port still does not answer. */
+ | {
+    readonly status: 'failed';
+};
+export interface WorkerStartDeps {
+    /** Null only when the connection was refused, meaning no Worker holds the port. */
+    readonly probe: () => Promise<{
+        version: string | null;
+    } | null>;
+    readonly disabled: () => boolean;
+    readonly launcher: () => string | null;
+    /** Resolves false when the launcher could not be spawned. */
+    readonly start: (launcher: string) => Promise<boolean>;
+    readonly waitMs: number;
+    readonly pollMs: number;
+}
+/**
+ * True for a refused connection, however the runtime reports it: Bun sets
+ * `code: 'ConnectionRefused'`, Node keeps ECONNREFUSED on `cause` or nested `errors`.
+ */
+export declare function isConnectionRefused(error: unknown, seen?: Set<unknown>): boolean;
+/** Where `npx claude-mem install` places the launcher (claude-mem's install-launcher.ts). */
+export declare function launcherPath(platform: NodeJS.Platform, env: Record<string, string | undefined>, home: string): string;
+/**
+ * claude-mem's own switches for "do not start a Worker here": an explicit Worker URL,
+ * `CLAUDE_MEM_WORKER_AUTOSTART=false`, or a Worker host that is another machine.
+ */
+export declare function autostartDisabled(read: (key: string) => string | null, host?: string): boolean;
+/** The Worker as it is now, without starting anything. */
+export declare function workerState(deps?: WorkerStartDeps): Promise<WorkerState>;
+/** One start at a time per process; every caller during it gets the same answer. */
+export declare function ensureWorker(deps?: WorkerStartDeps): Promise<WorkerState>;

package/dist/worker-tools.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One namespace for every tool: a direct tool call sees `claude_mem_<name>`, Code Mode
+ * sees `tools.claude_mem.<name>` under a single catalog entry with this description.
+ */
+export declare const TOOL_NAMESPACE: {
+    readonly name: "claude_mem";
+    readonly description: "claude-mem memory beyond search. work_state_write / work_state_read are your canonical to-do list and working state for this project: use them instead of any built-in to-do tool. save_memory records a durable note. dumb_search is a one-call lookup; get_tool_uses fetches raw tool I/O; the corpus tools build and query knowledge corpora.";
+};
+export interface WorkerTool {
+    /** Without the namespace: `save_memory`, not `claude_mem_save_memory`. */
+    readonly name: string;
+    readonly description: string;
+    readonly input: Record<string, unknown>;
+    readonly options: {
+        readonly namespace: string;
+        readonly pinned?: true;
+    };
+    /** `context.signal` aborts when the session stops; the request is dropped with it. */
+    readonly execute: (input: unknown, context?: {
+        readonly signal?: AbortSignal;
+    }) => Promise<{
+        content: string;
+    }>;
+}
+export interface WorkerToolOptions {
+    /** The session's checkout: the Worker derives the project from it. */
+    readonly directory: string;
+    readonly baseUrl?: string;
+    /** Starts the Worker after a refused connection; resolves true when it answers. */
+    readonly startWorker?: () => Promise<boolean>;
+    readonly corpusIdleTimeoutMs?: number;
+}
+export declare function createWorkerTools(options: WorkerToolOptions): WorkerTool[];

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@ephemushroom/opencode-claude-mem",
-  "version": "0.7.0",
-  "description": "OpenCode Memory sidebar for Claude-Mem; pairs with the official claude-mem OpenCode plugin",
+  "version": "0.7.1",
+  "description": "Claude-Mem for OpenCode: capture through the official claude-mem plugin, memory tools and the Memory sidebar in one package",
   "type": "module",
   "files": [
     "dist"
   ],
   "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
     "./tui": {
       "types": "./dist/package-tui.d.ts",
       "import": "./dist/package-tui.js"
@@ -17,7 +21,7 @@
     }
   },
   "scripts": {
-    "build": "bun build src/tui.ts --outfile dist/tui.js --target bun --format esm --external @opentui/solid --external solid-js && bun build src/cli.ts --outfile dist/cli.js --target bun --format esm --external @opentui/solid --external solid-js && bun src/build-tui-bridge.ts && tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build": "bun build src/server.ts --outfile dist/server.js --target bun --format esm && bun build src/tui.ts --outfile dist/tui.js --target bun --format esm --external @opentui/solid --external solid-js && bun build src/cli.ts --outfile dist/cli.js --target bun --format esm --external @opentui/solid --external solid-js && bun src/build-tui-bridge.ts && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "lint": "oxlint",