om-memory-system 3.7.0-next.51 → 3.7.0-next.52

package/dist/adapters/opencode/package-skills.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The package's `skills` folder: the nearest parent folder whose
+ * `package.json` names om-memory-system. Walking up also works when a host
+ * bundles the plugin into one file at another depth.
+ */
+export declare function packageSkillsFolder(moduleUrl?: string): string;
+/**
+ * V1: add the package's skills folder to OpenCode's skill paths once. The V1
+ * SDK `Config` type has no `skills` key, although OpenCode reads it.
+ */
+export declare function applySkillsPathConfig(config: object, folder?: string): void;
+/** V2: add the omms-memory skill to the plugin's skill list once. */
+export declare function addPackageSkill(editor: {
+    get(id: string): unknown;
+    add(skill: any): void;
+}, folder?: string): void;

package/dist/adapters/opencode/package-skills.js

@@ -0,0 +1,60 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log } from "../../services/logger.js";
+const SKILL_NAME = "omms-memory";
+/**
+ * The package's `skills` folder: the nearest parent folder whose
+ * `package.json` names om-memory-system. Walking up also works when a host
+ * bundles the plugin into one file at another depth.
+ */
+export function packageSkillsFolder(moduleUrl = import.meta.url) {
+    let folder = dirname(fileURLToPath(moduleUrl));
+    for (let depth = 0; depth < 8; depth++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(folder, "package.json"), "utf8"));
+            if (pkg.name === "om-memory-system")
+                return join(folder, "skills");
+        }
+        catch {
+            // No readable package.json here; keep walking up.
+        }
+        const parent = dirname(folder);
+        if (parent === folder)
+            break;
+        folder = parent;
+    }
+    return join(dirname(fileURLToPath(moduleUrl)), "..", "..", "..", "skills");
+}
+const defaultFolder = packageSkillsFolder();
+/**
+ * V1: add the package's skills folder to OpenCode's skill paths once. The V1
+ * SDK `Config` type has no `skills` key, although OpenCode reads it.
+ */
+export function applySkillsPathConfig(config, folder = defaultFolder) {
+    const cfg = config;
+    if (!existsSync(folder)) {
+        log("OMMS skills folder not found; the omms-memory skill is not loaded", { folder });
+        return;
+    }
+    const paths = cfg.skills?.paths ?? [];
+    if (paths.includes(folder))
+        return;
+    cfg.skills = { ...cfg.skills, paths: [...paths, folder] };
+}
+/** V2: add the omms-memory skill to the plugin's skill list once. */
+export function addPackageSkill(editor, folder = defaultFolder) {
+    if (editor.get(SKILL_NAME))
+        return;
+    const path = join(folder, SKILL_NAME, "SKILL.md");
+    let content;
+    try {
+        content = readFileSync(path, "utf8");
+    }
+    catch {
+        log("OMMS skill file not found; the omms-memory skill is not loaded", { path });
+        return;
+    }
+    const description = content.match(/^description: (.+)$/m)?.[1]?.trim();
+    editor.add({ id: SKILL_NAME, name: SKILL_NAME, description, path, content });
+}

package/dist/adapters/opencode/profile-learning.js

@@ -1,4 +1,5 @@
 import { getTags } from "../../services/tags.js";
+import { profileBackoff, recordProfileFailure } from "../../core/profile-backoff.js";
 import { log } from "../../services/logger.js";
 import { CONFIG, refreshConfigIfChanged } from "../../config.js";
 import { resolveOpencodeHostModel } from "../../services/ai/live-model-choice.js";
