om-memory-system 4.6.0-next.83 → 4.7.0

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

@@ -6,6 +6,7 @@ import { resolveOpencodeHostModel } from "../../services/ai/live-model-choice.js
 import { userPromptManager } from "../../services/user-prompt/user-prompt-manager.js";
 import { userProfileManager } from "../../services/user-profile/user-profile-manager.js";
 import { sortProfileItems } from "../../utils/profile.js";
+import { truncateToMaxBytes } from "../../utils/context-limit.js";
 import { loadOpencodeProvider } from "./opencode-provider-loader.js";
 let isLearningRunning = false;
 export function shouldRunAutomaticProfileCleanup(previousPromptCount, addedPromptCount, interval = CONFIG.userProfileAutoCleanupInterval) {
@@ -46,6 +47,10 @@ export async function performUserProfileLearning(ctx, directory) {
     if (!profileBackoff.canRun())
         return;
     refreshConfigIfChanged(directory);
+    // Snapshot the byte limit right after the refresh: the prompt and profile
+    // reads below all await, and a config edit during them must not change
+    // this pass's input limit.
+    const profileContextMaxBytes = CONFIG.userProfileMaxContextBytes ?? 32768;
     if (!CONFIG.autoCaptureProviderStatus || !CONFIG.autoCaptureProviderStatus.ready) {
         log("user-profile-learning: skipped (provider not ready)", {
             issues: CONFIG.autoCaptureProviderStatus?.issues ?? ["status undefined"],
@@ -134,7 +139,7 @@ Rules:
             }
             existingProfile = { ...existingProfile, profileData: JSON.stringify(decayed) };
         }
-        const context = buildUserAnalysisContext(prompts, existingProfile, validationPrompt);
+        const context = buildUserAnalysisContext(prompts, existingProfile, validationPrompt, profileContextMaxBytes);
         const analysisResult = await analyzeUserProfile(context, existingProfile);
         profileBackoff.recordSuccess();
         log("user-profile-learning: analyze done", { hasResult: !!analysisResult });
@@ -282,7 +287,7 @@ function buildCategorySummary(profileData) {
 New observations are matched via embedding cosine similarity — write descriptions in your own words; do not reuse existing wording.`;
     return [catSection, ...wfParts, countSection].filter(Boolean).join("\n");
 }
-function buildUserAnalysisContext(prompts, existingProfile, validationPrompt) {
+function buildUserAnalysisContext(prompts, existingProfile, validationPrompt, maxBytes = CONFIG.userProfileMaxContextBytes ?? 32768) {
     const base = `# User Profile Analysis
 
 Analyze ${prompts.length} user prompts to ${existingProfile ? "update" : "create"} the user profile.
@@ -336,10 +341,10 @@ CRITICAL: Only output observations grounded in the RECENT PROMPTS above. Write d
 ❌ Do NOT extract as workflow:
 - "User analyzes problems and verifies solutions" (too abstract — not a concrete step sequence)
 - "User writes code and tests it" (too generic — covers everything)`;
-    const maxBytes = CONFIG.userProfileMaxContextBytes ?? 32768;
-    const truncate = (s) => s.length > maxBytes
-        ? s.substring(0, maxBytes) + "\n[... context truncated to userProfileMaxContextBytes ...]"
-        : s;
+    // UTF-8 byte limit: the marker counts inside the ceiling and a cut never
+    // splits a multi-byte character (a character count let multibyte input
+    // through oversized and could split surrogate pairs at the cut).
+    const truncate = (s) => truncateToMaxBytes(s, maxBytes, "\n[... context truncated to userProfileMaxContextBytes ...]");
     if (validationPrompt) {
         return truncate(base + "\n\n" + validationPrompt);
     }

package/dist/adapters/pi/extension.js

@@ -11,7 +11,8 @@ import { capturePiSettledWorkUnit, createPiCaptureState } from "./capture.js";
 import { createPiLiveModels } from "./live-model.js";
 import { registerPiHistoryImportCommand } from "./import-command.js";
 import { performPiProfileLearning } from "./profile.js";
-import { buildRetrievalSection, wrapRetrievalSection } from "../../core/retrieval.js";
+import { buildRetrievalSection, retrievalWrapperBytes, wrapRetrievalSection, } from "../../core/retrieval.js";
+import { DEFAULT_RETRIEVAL_MAX_TOKENS, tokensToByteCeiling } from "../../core/context-budget.js";
 const GLOBAL_PLUGIN_WARMUP_KEY = Symbol.for("omms.plugin.warmedup");
 const GLOBAL_PI_BACKFILL_KEY = Symbol.for("omms.pi.backfill.scheduled");
 const OMMS_STATUS_KEY = "omms";
@@ -224,11 +225,19 @@ export default function ommsPiExtension(pi) {
         }
     });
     pi.on("before_agent_start", async (event, ctx) => {
+        // Refresh first so the enabled check reads the current file, then capture
+        // this retrieval's allowance before the async search starts: a later
+        // config edit must not change an operation already in progress.
+        refreshConfigIfChanged(ctx.cwd);
+        // The default guards partial CONFIG stubs in tests.
+        const budgetBytes = tokensToByteCeiling(CONFIG.retrievalMaxTokens ?? DEFAULT_RETRIEVAL_MAX_TOKENS);
         if (!isConfigured() || !CONFIG.chatMessage.enabled)
             return;
         const status = startStatus(ctx, "recalling");
         try {
-            const section = await buildRetrievalSection(event.prompt, ctx.cwd, ctx.sessionManager.getSessionId());
+            // The wrapper counts against the captured allowance, so the packed
+            // section reserves its bytes.
+            const section = await buildRetrievalSection(event.prompt, ctx.cwd, ctx.sessionManager.getSessionId(), { maxBytes: budgetBytes, wrapperBytes: retrievalWrapperBytes() });
             finishStatus(ctx, status, "connected");
             if (!section)
                 return;

package/dist/config.d.ts

@@ -14,6 +14,8 @@ interface OmmsConfig {
     embeddingUseTaskPrefixes?: boolean;
     similarityThreshold?: number;
     maxMemories?: number;
+    /** Shared budget for automatic memory context in approximate tokens (ceil(UTF-8 bytes / 4)). */
+    retrievalMaxTokens?: number;
     maxProfileItems?: number;
     injectProfile?: boolean;
     containerTagPrefix?: string;
@@ -102,7 +104,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 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 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  // Manual searches can ask for fewer; prompt retrieval uses this ceiling.\n  \"maxMemories\": 10,\n\n  // ============================================\n  // Memory Context Controls\n  // ============================================\n\n  // Recent memories added at fresh session start (OpenCode V1 and Claude Code).\n  // Pi and OpenCode V2 search the store with each prompt instead.\n  \"chatMessage\": {\n    \"enabled\": true,\n    // Recent memories injected at session start.\n    \"maxMemories\": 3,\n    \"excludeCurrentSession\": true,\n    // When to inject: \"first\" message of a session or \"always\".\n    // \"injectOn\": \"first\",\n  },\n\n  // OpenCode profile-learning input limit, in UTF-8 bytes. Smaller values can\n  // omit prompts from that input. Does not limit Pi or Claude Code profile input.\n  \"userProfileMaxContextBytes\": 32768,\n\n  // Shared budget for automatic memory context (profile text, memories, and\n  // formatting) across all hosts, in approximate tokens: ceil(UTF-8 bytes / 4).\n  // Covers prompt retrieval, recent-memory injection, and session-memory\n  // restoration. Not an exact provider token limit or a spending limit.\n  \"retrievalMaxTokens\": 2000,\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;
@@ -118,6 +120,7 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     embeddingApiKey: string | undefined;
     similarityThreshold: number;
     maxMemories: number;
+    retrievalMaxTokens: number;
     maxProfileItems: number;
     injectProfile: boolean;
     containerTagPrefix: string;
@@ -193,7 +196,7 @@ declare function buildConfig(fileConfig: OmmsConfig): {
     };
     chatMessage: {
         enabled: boolean | undefined;
-        maxMemories: number | undefined;
+        maxMemories: number;
         excludeCurrentSession: boolean | undefined;
         maxAgeDays: number | undefined;
         injectOn: "first" | "always";
@@ -213,6 +216,7 @@ export declare let CONFIG: {
     embeddingApiKey: string | undefined;
     similarityThreshold: number;
     maxMemories: number;
+    retrievalMaxTokens: number;
     maxProfileItems: number;
     injectProfile: boolean;
     containerTagPrefix: string;
@@ -288,7 +292,7 @@ export declare let CONFIG: {
     };
     chatMessage: {
         enabled: boolean | undefined;
-        maxMemories: number | undefined;
+        maxMemories: number;
         excludeCurrentSession: boolean | undefined;
         maxAgeDays: number | undefined;
         injectOn: "first" | "always";

package/dist/config.js

@@ -9,6 +9,7 @@ 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 { parseImportPathMaps } from "./importer/import-path-maps.js";
+import { checkedMemoryLimit, MEMORY_LIMITS } from "./utils/memory-limits.js";
 import { resolveDefaultStoragePath, runLegacyStoreMigration, legacyMigrationPaths, } from "./services/legacy-migration.js";
 const OMMS_CONFIG_DIR = join(homedir(), ".config", "omms");
 const DATA_DIR = join(homedir(), ".omms");
@@ -39,6 +40,7 @@ const DEFAULTS = {
     embeddingUseTaskPrefixes: false,
     similarityThreshold: 0.6,
     maxMemories: 10,
+    retrievalMaxTokens: 2000,
     maxProfileItems: 5,
     injectProfile: true,
     // omms since the tag prefix migration: new memories carry the fork's
@@ -493,9 +495,35 @@ export const CONFIG_TEMPLATE = `{
   // Minimum similarity score (0-1) for memory search results
   "similarityThreshold": 0.6,
 
-  // Maximum number of memories to return in search results
+  // Maximum number of memories to return in search results.
+  // Manual searches can ask for fewer; prompt retrieval uses this ceiling.
   "maxMemories": 10,
 
+  // ============================================
+  // Memory Context Controls
+  // ============================================
+
+  // Recent memories added at fresh session start (OpenCode V1 and Claude Code).
+  // Pi and OpenCode V2 search the store with each prompt instead.
+  "chatMessage": {
+    "enabled": true,
+    // Recent memories injected at session start.
+    "maxMemories": 3,
+    "excludeCurrentSession": true,
+    // When to inject: "first" message of a session or "always".
+    // "injectOn": "first",
+  },
+
+  // OpenCode profile-learning input limit, in UTF-8 bytes. Smaller values can
+  // omit prompts from that input. Does not limit Pi or Claude Code profile input.
+  "userProfileMaxContextBytes": 32768,
+
+  // Shared budget for automatic memory context (profile text, memories, and
+  // formatting) across all hosts, in approximate tokens: ceil(UTF-8 bytes / 4).
+  // Covers prompt retrieval, recent-memory injection, and session-memory
+  // restoration. Not an exact provider token limit or a spending limit.
+  "retrievalMaxTokens": 2000,
+
   // ============================================
   // Advanced Settings
   // ============================================
@@ -563,10 +591,18 @@ function getEmbeddingDimensions(model) {
     return dimensionMap[model] || 768;
 }
 export function normalizeAutoCaptureMaxContextBytes(value) {
-    if (!Number.isInteger(value) || value < 16384 || value > 16 * 1024 * 1024) {
-        throw new Error(`Invalid autoCaptureMaxContextBytes config: ${value}`);
-    }
-    return value;
+    return checkedMemoryLimit(MEMORY_LIMITS.autoCaptureMaxContextBytes, value);
+}
+/**
+ * Validate a top-level memory limit that is present in the file. A missing
+ * key uses the default, so only own properties reach the check and a null
+ * value is rejected instead of silently becoming the default.
+ */
+function checkedOwnMemoryLimit(rule, container, key, fallback) {
+    const value = Object.hasOwn(container, key)
+        ? container[key]
+        : fallback;
+    return checkedMemoryLimit(rule, value);
 }
 /** Whole hours from 0 to 720. A value that is not a number gives the default. */
 export function normalizeCaptureRetryRetentionHours(value) {
@@ -599,7 +635,13 @@ function buildConfig(fileConfig) {
     const memoryApiKey = resolveMemoryApiKey(fileConfig.memoryApiKey);
     const embeddingDimensions = fileConfig.embeddingDimensions ??
         getEmbeddingDimensions(fileConfig.embeddingModel ?? DEFAULTS.embeddingModel);
-    const autoCaptureMaxContextBytes = normalizeAutoCaptureMaxContextBytes(fileConfig.autoCaptureMaxContextBytes ?? DEFAULTS.autoCaptureMaxContextBytes);
+    const autoCaptureMaxContextBytes = checkedOwnMemoryLimit(MEMORY_LIMITS.autoCaptureMaxContextBytes, fileConfig, "autoCaptureMaxContextBytes", DEFAULTS.autoCaptureMaxContextBytes);
+    const maxMemories = checkedOwnMemoryLimit(MEMORY_LIMITS.maxMemories, fileConfig, "maxMemories", DEFAULTS.maxMemories);
+    const retrievalMaxTokens = checkedOwnMemoryLimit(MEMORY_LIMITS.retrievalMaxTokens, fileConfig, "retrievalMaxTokens", DEFAULTS.retrievalMaxTokens);
+    const userProfileMaxContextBytes = checkedOwnMemoryLimit(MEMORY_LIMITS.userProfileMaxContextBytes, fileConfig, "userProfileMaxContextBytes", DEFAULTS.userProfileMaxContextBytes);
+    const chatMessageMaxMemories = checkedMemoryLimit(MEMORY_LIMITS["chatMessage.maxMemories"], fileConfig.chatMessage && Object.hasOwn(fileConfig.chatMessage, "maxMemories")
+        ? fileConfig.chatMessage.maxMemories
+        : DEFAULTS.chatMessage.maxMemories);
     const userProfileAutoCleanupInterval = fileConfig.userProfileAutoCleanupInterval ?? DEFAULTS.userProfileAutoCleanupInterval;
     parseBackfillModel(fileConfig, "pi");
     parseBackfillModel(fileConfig, "opencode");
@@ -636,7 +678,8 @@ function buildConfig(fileConfig) {
                 resolveSecretValue(fileConfig.embeddingApiKey)
             : undefined,
         similarityThreshold: fileConfig.similarityThreshold ?? DEFAULTS.similarityThreshold,
-        maxMemories: fileConfig.maxMemories ?? DEFAULTS.maxMemories,
+        maxMemories,
+        retrievalMaxTokens,
         maxProfileItems: fileConfig.maxProfileItems ?? DEFAULTS.maxProfileItems,
         injectProfile: fileConfig.injectProfile ?? DEFAULTS.injectProfile,
         containerTagPrefix: fileConfig.containerTagPrefix ?? DEFAULTS.containerTagPrefix,
@@ -689,7 +732,7 @@ function buildConfig(fileConfig) {
         deduplicationEnabled: fileConfig.deduplicationEnabled ?? DEFAULTS.deduplicationEnabled,
         deduplicationSimilarityThreshold: fileConfig.deduplicationSimilarityThreshold ?? DEFAULTS.deduplicationSimilarityThreshold,
         userProfileAnalysisInterval: fileConfig.userProfileAnalysisInterval ?? DEFAULTS.userProfileAnalysisInterval,
-        userProfileMaxContextBytes: fileConfig.userProfileMaxContextBytes ?? DEFAULTS.userProfileMaxContextBytes,
+        userProfileMaxContextBytes,
         userProfileDisplayPreferences: fileConfig.userProfileDisplayPreferences ?? DEFAULTS.userProfileDisplayPreferences,
         userProfileDisplayPatterns: fileConfig.userProfileDisplayPatterns ?? DEFAULTS.userProfileDisplayPatterns,
         userProfileDisplayWorkflows: fileConfig.userProfileDisplayWorkflows ?? DEFAULTS.userProfileDisplayWorkflows,
@@ -726,7 +769,7 @@ function buildConfig(fileConfig) {
         },
         chatMessage: {
             enabled: fileConfig.chatMessage?.enabled ?? DEFAULTS.chatMessage.enabled,
-            maxMemories: fileConfig.chatMessage?.maxMemories ?? DEFAULTS.chatMessage.maxMemories,
+            maxMemories: chatMessageMaxMemories,
             excludeCurrentSession: fileConfig.chatMessage?.excludeCurrentSession ?? DEFAULTS.chatMessage.excludeCurrentSession,
             maxAgeDays: fileConfig.chatMessage?.maxAgeDays,
             injectOn: (fileConfig.chatMessage?.injectOn ?? DEFAULTS.chatMessage.injectOn),

package/dist/core/capture.js

@@ -36,11 +36,15 @@ async function getLatestProjectMemory(containerTag) {
  */
 export async function captureConversation(workUnit, provider) {
     refreshConfigIfChanged(workUnit.projectDirectory);
+    // Snapshot the markdown budget after the refresh and before the first
+    // await: a config edit during the memory read must not change this
+    // capture's input limit. The budget keeps its built-in request reserve.
+    const markdownBudget = getAutoCaptureMarkdownBudget();
     const diagnostics = {};
     const startedAt = Date.now();
     let outcome = "failed";
     try {
-        const result = await runCapture(workUnit, provider, diagnostics);
+        const result = await runCapture(workUnit, provider, diagnostics, markdownBudget);
         outcome = result.status === "captured" ? "saved" : "skipped";
         return result;
     }
@@ -60,10 +64,10 @@ export async function captureConversation(workUnit, provider) {
         emitCaptureAttempt(record, diagnostics, CONFIG);
     }
 }
-async function runCapture(workUnit, provider, diagnostics) {
+async function runCapture(workUnit, provider, diagnostics, markdownBudget) {
     const tags = getTags(workUnit.projectDirectory);
     const latestMemory = await getLatestProjectMemory(tags.project.tag);
-    const context = buildMarkdownContext(workUnit.userPrompt, workUnit.textResponses, workUnit.toolCalls, latestMemory, getAutoCaptureMarkdownBudget());
+    const context = buildMarkdownContext(workUnit.userPrompt, workUnit.textResponses, workUnit.toolCalls, latestMemory, markdownBudget);
     let summaryResult;
     try {
         summaryResult = await provider.summarize({

package/dist/core/context-budget.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Default approximate-token budget for automatically injected memory context.
+ * Hosts pass their snapshotted `CONFIG.retrievalMaxTokens` explicitly; this
+ * numeric default keeps the shared formatters host-neutral.
+ */
+export declare const DEFAULT_RETRIEVAL_MAX_TOKENS = 2000;
+/** Approximate token estimate: ceil(UTF-8 byte length / 4). Never provider-exact. */
+export declare function estimateTokens(text: string): number;
+/** Internal UTF-8 byte ceiling for an approximate-token budget. */
+export declare function tokensToByteCeiling(maxTokens: number): number;
+/**
+ * Budget options every automatic-memory formatter accepts.
+ * `maxBytes` is an explicit byte ceiling (a residual allowance shared with
+ * other sections in the same host request) and wins over `maxTokens`.
+ * `wrapperBytes` reserves the bytes of a host wrapper, such as the
+ * `omms-retrieval` tag, added around the emitted section.
+ */
+export interface ContextBudgetOptions {
+    maxTokens?: number;
+    maxBytes?: number;
+    wrapperBytes?: number;
+}
+/** One variable-content entry: fixed delimiters around a body that may be shortened. */
+export interface BudgetedEntry {
+    prefix: string;
+    body: string;
+    suffix: string;
+}
+/**
+ * A group of entries wrapped in fixed delimiters, such as the profile block or
+ * the `<project_knowledge>` block. `maxShare` caps the block at a fraction of
+ * the payload space left after fixed formatting; the profile uses 0.25.
+ */
+export interface BudgetedBlock {
+    prefix: string;
+    suffix: string;
+    /** Separator emitted before every entry, including the first. */
+    entrySeparator?: string;
+    /** Separator emitted between the last entry and the block suffix. */
+    suffixSeparator?: string;
+    entries: BudgetedEntry[];
+    maxShare?: number;
+}
+export interface PackContextSectionOptions extends ContextBudgetOptions {
+    /** Fixed section header emitted before all payload blocks. */
+    header: string;
+    /** Fixed section footer emitted after all payload blocks. */
+    footer?: string;
+    /** Separator between payload blocks. */
+    blockSeparator?: string;
+    /** Payload blocks in emission order: profile first, then memories. */
+    blocks: BudgetedBlock[];
+    /** Visible omission marker used when shortening a body. */
+    marker?: string;
+}
+export interface PackedSection {
+    /** Assembled section text; empty when no useful content fits the budget. */
+    text: string;
+    /** UTF-8 bytes of `text` (the host wrapper is not part of `text`). */
+    bytesUsed: number;
+}
+/**
+ * Pack payload blocks into a section that fits one byte ceiling.
+ *
+ * Fixed headers, footers, delimiters, and the host wrapper are reserved before
+ * any payload space is assigned. Blocks with `maxShare` (the profile) are
+ * shortened inside their share and never take more; space they leave unused
+ * stays available to later blocks. Entries keep their incoming order: each is
+ * kept whole while it fits, the first oversized entry is shortened with a
+ * visible marker and packing stops there, and later entries never displace it.
+ * The assembled text contains only complete delimiters and valid Unicode, and
+ * `bytesUsed + wrapperBytes` never exceeds the ceiling.
+ */
+export declare function packContextSection(options: PackContextSectionOptions): PackedSection;

package/dist/core/context-budget.js

@@ -0,0 +1,98 @@
+import { truncateToMaxBytes, utf8ByteLength } from "../utils/context-limit.js";
+/**
+ * Default approximate-token budget for automatically injected memory context.
+ * Hosts pass their snapshotted `CONFIG.retrievalMaxTokens` explicitly; this
+ * numeric default keeps the shared formatters host-neutral.
+ */
+export const DEFAULT_RETRIEVAL_MAX_TOKENS = 2000;
+// Must match the default marker in src/utils/context-limit.ts: the packer needs
+// its byte size to reserve room for a visible omission marker.
+const DEFAULT_TRUNCATION_MARKER = "\n[... truncated ...]\n";
+/** Approximate token estimate: ceil(UTF-8 byte length / 4). Never provider-exact. */
+export function estimateTokens(text) {
+    return Math.ceil(utf8ByteLength(text) / 4);
+}
+/** Internal UTF-8 byte ceiling for an approximate-token budget. */
+export function tokensToByteCeiling(maxTokens) {
+    return maxTokens * 4;
+}
+function resolveCeiling(options) {
+    if (options.maxBytes !== undefined)
+        return options.maxBytes;
+    return tokensToByteCeiling(options.maxTokens ?? DEFAULT_RETRIEVAL_MAX_TOKENS);
+}
+/**
+ * Pack payload blocks into a section that fits one byte ceiling.
+ *
+ * Fixed headers, footers, delimiters, and the host wrapper are reserved before
+ * any payload space is assigned. Blocks with `maxShare` (the profile) are
+ * shortened inside their share and never take more; space they leave unused
+ * stays available to later blocks. Entries keep their incoming order: each is
+ * kept whole while it fits, the first oversized entry is shortened with a
+ * visible marker and packing stops there, and later entries never displace it.
+ * The assembled text contains only complete delimiters and valid Unicode, and
+ * `bytesUsed + wrapperBytes` never exceeds the ceiling.
+ */
+export function packContextSection(options) {
+    const marker = options.marker ?? DEFAULT_TRUNCATION_MARKER;
+    const markerBytes = utf8ByteLength(marker);
+    const wrapperBytes = options.wrapperBytes ?? 0;
+    const blockSeparator = options.blockSeparator ?? "";
+    const payload = resolveCeiling(options) -
+        wrapperBytes -
+        utf8ByteLength(options.header) -
+        utf8ByteLength(options.footer ?? "");
+    if (payload <= 0)
+        return { text: "", bytesUsed: 0 };
+    const emittedBlocks = [];
+    let used = 0;
+    for (const block of options.blocks) {
+        const separatorBytes = emittedBlocks.length > 0 ? utf8ByteLength(blockSeparator) : 0;
+        let blockBudget = payload - used - separatorBytes;
+        if (block.maxShare !== undefined) {
+            blockBudget = Math.min(blockBudget, Math.floor(payload * block.maxShare));
+        }
+        if (blockBudget <= 0)
+            break;
+        const emittedEntries = [];
+        const entrySeparator = block.entrySeparator ?? "";
+        const entrySeparatorBytes = utf8ByteLength(entrySeparator);
+        const suffixSeparator = block.suffixSeparator ?? "";
+        let blockUsed = utf8ByteLength(block.prefix) + utf8ByteLength(block.suffix) + utf8ByteLength(suffixSeparator);
+        for (const entry of block.entries) {
+            const available = blockBudget - blockUsed - entrySeparatorBytes;
+            if (available <= 0)
+                break;
+            const entryFixed = utf8ByteLength(entry.prefix) + utf8ByteLength(entry.suffix);
+            const bodyBytes = utf8ByteLength(entry.body);
+            if (entryFixed + bodyBytes <= available) {
+                emittedEntries.push(entry.prefix + entry.body + entry.suffix);
+                blockUsed += entrySeparatorBytes + entryFixed + bodyBytes;
+                continue;
+            }
+            // First oversized entry: shorten its body with a visible marker, then stop.
+            const bodyAllowance = available - entryFixed;
+            if (bodyAllowance <= markerBytes)
+                break; // no room for content plus marker
+            const shortened = truncateToMaxBytes(entry.body, bodyAllowance, marker);
+            if (shortened.length === 0 || shortened === marker)
+                break;
+            emittedEntries.push(entry.prefix + shortened + entry.suffix);
+            blockUsed += entrySeparatorBytes + entryFixed + utf8ByteLength(shortened);
+            break;
+        }
+        if (emittedEntries.length === 0)
+            continue; // drop the block; it owes no separator
+        const blockText = block.prefix +
+            emittedEntries.map((entry) => entrySeparator + entry).join("") +
+            suffixSeparator +
+            block.suffix;
+        emittedBlocks.push(blockText);
+        used += separatorBytes + blockUsed;
+    }
+    if (emittedBlocks.length === 0)
+        return { text: "", bytesUsed: 0 };
+    const text = options.header + emittedBlocks.join(blockSeparator) + (options.footer ?? "");
+    const bytesUsed = utf8ByteLength(text);
+    return { text, bytesUsed };
+}

package/dist/core/memory-operations.js

@@ -1,4 +1,4 @@
-import { CONFIG, isConfigured } from "../config.js";
+import { CONFIG, isConfigured, refreshConfigIfChanged } from "../config.js";
 import { memoryClient } from "../services/client.js";
 import { getLanguageName } from "../services/language-detector.js";
 import { stripPrivateContent, isFullyPrivate } from "../services/privacy.js";
@@ -18,6 +18,9 @@ function formatSearchResults(query, results, limit) {
     };
 }
 export async function executeMemoryOperation(args, context) {
+    // The next operation sees a changed config file: manual tool and CLI calls
+    // happen outside the hosts' injection and capture boundaries.
+    refreshConfigIfChanged(context.directory);
     if (!isConfigured()) {
         return {
             success: false,

package/dist/core/retrieval.d.ts

@@ -1,3 +1,4 @@
+import { type ContextBudgetOptions } from "./context-budget.js";
 export declare const RETRIEVAL_SECTION_TAG = "omms-retrieval";
 /**
  * Prompt-aware semantic retrieval shared by every host (Pi `before_agent_start`,
@@ -5,7 +6,7 @@ export declare const RETRIEVAL_SECTION_TAG = "omms-retrieval";
  * the incoming prompt and format a bounded context section (memory + user
  * profile). Returns null when nothing relevant is found.
  */
-export declare function buildRetrievalSection(prompt: string, directory: string, sessionId: string): Promise<string | null>;
+export declare function buildRetrievalSection(prompt: string, directory: string, sessionId: string, budget?: ContextBudgetOptions): Promise<string | null>;
 export interface RecentMemoriesOptions {
     /** Project container tag, from `getTags(directory).project.tag`. */
     projectTag: string;
@@ -18,6 +19,8 @@ export interface RecentMemoriesOptions {
     excludeCurrentSession?: boolean;
     /** `CONFIG.chatMessage.maxAgeDays` */
     maxAgeDays?: number;
+    /** Shared packing budget; hosts pass the snapshotted `retrievalMaxTokens`. */
+    budget?: ContextBudgetOptions;
 }
 /**
  * The project's most recent memories as a context section, shared by every host
@@ -27,7 +30,9 @@ export interface RecentMemoriesOptions {
 export declare function buildRecentMemoriesSection(options: RecentMemoriesOptions): Promise<string | null>;
 /** Delimit a retrieval section so it is recognisable as injected memory, not user text. */
 export declare function wrapRetrievalSection(section: string): string;
+/** Byte overhead the `omms-retrieval` wrapper adds around one section. */
+export declare function retrievalWrapperBytes(): number;
 /** Remove injected retrieval sections, so injected memories are never captured as user text. */
 export declare function stripRetrievalSections(text: string): string;
-/** Format a session's own memories for re-injection after compaction. */
-export declare function formatMemoriesForCompaction(memories: any[]): string;
+/** Format a session's own memories for re-injection after compaction, within the budget. */
+export declare function formatMemoriesForCompaction(memories: any[], budget?: ContextBudgetOptions): string;