om-memory-system 3.2.0-next.9 → 3.3.0-next.18

package/dist/cli/web-command.js

@@ -0,0 +1,72 @@
+import { homedir } from "node:os";
+/** Run the standalone web app or manage its per-user login item. */
+export async function runWebCommand(args, options = {}, online) {
+    const home = options.home ?? homedir();
+    const config = await import("../config.js");
+    config.initConfig(home);
+    const { installWebAutostart, removeWebAutostart, webAutostartStatus } = await import("../services/web-autostart.js");
+    const [action, ...rest] = args;
+    if (rest.length ||
+        (action && !["install", "uninstall", "status", "--login-item"].includes(action))) {
+        console.error("Usage: om-memory-system web [install|uninstall|status]");
+        return 1;
+    }
+    if (action === "install" && !config.CONFIG.webServerEnabled) {
+        console.error("OMMS web server is disabled (webServerEnabled is false)");
+        return 1;
+    }
+    if (action === "install" || action === "uninstall") {
+        const { readGlobalConfigRevision, writeGlobalConfigKeys } = await import("../services/global-config-writer.js");
+        await writeGlobalConfigKeys({ webServerAutoStart: action === "install" }, readGlobalConfigRevision());
+        config.initConfig(home);
+        const result = action === "install"
+            ? installWebAutostart({ ...options, start: true })
+            : removeWebAutostart({ ...options, start: true });
+        console.log(`OMMS login item: ${result.state}`);
+        return action === "install" && result.state !== "installed" ? 1 : 0;
+    }
+    if (action === "status") {
+        const status = webAutostartStatus(options);
+        const check = online ??
+            (async () => {
+                const { WebServer } = await import("../services/web-server.js");
+                return new WebServer({
+                    port: config.CONFIG.webServerPort,
+                    host: config.CONFIG.webServerHost,
+                    enabled: true,
+                    apiToken: config.CONFIG.webServerApiToken,
+                }).checkServerAvailable();
+            });
+        console.log(JSON.stringify({ setting: config.CONFIG.webServerAutoStart, item: status, online: await check() }, null, 2));
+        return 0;
+    }
+    if (!config.CONFIG.webServerEnabled) {
+        console.error("OMMS web server is disabled (webServerEnabled is false)");
+        return 1;
+    }
+    const { WebAuth } = await import("../services/web-auth.js");
+    const { startWebServer } = await import("../services/web-server.js");
+    const server = await startWebServer({
+        directory: home,
+        port: config.CONFIG.webServerPort,
+        host: config.CONFIG.webServerHost,
+        enabled: true,
+        apiToken: config.CONFIG.webServerApiToken,
+        auth: new WebAuth({
+            password: config.CONFIG.webServerAuthPassword,
+            username: config.CONFIG.webServerAuthUsername,
+        }),
+    });
+    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);
+    const stop = () => {
+        clearInterval(keeper);
+        process.off("SIGINT", stop);
+        process.off("SIGTERM", stop);
+        void server.stop();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    return 0;
+}

package/dist/config.d.ts

