@zilliz/memsearch-opencode 0.3.0 → 0.3.2

package/README.md

@@ -148,13 +148,22 @@ memsearch config set embedding.provider openai
 export OPENAI_API_KEY=sk-...
 ```
 
-To override only the OpenCode capture summarization model:
+To override only the OpenCode native capture summarization model:
 
 ```bash
 memsearch config set plugins.opencode.summarize.model anthropic/claude-haiku
 ```
 
-Leave it empty or unset to keep the current `small_model` / plugin default behavior. This setting does not fall back to `llm.model`.
+To use a memsearch-managed API provider instead:
+
+```bash
+memsearch config set llm.providers.openai.type openai
+memsearch config set llm.providers.openai.model gpt-5-mini
+memsearch config set llm.providers.openai.api_key env:OPENAI_API_KEY
+memsearch config set plugins.opencode.summarize.provider openai
+```
+
+Leave `plugins.opencode.summarize.provider` empty or set it to `native` to keep the current `small_model` / plugin default behavior. This setting does not fall back to `llm.model`.
 
 ## How It Works
 

package/index.ts

@@ -19,11 +19,12 @@ import {
   existsSync,
   mkdirSync,
   readdirSync,
+  realpathSync,
 } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const PLUGIN_DIR = dirname(fileURLToPath(import.meta.url));
+const PLUGIN_DIR = dirname(realpathSync(fileURLToPath(import.meta.url)));
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -167,6 +168,19 @@ function stopCaptureDaemon(projectDir: string): void {
   }
 }
 
+function wakeMaintenance(projectDir: string, memsearchDir: string): void {
+  const runner = join(PLUGIN_DIR, "scripts", "maintenance-runner.py");
+  exec(
+    `python3 '${shellEscape(runner)}' --platform opencode ` +
+      `--project-dir '${shellEscape(projectDir)}' --memsearch-dir '${shellEscape(memsearchDir)}' &`,
+    {
+      timeout: 5000,
+      env: { ...process.env, MEMSEARCH_NO_WATCH: "1" },
+    },
+    () => { /* ignore */ }
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Plugin entry
 // ---------------------------------------------------------------------------
@@ -212,6 +226,7 @@ const MemsearchPlugin: Plugin = async ({ project, directory, worktree }) => {
   // Start capture daemon for auto-capture
   if (autoCapture) {
     startCaptureDaemon(projectDir, collectionName, memsearchCmd);
+    wakeMaintenance(projectDir, memsearchDir);
   }
 
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zilliz/memsearch-opencode",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "memsearch plugin for OpenCode — semantic memory search across sessions",
   "type": "module",
   "main": "index.ts",

package/prompts/project_review.txt

@@ -0,0 +1,42 @@
+You are maintaining a durable project memory file for {{AGENT_NAME}}.
+
+Task: {{TASK_NAME}}
+Project directory: {{PROJECT_DIR}}
+Input memory directory: {{INPUT_DIR}}
+Output file: {{OUTPUT_FILE}}
+
+You will receive the current output file and recent memory journal entries. Update the output only when there is durable project information worth preserving.
+
+Rules:
+- Return only a JSON object, with no prose outside JSON.
+- Use action "none" when the recent journals do not add durable project state.
+- Use action "replace" when recent journals contain a durable project decision, risk, constraint, active thread, or next step that is not already represented in the existing output file.
+- Treat journal lines explicitly labeled as project decision, project progress, project risk, project constraint, active thread, open question, or next step as project state unless they are clearly temporary noise.
+- Recent progress should be recorded when it changes implementation status, validation status, release status, or an important debugging/testing behavior.
+- If the existing output file is empty and recent journals contain any durable project state, use action "replace".
+- Use action "replace" only when the output file should be replaced.
+- The "content" field, when present, must be the full replacement Markdown file.
+- Preserve useful existing content. Do not rewrite for style.
+- Do not copy raw journals or raw transcript excerpts wholesale.
+- Keep this file about the project, not the user. Put stable user preferences, communication style, and personal workflow notes in USER.md instead.
+- Include user constraints only when they directly affect this project's execution.
+- Do not include general user preferences such as preferred language, dependency manager, PR wording style, verification style, or communication style unless the project has explicitly decided to encode them as project requirements.
+- Suggested sections are optional. Include only sections that are useful.
+- Keep the file concise and reviewable.
+- Prefer small targeted additions over broad rewrites when the existing output is already useful.
+
+Suggested Markdown shape:
+- # Project Memory
+- ## Current Direction
+- ## Active Threads
+- ## Recent Progress
+- ## Decisions
+- ## Open Questions
+- ## Risks and Constraints
+- ## Next Steps
+- ## Cold Items
+
+JSON examples:
+{"action":"none","reason":"Recent journals do not change durable project state."}
+
+{"action":"replace","reason":"Recent journals add a new active thread.","content":"# Project Memory\n\n## Current Direction\n..."}

package/prompts/user_profile.txt

@@ -0,0 +1,42 @@
+You are maintaining a conservative user/workflow profile for {{AGENT_NAME}}.
+
+Task: {{TASK_NAME}}
+Project directory: {{PROJECT_DIR}}
+Input memory directory: {{INPUT_DIR}}
+Output file: {{OUTPUT_FILE}}
+
+You will receive the current output file and recent memory journal entries. Update the output only when there is stable evidence about the user's durable preferences, priorities, constraints, or repeated workflows.
+
+Rules:
+- Return only a JSON object, with no prose outside JSON.
+- Use action "none" when the recent journals do not add stable user/workflow information.
+- Use action "replace" when recent journals contain a stable user preference, priority, constraint, communication style, or repeated workflow that is not already represented in the existing output file.
+- If the existing output file is empty and recent journals contain stable user/workflow information, use action "replace".
+- Use action "replace" only when the output file should be replaced.
+- The "content" field, when present, must be the full replacement Markdown file.
+- Preserve useful existing content. Do not rewrite for style.
+- Do not infer broad personality traits from one-off messages.
+- Keep this file about the user and reusable workflow patterns, not transient project status. Put active project threads and implementation state in PROJECT.md instead.
+- Do not include project technical constraints, implementation decisions, file paths, bug fixes, or architecture decisions unless they are evidence of a repeated user preference across projects.
+- Lines labeled as project decision, project progress, project risk, implementation note, or project constraint belong in PROJECT.md, not USER.md.
+- Do not rewrite project decisions as "User prefers ...". Only include a preference when the journal explicitly describes a user preference, communication preference, workflow preference, or repeated behavior.
+- Treat raw transcript excerpts, when provided, as stronger evidence for wording, style, and decision context.
+- Do not copy raw journals or raw transcript excerpts wholesale.
+- Suggested sections are optional. Include only sections that are useful.
+- Keep the file concise and reviewable.
+- Prefer small targeted additions over broad rewrites when the existing output is already useful.
+
+Suggested Markdown shape:
+- # User Memory
+- ## Priorities
+- ## Preferences
+- ## Working Style
+- ## Technical Defaults
+- ## Communication Notes
+- ## Repeated Workflows
+- ## Constraints
+
+JSON examples:
+{"action":"none","reason":"Recent journals do not provide stable new user-profile evidence."}
+
+{"action":"replace","reason":"Recent journals confirm a recurring workflow preference.","content":"# User Memory\n\n## Priorities\n..."}

package/scripts/capture-daemon.py

@@ -40,7 +40,7 @@ from opencode_turns import (
 )
 
 _ANCHOR_RE = re.compile(r"<!-- session:([^ ]+) turn:([^ ]+) db:")
-_TAIL_TURN_QUIET_PERIOD_MS = 300_000
+_TAIL_TURN_QUIET_PERIOD_MS = int(os.environ.get("MEMSEARCH_OPENCODE_TAIL_QUIET_MS", "300000"))
 
 
 class TailTurnObservation:
@@ -90,6 +90,38 @@ def get_plugin_summarize_model(memsearch_cmd: str | None = None) -> str:
         return ""
 
 
+def get_plugin_summarize_provider(memsearch_cmd: str | None = None) -> str:
+    """Read the memsearch OpenCode summarize provider route."""
+    if not memsearch_cmd:
+        return ""
+    try:
+        result = subprocess.run(
+            [*split_memsearch_cmd(memsearch_cmd), "config", "get", "plugins.opencode.summarize.provider"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.stdout.strip()
+    except Exception:
+        return ""
+
+
+def get_plugin_summarize_enabled(memsearch_cmd: str | None = None) -> bool:
+    """Read whether the memsearch OpenCode summarizer is enabled."""
+    if not memsearch_cmd:
+        return True
+    try:
+        result = subprocess.run(
+            [*split_memsearch_cmd(memsearch_cmd), "config", "get", "plugins.opencode.summarize.enabled"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        return result.stdout.strip().lower() != "false"
+    except Exception:
+        return True
+
+
 def ensure_isolated_config() -> str:
     """Create isolated config dir without plugins/ to prevent recursion."""
     isolated = os.path.expanduser("~/.codex/tmp/opencode-memsearch-summarize/opencode")
@@ -137,9 +169,36 @@ def _load_summarize_prompt(agent_name: str, memsearch_cmd: str | None = None) ->
 
 
 def summarize_with_llm(turn_text: str, small_model: str, memsearch_cmd: str | None = None) -> str | None:
-    """Summarize using opencode run in isolated env (no plugins -> no recursion)."""
+    """Summarize using configured provider routing."""
+    if not get_plugin_summarize_enabled(memsearch_cmd):
+        return None
+
     system_prompt = _load_summarize_prompt("OpenCode", memsearch_cmd)
     full_prompt = f"{system_prompt}\n\nTranscript:\n{turn_text}"
+
+    summarize_provider = get_plugin_summarize_provider(memsearch_cmd)
+    if summarize_provider and summarize_provider != "native" and memsearch_cmd:
+        try:
+            result = subprocess.run(
+                [*split_memsearch_cmd(memsearch_cmd), "summarize", "--plugin", "opencode", "--agent-name", "OpenCode"],
+                input=turn_text,
+                capture_output=True,
+                text=True,
+                timeout=30,
+                env={**os.environ, "MEMSEARCH_NO_WATCH": "1"},
+            )
+            output = result.stdout.strip()
+            lines = output.split("\n")
+            bullets = [line for line in lines if line.strip().startswith("- ")]
+            if bullets:
+                return "\n".join(bullets)
+            if output:
+                return output
+        except Exception:
+            pass
+        return None
+
+    # Native path: summarize using opencode run in isolated env (no plugins -> no recursion).
     isolated_dir = ensure_isolated_config()
 
     summarize_model = get_plugin_summarize_model(memsearch_cmd) or small_model
@@ -427,6 +486,8 @@ def capture_session_turns(
         # Check anchor first so that sidecar rebuilds repair state without
         # calling the summarizer again for already-captured turns.
         if not capture_exists(memory_dir, session_id, turn.turn_id):
+            if not get_plugin_summarize_enabled(memsearch_cmd):
+                continue
             summary = summarize_with_llm(turn_text, small_model, memsearch_cmd)
             write_capture(
                 memory_dir,
@@ -504,6 +565,12 @@ def main() -> None:
                     f"{args.memsearch_cmd} index '{memory_dir}' "
                     f"--collection {args.collection_name} &"
                 )
+                os.system(
+                    f"python3 {shlex.quote(str(Path(__file__).resolve().parent / 'maintenance-runner.py'))} "
+                    f"--platform opencode "
+                    f"--project-dir {shlex.quote(args.project_dir)} "
+                    f"--memsearch-dir {shlex.quote(os.path.join(args.project_dir, '.memsearch'))} &"
+                )
         except Exception:
             pass
         finally:

package/scripts/maintenance-runner.py

@@ -0,0 +1,260 @@
+#!/usr/bin/env python3
+"""Plugin-local runner for MemSearch maintenance tasks.
+
+This script belongs to the plugin layer. It handles host-native agent
+invocations, while the Python package provides shared config, due-state,
+prompt, and API-provider logic.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+
+DEFAULT_NATIVE_MODELS = {
+    "claude-code": "sonnet",
+    "codex": "",
+    "opencode": "",
+    "openclaw": "",
+}
+
+
+def run_command(cmd: list[str], *, env: dict[str, str], cwd: Path, timeout: int) -> str:
+    result = subprocess.run(
+        cmd,
+        capture_output=True,
+        text=True,
+        env=env,
+        cwd=str(cwd),
+        timeout=timeout,
+        check=False,
+    )
+    return (result.stdout or result.stderr or "").strip()
+
+
+def extract_task_json_output(output: str) -> str:
+    """Extract the first maintenance JSON object from noisy host output."""
+    for line in output.splitlines():
+        candidate = line.strip()
+        if not candidate.startswith("{"):
+            continue
+        try:
+            parsed = json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict) and "action" in parsed:
+            return json.dumps(parsed, ensure_ascii=False)
+    return output
+
+
+def ensure_opencode_isolated_config() -> Path:
+    home = Path.home()
+    isolated = home / ".codex" / "tmp" / "opencode-memsearch-maintenance" / "opencode"
+    isolated.mkdir(parents=True, exist_ok=True)
+    src = home / ".config" / "opencode" / "opencode.json"
+    if src.is_file():
+        shutil.copy2(src, isolated / "opencode.json")
+    return isolated
+
+
+def ensure_memsearch_importable() -> None:
+    user_paths = [
+        str(Path.home() / ".local" / "bin"),
+        str(Path.home() / ".cargo" / "bin"),
+        str(Path.home() / "bin"),
+        "/usr/local/bin",
+    ]
+    existing_path = os.environ.get("PATH", "")
+    path_parts = existing_path.split(os.pathsep) if existing_path else []
+    for user_path in reversed(user_paths):
+        if Path(user_path).is_dir() and user_path not in path_parts:
+            path_parts.insert(0, user_path)
+    os.environ["PATH"] = os.pathsep.join(path_parts)
+
+    for parent in Path(__file__).resolve().parents:
+        src_dir = parent / "src"
+        if (src_dir / "memsearch").is_dir():
+            sys.path.insert(0, str(src_dir))
+            break
+
+    try:
+        import memsearch  # noqa: F401
+
+        return
+    except ModuleNotFoundError:
+        pass
+
+    if os.environ.get("MEMSEARCH_MAINTENANCE_UV_BOOTSTRAP") == "1":
+        return
+
+    memsearch_bin = shutil.which("memsearch")
+    if memsearch_bin:
+        with contextlib.suppress(OSError, UnicodeDecodeError):
+            first_line = Path(memsearch_bin).read_text(encoding="utf-8", errors="ignore").splitlines()[0]
+            if first_line.startswith("#!"):
+                python_bin = first_line[2:].strip().split()[0]
+                if python_bin:
+                    os.execvpe(
+                        python_bin,
+                        [python_bin, str(Path(__file__).resolve()), *sys.argv[1:]],
+                        {**os.environ, "MEMSEARCH_MAINTENANCE_UV_BOOTSTRAP": "1"},
+                    )
+
+    uv = shutil.which("uv")
+    if not uv:
+        return
+
+    env = {**os.environ, "MEMSEARCH_MAINTENANCE_UV_BOOTSTRAP": "1"}
+    os.execvpe(
+        uv,
+        [
+            uv,
+            "run",
+            "--with",
+            "memsearch[onnx]",
+            "python",
+            str(Path(__file__).resolve()),
+            *sys.argv[1:],
+        ],
+        env,
+    )
+
+
+def apply_plugin_prompt_defaults(cfg) -> None:
+    plugin_dir = Path(__file__).resolve().parent.parent
+    prompts_dir = plugin_dir / "prompts"
+    for task in ("project_review", "user_profile"):
+        if getattr(cfg.prompts, task, ""):
+            continue
+        prompt_file = prompts_dir / f"{task}.txt"
+        if prompt_file.is_file():
+            setattr(cfg.prompts, task, str(prompt_file))
+
+
+def run_native_provider(ctx, prompt: str) -> str:
+    model = ctx.task_config.model or DEFAULT_NATIVE_MODELS.get(ctx.platform, "")
+    env = {**os.environ, "MEMSEARCH_NO_WATCH": "1"}
+
+    if ctx.platform == "claude-code":
+        cmd = ["claude", "-p", "--strict-mcp-config", "--no-session-persistence", "--no-chrome"]
+        if model:
+            cmd += ["--model", model]
+        cmd += [
+            "--system-prompt",
+            "You are a maintenance task runner. Output only the requested JSON object.",
+            prompt,
+        ]
+        env["CLAUDECODE"] = ""
+        return run_command(cmd, env=env, cwd=ctx.project_dir, timeout=120)
+
+    if ctx.platform == "codex":
+        with tempfile.NamedTemporaryFile(prefix="memsearch-codex-maintenance-", suffix=".txt", delete=False) as output_file:
+            output_path = Path(output_file.name)
+        cmd = [
+            "codex",
+            "exec",
+            "--ephemeral",
+            "--skip-git-repo-check",
+            "-s",
+            "read-only",
+            "-c",
+            "features.hooks=false",
+            "-c",
+            'model_reasoning_effort="medium"',
+            "-o",
+            str(output_path),
+        ]
+        profile = os.environ.get("MEMSEARCH_CODEX_PROFILE", "").strip()
+        if profile:
+            cmd += ["-p", profile]
+        if model:
+            cmd += ["-m", model]
+        cmd.append(prompt)
+        env["MEMSEARCH_IN_STOP_WORKER"] = "1"
+        try:
+            run_command(cmd, env=env, cwd=ctx.project_dir, timeout=120)
+            return output_path.read_text(encoding="utf-8", errors="replace").strip()
+        finally:
+            output_path.unlink(missing_ok=True)
+
+    if ctx.platform == "openclaw":
+        cmd = ["openclaw", "agent", "--local", "--session-id", "memsearch-maintenance"]
+        if model:
+            cmd += ["--model", model]
+        cmd += ["-m", prompt]
+        env["MEMSEARCH_DISABLE"] = "1"
+        return extract_task_json_output(run_command(cmd, env=env, cwd=ctx.project_dir, timeout=120))
+
+    if ctx.platform == "opencode":
+        isolated = ensure_opencode_isolated_config()
+        cmd = ["opencode", "run"]
+        if model:
+            cmd += ["-m", model]
+        cmd.append(prompt)
+        env["XDG_CONFIG_HOME"] = str(isolated)
+        env["XDG_DATA_HOME"] = str(isolated / "data")
+        return run_command(cmd, env=env, cwd=ctx.project_dir, timeout=120)
+
+    raise RuntimeError(f"Unsupported native maintenance platform {ctx.platform!r}")
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run plugin-local MemSearch maintenance tasks.")
+    parser.add_argument("--platform", required=True, choices=["claude-code", "codex", "opencode", "openclaw"])
+    parser.add_argument("--project-dir", default=None)
+    parser.add_argument("--memsearch-dir", default=None)
+    parser.add_argument("--force", action="store_true")
+    parser.add_argument("--json-output", action="store_true")
+    args = parser.parse_args()
+
+    old_cwd = Path.cwd()
+    try:
+        ensure_memsearch_importable()
+        from memsearch.config import resolve_config
+        from memsearch.maintenance import run_due_tasks, run_task_llm
+
+        project_dir = Path(args.project_dir or old_cwd).expanduser().resolve()
+        os.chdir(project_dir)
+        cfg = resolve_config()
+        apply_plugin_prompt_defaults(cfg)
+
+        def llm_runner(ctx, prompt: str) -> str:
+            provider_name = (ctx.task_config.provider or "native").strip()
+            if provider_name in {"", "native"}:
+                return run_native_provider(ctx, prompt)
+            return run_task_llm(ctx, prompt, cfg)
+
+        results = run_due_tasks(
+            platform=args.platform,
+            project_dir=project_dir,
+            memsearch_dir=args.memsearch_dir,
+            cfg=cfg,
+            force=args.force,
+            llm_runner=llm_runner,
+        )
+    except (KeyError, RuntimeError, ValueError, subprocess.SubprocessError) as exc:
+        sys.stderr.write(f"Maintenance error: {exc}\n")
+        return 1
+    finally:
+        with contextlib.suppress(OSError):
+            os.chdir(old_cwd)
+
+    payload = [result.__dict__ for result in results]
+    if args.json_output:
+        sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=False) + "\n")
+    else:
+        for result in results:
+            detail = f": {result.reason}" if result.reason else ""
+            sys.stdout.write(f"{result.task}: {result.action}{detail}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/opencode_turns.py

@@ -17,7 +17,7 @@ from dataclasses import dataclass, field
 from pathlib import Path
 
 
-@dataclass(slots=True)
+@dataclass
 class OpenCodeMessage:
     """A single meaningful OpenCode message with rendered text."""
 
@@ -29,7 +29,7 @@ class OpenCodeMessage:
     text: str
 
 
-@dataclass(slots=True)
+@dataclass
 class OpenCodeTurn:
     """A user turn plus its assistant follow-up messages."""
 
@@ -60,7 +60,7 @@ class OpenCodeTurn:
         return "\n".join(lines).strip()
 
 
-@dataclass(slots=True)
+@dataclass
 class TurnState:
     """Persistent capture progress for a session."""
 

package/skills/memory-config/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: memory-config
+description: "Diagnose and configure MemSearch memory behavior for the OpenCode plugin. Use when the user asks about MemSearch configuration, plugin summarization, PROJECT.md/USER.md maintenance, memory directories, index health, provider routing, prompt files, or migration/compatibility questions."
+---
+
+You are a MemSearch configuration assistant for the OpenCode plugin. This skill manages MemSearch settings only. It is not OpenCode's built-in memory configuration.
+
+Start every user-facing answer with:
+
+> This is MemSearch memory config, not OpenCode's own memory config.
+
+When this skill is triggered, inspect the user's request text. If there is no concrete request, run a diagnostic. If they ask for a specific setting or change, route the request using the flows below.
+
+## Intent Routing
+
+- Empty request or "check": diagnose current MemSearch setup.
+- "Show/get setting": read the requested resolved/global/project value.
+- "Set/enable/disable/change": make a safe project-scoped change after confirming ambiguous choices.
+- "Not capturing/search empty/no memory": troubleshoot files, config, and index health.
+- "Use OpenAI/Gemini/Anthropic/native/model": configure provider routing.
+- "PROJECT.md/USER.md/profile/review": configure advanced maintenance.
+- "Prompt": explain or configure prompt overrides.
+
+Ask the user before enabling external or paid providers, changing output paths, re-indexing, deleting state, or broadening what gets indexed.
+
+## Diagnose First
+
+```bash
+memsearch config list --resolved
+memsearch config list --global
+memsearch config list --project
+```
+
+If `memsearch` is unavailable, try `uvx --from memsearch[onnx] memsearch --version`.
+
+Check memory files:
+
+```bash
+MDIR="${MEMSEARCH_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)/.memsearch}/memory"
+ls -la "$MDIR"
+find "$MDIR" -maxdepth 1 -type f -name '*.md' | sort | tail -10
+tail -120 "$MDIR/$(date +%Y-%m-%d).md"
+```
+
+Check index health:
+
+```bash
+memsearch stats
+```
+
+OpenCode transcript recall reads from OpenCode's SQLite database, while captured MemSearch memory lives as markdown under `.memsearch/memory/`.
+
+## Background and Compatibility
+
+Some plugin config fields may be missing or empty. That is usually normal:
+
+- `summarize.enabled`, advanced maintenance, and task-specific provider/model fields are newer settings.
+- Existing users' TOML files are not rewritten automatically after package/plugin upgrades.
+- Empty strings usually mean "use the built-in or host-native default"; they do not necessarily mean "disabled" or "broken".
+- Missing fields should be interpreted through `memsearch config list --resolved`, not by reading raw TOML alone.
+- New users who run `memsearch config init` may see more fields than old users because the template includes newer options.
+- Advanced maintenance is intentionally disabled by default to avoid surprise background model calls.
+
+## Configuration Logic
+
+Config is resolved from built-in defaults, global config, project config, env refs like `env:OPENAI_API_KEY`, and runtime env such as `MEMSEARCH_DIR`.
+
+Use `memsearch config list --resolved` for effective behavior, `--global` for global overrides, and `--project` for repository-specific overrides.
+
+Default recommendation:
+
+- Put reusable defaults in global config so users do not repeat setup in every project.
+- Put only project-specific overrides in project config.
+- Use global config for named LLM providers, common model choices, normal input/output defaults, and shared prompt defaults.
+- Use project config for one repo's enable/disable switches, unusual output files, special intervals, or repo-specific providers.
+
+Maintenance `input_dir` and `output_file` may be relative even when configured globally. They are resolved from the current project directory at runtime. For custom prompt paths, prefer absolute paths in global config and relative paths in project config.
+
+OpenCode plugin keys:
+
+```toml
+[plugins.opencode.summarize]
+enabled = true
+provider = ""      # empty/native = OpenCode native summarizer
+model = ""
+
+[plugins.opencode.project_review]
+enabled = false
+provider = "native"
+model = ""
+min_interval_hours = 24
+input_dir = ".memsearch/memory"
+output_file = ".memsearch/PROJECT.md"
+
+[plugins.opencode.user_profile]
+enabled = false
+provider = "native"
+model = ""
+min_interval_hours = 24
+input_dir = ".memsearch/memory"
+output_file = ".memsearch/USER.md"
+```
+
+Provider rules:
+
+- `provider = ""` or `native` uses OpenCode's non-interactive native path.
+- Any other provider value is a name that must exist under `[llm.providers.<name>]`.
+- Model resolution order is task-level `plugins.opencode.<task>.model`, then named provider model, then built-in default.
+- API keys should be configured as env refs, not pasted into chat.
+- If a raw TOML field is blank, check resolved config before calling it unset or broken.
+
+Common provider examples:
+
+```toml
+[llm.providers.openai]
+type = "openai"
+model = "gpt-5-mini"
+api_key = "env:OPENAI_API_KEY"
+
+[llm.providers.anthropic]
+type = "anthropic"
+model = "claude-sonnet-4-6"
+api_key = "env:ANTHROPIC_API_KEY"
+
+[llm.providers.gemini]
+type = "gemini"
+model = "gemini-3-flash-preview"
+api_key = "env:GEMINI_API_KEY"
+```
+
+Model guidance:
+
+- Normal turn summaries can use small/fast models. OpenCode native summarize uses OpenCode `small_model`, then its configured model/default behavior.
+- Advanced maintenance needs better judgment. OpenCode native maintenance uses OpenCode's default unless `plugins.opencode.<task>.model` is set.
+- For API providers, defaults are `openai -> gpt-5-mini`, `anthropic -> claude-sonnet-4-6`, and `gemini -> gemini-3-flash-preview`.
+- If quality matters more than cost for maintenance, set `plugins.opencode.project_review.model` and `plugins.opencode.user_profile.model` explicitly.
+
+Advanced maintenance runs after the plugin wakes it, only when enabled, journal input changed, and `min_interval_hours` elapsed. `PROJECT.md` and `USER.md` are maintenance artifacts by default and are not automatically indexed.
+
+Before enabling advanced maintenance, ask which provider to use, whether the default 24-hour interval is acceptable, and whether `.memsearch/PROJECT.md` / `.memsearch/USER.md` are acceptable output files.
+
+Prompt overrides:
+
+```toml
+[prompts]
+summarize = ""
+project_review = ""
+user_profile = ""
+```
+
+Empty prompt paths mean use the built-in MemSearch prompts. Custom prompt files may use `{{AGENT_NAME}}`, `{{TASK_NAME}}`, `{{PROJECT_DIR}}`, `{{INPUT_DIR}}`, and `{{OUTPUT_FILE}}`; the runner appends existing output, recent journals, and digest automatically.
+
+Use `memsearch config set` for changes. After changing anything, show the command, the resolved value, and whether a new session is needed.
+
+MemSearch TOML changes are read lazily by the CLI, capture daemon, and maintenance runner, so values such as `plugins.opencode.summarize.*`, `plugins.opencode.project_review.*`, `plugins.opencode.user_profile.*`, `[llm.providers.*]`, `[prompts]`, `milvus.*`, and `embedding.*` usually apply on the next capture, recall, index, or maintenance invocation. Restart OpenCode after `opencode.json` or plugin package changes; if capture behavior still looks stale after TOML edits, restart OpenCode or the capture daemon. After any answer, make clear that this is MemSearch memory configuration, not OpenCode's own memory/config system.
+
+When useful, remind the user that they can either continue using this `memory-config` skill for guided configuration, or manually run `memsearch config init` for global interactive setup, `memsearch config init --project` for project interactive setup, and `memsearch config set/get/list` for direct CLI changes.