om-memory-system 3.6.0-next.42 → 3.6.0-next.44

package/dist/cli/web-command.js

@@ -173,7 +173,7 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
     });
     console.log(`OMMS web app: ${server.getUrl()}`);
     // The Node HTTP adapter unrefs its socket for plugin use. Keep the CLI alive.
-    const keeper = setInterval(() => { }, 60_000);
+    let keeper = setInterval(() => { }, 60_000);
     const stop = () => {
         clearInterval(keeper);
         process.off("SIGINT", stop);
@@ -191,6 +191,14 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
             process.off("SIGTERM", stop);
             await server.stop();
         },
+        // A restart whose copy failed serves again from this process.
+        resumeServer: async () => {
+            keeper = setInterval(() => { }, 60_000);
+            process.once("SIGINT", stop);
+            process.once("SIGTERM", stop);
+            await server.start();
+        },
+        baseUrl: server.getUrl(),
         loginItem: action === "--login-item",
         autostart: options,
     }));

package/dist/cli/web-power.d.ts

@@ -1,10 +1,15 @@
 import type { WebAutostartOptions } from "../services/web-autostart.js";
+/** The two choices the page offers; the web server passes them through unchanged. */
 export type PowerAction = "stop" | "restart";
 interface SpawnedChild {
     pid?: number;
     unref(): void;
-    on(event: "error", listener: (error: Error) => void): unknown;
+    on(event: "error" | "exit", listener: () => void): unknown;
+    kill(signal?: NodeJS.Signals): boolean;
 }