@@ -38,6 +38,14 @@ interface OmmsConfig {
     piProvider?: string;
     piModel?: string;
     aiSessionRetentionDays?: number;
+    /** Write full capture prompts and replies to ~/.omms/traces. Global config only. */
+    captureTrace?: boolean;
+    captureTraceRetentionDays?: number;
+    captureAttemptRetentionDays?: number;
+    autoBackfill?: boolean;
+    opencodeBackfillModel?: string;
+    piBackfillModel?: string;
+    webServerAutoStart?: boolean;
     webServerEnabled?: boolean;
     webServerPort?: number;
     webServerHost?: string;
@@ -85,6 +93,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 \"provider/model\"\n  // \"opencodeBackfillModel\": \"inherit\", // or \"provider/model\"\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-Opencode-Mem-Token.\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.\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\"\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  // Maximum number of times to retry capturing a prompt if it fails (due to network, API errors, etc.)\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  // 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;
 export declare function normalizeAutoCleanupRetentionDays(value: number): number;
 declare function buildConfig(fileConfig: OmmsConfig): {
@@ -119,6 +128,13 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     piModel: string | undefined;
     autoCaptureProviderStatus: import("./config.js").AutoCaptureProviderStatus;
     aiSessionRetentionDays: number;
+    captureTrace: boolean;
+    captureTraceRetentionDays: number;
+    captureAttemptRetentionDays: number;
+    autoBackfill: boolean;
+    opencodeBackfillModel: string;
+    piBackfillModel: string;
+    webServerAutoStart: boolean;
     webServerEnabled: boolean;
     webServerPort: number;
     webServerHost: string;
@@ -169,6 +185,9 @@ declare function buildConfig(fileConfig: OmmsConfig): {
         injectOn: "first" | "always";
     };
 };
+export declare function getGlobalConfigSourcePath(): string | undefined;
+export declare function getGlobalConfigWritePath(): string;
+export declare function validateGlobalConfig(value: unknown): void;
 export declare let CONFIG: {
     storagePath: string;
     userEmailOverride: string | undefined;
@@ -201,6 +220,13 @@ export declare let CONFIG: {
     piModel: string | undefined;
     autoCaptureProviderStatus: import("./config.js").AutoCaptureProviderStatus;
     aiSessionRetentionDays: number;
+    captureTrace: boolean;
+    captureTraceRetentionDays: number;
+    captureAttemptRetentionDays: number;
+    autoBackfill: boolean;
+    opencodeBackfillModel: string;
+    piBackfillModel: string;
+    webServerAutoStart: boolean;
     webServerEnabled: boolean;
     webServerPort: number;
     webServerHost: string;
@@ -255,7 +281,10 @@ type RuntimeConfig = ReturnType<typeof buildConfig>;
 export { getAutoCaptureProviderStatus, type AutoCaptureProviderStatus, } from "./services/ai/live-model-choice.js";
 export { isPlaceholderApiKey };
 export declare function hasAutoCaptureProviderConfig(config?: RuntimeConfig): boolean;
-export declare function initConfig(directory: string): void;
+export declare function refreshConfigIfChanged(directory: string): void;
+export declare function initConfig(directory: string, options?: {
+    strict?: boolean;
+}): void;
 /**
  * initConfig plus the one-time legacy store migration (decision D13).
  *

package/dist/config.js

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, writeFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 import { stripJsoncComments } from "./services/jsonc.js";
@@ -6,6 +6,7 @@ import { log } from "./services/logger.js";
 import { resolveSecretValue } from "./services/secret-resolver.js";
 import { isPlaceholderApiKey } from "./services/ai/api-key-placeholder.js";
 import { getAutoCaptureProviderStatus } from "./services/ai/live-model-choice.js";
+import { parseBackfillModel } from "./importer/backfill-model.js";
 import { resolveDefaultStoragePath, runLegacyStoreMigration, legacyMigrationPaths, } from "./services/legacy-migration.js";
 const OMMS_CONFIG_DIR = join(homedir(), ".config", "omms");
 const DATA_DIR = join(homedir(), ".omms");
@@ -48,6 +49,13 @@ const DEFAULTS = {
     autoCaptureMaxRetries: 3,
     autoCaptureMaxContextBytes: 131072,
     aiSessionRetentionDays: 7,
+    captureTrace: false,
+    captureTraceRetentionDays: 7,
+    captureAttemptRetentionDays: 30,
+    autoBackfill: true,
+    opencodeBackfillModel: "inherit",
+    piBackfillModel: "inherit",
+    webServerAutoStart: true,
     webServerEnabled: true,
     webServerPort: 4747,
     webServerHost: "127.0.0.1",
@@ -108,8 +116,9 @@ function expandPath(path) {
  * Load the first config file that exists, in priority order. A file that
  * exists but cannot be read or parsed is not skipped: falling through would let
  * a lower-priority (legacy) file silently supply settings such as storagePath.
+ * `strict` (live reload) throws instead, so running hosts keep their settings.
  */
-function loadConfigFromPaths(paths) {
+function loadConfigFromPaths(paths, strict = false) {
     const path = paths.find((candidate) => existsSync(candidate));
     if (!path)
         return {};
@@ -119,6 +128,9 @@ function loadConfigFromPaths(paths) {
         return JSON.parse(json);
     }
     catch (error) {
+        // The parser's message can quote file content, so a reload names the file only.
+        if (strict)
+            throw new Error(`Config file cannot be parsed: ${path}`, { cause: error });
         log("Config file is invalid; using defaults instead of lower-priority files", {
             path,
             error: String(error),
@@ -140,7 +152,7 @@ function assertProjectRemoteProviderConfigIsSafe(projectConfig) {
             `Move them to the global config at ${CONFIG_FILES[0]}.`);
     }
 }
-const CONFIG_TEMPLATE = `{
+export const CONFIG_TEMPLATE = `{
   // ============================================
   // omms (Opinionated Modular Memory System) Configuration
   // ============================================
@@ -184,6 +196,13 @@ const CONFIG_TEMPLATE = `{
   // Web Server Settings
   // ============================================
   
+  // Start a background import of past chats on each host's next start.
+  "autoBackfill": true,
+  // "piBackfillModel": "inherit", // or "provider/model"
+  // "opencodeBackfillModel": "inherit", // or "provider/model"
+
+  // Register the web app to start when you log in.
+  "webServerAutoStart": true,
   // Enable web UI for managing memories (accessible at http://localhost:4747)
   "webServerEnabled": true,
   
@@ -352,6 +371,17 @@ const CONFIG_TEMPLATE = `{
   // Days to keep AI session history before cleanup
   "aiSessionRetentionDays": 7,
 
+  // Capture diagnostics: every capture attempt always writes one metadata line
+  // (model, stop reason, sizes, outcome) to ~/.omms/omms.log, with no
+  // conversation text. Set captureTrace to true to also write each attempt's
+  // prompt and raw reply to ~/.omms/traces/ for debugging. Traces can contain
+  // conversation content: <private> text and common API key formats are
+  // redacted, files are readable only by you, and they are deleted after
+  // captureTraceRetentionDays. Only this global file can turn tracing on.
+  // "captureTrace": false,
+  // "captureTraceRetentionDays": 7,
+  // "captureAttemptRetentionDays": 30,
+
   // Temperature for AI API requests (set to false to omit parameter for models that don't support it)
   // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter
   // Set to false and add "memoryTemperature": false in config when using such models
@@ -530,6 +560,13 @@ function buildConfig(fileConfig) {
         getEmbeddingDimensions(fileConfig.embeddingModel ?? DEFAULTS.embeddingModel);
     const autoCaptureMaxContextBytes = normalizeAutoCaptureMaxContextBytes(fileConfig.autoCaptureMaxContextBytes ?? DEFAULTS.autoCaptureMaxContextBytes);
     const userProfileAutoCleanupInterval = fileConfig.userProfileAutoCleanupInterval ?? DEFAULTS.userProfileAutoCleanupInterval;
+    parseBackfillModel(fileConfig, "pi");
+    parseBackfillModel(fileConfig, "opencode");
+    for (const key of ["autoBackfill", "webServerAutoStart"]) {
+        if (fileConfig[key] !== undefined && typeof fileConfig[key] !== "boolean") {
+            throw new Error(`Invalid ${key} config`);
+        }
+    }
     if (!Number.isInteger(embeddingDimensions) ||
         embeddingDimensions <= 0 ||
         embeddingDimensions > 65536) {
@@ -580,6 +617,13 @@ function buildConfig(fileConfig) {
             memoryApiKey,
         }),
         aiSessionRetentionDays: fileConfig.aiSessionRetentionDays ?? DEFAULTS.aiSessionRetentionDays,
+        captureTrace: fileConfig.captureTrace === true,
+        captureTraceRetentionDays: Math.max(1, Math.floor(fileConfig.captureTraceRetentionDays ?? DEFAULTS.captureTraceRetentionDays)),
+        captureAttemptRetentionDays: normalizeAutoCleanupRetentionDays(fileConfig.captureAttemptRetentionDays ?? DEFAULTS.captureAttemptRetentionDays),
+        autoBackfill: fileConfig.autoBackfill ?? DEFAULTS.autoBackfill,
+        opencodeBackfillModel: fileConfig.opencodeBackfillModel ?? DEFAULTS.opencodeBackfillModel,
+        piBackfillModel: fileConfig.piBackfillModel ?? DEFAULTS.piBackfillModel,
+        webServerAutoStart: fileConfig.webServerAutoStart ?? DEFAULTS.webServerAutoStart,
         webServerEnabled: fileConfig.webServerEnabled ?? DEFAULTS.webServerEnabled,
         webServerPort: fileConfig.webServerPort ?? DEFAULTS.webServerPort,
         webServerHost: fileConfig.webServerHost ?? DEFAULTS.webServerHost,
@@ -638,6 +682,21 @@ function buildConfig(fileConfig) {
         },
     };
 }
+export function getGlobalConfigSourcePath() {
+    return CONFIG_FILES.find((candidate) => existsSync(candidate));
+}
+export function getGlobalConfigWritePath() {
+    const source = getGlobalConfigSourcePath();
+    return source && !LEGACY_CONFIG_FILES.includes(source)
+        ? source
+        : join(OMMS_CONFIG_DIR, "omms.jsonc");
+}
+export function validateGlobalConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Global config must be an object");
+    }
+    buildConfig(value);
+}
 const _globalFileConfig = loadConfigFromPaths(CONFIG_FILES);
 let lastFileConfig = _globalFileConfig;
 export let CONFIG = buildConfig(_globalFileConfig);
@@ -646,23 +705,86 @@ export { isPlaceholderApiKey };
 export function hasAutoCaptureProviderConfig(config = CONFIG) {
     return getAutoCaptureProviderStatus(config).ready;
 }
-export function initConfig(directory) {
-    // omms project overrides win; the legacy opencode-mem file is still read.
-    const projectPaths = [
+function projectConfigPaths(directory) {
+    return [
         join(directory, ".opencode", "omms.jsonc"),
         join(directory, ".opencode", "omms.json"),
         join(directory, ".opencode", "opencode-mem.jsonc"),
         join(directory, ".opencode", "opencode-mem.json"),
     ];
-    const globalConfig = loadConfigFromPaths(CONFIG_FILES);
-    const projectConfig = loadConfigFromPaths(projectPaths);
+}
+function configSignature(directory) {
+    return [...CONFIG_FILES, ...projectConfigPaths(directory)]
+        .filter((path) => existsSync(path))
+        .map((path) => {
+        try {
+            const stat = statSync(path);
+            return `${path}:${stat.mtimeMs}:${stat.size}`;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return `${path}:missing`;
+            throw error;
+        }
+    })
+        .join("|");
+}
+let lastConfigDirectory;
+let lastConfigSignature;
+/** Directory and signature of the last reload that failed. */
+let lastFailedConfig;
+export function refreshConfigIfChanged(directory) {
+    // Both hosts initialise their config at startup. Direct callers that have
+    // not initialised it keep their in-memory settings untouched.
+    if (lastConfigDirectory === undefined)
+        return;
+    let attempt;
+    try {
+        const signature = configSignature(directory);
+        if (directory === lastConfigDirectory && signature === lastConfigSignature)
+            return;
+        attempt = `${directory}\0${signature}`;
+        if (attempt === lastFailedConfig)
+            return;
+        initConfig(directory, { strict: true });
+        lastFailedConfig = undefined;
+    }
+    catch (error) {
+        // A bad hand edit must not stop capture: keep the last good settings, and
+        // skip this exact file state until it changes, instead of re-reading it on
+        // every unit. The last good directory and signature stay as they were.
+        log("Config reload failed; keeping the previous settings", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        lastFailedConfig = attempt;
+    }
+}
+export function initConfig(directory, options = {}) {
+    // omms project overrides win; the legacy opencode-mem file is still read.
+    const globalConfig = loadConfigFromPaths(CONFIG_FILES, options.strict);
+    const projectConfig = loadConfigFromPaths(projectConfigPaths(directory), options.strict);
     assertProjectRemoteProviderConfigIsSafe(projectConfig);
     const projectOverrides = { ...projectConfig };
     delete projectOverrides.autoCleanupEnabled;
     delete projectOverrides.autoCleanupRetentionDays;
+    // A checked-in project file must not start recording conversations; it may
+    // only turn tracing off for its project.
+    if (projectOverrides.captureTrace === true) {
+        log("Project config cannot turn on captureTrace; the value was ignored", { directory });
+        delete projectOverrides.captureTrace;
+    }
+    delete projectOverrides.captureTraceRetentionDays;
+    delete projectOverrides.autoBackfill;
+    delete projectOverrides.opencodeBackfillModel;
+    delete projectOverrides.piBackfillModel;
+    delete projectOverrides.webServerAutoStart;
+    delete projectOverrides.webServerEnabled;
     const merged = { ...globalConfig, ...projectOverrides };
+    const nextConfig = buildConfig(merged);
     lastFileConfig = merged;
-    CONFIG = buildConfig(merged);
+    CONFIG = nextConfig;
+    lastConfigDirectory = directory;
+    lastConfigSignature = configSignature(directory);
 }
 /**
  * Rebuild CONFIG from the last loaded file config. Used after the legacy

package/dist/core/capture-context.js

@@ -4,7 +4,7 @@ const DEFAULT_AUTO_CAPTURE_MAX_CONTEXT_BYTES = 131072;
 const CONTEXT_TRUNCATION_MARKER = "\n[... truncated to autoCaptureMaxContextBytes ...]\n";
 const SUMMARY_REQUEST_OVERHEAD_BYTES = 1024;
 const SUMMARY_OUTPUT_RESERVE_BYTES = 16384;
-const SUMMARY_ANALYSIS_SUFFIX = 'Analyze this conversation. If it contains technical work (code, bugs, features, decisions), create a concise summary and relevant tags. If it\'s non-technical (greetings, casual chat, incomplete requests), return type="skip" with empty summary.';
+const SUMMARY_ANALYSIS_SUFFIX = 'Analyze this conversation. If it contains technical work (code, bugs, features, decisions), create a concise summary and relevant tags. If it\'s non-technical (greetings, casual chat, incomplete requests), set "type" to "skip" with an empty "summary".';
 function fitTextResponses(textResponses, maxBytes) {
     if (textResponses.length === 0 || maxBytes <= 0)
         return "";

package/dist/core/capture.d.ts

@@ -12,4 +12,8 @@ export type CaptureResult = {
     status: "skipped";
     type?: string;
 };
+/**
+ * Run one capture attempt and write exactly one diagnostics record for it,
+ * whether it is saved, skipped, or fails.
+ */
 export declare function captureConversation(workUnit: CaptureWorkUnit, provider: CaptureSummaryProvider): Promise<CaptureResult>;

package/dist/core/capture.js

@@ -1,3 +1,5 @@
+import { CONFIG, refreshConfigIfChanged } from "../config.js";
+import { buildCaptureAttemptRecord, emitCaptureAttempt } from "../services/capture-diagnostics.js";
 import { memoryClient } from "../services/client.js";
 import { getTags } from "../services/tags.js";
 import { buildMarkdownContext, getAutoCaptureMarkdownBudget } from "./capture-context.js";
@@ -15,7 +17,30 @@ async function getLatestProjectMemory(containerTag) {
         return null;
     }
 }
+/**
+ * Run one capture attempt and write exactly one diagnostics record for it,
+ * whether it is saved, skipped, or fails.
+ */
 export async function captureConversation(workUnit, provider) {
+    refreshConfigIfChanged(workUnit.projectDirectory);
+    const diagnostics = {};
+    const startedAt = Date.now();
+    let outcome = "failed";
+    try {
+        const result = await runCapture(workUnit, provider, diagnostics);
+        outcome = result.status === "captured" ? "saved" : "skipped";
+        return result;
+    }
+    finally {
+        const record = buildCaptureAttemptRecord({
+            host: workUnit.host,
+            sourceType: workUnit.sourceType,
+            sessionId: workUnit.hostSessionId,
+        }, diagnostics, outcome, Date.now() - startedAt);
+        emitCaptureAttempt(record, diagnostics, CONFIG);
+    }
+}
+async function runCapture(workUnit, provider, diagnostics) {
     const tags = getTags(workUnit.projectDirectory);
     const latestMemory = await getLatestProjectMemory(tags.project.tag);
     const context = buildMarkdownContext(workUnit.userPrompt, workUnit.textResponses, workUnit.toolCalls, latestMemory, getAutoCaptureMarkdownBudget());
@@ -27,9 +52,11 @@ export async function captureConversation(workUnit, provider) {
             projectDirectory: workUnit.projectDirectory,
             userPrompt: workUnit.userPrompt,
             prompt: workUnit.prompt,
+            diagnostics,
         });
     }
     catch (error) {
+        diagnostics.failureReason ??= "call-error";
         const message = error instanceof Error ? error.message : String(error);
         throw new Error(`Summary generation failed: ${message}`, { cause: error });
     }
@@ -40,6 +67,8 @@ export async function captureConversation(workUnit, provider) {
         ? `${summaryResult.summary}\n\nTags: ${summaryResult.tags.join(", ")}`
         : summaryResult.summary;
     const source = workUnit.sourceType === "history-import" ? "import" : "auto-capture";
+    // Anything that goes wrong from here on is a storage failure, thrown or reported.
+    diagnostics.failureReason = "persist-error";
     const result = await memoryClient.addMemory(summaryWithTags, tags.project.tag, {
         source,
         type: summaryResult.type,
@@ -64,5 +93,6 @@ export async function captureConversation(workUnit, provider) {
     if (!result.success) {
         throw new Error(`Memory persistence failed: ${result.error || "database write failed"}`);
     }
+    diagnostics.failureReason = undefined;
     return { status: "captured", memoryId: result.id };
 }

package/dist/core/extraction.d.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { CaptureSummary } from "./host.js";
+import type { CaptureFailureReason, CaptureSummary } from "./host.js";
 /**
  * Shared structured-extraction contract for automatic capture.
  *
@@ -38,6 +38,13 @@ export declare const captureSummaryToolSchema: {
     };
     required: string[];
 };
+/**
+ * Reply-format instruction for paths that get plain text back (the Pi model
+ * bridge). Structured-output and tool-call paths enforce the shape themselves,
+ * so without this the model only sees the Markdown layout of the summary field
+ * and `type="skip"`, and tends to answer in that form instead of JSON.
+ */
+export declare function buildCaptureReplyInstruction(): string;
 export declare function buildCaptureSystemPrompt(languageName: string): string;
 /** Upper bound for LLM-inferred preference confidence (0–1 scale). */
 export declare const USER_PROFILE_LLM_CONFIDENCE_MAX = 1;
@@ -78,3 +85,18 @@ export declare function extractJsonObject(raw: string): unknown;
  * blocks and surrounding prose. Returns null when no valid payload is present.
  */
 export declare function parseCaptureSummary(raw: string): CaptureSummary | null;
+/**
+ * Map provider-specific stop reasons onto one vocabulary so a length limit
+ * reads as `length` on every extraction path. Other values pass through in
+ * lower case.
+ */
+export declare function normalizeStopReason(stopReason: string | null | undefined): string | undefined;
+/**
+ * Explain why a reply is not a usable capture summary. Returns null when the
+ * reply parses (including a skip). Codes are checked in the spec's order, so a
+ * cut-off reply reads as `truncated` rather than `invalid-json`.
+ */
+export declare function classifyCaptureReply(reply: {
+    text: string;
+    stopReason?: string | null;
+}): CaptureFailureReason | null;

package/dist/core/extraction.js

@@ -40,6 +40,18 @@ export const captureSummaryToolSchema = {
     },
     required: ["summary", "type", "tags"],
 };
+/**
+ * Reply-format instruction for paths that get plain text back (the Pi model
+ * bridge). Structured-output and tool-call paths enforce the shape themselves,
+ * so without this the model only sees the Markdown layout of the summary field
+ * and `type="skip"`, and tends to answer in that form instead of JSON.
+ */
+export function buildCaptureReplyInstruction() {
+    return `Reply with only one JSON object and nothing else: no prose, no code fence. It must match this JSON schema:
+${JSON.stringify(captureSummaryToolSchema)}
+Put the Markdown summary (## Request / ## Outcome) inside the "summary" string.
+For a non-technical conversation reply exactly: {"type":"skip","summary":"","tags":[]}`;
+}
 export function buildCaptureSystemPrompt(languageName) {
     return `You are a technical memory recorder for a software development project.
 
@@ -143,3 +155,32 @@ export function parseCaptureSummary(raw) {
         tags: parsed.data.tags.map((tag) => tag.toLowerCase().trim()).filter(Boolean),
     };
 }
+const LENGTH_STOP_REASONS = new Set(["length", "max_tokens", "max_output_tokens"]);
+/**
+ * Map provider-specific stop reasons onto one vocabulary so a length limit
+ * reads as `length` on every extraction path. Other values pass through in
+ * lower case.
+ */
+export function normalizeStopReason(stopReason) {
+    if (!stopReason)
+        return undefined;
+    const lower = stopReason.toLowerCase();
+    return LENGTH_STOP_REASONS.has(lower) ? "length" : lower;
+}
+/**
+ * Explain why a reply is not a usable capture summary. Returns null when the
+ * reply parses (including a skip). Codes are checked in the spec's order, so a
+ * cut-off reply reads as `truncated` rather than `invalid-json`.
+ */
+export function classifyCaptureReply(reply) {
+    if (parseCaptureSummary(reply.text))
+        return null;
+    if (reply.text.trim().length === 0)
+        return "empty-text";
+    if (normalizeStopReason(reply.stopReason) === "length")
+        return "truncated";
+    const json = extractJsonObject(reply.text);
+    if (json === null || typeof json !== "object" || Array.isArray(json))
+        return "invalid-json";
+    return "schema-mismatch";
+}

package/dist/core/host.d.ts

@@ -19,12 +19,35 @@ export interface CaptureSummary {
     type: string;
     tags: string[];
 }
+export type CaptureAttemptOutcome = "saved" | "skipped" | "failed";
+/** Fixed failure codes, in the order classification checks them. */
+export declare const CAPTURE_FAILURE_REASONS: readonly ["call-error", "empty-text", "truncated", "invalid-json", "schema-mismatch", "persist-error"];
+export type CaptureFailureReason = (typeof CAPTURE_FAILURE_REASONS)[number];
+export type CaptureExtractionPath = "host-model" | "external-api";
+/**
+ * Filled in by the extraction path during one capture attempt. The capture
+ * pipeline owns the object and emits it once the outcome is known. Fields a
+ * path cannot observe stay undefined. The prompt and reply fields are only
+ * ever written to the opt-in trace file, never to the log.
+ */
+export interface CaptureAttemptDiagnostics {
+    path?: CaptureExtractionPath;
+    provider?: string;
+    model?: string;
+    stopReason?: string;
+    blockTypes?: string[];
+    systemPrompt?: string;
+    userPrompt?: string;
+    rawReply?: string;
+    failureReason?: CaptureFailureReason;
+}
 export interface CaptureSummaryRequest {
     context: string;
     sessionId: string;
     projectDirectory: string;
     userPrompt: string;
     prompt?: CapturePromptContext;
+    diagnostics?: CaptureAttemptDiagnostics;
 }
 export interface CaptureSummaryProvider {
     summarize(request: CaptureSummaryRequest): Promise<CaptureSummary | null>;

package/dist/core/host.js

@@ -1 +1,9 @@
-export {};
+/** Fixed failure codes, in the order classification checks them. */
+export const CAPTURE_FAILURE_REASONS = [
+    "call-error",
+    "empty-text",
+    "truncated",
+    "invalid-json",
+    "schema-mismatch",
+    "persist-error",
+];

package/dist/core/profile-analysis.js

@@ -10,7 +10,15 @@ CRITICAL: Detect the language used by the user in their prompts. You MUST output
 
 CRITICAL: All JSON string values MUST escape double quotes with backslash. Do NOT use unescaped quotation marks inside string values.
 
-Respond with a single JSON object matching the update_user_profile contract.`;
+Respond with one JSON object. It must have these required fields:
+{
+  "preferences": [{ "category": "string", "description": "string", "confidence": 0.8, "evidence": ["string"] }],
+  "patterns": [{ "category": "string", "description": "string" }],
+  "workflows": [{ "description": "string", "steps": ["string"] }]
+}
+Use an empty array for a field with no findings. Confidence must be a number from 0 to 1.
+If you include "validations", each entry needs a numeric "index", a string "reason", and a "verdict" of "confirmed", "contradicted", "no_evidence", "inaccurate", or "oversimplified".
+Return JSON only, without Markdown or other text.`;
 }
 /** Analyse prompts with a host-neutral model and merge the validated profile. */
 export async function analyzeProfile(model, context, existingProfile, timeoutMs = 120000) {