@@ -42,6 +43,8 @@ async function runAutomaticProfileCleanup(userId) {
 export async function performUserProfileLearning(ctx, directory) {
     if (isLearningRunning)
         return;
+    if (!profileBackoff.canRun())
+        return;
     refreshConfigIfChanged(directory);
     if (!CONFIG.autoCaptureProviderStatus || !CONFIG.autoCaptureProviderStatus.ready) {
         log("user-profile-learning: skipped (provider not ready)", {
@@ -51,13 +54,16 @@ export async function performUserProfileLearning(ctx, directory) {
     }
     isLearningRunning = true;
     try {
+        await userPromptManager.skipTrivialPromptsForLearning();
         const count = await userPromptManager.countUnanalyzedForUserLearning();
         const threshold = CONFIG.userProfileAnalysisInterval;
         log("user-profile-learning: check", { count, threshold });
         if (count < threshold) {
             return;
         }
-        const prompts = await userPromptManager.getPromptsForUserLearning(threshold);
+        const prompts = await userPromptManager.getPromptsForUserLearning(threshold, {
+            recentFirst: true,
+        });
         if (prompts.length === 0) {
             return;
         }
@@ -130,6 +136,7 @@ Rules:
         }
         const context = buildUserAnalysisContext(prompts, existingProfile, validationPrompt);
         const analysisResult = await analyzeUserProfile(context, existingProfile);
+        profileBackoff.recordSuccess();
         log("user-profile-learning: analyze done", { hasResult: !!analysisResult });
         if (!analysisResult) {
             await userPromptManager.markMultipleAsUserLearningCaptured(prompts.map((p) => p.id));
@@ -213,7 +220,7 @@ Rules:
         // would surface as an unhandled promise rejection. The caller (src/index.ts idle
         // timer) already wraps this call in its own try/catch, and issue #265 requires
         // provider errors to propagate instead of being masked, so rethrow after logging.
-        log("user-profile-learning: aborted", { error: String(error) });
+        recordProfileFailure("opencode", "user-profile-learning: aborted", error);
         throw error;
     }
     finally {

package/dist/adapters/pi/extension.js

@@ -2,6 +2,8 @@ import { Type } from "typebox";
 import { CONFIG, initConfigWithLegacyMigration, isConfigured, refreshConfigIfChanged, } from "../../config.js";
 import { pruneTraces } from "../../services/capture-diagnostics.js";
 import { executeMemoryOperation } from "../../core/memory-operations.js";
+import { memoryToolDescription } from "../../core/memory-tool-text.js";
+import { isTrivialPrompt } from "../../core/trivial-prompt.js";
 import { getLanguageName } from "../../services/language-detector.js";
 import { log } from "../../services/logger.js";
 import { memoryClient } from "../../services/client.js";
@@ -251,7 +253,9 @@ export default function ommsPiExtension(pi) {
                 notify: notify(ctx),
             });
             const settledPrompt = lastSettledUserPrompt(entries);
+            // Pi batches this session's prompts in memory, so they are recent by design.
             if (settledPrompt &&
+                !isTrivialPrompt(settledPrompt) &&
                 CONFIG.userProfileAnalysisInterval > 0 &&
                 !memoryClient.getEmbeddingInitError?.()) {
                 promptsSinceProfileAnalysis.push(settledPrompt);
@@ -295,7 +299,7 @@ export default function ommsPiExtension(pi) {
     pi.registerTool({
         name: "memory",
         label: "Memory",
-        description: `Manage and query project memory (MATCH USER LANGUAGE: ${getLanguageName(CONFIG.autoCaptureLanguage || "en")}). Use 'search' with technical keywords/tags, 'add' to store knowledge, 'profile' for preferences. Use migrate/list-shards/export/import when a project directory moves. Search/list scope: project or all-projects.`,
+        description: memoryToolDescription(getLanguageName(CONFIG.autoCaptureLanguage || "en")),
         parameters: Type.Object({
             mode: Type.Optional(Type.Union(MEMORY_TOOL_MODES.map((mode) => Type.Literal(mode)))),
             content: Type.Optional(Type.String()),

package/dist/adapters/pi/profile.js

@@ -1,5 +1,6 @@
 import { CONFIG, refreshConfigIfChanged } from "../../config.js";
 import { analyzeProfile, } from "../../core/profile-analysis.js";
+import { profileBackoff, recordProfileFailure } from "../../core/profile-backoff.js";
 import { log } from "../../services/logger.js";
 import { getTags } from "../../services/tags.js";
 function replyText(reply) {
@@ -46,6 +47,10 @@ export function createPiProfileAnalyzer(resolveModel, timeoutMs = 120000) {
 export async function performPiProfileLearning(input) {
     if (input.prompts.length === 0)
         return;
+    if (!profileBackoff.canRun()) {
+        log("pi profile learning: skipped (waiting after a failure)");
+        return;
+    }
     try {
         refreshConfigIfChanged(input.directory);
         const tags = getTags(input.directory);
@@ -83,6 +88,7 @@ export async function performPiProfileLearning(input) {
         else {
             await userProfileManager.createProfile(userId, tags.user.displayName || userId, tags.user.userName || userId, tags.user.userEmail || userId, analysis.raw, input.prompts.length);
         }
+        profileBackoff.recordSuccess();
         log("pi profile learning: profile updated", {
             userId,
             prompts: input.prompts.length,
@@ -98,7 +104,7 @@ export async function performPiProfileLearning(input) {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        log(`pi profile learning: aborted (${message})`);
+        recordProfileFailure("pi", "pi profile learning: aborted", error);
         if (CONFIG.showErrorToasts && input.notify) {
             const shortReason = message.length > 100 ? message.substring(0, 100) + "..." : message;
             await Promise.resolve(input.notify({

package/dist/cli/index.js

@@ -16,6 +16,7 @@ Commands:
   web                       Start the web app in the foreground
   web install|uninstall|status  Manage the web app login item
   memory <mode> [options]   Search, add, list, or forget memories (run with --help)
+  profile-catch-up          Analyse every prompt waiting for profile learning (run with --help)
   claude-hook <event>       Run a Claude Code hook (used by the Claude Code plugin)
 
 Options:
@@ -56,6 +57,10 @@ export async function runCli(argv) {
         const { runMemoryCommand } = await import("./memory-command.js");
         return await runMemoryCommand(argv.slice(1));
     }
+    if (argv[0] === "profile-catch-up") {
+        const { runProfileCatchUpCommand } = await import("./profile-catch-up-command.js");
+        return await runProfileCatchUpCommand(argv.slice(1));
+    }
     if (argv[0] === "web") {
         try {
             const { runWebCommand } = await import("./web-command.js");

package/dist/cli/profile-catch-up-command.d.ts

@@ -0,0 +1,2 @@
+/** `om-memory-system profile-catch-up`: the same run as the Settings page button. */
+export declare function runProfileCatchUpCommand(argv: string[], print?: (line: string) => void): Promise<number>;

package/dist/cli/profile-catch-up-command.js

@@ -0,0 +1,110 @@
+const usage = `Usage: om-memory-system profile-catch-up [options]
+
+Analyse every prompt that waits for profile learning, in batches of 50.
+Without --yes the command prints the counts and exits without model calls.
+
+Options:
+  --yes                     Start the run
+  --dry-run                 Print the counts only
+  --provider <type>         Provider type (default: saved memoryProvider)
+  --model <id>              Model id (default: saved memoryModel)
+  --api-url <url>           API URL (default: saved memoryApiUrl)
+  --api-key-env <NAME>      Read the API key from this environment variable
+  --help                    Show this help`;
+const VALUE_FLAGS = {
+    "--provider": "provider",
+    "--model": "model",
+    "--api-url": "apiUrl",
+    "--api-key-env": "apiKeyEnv",
+};
+function parseFlags(argv) {
+    const flags = { yes: false, dryRun: false, help: false, model: {} };
+    for (let index = 0; index < argv.length; index++) {
+        const [name, inline] = argv[index].split(/=(.*)/s, 2);
+        if (name === "--yes")
+            flags.yes = true;
+        else if (name === "--dry-run")
+            flags.dryRun = true;
+        else if (name === "--help" || name === "-h")
+            flags.help = true;
+        else if (name in VALUE_FLAGS) {
+            const value = inline ?? argv[++index];
+            if (!value)
+                throw new Error(`${name} needs a value`);
+            flags.model[VALUE_FLAGS[name]] = value;
+        }
+        else
+            throw new Error(`Unknown option ${name}; use --help`);
+    }
+    return flags;
+}
+/** `om-memory-system profile-catch-up`: the same run as the Settings page button. */
+export async function runProfileCatchUpCommand(argv, print = console.log) {
+    let flags;
+    try {
+        flags = parseFlags(argv);
+    }
+    catch (error) {
+        print(error instanceof Error ? error.message : String(error));
+        return 1;
+    }
+    if (flags.help) {
+        print(usage);
+        return 0;
+    }
+    const { CONFIG, initConfig, initConfigWithLegacyMigration } = await import("../config.js");
+    try {
+        if (flags.dryRun || !flags.yes)
+            initConfig(process.cwd());
+        else
+            initConfigWithLegacyMigration(process.cwd());
+        const { previewCatchUp, CATCH_UP_BATCH_SIZE } = await import("../importer/profile-catch-up.js");
+        const preview = await previewCatchUp();
+        print(`Waiting prompts: ${preview.waiting}`);
+        print(`Model calls: ${preview.calls} (batches of ${CATCH_UP_BATCH_SIZE})`);
+        if (flags.dryRun)
+            return 0;
+        if (!flags.yes) {
+            print("Run again with --yes to start.");
+            return 0;
+        }
+        const { getTags } = await import("../services/tags.js");
+        const user = getTags(process.cwd()).user;
+        if (!user.userEmail)
+            throw new Error("Profile learning needs a user email");
+        const { selectImportModel } = await import("../importer/model-selection.js");
+        const selected = selectImportModel(flags.model);
+        print(`Profile model: ${selected.provider}/${selected.modelId}`);
+        const { drainProfileBacklog } = await import("../importer/profile-backlog.js");
+        const { catchUpLeaseHooks } = await import("../importer/profile-catch-up.js");
+        const hooks = await catchUpLeaseHooks();
+        const report = await drainProfileBacklog({
+            beforeBatch: hooks.beforeBatch,
+            afterBatch: hooks.afterBatch,
+            user: { ...user, userEmail: user.userEmail },
+            model: selected.profile,
+            batchSize: CATCH_UP_BATCH_SIZE,
+            onProgress: ({ batchesBuilt, remaining }) => print(`Batches done: ${batchesBuilt}; prompts waiting: ${remaining}`),
+        }).finally(() => hooks.release().catch(() => { }));
+        print(`Batches done: ${report.batchesBuilt}; prompts waiting: ${report.remaining}`);
+        if (report.superseded) {
+            print("Stopped: a newer catch-up run took over.");
+            return 0;
+        }
+        if (report.reason) {
+            print(`Stopped: ${report.reason}. Run the command again to continue.`);
+            return 1;
+        }
+        return 0;
+    }
+    catch (error) {
+        const key = flags.model.apiKeyEnv ? process.env[flags.model.apiKeyEnv] : undefined;
+        let message = error instanceof Error ? error.message : String(error);
+        for (const secret of [key, CONFIG.memoryApiKey]) {
+            if (secret)
+                message = message.replaceAll(secret, "[redacted]");
+        }
+        print(`Profile catch-up failed: ${message}`);
+        return 1;
+    }
+}

package/dist/cli/web-command.js

@@ -117,16 +117,13 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
                 import("../services/auth-token.js"),
                 import("../services/package-version.js"),
             ]);
-            const apiToken = config.CONFIG.webServerApiToken;
             context = {
                 fetchFn: handover.fetch ?? fetch,
                 sleep: handover.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms))),
                 url,
                 port: config.CONFIG.webServerPort,
-                headers: {
-                    [AUTH_HEADER]: getOrCreateAuthToken(),
-                    ...(apiToken ? { authorization: `Bearer ${apiToken}` } : {}),
-                },
+                // The web app runs on this machine, so the local token file is enough.
+                headers: { [AUTH_HEADER]: getOrCreateAuthToken() },
                 version: handover.version ?? packageVersion(),
             };
             outcome = await negotiateOwner(context);
@@ -148,7 +145,6 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
                     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, url, online: await check() }, null, 2));
@@ -165,6 +161,7 @@ export async function runWebCommand(args, options = {}, online, handover = {}) {
         port: config.CONFIG.webServerPort,
         host: config.CONFIG.webServerHost,
         enabled: true,
+        // Imported into the token table once at start; not read for authorisation.
         apiToken: config.CONFIG.webServerApiToken,
         auth: new WebAuth({
             password: config.CONFIG.webServerAuthPassword,

package/dist/config.d.ts

@@ -102,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  // 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 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 embeddingApiUrl (OpenAI-compatible /embeddings); embeddingApiKey is optional.\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 (URL required; key only if the server needs one)\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  // Deprecated: imported once into the API token table, then no longer read.\n  // Create API tokens on the Settings page (Keys and access) instead.\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;

package/dist/config.js

@@ -174,7 +174,7 @@ export const CONFIG_TEMPLATE = `{
   // Embedding Model (for similarity search)
   // ============================================
   // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).
-  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).
+  // Remote = set embeddingApiUrl (OpenAI-compatible /embeddings); embeddingApiKey is optional.
   
   // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)
   "embeddingModel": "Xenova/nomic-embed-text-v1",
@@ -192,7 +192,7 @@ export const CONFIG_TEMPLATE = `{
   // "embeddingModel": "Xenova/all-MiniLM-L6-v2",            // 384 dims, very fast, 512 context
   // "embeddingModel": "Xenova/all-mpnet-base-v2",           // 768 dims, good quality, 512 context
   
-  // Optional: OpenAI-compatible API for embeddings (both URL and key required)
+  // Optional: OpenAI-compatible API for embeddings (URL required; key only if the server needs one)
   // "embeddingApiUrl": "https://api.openai.com/v1",
   // "embeddingApiKey": "env://OPENAI_API_KEY",  // or "sk-..." / "file:///path/to/key"
   // "embeddingModel": "text-embedding-3-small",  // 1536 dims, auto-detected
@@ -225,7 +225,8 @@ export const CONFIG_TEMPLATE = `{
   // "webServerAuthPassword": "",
   // "webServerAuthUsername": "",
 
-  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Omms-Token (legacy X-Opencode-Mem-Token still works).
+  // Deprecated: imported once into the API token table, then no longer read.
+  // Create API tokens on the Settings page (Keys and access) instead.
   // "webServerApiToken": "env://OMMS_WEB_TOKEN",
   
   // ============================================
@@ -631,7 +632,8 @@ function buildConfig(fileConfig) {
         embeddingUseTaskPrefixes: fileConfig.embeddingUseTaskPrefixes ?? DEFAULTS.embeddingUseTaskPrefixes,
         embeddingApiUrl: fileConfig.embeddingApiUrl,
         embeddingApiKey: fileConfig.embeddingApiUrl
-            ? resolveSecretValue(fileConfig.embeddingApiKey ?? process.env.OPENAI_API_KEY)
+            ? // No ambient OPENAI_API_KEY: an unset key means no Authorization header.
+                resolveSecretValue(fileConfig.embeddingApiKey)
             : undefined,
         similarityThreshold: fileConfig.similarityThreshold ?? DEFAULTS.similarityThreshold,
         maxMemories: fileConfig.maxMemories ?? DEFAULTS.maxMemories,

package/dist/core/memory-tool-text.d.ts

@@ -0,0 +1,4 @@
+/** Earlier fixes and decisions are stored in memory, so agents should look there first. */
+export declare const MEMORY_SEARCH_FIRST = "Search it before you debug or investigate a problem: earlier fixes and decisions are stored here.";
+/** The `memory` tool description, the same text for Pi and OpenCode. */
+export declare function memoryToolDescription(languageName: string): string;

package/dist/core/memory-tool-text.js

@@ -0,0 +1,6 @@
+/** Earlier fixes and decisions are stored in memory, so agents should look there first. */
+export const MEMORY_SEARCH_FIRST = "Search it before you debug or investigate a problem: earlier fixes and decisions are stored here.";
+/** The `memory` tool description, the same text for Pi and OpenCode. */
+export function memoryToolDescription(languageName) {
+    return `Manage and query project memory (MATCH USER LANGUAGE: ${languageName}). ${MEMORY_SEARCH_FIRST} Use 'search' with technical keywords/tags, 'add' to store knowledge, 'profile' for preferences. Use migrate/list-shards/export/import when a project directory moves. Search/list scope: project or all-projects.`;
+}

package/dist/core/profile-backoff.d.ts

@@ -0,0 +1,20 @@
+import { type ProfileFailureCode } from "./profile-failure.js";
+/** After a failed profile pass, the process waits this long before the next one. */
+export declare const PROFILE_FAILURE_WAIT_MS: number;
+/**
+ * An in-process gate: a failing batch is not retried, and paid for, after
+ * every turn. Capture never checks it. A restart clears it.
+ */
+export declare const profileBackoff: {
+    canRun(now?: number): boolean;
+    recordSuccess(): void;
+    recordFailure(now?: number): void;
+};
+/** Log one metadata record for a failed pass and start the wait. */
+export declare function recordProfileFailure(host: "opencode" | "pi" | "claude-code", message: string, error: unknown, now?: number): ProfileFailureCode;
+/** One catch-up run at a time, and no live pass in this process while it runs. */
+export declare const profileCatchUpLock: {
+    isActive: () => boolean;
+    begin(): boolean;
+    end(): void;
+};

package/dist/core/profile-backoff.js

@@ -0,0 +1,41 @@
+import { log } from "../services/logger.js";
+import { profileFailureCode } from "./profile-failure.js";
+/** After a failed profile pass, the process waits this long before the next one. */
+export const PROFILE_FAILURE_WAIT_MS = 10 * 60 * 1000;
+let lastFailureAt = null;
+/**
+ * An in-process gate: a failing batch is not retried, and paid for, after
+ * every turn. Capture never checks it. A restart clears it.
+ */
+export const profileBackoff = {
+    canRun(now = Date.now()) {
+        return lastFailureAt === null || now - lastFailureAt >= PROFILE_FAILURE_WAIT_MS;
+    },
+    recordSuccess() {
+        lastFailureAt = null;
+    },
+    recordFailure(now = Date.now()) {
+        lastFailureAt = now;
+    },
+};
+/** Log one metadata record for a failed pass and start the wait. */
+export function recordProfileFailure(host, message, error, now = Date.now()) {
+    const reason = profileFailureCode(error);
+    profileBackoff.recordFailure(now);
+    log(message, { host, reason });
+    return reason;
+}
+let catchUpActive = false;
+/** One catch-up run at a time, and no live pass in this process while it runs. */
+export const profileCatchUpLock = {
+    isActive: () => catchUpActive,
+    begin() {
+        if (catchUpActive)
+            return false;
+        catchUpActive = true;
+        return true;
+    },
+    end() {
+        catchUpActive = false;
+    },
+};

package/dist/core/profile-failure.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Fixed reason codes for a failed profile learning step. Log lines carry only
+ * the code, never the prompt, the reply, or the provider's message.
+ */
+export type ProfileFailureCode = "timeout" | `http-${number}` | "no-tool-call" | "invalid-reply" | "not-configured" | "error";
+export declare class ProfileModelError extends Error {
+    readonly code: ProfileFailureCode;
+    constructor(code: ProfileFailureCode);
+}
+/** The code for a failed provider call result. */
+export declare function profileResultCode(result: {
+    error?: string;
+    httpStatus?: number;
+}): ProfileFailureCode;
+/** The code for any error thrown by a profile learning step. */
+export declare function profileFailureCode(error: unknown): ProfileFailureCode;

package/dist/core/profile-failure.js

@@ -0,0 +1,34 @@
+export class ProfileModelError extends Error {
+    code;
+    constructor(code) {
+        super(`Profile model call failed: ${code}`);
+        this.code = code;
+        this.name = "ProfileModelError";
+    }
+}
+/** The code for a failed provider call result. */
+export function profileResultCode(result) {
+    const message = result.error ?? "";
+    if (/timeout/i.test(message))
+        return "timeout";
+    if (result.httpStatus !== undefined)
+        return `http-${result.httpStatus}`;
+    if (/max iterations/i.test(message))
+        return "no-tool-call";
+    if (/validation/i.test(message))
+        return "invalid-reply";
+    return "error";
+}
+/** The code for any error thrown by a profile learning step. */
+export function profileFailureCode(error) {
+    if (error instanceof ProfileModelError)
+        return error.code;
+    const message = error instanceof Error ? error.message : String(error);
+    if (/timeout/i.test(message))
+        return "timeout";
+    if (/invalid profile payload|validation/i.test(message))
+        return "invalid-reply";
+    if (/not configured|^Missing memory/i.test(message))
+        return "not-configured";
+    return "error";
+}

package/dist/core/trivial-prompt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * A prompt too short to say anything about the user, such as "yes go". The
+ * word rule keeps short real preferences such as "use bun not npm".
+ */
+export declare function isTrivialPrompt(text: string): boolean;