opencode-mem.example.jsonc

{
  // ============================================
  // OpenCode Memory Plugin Configuration
  // ============================================
  // Reference template for all settings. Copy values into:
  //   ~/.config/opencode/opencode-mem.jsonc
  // Project overrides: <project>/.opencode/opencode-mem.jsonc
  // On first startup the plugin also writes a starter config at the global path.

  // Storage location for vector database (and search index when using markdown backend)
  "storagePath": "~/.opencode-mem/data",

  // Memory persistence: "database" (default) or "markdown".
  // When "markdown", all .md files under markdownPath are the source of truth;
  // Turso under storagePath is only a rebuildable semantic-search index.
  // "memoryBackend": "markdown",
  // "markdownPath": "~/Documents/LLM-Wiki",

  "userEmailOverride": "",
  "userNameOverride": "",

  // ============================================
  // Embedding Model (for similarity search)
  // ============================================
  // Local = Hugging Face / ONNX via @huggingface/transformers (not Apple MLX).
  // Remote = set BOTH embeddingApiUrl and embeddingApiKey (OpenAI-compatible /embeddings).

  // Default: Nomic Embed v1 (768 dimensions, 8192 context, multilingual)
  "embeddingModel": "Xenova/nomic-embed-text-v1",

  // Opt-in Nomic task prefixes (search_document: / search_query:). After enabling,
  // re-index existing memories so store and query vectors stay aligned.
  "embeddingUseTaskPrefixes": false,

  // Local pooling: "mean" (default) | "cls" | "last_token".
  // Unset → model preset (bge-m3=cls, Qwen3-Embedding=last_token) or "mean".
  // "embeddingPooling": "mean",

  // Custom task prefixes (override presets / Nomic). Explicit "" disables a side.
  // Changing pooling or prefixes requires re-embedding stored memories.
  // "embeddingQueryPrefix": "query: ",
  // "embeddingDocumentPrefix": "passage: ",

  // Optional local ONNX dtype override (e.g. "q8", "fp32"). When unset, transformers.js defaults apply.
  // "embeddingDtype": "q8",

  // Auto-detected dimensions (no need to set manually)
  // "embeddingDimensions": 768,

  // Other recommended local models:
  // "embeddingModel": "Xenova/jina-embeddings-v2-base-en",  // 768 dims, English-only, 8192 context
  // "embeddingModel": "Xenova/jina-embeddings-v2-small-en", // 512 dims, faster, 8192 context
  // "embeddingModel": "Xenova/all-MiniLM-L6-v2",            // 384 dims, very fast, 512 context
  // "embeddingModel": "Xenova/all-mpnet-base-v2",           // 768 dims, good quality, 512 context
  // "embeddingModel": "Xenova/bge-m3",                      // 1024 dims, CLS pooling (auto)
  // "embeddingModel": "intfloat/multilingual-e5-large",     // 1024 dims, query:/passage: prefixes (auto)

  // Optional: OpenAI-compatible API for embeddings (both URL and key required)
  // "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

  // ============================================
  // Web Server Settings
  // ============================================

  // Enable web UI for managing memories (accessible at http://localhost:4747)
  "webServerEnabled": true,

  // Port for web UI server
  "webServerPort": 4747,

  // Host address for web UI (use 127.0.0.1 for local only, 0.0.0.0 for network access)
  "webServerHost": "127.0.0.1",

  // Optional HTTP Basic Auth for the web UI. Accepts literal, env://, or file:// secrets.
  // "webServerAuthPassword": "",
  // "webServerAuthUsername": "",

  // Required when webServerHost is not loopback. Protects /api/* with Bearer / X-Opencode-Mem-Token.
  // "webServerApiToken": "env://OPENCODE_MEM_WEB_TOKEN",

  // ============================================
  // Database Settings
  // ============================================

  // Maximum vectors per database shard (auto-creates new shard when limit reached)
  "maxVectorsPerShard": 50000,

  // Automatically delete old memories based on retention period
  "autoCleanupEnabled": true,

  // Days to keep memories before auto-cleanup (only if autoCleanupEnabled is true)
  "autoCleanupRetentionDays": 30,

  // Automatically detect and remove duplicate memories
  "deduplicationEnabled": true,

  // Similarity threshold (0-1) for detecting duplicates (higher = stricter)
  "deduplicationSimilarityThreshold": 0.9,

  // ============================================
  // Memory Scope Settings
  // ============================================

  // Default scope for memory list/search queries
  // "project" keeps queries within the current project, "all-projects" searches across all project shards
  "memory": {
    "defaultScope": "project",
  },

  // ============================================
  // Compaction Memory Injection
  // ============================================

  // Inject relevant memories after session compaction
  "compaction": {
    "enabled": true,
    "memoryLimit": 10,
  },

  // ============================================
  // Chat Message Memory Injection
  // ============================================

  "chatMessage": {
    "enabled": true,
    "maxMemories": 3,
    "excludeCurrentSession": true,
    // Optional max age in days; omit for no limit:
    // "maxAgeDays": 30,
    // "first" = only on the first user message in a session; "always" = every message
    "injectOn": "first",
    // "relevant" (default) = vector search against each authored user prompt
    // (refreshes every turn even when injectOn is "first");
    // "recent" = newest-N listing (honors injectOn); "both" = relevant first, then fill
    "recall": "relevant",
    // "default" follows memory.defaultScope; or "project" / "all-projects"
    "recallScope": "default",
    // Optional override of top-level similarityThreshold for relevant recall:
    // "similarityThreshold": 0.6,
    // Skip prompt text injected by the host or by other OpenCode plugins
    // (system reminders, orchestration directives, background-task
    // notifications) so it is never stored as if the user had typed it.
    // Disable only if you deliberately want that content memorized.
    "filterInjectedPrompts": true,
    // Capture prompts from orchestrator child sessions (sessions with a parentID,
    // e.g. OpenCode task/subagent children). Their "user" messages are written
    // by the parent agent, not by you, so the default false means they are not
    // stored, auto-captured, used for profile learning, or given memory
    // context. Enable only if you deliberately want those prompts memorized.
    "captureChildSessions": false,
    // Extra markers identifying injected blocks. These are ADDED to the
    // built-in list, never replace it.
    // "injectionMarkers": ["<my-plugin-banner>"],
  },

  // Opt-in background consolidation ("dreaming"): merge/update/supersede related
  // memories via LLM and soft-delete superseded rows into recoverable trash.
  "dreaming": {
    "enabled": false,
    "intervalHours": 24,
    "maxGroupsPerRun": 5,
    "trashRetentionDays": 30,
    "relatedThreshold": 0.75,
    // Also effective when memory.defaultScope is "all-projects".
    "crossProject": false,
  },

  // ============================================
  // OpenCode Provider Settings (RECOMMENDED)
  // ============================================

  // Use any provider that is already authenticated in opencode for auto-capture
  // and user profile learning. The plugin calls opencode's session.prompt API
  // (with structured output) instead of talking to provider HTTPS endpoints
  // directly, so opencode owns the auth, token refresh, and provider routing.
  //
  // No separate API key is needed in this plugin — whatever you configured in
  // opencode (OAuth like Claude Pro/Max, GitHub Copilot personal/business,
  // bring-your-own API key, custom provider, ...) just works.
  //
  // If NOT set, falls back to the manual config (memoryApiKey/memoryApiUrl/memoryModel below).
  //
  // Examples (the provider name must be one returned by 'opencode providers list'):
  //   Anthropic (OAuth/API key): "opencodeProvider": "anthropic",      "opencodeModel": "claude-haiku-4-5-20251001"
  //   OpenAI (API key):          "opencodeProvider": "openai",          "opencodeModel": "gpt-4o-mini"
  //   GitHub Copilot:            "opencodeProvider": "github-copilot",  "opencodeModel": "gpt-4o-mini"
  //
  // "opencodeProvider": "anthropic",
  // "opencodeModel": "claude-haiku-4-5-20251001",
  // Optional model reasoning variant for internal LLM calls (e.g. "xhigh");
  // also applies when opencodeModel is "inherit":
  // "opencodeVariant": "xhigh",
  // Optional timeout (ms) for the plugin's internal structured-output LLM calls
  // (auto-capture summaries, profile learning; default 90000, clamped to 10000..600000;
  // invalid values fall back to the default; numeric strings are coerced):
  // "opencodeTimeoutMs": 180000,

  // ============================================
  // Auto-Capture Settings
  // ============================================

  // IMPORTANT: Auto-capture only runs after either opencodeProvider/opencodeModel
  // above is configured, or the manual fallback below is uncommented with real values.
  // It runs in background without blocking your main session
  // Note: Ollama may not support tool calling. Use OpenAI, Anthropic, or Groq for best results.

  "autoCaptureEnabled": true,

  // Opt-in: before saving a new auto-capture memory, search for similar entries
  // and let the model choose add / update / supersede (old rows go to trash).
  // "updateOnCaptureEnabled": true,
  // "updateOnCaptureSimilarityThreshold": 0.75,
  // "updateOnCaptureMaxCandidates": 5,

  // When both opencodeProvider and manual memoryModel/memoryApiUrl are set, which
  // channel to try first for auto-capture summaries. Default "opencode-first".
  // Prefer "external-first" if the host session API is slow/busy and you want the
  // faster external API path. Failed primary falls back to the other channel.
  // Faster opencode failover: also lower "opencodeTimeoutMs" (default 90000).
  // "autoCaptureProviderOrder": "external-first",

  // Provider type: "api-route" | "atlas-cloud" | "cheaper-inference" | "openai-chat" | "openai-responses" | "anthropic" | "minimax" | "orcarouter" | "runcrate"
  // Note: "openai-chat" is a generic OpenAI API-compatible mode.
  // Any service that follows the OpenAI Chat Completions API can use it via custom "memoryApiUrl".
  "memoryProvider": "openai-chat",

  // Manual fallback. Uncomment all 3 lines and replace memoryApiKey before use:
  // "memoryModel": "gpt-4o-mini",
  // "memoryApiUrl": "https://api.openai.com/v1",
  // "memoryApiKey": "sk-...",

  // API Key Formats:
  // Direct value:        "sk-..."
  // From file:           "file://~/.config/litellm-key.txt"
  // From env variable:   "env://LITELLM_API_KEY"

  // Examples for different providers:
  // Any OpenAI-compatible endpoint can use the "openai-chat" provider pattern below.
  // Common examples: DeepSeek, Qwen (via Alibaba Cloud ModelStudio),
  // Zhipu GLM (BigModel platform), and Kimi (Moonshot AI platform).

  // OpenAI Chat Completion (default, backward compatible):
  //   "memoryProvider": "openai-chat"
  //   "memoryModel": "gpt-4o-mini"
  //   "memoryApiUrl": "https://api.openai.com/v1"
  //   "memoryApiKey": "sk-..."

  // DeepSeek (OpenAI-compatible example):
  //   "memoryProvider": "openai-chat"
  //   "memoryModel": "deepseek-chat"
  //   "memoryApiUrl": "https://api.deepseek.com/v1"
  //   "memoryApiKey": "sk-..."

  // OpenAI Responses API (recommended, with session support):
  //   "memoryProvider": "openai-responses"
  //   "memoryModel": "gpt-4o"
  //   "memoryApiUrl": "https://api.openai.com/v1"
  //   "memoryApiKey": "sk-..."

  // Anthropic (with session support):
  //   "memoryProvider": "anthropic"
  //   "memoryModel": "claude-3-5-haiku-20241022"
  //   "memoryApiUrl": "https://api.anthropic.com/v1"
  //   "memoryApiKey": "sk-ant-..."

  // MiniMax (Anthropic Messages-compatible endpoint, with session support):
  //   "memoryProvider": "minimax"
  //   "memoryModel": "MiniMax-M3.1-Flash"          // 1,000,000-token context; thinking always on
  //   // Alternative: "MiniMax-M3"                  // 1,000,000-token context; thinking off by default
  //   "memoryApiUrl": "https://api.minimax.io"        // global endpoint
  //   "memoryApiKey": "<MiniMax API key>"
  //   // China endpoint: "memoryApiUrl": "https://api.minimax.cn"
  //   // Flash effort: low | medium | high | xhigh | max (default). Do not disable thinking.
  //   "memoryExtraParams": { "output_config": { "effort": "max" } }
  //   // For MiniMax-M3, optionally use { "thinking": { "type": "adaptive" } } instead.

  // OrcaRouter (OpenAI-compatible gateway, namespaced model IDs, with session support):
  //   "memoryProvider": "orcarouter"
  //   "memoryApiKey": "<OrcaRouter API key>"
  //   // memoryApiUrl and memoryModel are optional — they default to
  //   // https://api.orcarouter.ai/v1 and "orcarouter/auto" (a routing alias).
  //   // OrcaRouter rejects bare model names, so if you set memoryModel, use a
  //   // namespaced ID such as "openai/gpt-5.5" or "deepseek/deepseek-v4-flash".
  //   "memoryModel": "openai/gpt-5.5"

  // Atlas Cloud (OpenAI-compatible Chat Completions preset, with session support):
  //   "memoryProvider": "atlas-cloud"
  //   "memoryApiKey": "env://ATLASCLOUD_API_KEY"
  //   // memoryApiUrl and memoryModel are optional — they default to
  //   // https://api.atlascloud.ai/v1 and "deepseek-ai/deepseek-v4-pro".
  //   // When selected, auto-capture/profile prompts, responses, and relevant
  //   // conversation context are sent to api.atlascloud.ai.
  //   // "memoryModel": "deepseek-ai/deepseek-v4-pro"

  // Cheaper Inference (OpenAI-compatible Chat Completions preset, with session support):
  //   "memoryProvider": "cheaper-inference"
  //   "memoryApiKey": "env://CHEAPER_INFERENCE_API_KEY"
  //   // memoryApiUrl and memoryModel are optional — they default to
  //   // https://api.cheaperinference.com/v1 and "gpt-5.4-mini".
  //   // When selected, auto-capture/profile prompts, responses, and relevant
  //   // conversation context are sent to api.cheaperinference.com.
  //   // "memoryModel": "gpt-5.4-mini"

  // API Route (OpenAI-compatible Chat Completions preset, with session support):
  //   "memoryProvider": "api-route"
  //   "memoryApiKey": "env://API_ROUTE_API_KEY"
  //   // memoryApiUrl and memoryModel are optional — they default to
  //   // https://global.api-route.com/v1 and "gpt-6.1-sol".
  //   // When selected, auto-capture/profile prompts, responses, and relevant
  //   // conversation context are sent to global.api-route.com.
  //   // "memoryModel": "gpt-6.1-sol"

  // Runcrate (OpenAI-compatible Chat Completions preset, with session support):
  //   "memoryProvider": "runcrate"
  //   "memoryApiKey": "env://RUNCRATE_API_KEY"
  //   // memoryApiUrl and memoryModel are optional — they default to
  //   // https://api.runcrate.ai/v1 and "deepseek-ai/DeepSeek-V4.1-Flash".
  //   // When selected, auto-capture/profile prompts, responses, and relevant
  //   // conversation context are sent to api.runcrate.ai.
  //   // "memoryModel": "deepseek-ai/DeepSeek-V4.1-Flash"

  // Groq (OpenAI-compatible, use openai-chat provider):
  //   "memoryProvider": "openai-chat"
  //   "memoryModel": "llama-3.3-70b-versatile"
  //   "memoryApiUrl": "https://api.groq.com/openai/v1"
  //   "memoryApiKey": "gsk_..."

  // Maximum iterations for multi-turn AI analysis (for openai-responses, anthropic, and minimax)
  "autoCaptureMaxIterations": 5,

  // Timeout per iteration in milliseconds (30 seconds default)
  "autoCaptureIterationTimeout": 30000,

  // Maximum number of times to retry capturing a prompt if it fails (due to network, API errors, etc.)
  "autoCaptureMaxRetries": 3,

  // Maximum UTF-8 bytes for the auto-capture markdown context sent to the summary model.
  // Prevents HTTP 400 context overflows on models with ~131K token windows (e.g. Groq Llama).
  // Rough guide: tokens ≈ bytes / 4 for mixed code/prose.
  "autoCaptureMaxContextBytes": 131072,

  // Days to keep AI session history before cleanup
  "aiSessionRetentionDays": 7,

  // Temperature for AI API requests (set to false to omit parameter for models that don't support it)
  // Some reasoning models (like o1, o3, gpt-5) don't support temperature parameter
  // Set to false and add "memoryTemperature": false in config when using such models
  "memoryTemperature": 0.3,

  // Force tool calls on openai-chat / orcarouter / atlas-cloud / cheaper-inference / api-route / runcrate (tool_choice: "required"). Default true.
  // Some thinking/reasoning models reject forced tool choice — set false to fall back to "auto":
  // "forceToolChoice": false,

  // Extra parameters to include in API request body
  // Useful for local inference servers (e.g. llama-server with --jinja) that support
  // additional parameters like disabling thinking/reasoning mode
  // Example for Qwen3 models: { "enable_thinking": false }
  // "memoryExtraParams": {},

  // Language for auto-capture summaries and user profile learning (default: "auto" for auto-detection)
  // Options: "auto", "en", "id", "zh", "ja", "es", "fr", "de", "ru", "pt", "ar", "ko"
  // "autoCaptureLanguage": "auto",

  // ============================================
  // Toast Notifications
  // ============================================

  // Show toast when memory is auto-captured
  "showAutoCaptureToasts": true,

  // Show toast when user profile is updated
  "showUserProfileToasts": true,

  // Show toast for error messages
  "showErrorToasts": true,

  // Opt-in encryption at rest for local Turso DB shards (AES-256-GCM).
  // When enabled without a key, the plugin creates
  // ~/.config/opencode/opencode-mem-db.key (chmod 600) once.
  "databaseEncryptionEnabled": false,
  // Optional override: "databaseEncryptionKey": "env://OPENCODE_MEM_DB_KEY",
  "databaseEncryptionCipher": "aes256gcm",

  // Automatically update when installed as opencode-mem@latest (or a range).
  // Pinned versions like opencode-mem@2.26.0 are never auto-updated.
  "autoUpdate": true,

  // Recover a store whose Turso WAL index is stale (a leftover -tshm/-shm, often
  // beside a 0-byte -wal). The guard copies the main .db, verifies it with
  // PRAGMA integrity_check, moves the -shm/-tshm index sidecars to
  // <storagePath>/recovery/, and retries the open once. A non-empty -wal is
  // never moved; only an absent or 0-byte -wal is removed. Concurrent sessions
  // serialise healing through <storagePath>/recovery/<db>.lock.
  "tursoAutoHeal": true,

  // Turso experimental multiprocess_wal (Unix). Set false for single-owner mode:
  // a second process then fails loudly with "database is locked" instead of
  // writing into a divergent WAL. See issue #435.
  "tursoMultiprocessWal": true,

  // ============================================
  // User Profile System
  // ============================================

  // Analyze user prompts every N prompts to build/update your user profile
  // When N uncaptured prompts accumulate, AI will analyze them to identify:
  // - User preferences (code style, communication style, tool preferences)
  // - User patterns (recurring topics, problem domains, technical interests)
  // - User workflows (development habits, sequences, learning style)
  // - Skill level (overall and per-domain assessment)
  "userProfileAnalysisInterval": 10,

  // Maximum UTF-8 bytes of recent prompts sent to profile analysis
  "userProfileMaxContextBytes": 32768,

  // Days before inactive items (all types) are eligible for removal
  "userProfileStaleDays": 2,

  // Number of preferences shown in UI
  "userProfileDisplayPreferences": 20,

  // Number of patterns shown in UI
  "userProfileDisplayPatterns": 15,

  // Number of workflows shown in UI
  "userProfileDisplayWorkflows": 10,

  // Number of preferences injected into LLM conversation context
  // Keep this small — the strongest signals are enough; more dilute LLM attention
  "userProfileInjectPreferences": 5,

  // Number of patterns injected into LLM conversation context
  "userProfileInjectPatterns": 5,

  // Number of workflows injected into LLM conversation context
  "userProfileInjectWorkflows": 3,

  // Days before preference confidence starts to decay (if not reinforced)
  // Preferences that aren't seen again will gradually lose confidence and be removed
  "userProfileConfidenceDecayDays": 30,

  // Number of profile versions to keep in changelog (for rollback/debugging)
  // Older versions are automatically cleaned up
  "userProfileChangelogRetentionCount": 5,

  // Embedding similarity thresholds for profile item deduplication
  "userProfileEmbeddingThresholdSameCat": 0.8,
  "userProfileEmbeddingThresholdSameCatWeak": 0.5,
  "userProfileEmbeddingThresholdCrossCat": 0.9,
  "userProfileEmbeddingThresholdCrossCatWeak": 0.8,
  "userProfileCentroidDriftThreshold": 0.65,
  "userProfileEmbeddingMinDescriptionLength": 5,

  // Minimum evidence count for a preference/pattern to survive confidence decay
  // Items confirmed fewer times are more likely to be pruned when confidence decays
  "userProfileMinEvidenceForRetention": 3,

  // Periodically merge duplicate or irrelevant profile items with the configured AI provider
  "userProfileAutoCleanupEnabled": true,
  // Number of analyzed user prompts between automatic AI cleanup runs
  "userProfileAutoCleanupInterval": 100,

  // Enable LLM validation of existing preferences against recent behavior.
  // When enabled, each analysis round checks if top-5 preferences still match recent prompts.
  // Experimental — disabled by default.
  "userProfileValidationEnabled": false,

  // ============================================
  // Search Settings
  // ============================================

  // Minimum similarity score (0-1) for memory search results
  "similarityThreshold": 0.6,

  // Maximum number of memories to return in search results
  "maxMemories": 10,

  // Maximum profile items considered for injection / ranking
  "maxProfileItems": 5,

  // Prefix for user/project container tags
  "containerTagPrefix": "opencode",

  // ============================================
  // Advanced Settings
  // ============================================

  // Inject user profile into AI context (preferences, patterns, workflows)
  "injectProfile": true,
}