+/** How long the old process waits for the copy to answer before it serves again. */
+export declare const HANDOFF_WAIT_MS = 15000;
+/** Injected so tests check the restart order without spawning or exiting. */
 export interface PowerDeps {
     spawn: (command: string, args: string[], options: {
         detached: true;
@@ -16,6 +21,12 @@ export interface PowerDeps {
     restartLoginItem: () => boolean | Promise<boolean>;
     /** Write the start lock, naming `pid`, so a host that starts meanwhile waits. */
     writeStartLock: (pid: number) => void | Promise<void>;
+    /** Remove the start lock when it names `pid`. */
+    removeStartLock: (pid: number) => void | Promise<void>;
+    /** True when an OMMS web app answers health at `baseUrl`. */
+    probe: (baseUrl: string) => Promise<boolean>;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
     exit: (code: number) => void;
     /** The runtime and arguments of this process, for a detached copy. */
     execPath: string;
@@ -26,13 +37,17 @@ export interface PowerDeps {
 }
 /**
  * The callback the web server runs after it replies to Stop or Restart.
- * `stopServer` stops serving and any keep-alive timer. Restart starts a fresh
- * copy on the same port: the service manager for the login item, and a detached
- * copy otherwise. A detached child of the login item would die with its
- * launchd job or systemd control group.
+ * `stopServer` stops serving and any keep-alive timer; `resumeServer` undoes it.
+ * Restart starts a fresh copy on the same port: the service manager for the
+ * login item, and a detached copy otherwise. A detached child of the login item
+ * would die with its launchd job or systemd control group. A restart never
+ * leaves the port empty because the copy failed: the old process serves again.
  */
 export declare function createPowerAction(options: {
     stopServer: () => Promise<void>;
+    resumeServer: () => Promise<void>;
+    /** The URL this web app serves, where the copy must answer after the handoff. */
+    baseUrl: string;
     loginItem: boolean;
     autostart?: WebAutostartOptions;
     deps?: Partial<PowerDeps>;

package/dist/cli/web-power.js

@@ -1,15 +1,33 @@
 import { spawn as nodeSpawn } from "node:child_process";
 import { homedir } from "node:os";
+/** How long a fresh copy must stay up before the old process stops serving. */
+const SPAWN_CHECK_MS = 1_000;
+/** How long the old process waits for the copy to answer before it serves again. */
+export const HANDOFF_WAIT_MS = 15_000;
+const HANDOFF_POLL_MS = 250;
 function productionDeps(options) {
     return {
         spawn: nodeSpawn,
         restartLoginItem: async () => (await import("../services/web-autostart.js")).restartWebAutostart(options),
         writeStartLock: async (pid) => {
             const { nodeLockFs, startLockPath } = await import("../services/web-ensure.js");
-            const path = startLockPath();
-            nodeLockFs.remove(path);
-            nodeLockFs.createExclusive(path, JSON.stringify({ pid, at: Date.now() }));
+            nodeLockFs.replace(startLockPath(), JSON.stringify({ pid, at: Date.now() }));
         },
+        removeStartLock: async (pid) => (await import("../services/web-ensure.js")).removeStartLockFor(pid),
+        probe: async (baseUrl) => {
+            try {
+                const response = await fetch(`${baseUrl}/api/health`, {
+                    signal: AbortSignal.timeout(1_000),
+                });
+                const body = (await response.json());
+                return response.ok && body.success === true && body.status === "ok";
+            }
+            catch {
+                return false;
+            }
+        },
+        sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+        now: () => Date.now(),
         exit: (code) => process.exit(code),
         execPath: process.execPath,
         args: process.argv.slice(1),
@@ -20,42 +38,104 @@ function productionDeps(options) {
 }
 /**
  * The callback the web server runs after it replies to Stop or Restart.
- * `stopServer` stops serving and any keep-alive timer. Restart starts a fresh
- * copy on the same port: the service manager for the login item, and a detached
- * copy otherwise. A detached child of the login item would die with its
- * launchd job or systemd control group.
+ * `stopServer` stops serving and any keep-alive timer; `resumeServer` undoes it.
+ * Restart starts a fresh copy on the same port: the service manager for the
+ * login item, and a detached copy otherwise. A detached child of the login item
+ * would die with its launchd job or systemd control group. A restart never
+ * leaves the port empty because the copy failed: the old process serves again.
  */
 export function createPowerAction(options) {
     const deps = { ...productionDeps(options.autostart ?? {}), ...options.deps };
+    const logFailure = (code) => Promise.resolve(deps.log("Web app restart failed", { code })).catch(() => undefined);
+    let stopped = false;
+    /** Start the copy, check it, stop serving, and wait until the copy answers. */
+    async function handOff() {
+        let child;
+        try {
+            child = deps.spawn(deps.execPath, deps.args, {
+                detached: true,
+                stdio: "ignore",
+                cwd: deps.cwd,
+                windowsHide: true,
+            });
+        }
+        catch {
+            return giveUp("spawn-error");
+        }
+        let failed = false;
+        let exited = false;
+        child.on("error", () => (failed = true));
+        child.on("exit", () => (exited = true));
+        child.unref();
+        const copyPid = child.pid;
+        if (!copyPid)
+            return giveUp("spawn-error");
+        // A missing script or a broken runtime ends the copy within this time.
+        await deps.sleep(SPAWN_CHECK_MS);
+        if (failed)
+            return giveUp("spawn-error");
+        if (exited)
+            return giveUp("copy-exit");
+        await deps.writeStartLock(copyPid);
+        if (!stopped) {
+            await options.stopServer();
+            stopped = true;
+        }
+        // The copy waits as a non-owner and takes the port within about 7 seconds.
+        const began = deps.now();
+        while (deps.now() - began < HANDOFF_WAIT_MS) {
+            if (exited)
+                return giveUp("copy-exit", copyPid);
+            if (await deps.probe(options.baseUrl))
+                return deps.exit(0);
+            await deps.sleep(HANDOFF_POLL_MS);
+        }
+        if (exited)
+            return giveUp("copy-exit", copyPid);
+        // A copy that never answers would wait as a non-owner for ever.
+        child.kill("SIGTERM");
+        return giveUp("handoff", copyPid);
+    }
+    /** Keep or resume serving on the old process, and release the lock it wrote. */
+    async function giveUp(code, copyPid) {
+        if (copyPid !== undefined)
+            await deps.removeStartLock(copyPid);
+        else if (!options.loginItem)
+            await deps.removeStartLock(deps.pid);
+        await logFailure(code);
+        if (!stopped)
+            return;
+        try {
+            await options.resumeServer();
+            stopped = false;
+        }
+        catch (error) {
+            await logFailure(error instanceof Error ? error.name : "resume-error");
+            deps.exit(1);
+        }
+    }
     return async (action) => {
         if (action === "stop") {
             await options.stopServer();
             deps.exit(0);
             return;
         }
+        stopped = false;
         try {
-            // Hold other hosts off until the copy owns the port.
-            if (!options.loginItem)
+            if (options.loginItem) {
+                await options.stopServer();
+                stopped = true;
+                if (await deps.restartLoginItem())
+                    return deps.exit(0);
+            }
+            else {
+                // Hold other hosts off until the copy owns the port.
                 await deps.writeStartLock(deps.pid);
-            await options.stopServer();
-            if (options.loginItem && (await deps.restartLoginItem()))
-                return deps.exit(0);
-            const child = deps.spawn(deps.execPath, deps.args, {
-                detached: true,
-                stdio: "ignore",
-                cwd: deps.cwd,
-                windowsHide: true,
-            });
-            child.on("error", () => undefined);
-            child.unref();
-            if (child.pid)
-                await deps.writeStartLock(child.pid);
+            }
+            await handOff();
         }
         catch (error) {
-            await Promise.resolve(deps.log("Web app restart failed", {
-                code: error instanceof Error ? error.name : "unknown",
-            })).catch(() => undefined);
+            await giveUp(error instanceof Error ? error.name : "unknown");
         }
-        deps.exit(0);
     };
 }

package/dist/config.d.ts

@@ -52,6 +52,8 @@ interface OmmsConfig {
         from: string;
         to: string;
     }>;
+    /** Claude Code's folder (its transcripts are in `<folder>/projects`). Empty means `CLAUDE_CONFIG_DIR`, then `~/.claude`. Global config only. */
+    claudeConfigDir?: string;
     webServerAutoStart?: boolean;
     webServerEnabled?: boolean;
     webServerPort?: number;
@@ -100,7 +102,7 @@ interface OmmsConfig {
         injectOn?: "first" | "always";
     };
 }
-export declare const CONFIG_TEMPLATE = "{\n  // ============================================\n  // omms (Opinionated Modular Memory System) Configuration\n  // ============================================\n  \n  // Storage location for the vector database. Leave unset to use the\n  // default ~/.omms/data (a legacy ~/.opencode-mem/data store is migrated\n  // there automatically on first start; see docs/omms-migration.md).\n  // \"storagePath\": \"~/.omms/data\",\n\n  \"userEmailOverride\": \"\",\n  \"userNameOverride\": \"\",\n  \n  // ============================================\n  // Embedding Model (for similarity search)\n  // ============================================\n  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).\n  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).\n  \n  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)\n  \"embeddingModel\": \"Xenova/nomic-embed-text-v1\",\n\n  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,\n  // re-index existing memories so store and query vectors stay aligned.\n  // \"embeddingUseTaskPrefixes\": true,\n  \n  // Auto-detected dimensions (no need to set manually)\n  // \"embeddingDimensions\": 768,\n  \n  // Other recommended local models:\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-base-en\",  // 768 dims, English-only, 8192 context\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-small-en\", // 512 dims, faster, 8192 context\n  // \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",            // 384 dims, very fast, 512 context\n  // \"embeddingModel\": \"Xenova/all-mpnet-base-v2\",           // 768 dims, good quality, 512 context\n  \n  // Optional: OpenAI-compatible API for embeddings (both URL and key required)\n  // \"embeddingApiUrl\": \"https://api.openai.com/v1\",\n  // \"embeddingApiKey\": \"env://OPENAI_API_KEY\",  // or \"sk-...\" / \"file:///path/to/key\"\n  // \"embeddingModel\": \"text-embedding-3-small\",  // 1536 dims, auto-detected\n \n  // ============================================\n  // Web Server Settings\n  // ============================================\n  \n  // Start a background import of past chats on each host's next start.\n  \"autoBackfill\": true,\n  // \"piBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // Directory maps for history recorded in moved or deleted directories.\n  // \"importPathMaps\": [{ \"from\": \"~/code/app-feat-x\", \"to\": \"~/code/app\" }],\n\n  // Register the web app to start when you log in.\n  \"webServerAutoStart\": true,\n  // Enable web UI for managing memories (accessible at http://localhost:4747)\n  \"webServerEnabled\": true,\n  \n  // Port for web UI server\n  \"webServerPort\": 4747,\n  \n  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)\n  \"webServerHost\": \"127.0.0.1\",\n\n  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.\n  // \"webServerAuthPassword\": \"\",\n  // \"webServerAuthUsername\": \"\",\n\n  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).\n  // \"webServerApiToken\": \"env://OMMS_WEB_TOKEN\",\n  \n  // ============================================\n  // Database Settings\n  // ============================================\n  \n  // Maximum vectors per database shard (auto-creates new shard when limit reached)\n  \"maxVectorsPerShard\": 50000,\n  \n  // Automatically delete old memories based on retention period\n  \"autoCleanupEnabled\": true,\n  \n  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)\n  \"autoCleanupRetentionDays\": 30,\n  \n  // Automatically detect and remove duplicate memories\n  \"deduplicationEnabled\": true,\n  \n   // Similarity threshold (0-1) for detecting duplicates (higher = stricter)\n   \"deduplicationSimilarityThreshold\": 0.90,\n   \n  // ============================================\n  // Memory Scope Settings\n  // ============================================\n\n  // Default scope for memory list/search queries\n  // \"project\" keeps queries within the current project, \"all-projects\" searches across all project shards\n  \"memory\": {\n    \"defaultScope\": \"project\"\n  },\n\n  // ============================================\n  // Model for auto-capture and profile learning (same rule in OpenCode and Pi)\n  // ============================================\n\n   // Which model summarises your work, in this order:\n   //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,\n   //      piProvider/piModel in Pi. Set the model to \"inherit\" to follow\n   //      whatever model the session is using, or to \"external\" to send\n   //      every call to the external API below.\n   //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/\n   //      memoryApiKey further down).\n   //   3. If neither is set: the session's own model.\n   // If the host model fails and the external API is configured, the external\n   // API is used instead.\n   //\n   // Host models go through OpenCode's or Pi's own sign-in (OAuth like Claude\n   // Pro/Max, GitHub Copilot, ChatGPT, or your own key there), so no separate API\n   // key is needed here.\n   //\n   // Examples (OpenCode names from 'opencode providers list'; Pi names from its model list):\n   //   \"opencodeProvider\": \"anthropic\",    \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n   //   \"opencodeProvider\": \"openai\",       \"opencodeModel\": \"inherit\"\n   //   \"piProvider\": \"openai-codex\",       \"piModel\": \"gpt-5.6-luna\"\n   //\n   // \"opencodeProvider\": \"anthropic\",\n   // \"opencodeModel\": \"claude-haiku-4-5-20251001\",\n   // \"piProvider\": \"openai-codex\",\n   // \"piModel\": \"gpt-5.6-luna\",\n\n   // ============================================\n   // Auto-Capture Settings\n   // ============================================\n  \n  // Auto-capture runs in the background without blocking your main session.\n  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.\n  \n  \"autoCaptureEnabled\": true,\n  \n  // Provider type: \"openai-chat\" | \"openai-responses\" | \"anthropic\" | \"minimax\" | \"orcarouter\" | \"google-gemini\"\n  // Note: \"openai-chat\" is a generic OpenAI API-compatible mode.\n  // Any service that follows the OpenAI Chat Completions API can use it via custom \"memoryApiUrl\".\n  \"memoryProvider\": \"openai-chat\",\n  \n  // External API (step 2 above, and the fallback when a host model fails).\n  // Uncomment all 3 lines and replace memoryApiKey before use:\n  // \"memoryModel\": \"gpt-4o-mini\",\n  // \"memoryApiUrl\": \"https://api.openai.com/v1\",\n  // \"memoryApiKey\": \"sk-...\",\n\n  // API Key Formats:\n  // Direct value:        \"sk-...\"\n  // From file:           \"file://~/.config/litellm-key.txt\"\n  // From env variable:   \"env://LITELLM_API_KEY\"\n  \n  // Examples for different providers:\n  // Any OpenAI-compatible endpoint can use the \"openai-chat\" provider pattern below.\n  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),\n  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).\n\n  // OpenAI Chat Completion (default, backward compatible):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"gpt-4o-mini\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n\n  // DeepSeek (OpenAI-compatible example):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"deepseek-chat\"\n  //   \"memoryApiUrl\": \"https://api.deepseek.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // OpenAI Responses API (recommended, with session support):\n  //   \"memoryProvider\": \"openai-responses\"\n  //   \"memoryModel\": \"gpt-4o\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // Anthropic (with session support):\n  //   \"memoryProvider\": \"anthropic\"\n  //   \"memoryModel\": \"claude-3-5-haiku-20241022\"\n  //   \"memoryApiUrl\": \"https://api.anthropic.com/v1\"\n  //   \"memoryApiKey\": \"sk-ant-...\"\n\n  // MiniMax (Anthropic Messages-compatible endpoint, with session support):\n  //   \"memoryProvider\": \"minimax\"\n  //   \"memoryModel\": \"MiniMax-M3\"\n  //   \"memoryApiUrl\": \"https://api.minimax.io\"        // global endpoint\n  //   \"memoryApiKey\": \"<MiniMax API key>\"\n  //   // China endpoint: \"memoryApiUrl\": \"https://api.minimaxi.com\"\n  //   // Optional adaptive thinking for MiniMax-M3:\n  //   \"memoryExtraParams\": { \"thinking\": { \"type\": \"adaptive\" } }\n\n  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):\n  //   \"memoryProvider\": \"orcarouter\"\n  //   \"memoryApiKey\": \"<OrcaRouter API key>\"\n  //   // memoryApiUrl and memoryModel are optional \u2014 they default to\n  //   // https://api.orcarouter.ai/v1 and \"orcarouter/auto\" (a routing alias).\n  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a\n  //   // namespaced ID such as \"openai/gpt-5.5\" or \"deepseek/deepseek-v4-flash\".\n  //   \"memoryModel\": \"openai/gpt-5.5\"\n\n  // Groq (OpenAI-compatible, use openai-chat provider):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"llama-3.3-70b-versatile\"\n  //   \"memoryApiUrl\": \"https://api.groq.com/openai/v1\"\n  //   \"memoryApiKey\": \"gsk_...\"\n  \n  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)\n  \"autoCaptureMaxIterations\": 5,\n   \n  // Timeout per iteration in milliseconds (30 seconds default)\n  \"autoCaptureIterationTimeout\": 30000,\n\n  // Tries for one turn's capture, on Pi and OpenCode, 2 and 4 seconds apart. After the\n  // last one fails, a turn the model could not reach goes to the capture retry queue.\n  \"autoCaptureMaxRetries\": 3,\n\n  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.\n  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).\n  // Rough guide: tokens \u2248 bytes / 4 for mixed code/prose.\n  \"autoCaptureMaxContextBytes\": 131072,\n   \n  // Days to keep AI session history before cleanup\n  \"aiSessionRetentionDays\": 7,\n\n  // Capture diagnostics: every capture attempt always writes one metadata line\n  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no\n  // conversation text. Set captureTrace to true to also write each attempt's\n  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain\n  // conversation content: <private> text and common API key formats are\n  // redacted, files are readable only by you, and they are deleted after\n  // captureTraceRetentionDays. Only this global file can turn tracing on.\n  // \"captureTrace\": false,\n  // \"captureTraceRetentionDays\": 7,\n  // \"captureAttemptRetentionDays\": 30,\n\n  // Capture retry queue: when a live capture fails because the model cannot be\n  // reached (network error, timeout, HTTP 408, 429 or 5xx), OMMS keeps a copy of\n  // the turn in ~/.omms/data and tries it again later. The copy has <private>\n  // text and common API key formats removed. Turns are deleted when the retry\n  // ends or after captureRetryRetentionHours (0 to 720). 0 turns the queue off.\n  // Only this global file can set it.\n  // \"captureRetryRetentionHours\": 72,\n\n  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)\n  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter\n  // Set to false and add \"memoryTemperature\": false in config when using such models\n  \"memoryTemperature\": 0.3,\n\n  // Extra parameters to include in API request body\n  // Useful for local inference servers (e.g. llama-server with --jinja) that support\n  // additional parameters like disabling thinking/reasoning mode\n  // Example for Qwen3 models: { \"enable_thinking\": false }\n  // \"memoryExtraParams\": {},\n\n  // Language for auto-capture summaries (default: \"auto\" for auto-detection)\n  // Options: \"auto\", \"en\", \"id\", \"zh\", \"ja\", \"es\", \"fr\", \"de\", \"ru\", \"pt\", \"ar\", \"ko\"\n  // \"autoCaptureLanguage\": \"auto\",\n\n  // ============================================\n  // Toast Notifications\n  // ============================================\n\n  // Show toast when memory is auto-captured\n  \"showAutoCaptureToasts\": true,\n\n  // Show toast when user profile is updated\n  \"showUserProfileToasts\": true,\n\n  // Show toast for error messages\n  \"showErrorToasts\": true,\n\n  // ============================================\n  // User Profile System\n  // ============================================\n\n  // Analyze user prompts every N prompts to build/update your user profile\n  // When N uncaptured prompts accumulate, AI will analyze them to identify:\n  // - User preferences (code style, communication style, tool preferences)\n  // - User patterns (recurring topics, problem domains, technical interests)\n  // - User workflows (development habits, sequences, learning style)\n  // - Skill level (overall and per-domain assessment)\n  \"userProfileAnalysisInterval\": 10,\n\n  // Days before inactive items (all types) are eligible for removal\n  \"userProfileStaleDays\": 2,\n\n  // Number of preferences shown in UI\n  \"userProfileDisplayPreferences\": 20,\n  \n  // Number of patterns shown in UI\n  \"userProfileDisplayPatterns\": 15,\n  \n  // Number of workflows shown in UI\n  \"userProfileDisplayWorkflows\": 10,\n  \n  // Number of preferences injected into LLM conversation context\n  // Keep this small \u2014 the strongest signals are enough; more dilute LLM attention\n  \"userProfileInjectPreferences\": 5,\n  \n  // Number of patterns injected into LLM conversation context\n  \"userProfileInjectPatterns\": 5,\n  \n  // Number of workflows injected into LLM conversation context\n  \"userProfileInjectWorkflows\": 3,\n  \n  // Days before preference confidence starts to decay (if not reinforced)\n  // Preferences that aren't seen again will gradually lose confidence and be removed\n  \"userProfileConfidenceDecayDays\": 30,\n  \n  // Number of profile versions to keep in changelog (for rollback/debugging)\n  // Older versions are automatically cleaned up\n  \"userProfileChangelogRetentionCount\": 5,\n\n  // Minimum evidence count for a preference/pattern to survive confidence decay\n  // Items confirmed fewer times are more likely to be pruned when confidence decays\n  \"userProfileMinEvidenceForRetention\": 3,\n\n  // Periodically merge duplicate or irrelevant profile items with the configured AI provider\n  \"userProfileAutoCleanupEnabled\": true,\n  // Number of analyzed user prompts between automatic AI cleanup runs\n  \"userProfileAutoCleanupInterval\": 100,\n\n  // Enable LLM validation of existing preferences against recent behavior.\n  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.\n  // Experimental \u2014 disabled by default.\n  \"userProfileValidationEnabled\": false,\n\n  // ============================================\n  // Search Settings\n  // ============================================\n  \n  // Minimum similarity score (0-1) for memory search results\n  \"similarityThreshold\": 0.6,\n\n  // Maximum number of memories to return in search results\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Advanced Settings\n  // ============================================\n  \n  // Inject user profile into AI context (preferences, patterns, workflows)\n  \"injectProfile\": true\n}\n";
+export declare const CONFIG_TEMPLATE = "{\n  // ============================================\n  // omms (Opinionated Modular Memory System) Configuration\n  // ============================================\n  \n  // Storage location for the vector database. Leave unset to use the\n  // default ~/.omms/data (a legacy ~/.opencode-mem/data store is migrated\n  // there automatically on first start; see docs/omms-migration.md).\n  // \"storagePath\": \"~/.omms/data\",\n\n  \"userEmailOverride\": \"\",\n  \"userNameOverride\": \"\",\n  \n  // ============================================\n  // Embedding Model (for similarity search)\n  // ============================================\n  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).\n  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).\n  \n  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)\n  \"embeddingModel\": \"Xenova/nomic-embed-text-v1\",\n\n  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,\n  // re-index existing memories so store and query vectors stay aligned.\n  // \"embeddingUseTaskPrefixes\": true,\n  \n  // Auto-detected dimensions (no need to set manually)\n  // \"embeddingDimensions\": 768,\n  \n  // Other recommended local models:\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-base-en\",  // 768 dims, English-only, 8192 context\n  // \"embeddingModel\": \"Xenova/jina-embeddings-v2-small-en\", // 512 dims, faster, 8192 context\n  // \"embeddingModel\": \"Xenova/all-MiniLM-L6-v2\",            // 384 dims, very fast, 512 context\n  // \"embeddingModel\": \"Xenova/all-mpnet-base-v2\",           // 768 dims, good quality, 512 context\n  \n  // Optional: OpenAI-compatible API for embeddings (both URL and key required)\n  // \"embeddingApiUrl\": \"https://api.openai.com/v1\",\n  // \"embeddingApiKey\": \"env://OPENAI_API_KEY\",  // or \"sk-...\" / \"file:///path/to/key\"\n  // \"embeddingModel\": \"text-embedding-3-small\",  // 1536 dims, auto-detected\n \n  // ============================================\n  // Web Server Settings\n  // ============================================\n  \n  // Start a background import of past chats on each host's next start.\n  \"autoBackfill\": true,\n  // \"piBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"external\", or \"provider/model\"\n  // Directory maps for history recorded in moved or deleted directories.\n  // \"importPathMaps\": [{ \"from\": \"~/code/app-feat-x\", \"to\": \"~/code/app\" }],\n  // Claude Code's folder, when it is not ~/.claude (like CLAUDE_CONFIG_DIR).\n  // \"claudeConfigDir\": \"~/.claude-work\",\n\n  // Register the web app to start when you log in.\n  \"webServerAutoStart\": true,\n  // Enable web UI for managing memories (accessible at http://localhost:4747)\n  \"webServerEnabled\": true,\n  \n  // Port for web UI server\n  \"webServerPort\": 4747,\n  \n  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)\n  \"webServerHost\": \"127.0.0.1\",\n\n  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.\n  // \"webServerAuthPassword\": \"\",\n  // \"webServerAuthUsername\": \"\",\n\n  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).\n  // \"webServerApiToken\": \"env://OMMS_WEB_TOKEN\",\n  \n  // ============================================\n  // Database Settings\n  // ============================================\n  \n  // Maximum vectors per database shard (auto-creates new shard when limit reached)\n  \"maxVectorsPerShard\": 50000,\n  \n  // Automatically delete old memories based on retention period\n  \"autoCleanupEnabled\": true,\n  \n  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)\n  \"autoCleanupRetentionDays\": 30,\n  \n  // Automatically detect and remove duplicate memories\n  \"deduplicationEnabled\": true,\n  \n   // Similarity threshold (0-1) for detecting duplicates (higher = stricter)\n   \"deduplicationSimilarityThreshold\": 0.90,\n   \n  // ============================================\n  // Memory Scope Settings\n  // ============================================\n\n  // Default scope for memory list/search queries\n  // \"project\" keeps queries within the current project, \"all-projects\" searches across all project shards\n  \"memory\": {\n    \"defaultScope\": \"project\"\n  },\n\n  // ============================================\n  // Model for auto-capture and profile learning (same rule in OpenCode and Pi)\n  // ============================================\n\n   // Which model summarises your work, in this order:\n   //   1. The host model below: opencodeProvider/opencodeModel in OpenCode,\n   //      piProvider/piModel in Pi. Set the model to \"inherit\" to follow\n   //      whatever model the session is using, or to \"external\" to send\n   //      every call to the external API below.\n   //   2. If no host model is set: the external API (memoryModel/memoryApiUrl/\n   //      memoryApiKey further down).\n   //   3. If neither is set: the session's own model.\n   // If the host model fails and the external API is configured, the external\n   // API is used instead.\n   //\n   // Host models go through OpenCode's or Pi's own sign-in (OAuth like Claude\n   // Pro/Max, GitHub Copilot, ChatGPT, or your own key there), so no separate API\n   // key is needed here.\n   //\n   // Examples (OpenCode names from 'opencode providers list'; Pi names from its model list):\n   //   \"opencodeProvider\": \"anthropic\",    \"opencodeModel\": \"claude-haiku-4-5-20251001\"\n   //   \"opencodeProvider\": \"openai\",       \"opencodeModel\": \"inherit\"\n   //   \"piProvider\": \"openai-codex\",       \"piModel\": \"gpt-5.6-luna\"\n   //\n   // \"opencodeProvider\": \"anthropic\",\n   // \"opencodeModel\": \"claude-haiku-4-5-20251001\",\n   // \"piProvider\": \"openai-codex\",\n   // \"piModel\": \"gpt-5.6-luna\",\n\n   // ============================================\n   // Auto-Capture Settings\n   // ============================================\n  \n  // Auto-capture runs in the background without blocking your main session.\n  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.\n  \n  \"autoCaptureEnabled\": true,\n  \n  // Provider type: \"openai-chat\" | \"openai-responses\" | \"anthropic\" | \"minimax\" | \"orcarouter\" | \"google-gemini\"\n  // Note: \"openai-chat\" is a generic OpenAI API-compatible mode.\n  // Any service that follows the OpenAI Chat Completions API can use it via custom \"memoryApiUrl\".\n  \"memoryProvider\": \"openai-chat\",\n  \n  // External API (step 2 above, and the fallback when a host model fails).\n  // Uncomment all 3 lines and replace memoryApiKey before use:\n  // \"memoryModel\": \"gpt-4o-mini\",\n  // \"memoryApiUrl\": \"https://api.openai.com/v1\",\n  // \"memoryApiKey\": \"sk-...\",\n\n  // API Key Formats:\n  // Direct value:        \"sk-...\"\n  // From file:           \"file://~/.config/litellm-key.txt\"\n  // From env variable:   \"env://LITELLM_API_KEY\"\n  \n  // Examples for different providers:\n  // Any OpenAI-compatible endpoint can use the \"openai-chat\" provider pattern below.\n  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),\n  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).\n\n  // OpenAI Chat Completion (default, backward compatible):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"gpt-4o-mini\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n\n  // DeepSeek (OpenAI-compatible example):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"deepseek-chat\"\n  //   \"memoryApiUrl\": \"https://api.deepseek.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // OpenAI Responses API (recommended, with session support):\n  //   \"memoryProvider\": \"openai-responses\"\n  //   \"memoryModel\": \"gpt-4o\"\n  //   \"memoryApiUrl\": \"https://api.openai.com/v1\"\n  //   \"memoryApiKey\": \"sk-...\"\n  \n  // Anthropic (with session support):\n  //   \"memoryProvider\": \"anthropic\"\n  //   \"memoryModel\": \"claude-3-5-haiku-20241022\"\n  //   \"memoryApiUrl\": \"https://api.anthropic.com/v1\"\n  //   \"memoryApiKey\": \"sk-ant-...\"\n\n  // MiniMax (Anthropic Messages-compatible endpoint, with session support):\n  //   \"memoryProvider\": \"minimax\"\n  //   \"memoryModel\": \"MiniMax-M3\"\n  //   \"memoryApiUrl\": \"https://api.minimax.io\"        // global endpoint\n  //   \"memoryApiKey\": \"<MiniMax API key>\"\n  //   // China endpoint: \"memoryApiUrl\": \"https://api.minimaxi.com\"\n  //   // Optional adaptive thinking for MiniMax-M3:\n  //   \"memoryExtraParams\": { \"thinking\": { \"type\": \"adaptive\" } }\n\n  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):\n  //   \"memoryProvider\": \"orcarouter\"\n  //   \"memoryApiKey\": \"<OrcaRouter API key>\"\n  //   // memoryApiUrl and memoryModel are optional \u2014 they default to\n  //   // https://api.orcarouter.ai/v1 and \"orcarouter/auto\" (a routing alias).\n  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a\n  //   // namespaced ID such as \"openai/gpt-5.5\" or \"deepseek/deepseek-v4-flash\".\n  //   \"memoryModel\": \"openai/gpt-5.5\"\n\n  // Groq (OpenAI-compatible, use openai-chat provider):\n  //   \"memoryProvider\": \"openai-chat\"\n  //   \"memoryModel\": \"llama-3.3-70b-versatile\"\n  //   \"memoryApiUrl\": \"https://api.groq.com/openai/v1\"\n  //   \"memoryApiKey\": \"gsk_...\"\n  \n  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)\n  \"autoCaptureMaxIterations\": 5,\n   \n  // Timeout per iteration in milliseconds (30 seconds default)\n  \"autoCaptureIterationTimeout\": 30000,\n\n  // Tries for one turn's capture, on Pi and OpenCode, 2 and 4 seconds apart. After the\n  // last one fails, a turn the model could not reach goes to the capture retry queue.\n  \"autoCaptureMaxRetries\": 3,\n\n  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.\n  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).\n  // Rough guide: tokens \u2248 bytes / 4 for mixed code/prose.\n  \"autoCaptureMaxContextBytes\": 131072,\n   \n  // Days to keep AI session history before cleanup\n  \"aiSessionRetentionDays\": 7,\n\n  // Capture diagnostics: every capture attempt always writes one metadata line\n  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no\n  // conversation text. Set captureTrace to true to also write each attempt's\n  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain\n  // conversation content: <private> text and common API key formats are\n  // redacted, files are readable only by you, and they are deleted after\n  // captureTraceRetentionDays. Only this global file can turn tracing on.\n  // \"captureTrace\": false,\n  // \"captureTraceRetentionDays\": 7,\n  // \"captureAttemptRetentionDays\": 30,\n\n  // Capture retry queue: when a live capture fails because the model cannot be\n  // reached (network error, timeout, HTTP 408, 429 or 5xx), OMMS keeps a copy of\n  // the turn in ~/.omms/data and tries it again later. The copy has <private>\n  // text and common API key formats removed. Turns are deleted when the retry\n  // ends or after captureRetryRetentionHours (0 to 720). 0 turns the queue off.\n  // Only this global file can set it.\n  // \"captureRetryRetentionHours\": 72,\n\n  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)\n  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter\n  // Set to false and add \"memoryTemperature\": false in config when using such models\n  \"memoryTemperature\": 0.3,\n\n  // Extra parameters to include in API request body\n  // Useful for local inference servers (e.g. llama-server with --jinja) that support\n  // additional parameters like disabling thinking/reasoning mode\n  // Example for Qwen3 models: { \"enable_thinking\": false }\n  // \"memoryExtraParams\": {},\n\n  // Language for auto-capture summaries (default: \"auto\" for auto-detection)\n  // Options: \"auto\", \"en\", \"id\", \"zh\", \"ja\", \"es\", \"fr\", \"de\", \"ru\", \"pt\", \"ar\", \"ko\"\n  // \"autoCaptureLanguage\": \"auto\",\n\n  // ============================================\n  // Toast Notifications\n  // ============================================\n\n  // Show toast when memory is auto-captured\n  \"showAutoCaptureToasts\": true,\n\n  // Show toast when user profile is updated\n  \"showUserProfileToasts\": true,\n\n  // Show toast for error messages\n  \"showErrorToasts\": true,\n\n  // ============================================\n  // User Profile System\n  // ============================================\n\n  // Analyze user prompts every N prompts to build/update your user profile\n  // When N uncaptured prompts accumulate, AI will analyze them to identify:\n  // - User preferences (code style, communication style, tool preferences)\n  // - User patterns (recurring topics, problem domains, technical interests)\n  // - User workflows (development habits, sequences, learning style)\n  // - Skill level (overall and per-domain assessment)\n  \"userProfileAnalysisInterval\": 10,\n\n  // Days before inactive items (all types) are eligible for removal\n  \"userProfileStaleDays\": 2,\n\n  // Number of preferences shown in UI\n  \"userProfileDisplayPreferences\": 20,\n  \n  // Number of patterns shown in UI\n  \"userProfileDisplayPatterns\": 15,\n  \n  // Number of workflows shown in UI\n  \"userProfileDisplayWorkflows\": 10,\n  \n  // Number of preferences injected into LLM conversation context\n  // Keep this small \u2014 the strongest signals are enough; more dilute LLM attention\n  \"userProfileInjectPreferences\": 5,\n  \n  // Number of patterns injected into LLM conversation context\n  \"userProfileInjectPatterns\": 5,\n  \n  // Number of workflows injected into LLM conversation context\n  \"userProfileInjectWorkflows\": 3,\n  \n  // Days before preference confidence starts to decay (if not reinforced)\n  // Preferences that aren't seen again will gradually lose confidence and be removed\n  \"userProfileConfidenceDecayDays\": 30,\n  \n  // Number of profile versions to keep in changelog (for rollback/debugging)\n  // Older versions are automatically cleaned up\n  \"userProfileChangelogRetentionCount\": 5,\n\n  // Minimum evidence count for a preference/pattern to survive confidence decay\n  // Items confirmed fewer times are more likely to be pruned when confidence decays\n  \"userProfileMinEvidenceForRetention\": 3,\n\n  // Periodically merge duplicate or irrelevant profile items with the configured AI provider\n  \"userProfileAutoCleanupEnabled\": true,\n  // Number of analyzed user prompts between automatic AI cleanup runs\n  \"userProfileAutoCleanupInterval\": 100,\n\n  // Enable LLM validation of existing preferences against recent behavior.\n  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.\n  // Experimental \u2014 disabled by default.\n  \"userProfileValidationEnabled\": false,\n\n  // ============================================\n  // Search Settings\n  // ============================================\n  \n  // Minimum similarity score (0-1) for memory search results\n  \"similarityThreshold\": 0.6,\n\n  // Maximum number of memories to return in search results\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Advanced Settings\n  // ============================================\n  \n  // Inject user profile into AI context (preferences, patterns, workflows)\n  \"injectProfile\": true\n}\n";
 export declare function normalizeAutoCaptureMaxContextBytes(value: number): number;
 /** Whole hours from 0 to 720. A value that is not a number gives the default. */
 export declare function normalizeCaptureRetryRetentionHours(value: unknown): number;
@@ -145,6 +147,7 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     opencodeBackfillModel: string;
     piBackfillModel: string;
     importPathMaps: import("./importer/importer.js").ImportPathMap[];
+    claudeConfigDir: string;
     webServerAutoStart: boolean;
     webServerEnabled: boolean;
     webServerPort: number;
@@ -239,6 +242,7 @@ export declare let CONFIG: {
     opencodeBackfillModel: string;
     piBackfillModel: string;
     importPathMaps: import("./importer/importer.js").ImportPathMap[];
+    claudeConfigDir: string;
     webServerAutoStart: boolean;
     webServerEnabled: boolean;
     webServerPort: number;

package/dist/config.js

@@ -2,6 +2,7 @@ import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync } from "no
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { stripJsoncComments } from "./services/jsonc.js";
+import { isValidClaudeConfigDir } from "./services/claude-folder.js";
 import { log } from "./services/logger.js";
 import { resolveSecretValue } from "./services/secret-resolver.js";
 import { isPlaceholderApiKey } from "./services/ai/api-key-placeholder.js";
@@ -58,6 +59,7 @@ const DEFAULTS = {
     opencodeBackfillModel: "inherit",
     piBackfillModel: "inherit",
     importPathMaps: [],
+    claudeConfigDir: "",
     webServerAutoStart: true,
     webServerEnabled: true,
     webServerPort: 4747,
@@ -205,6 +207,8 @@ export const CONFIG_TEMPLATE = `{
   // "opencodeBackfillModel": "inherit", // or "external", or "provider/model"
   // Directory maps for history recorded in moved or deleted directories.
   // "importPathMaps": [{ "from": "~/code/app-feat-x", "to": "~/code/app" }],
+  // Claude Code's folder, when it is not ~/.claude (like CLAUDE_CONFIG_DIR).
+  // "claudeConfigDir": "~/.claude-work",
 
   // Register the web app to start when you log in.
   "webServerAutoStart": true,
@@ -599,6 +603,10 @@ function buildConfig(fileConfig) {
     parseBackfillModel(fileConfig, "pi");
     parseBackfillModel(fileConfig, "opencode");
     const importPathMaps = parseImportPathMaps(fileConfig.importPathMaps);
+    if (fileConfig.claudeConfigDir !== undefined &&
+        !isValidClaudeConfigDir(fileConfig.claudeConfigDir)) {
+        throw new Error("Invalid claudeConfigDir config");
+    }
     for (const key of ["autoBackfill", "webServerAutoStart"]) {
         if (fileConfig[key] !== undefined && typeof fileConfig[key] !== "boolean") {
             throw new Error(`Invalid ${key} config`);
@@ -663,6 +671,7 @@ function buildConfig(fileConfig) {
         opencodeBackfillModel: fileConfig.opencodeBackfillModel ?? DEFAULTS.opencodeBackfillModel,
         piBackfillModel: fileConfig.piBackfillModel ?? DEFAULTS.piBackfillModel,
         importPathMaps,
+        claudeConfigDir: expandPath(fileConfig.claudeConfigDir?.trim() ?? DEFAULTS.claudeConfigDir),
         webServerAutoStart: fileConfig.webServerAutoStart ?? DEFAULTS.webServerAutoStart,
         webServerEnabled: fileConfig.webServerEnabled ?? DEFAULTS.webServerEnabled,
         webServerPort: fileConfig.webServerPort ?? DEFAULTS.webServerPort,
@@ -820,6 +829,8 @@ export function initConfig(directory, options = {}) {
     delete projectOverrides.opencodeBackfillModel;
     delete projectOverrides.piBackfillModel;
     delete projectOverrides.importPathMaps;
+    // A checked-in project file must not point the web app at another folder.
+    delete projectOverrides.claudeConfigDir;
     delete projectOverrides.webServerAutoStart;
     delete projectOverrides.webServerEnabled;
     const merged = { ...globalConfig, ...projectOverrides };

package/dist/importer/claude-hook-api.js

@@ -92,7 +92,7 @@ function checkedTranscriptPath(transcriptPath, sessionId) {
     if (basename(transcriptPath) !== fileName || basename(real) !== fileName) {
         throw new ClaudeHookRequestError("transcript_path must be named <session_id>.jsonl");
     }
-    const root = realPathOrResolved(defaultClaudeProjectsRoot());
+    const root = realPathOrResolved(defaultClaudeProjectsRoot(CONFIG.claudeConfigDir));
     if (!real.startsWith(root + sep)) {
         throw new ClaudeHookRequestError("transcript_path must be under the Claude projects folder");
     }
@@ -107,6 +107,8 @@ function parseCaptureRequest(body) {
         throw new ClaudeHookRequestError("transcript_path must be an absolute .jsonl path");
     }
     const { sessionId, cwd } = sessionAndCwd(input);
+    // The path check uses `claudeConfigDir`, which the Settings page may just have changed.
+    refreshConfigIfChanged(cwd);
     return {
         sessionId,
         cwd,

package/dist/importer/claude-reader.d.ts

@@ -16,8 +16,8 @@ import { type ImportPathMap, type ImportProjectReport, type LazyImportSource } f
  * time.
  */
 export declare const CLAUDE_HEADER_READ_LIMIT: number;
-/** `$CLAUDE_CONFIG_DIR/projects` when the variable is set, else `~/.claude/projects`. */
-export declare function defaultClaudeProjectsRoot(): string;
+/** The Claude projects folder; `claudeConfigDir` is `CONFIG.claudeConfigDir`. */
+export declare function defaultClaudeProjectsRoot(claudeConfigDir?: string): string;
 export interface DiscoveredClaudeSession {
     file: string;
     /** Path relative to the root, with `/` separators; the file name for a file root. */

package/dist/importer/claude-reader.js

@@ -1,7 +1,8 @@
 import { closeSync, existsSync, openSync, readFileSync, readSync, readdirSync, statSync, } from "node:fs";
-import { homedir } from "node:os";
 import { basename, join } from "node:path";
 import { StringDecoder } from "node:string_decoder";
+import { CONFIG } from "../config.js";
+import { claudeProjectsRoot } from "../services/claude-folder.js";
 import { extractScopeFromContainerTag } from "../services/memory-scope.js";
 import { getTags } from "../services/tags.js";
 import { extractClaudeConversationWindows, parseClaudeTranscript, parseClaudeTranscriptLine, } from "./claude-conversation.js";
@@ -23,10 +24,9 @@ import { countImportableUnits, projectFilterTag, selectImportWindows, } from "./
  */
 export const CLAUDE_HEADER_READ_LIMIT = 1024 * 1024;
 const READ_CHUNK = 64 * 1024;
-/** `$CLAUDE_CONFIG_DIR/projects` when the variable is set, else `~/.claude/projects`. */
-export function defaultClaudeProjectsRoot() {
-    const configDir = process.env.CLAUDE_CONFIG_DIR?.trim();
-    return join(configDir || join(homedir(), ".claude"), "projects");
+/** The Claude projects folder; `claudeConfigDir` is `CONFIG.claudeConfigDir`. */
+export function defaultClaudeProjectsRoot(claudeConfigDir) {
+    return claudeProjectsRoot(claudeConfigDir);
 }
 /** A missing folder is an empty history. Any other read error is reported, not hidden. */
 function readEntries(dir, unreadable) {
@@ -128,7 +128,7 @@ function isFile(path) {
     }
 }
 export function discoverClaudeSessions(options = {}) {
-    const root = options.root ?? defaultClaudeProjectsRoot();
+    const root = options.root ?? defaultClaudeProjectsRoot(CONFIG.claudeConfigDir);
     const sessions = [];
     const unrecognized = [];
     if (!existsSync(root))

package/dist/importer/import-readiness.js

@@ -37,7 +37,7 @@ export async function importReadiness(deps = {}) {
         external: { state, provider: CONFIG.memoryProvider, model: CONFIG.memoryModel ?? null },
         opencode: { available: opencode.available, models: opencode.models ?? [] },
         piReader,
-        claudeCode: claudeReadiness(deps.claudeRoot?.() ?? defaultClaudeSourcePath()),
+        claudeCode: claudeReadiness(deps.claudeRoot?.() ?? defaultClaudeSourcePath(CONFIG.claudeConfigDir)),
     };
 }
 function claudeReadiness(defaultRoot) {

package/dist/importer/import-sessions.js

@@ -136,7 +136,7 @@ export function validateSessionListRequest(value) {
 /** One page of session metadata; no prompts, replies, or tool data. */
 export async function listImportSessions(request, options) {
     const source = request.sourceToken === undefined
-        ? validateImportSource(options.host, defaultImportSourcePath(options.host))
+        ? validateImportSource(options.host, defaultImportSourcePath(options.host, (await import("../config.js")).CONFIG.claudeConfigDir))
         : null;
     const token = source?.sourceToken ?? request.sourceToken;
     const identity = readImportSourceToken(token, options.host);

package/dist/importer/import-sources.d.ts

@@ -22,13 +22,9 @@ export declare function readImportSourceToken(token: unknown, host: ImportHost):
 export declare function importSourceKey(identity: ImportSourceIdentity): string;
 /** Refuse a source whose path now names another file, such as a swapped-in symlink. */
 export declare function assertImportSourceUnchanged(identity: ImportSourceIdentity): void;
-/**
- * Same folder as `defaultClaudeProjectsRoot()` in `claude-reader.ts`. That
- * module loads the storage engine, so this light module keeps its own copy;
- * `tests/import-sources.test.ts` checks that the two agree.
- */
-export declare function defaultClaudeSourcePath(): string;
-export declare function defaultImportSourcePath(host: ImportHost): string;
+/** The Claude projects folder; `claudeConfigDir` is `CONFIG.claudeConfigDir`. */
+export declare function defaultClaudeSourcePath(claudeConfigDir?: string): string;
+export declare function defaultImportSourcePath(host: ImportHost, claudeConfigDir?: string): string;
 export interface ValidatedImportSource {
     kind: ImportSourceKind;
     displayPath: string;
@@ -45,7 +41,7 @@ export interface BrowseEntry {
  * One folder at a time, with no recursion: subfolders and files the host can
  * import. A Claude Code source is always a folder, so it lists folders only. Symlinked entries are hidden. Only offered on loopback binds.
  */
-export declare function browseImportSources(host: ImportHost, path?: unknown): {
+export declare function browseImportSources(host: ImportHost, path?: unknown, claudeConfigDir?: string): {
     path: string;
     parent: string | null;
     entries: BrowseEntry[];

package/dist/importer/import-sources.js

@@ -2,6 +2,7 @@ import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
 import { closeSync, existsSync, openSync, readdirSync, readSync, realpathSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
+import { claudeProjectsRoot } from "../services/claude-folder.js";
 import { DEFAULT_PI_SESSION_ROOT, readPiSessionHeader } from "./discovery.js";
 import { DEFAULT_OPENCODE_DB } from "./opencode-reader.js";
 export class ImportSourceError extends Error {
@@ -79,19 +80,15 @@ function isSqliteFile(path) {
         closeSync(fd);
     }
 }
-/**
- * Same folder as `defaultClaudeProjectsRoot()` in `claude-reader.ts`. That
- * module loads the storage engine, so this light module keeps its own copy;
- * `tests/import-sources.test.ts` checks that the two agree.
- */
-export function defaultClaudeSourcePath() {
-    return join(homedir(), ".claude", "projects");
+/** The Claude projects folder; `claudeConfigDir` is `CONFIG.claudeConfigDir`. */
+export function defaultClaudeSourcePath(claudeConfigDir) {
+    return claudeProjectsRoot(claudeConfigDir);
 }
-export function defaultImportSourcePath(host) {
+export function defaultImportSourcePath(host, claudeConfigDir) {
     if (host === "pi")
         return DEFAULT_PI_SESSION_ROOT;
     if (host === "claude-code")
-        return defaultClaudeSourcePath();
+        return defaultClaudeSourcePath(claudeConfigDir);
     return DEFAULT_OPENCODE_DB;
 }
 /** Check an absolute path's kind and format; never returns file contents. */
@@ -130,10 +127,12 @@ const BROWSE_LIMIT = 500;
  * One folder at a time, with no recursion: subfolders and files the host can
  * import. A Claude Code source is always a folder, so it lists folders only. Symlinked entries are hidden. Only offered on loopback binds.
  */
-export function browseImportSources(host, path) {
+export function browseImportSources(host, path, claudeConfigDir) {
     let start = path;
     if (start === undefined || start === null || start === "") {
-        const preferred = host === "opencode" ? dirname(DEFAULT_OPENCODE_DB) : defaultImportSourcePath(host);
+        const preferred = host === "opencode"
+            ? dirname(DEFAULT_OPENCODE_DB)
+            : defaultImportSourcePath(host, claudeConfigDir);
         start = existsSync(preferred) ? preferred : homedir();
     }
     const folder = checkedPath(start);

package/dist/importer/run-import.js

@@ -150,7 +150,17 @@ async function runUntracked(host, args, run) {
     };
     if (host === "claude-code") {
         const { importClaudeHistory } = await import("./claude-import.js");
-        return importClaudeHistory(deps, filters);
+        if (args.source)
+            return importClaudeHistory(deps, filters);
+        // Without --root, read the folder live capture uses.
+        const [{ CONFIG }, { claudeProjectsRoot }] = await Promise.all([
+            import("../config.js"),
+            import("../services/claude-folder.js"),
+        ]);
+        return importClaudeHistory(deps, {
+            ...filters,
+            root: claudeProjectsRoot(CONFIG.claudeConfigDir),
+        });
     }
     const { importPiHistory } = await import("./importer.js");
     const { loadPiSessionForImport } = await import("./session-loader.js");

package/dist/services/claude-folder.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The Claude Code folder, in one place for every caller: the `claudeConfigDir`
+ * setting, then `CLAUDE_CONFIG_DIR`, then `~/.claude`. Pure on purpose: callers
+ * pass `CONFIG.claudeConfigDir`, because many tests stub `src/config.js`.
+ * It sits in services so the settings snapshot can use it too.
+ */
+export type ClaudeFolderSource = "setting" | "env" | "default";
+export interface ClaudeFolder {
+    folder: string;
+    source: ClaudeFolderSource;
+}
+/** Empty, an absolute path, or `~/...`. A relative path would depend on the web app's working directory. */
+export declare function isValidClaudeConfigDir(value: unknown): value is string;
+export declare function resolveClaudeFolder(configured: string | undefined, env?: string | undefined, home?: string): ClaudeFolder;
+/** `<Claude folder>/projects`, where Claude Code writes its transcripts. */
+export declare function claudeProjectsRoot(configured: string | undefined, env?: string, home?: string): string;