@zilliz/memsearch-opencode 0.3.4 → 0.3.6

package/package.json

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

package/prompts/memory_to_skill.txt

@@ -0,0 +1,74 @@
+You are distilling reusable skills from {{AGENT_NAME}}'s recent memory journals.
+
+Project directory: {{PROJECT_DIR}}
+Input memory directory: {{INPUT_DIR}}
+
+A "skill" is procedural memory: a reusable, multi-step procedure for getting a
+recurring task done (how to run the app, how to deploy, how to debug a class of
+error). It is NOT a fact, a decision, or a preference — those belong in
+PROJECT.md and USER.md.
+
+You will receive recent memory journal entries and a list of existing skills
+(which you MAY revise). Propose or revise skills only when they clearly earn it.
+
+Be conservative. Quality over quantity. Most runs should return an empty list.
+
+A NEW workflow qualifies as a candidate ONLY when ALL of these hold:
+- It is a repeatable multi-step procedure, not a one-off action or a fact.
+- It recurs across at least {{MIN_OCCURRENCES}} distinct sessions or days in the
+  journals below.
+- It generalizes into a reusable capability. If it is tightly coupled to one
+  specific ticket, one specific value, or a one-time condition, do NOT propose it.
+- The recent runs were not immediately corrected, abandoned, or undone (a
+  workflow the user kept fighting is not a good skill).
+- It is not already covered by an existing skill.
+
+You may also REVISE an existing skill (re-emit it with the SAME name and a
+corrected body) when the recent journals show that procedure has genuinely
+changed — a tool, command, flag, or step is now done differently. Only revise when
+there is clear evidence of change; do not rewrite for style.
+
+Rules:
+- Return only a JSON object, with no prose outside JSON.
+- Use {"skills": []} when nothing in the journals qualifies. This is the common case.
+- For each candidate, write a clean, portable SKILL.md body in "body": step-by-step
+  instructions an agent can follow. Do not include YAML frontmatter — only the
+  markdown body. Keep it concise and concrete.
+- "name" must be a short lowercase slug (letters, digits, dashes), e.g. "run-tests".
+  It becomes the skill's command name. Do not reuse an existing skill name.
+- "description" is one line: what the skill does AND when it should trigger.
+  Lead with the verbs a user would actually type ("run", "deploy", "debug").
+- "occurrences" is how many distinct sessions/days you saw this workflow.
+- "sources" lists the journal file names the workflow was observed in.
+- Do not copy raw journal text wholesale into the body; abstract it into a procedure.
+
+How to write a good skill body (this is what makes the skill usable):
+- Write imperative, numbered steps an agent can follow top to bottom.
+- Be concrete: real commands, file paths, and flags — not vague prose.
+- Keep it focused and short. A skill loads only when triggered, so include just
+  what is needed to do this one task well, and push rare detail to the end.
+- State any preconditions, and where useful, when NOT to use the skill.
+- Never bake in secrets, tokens, or one-off values; describe them as placeholders.
+- Make it self-contained: an agent on a clean checkout should be able to follow it.
+- The "description" is the trigger signal — if it does not name the situation and
+  the verbs a user would type, the skill will never fire. Spend care on it.
+
+Accuracy — confirm from the original, do not hallucinate:
+- The journal entries are LOSSY SUMMARIES; they drop the exact commands, flags,
+  and paths. Do not reconstruct those from the summary alone.
+- Before writing a step's exact command, confirm it from the original transcript.
+  Each journal entry has an anchor comment naming the original conversation; the
+  key differs by agent — `transcript:<file>` (Claude Code), `rollout:<file>`
+  (Codex), or `db:`/a `session:` id (OpenCode). For a file-based transcript, run
+  `memsearch transcript <file>` (optionally `--turn <id>`) to read the original
+  turns WITH their tool calls — that is where the real commands and output live.
+  For a session/db anchor (OpenCode), use that platform's transcript script.
+- If you cannot read the transcript or confirm a detail, capture only what the
+  summary clearly states; keep the step general or omit it — a plausible-but-wrong
+  command is worse than none. Never invent specifics.
+- Prefer fewer, verified steps over a complete-looking but partly-guessed procedure.
+
+JSON examples:
+{"skills":[]}
+
+{"skills":[{"name":"run-tests","description":"Run the project's test suite and report failures. Use when asked to run tests, check tests, or verify a change.","body":"## Run the tests\n\n1. ...\n2. ...","occurrences":4,"sources":["2026-06-12.md","2026-06-14.md"],"reason":"Test run procedure recurred across 4 sessions."}]}

package/scripts/maintenance-runner.py

@@ -363,7 +363,7 @@ def ensure_memsearch_importable() -> None:
 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"):
+    for task in ("project_review", "user_profile", "memory_to_skill"):
         if getattr(cfg.prompts, task, ""):
             continue
         prompt_file = prompts_dir / f"{task}.txt"
@@ -376,7 +376,14 @@ def run_native_provider(ctx, prompt: str) -> str:
     env = {**os.environ, "MEMSEARCH_NO_WATCH": "1"}
 
     if ctx.platform == "claude-code":
-        cmd = ["claude", "-p", "--strict-mcp-config", "--tools", "", "--no-session-persistence", "--no-chrome"]
+        cmd = ["claude", "-p", "--strict-mcp-config", "--no-session-persistence", "--no-chrome"]
+        # Skill distillation needs to read original transcripts for exact commands.
+        # Open a narrow hole — Bash limited to the two read-only memsearch drill
+        # commands — only for that task; other maintenance keeps all tools off.
+        if getattr(ctx, "task", "") == "memory_to_skill":
+            cmd += ["--tools", "Bash", "--allowed-tools", "Bash(memsearch transcript:*) Bash(memsearch expand:*)"]
+        else:
+            cmd += ["--tools", ""]
         if model:
             cmd += ["--model", model]
         cmd += [
@@ -388,7 +395,9 @@ def run_native_provider(ctx, prompt: str) -> str:
         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:
+        with tempfile.NamedTemporaryFile(
+            prefix="memsearch-codex-maintenance-", suffix=".txt", delete=False
+        ) as output_file:
             output_path = Path(output_file.name)
         cmd = [
             "codex",
@@ -476,6 +485,20 @@ def main() -> int:
             force=args.force,
             llm_runner=llm_runner,
         )
+
+        # Distill recurring workflows into candidate skills (procedural memory).
+        # Same session-end trigger, due-state, and llm_runner as the tasks above;
+        # this only ever touches the candidate store, never an agent's skills dir.
+        from memsearch.skills import distill as distill_skills
+
+        skill_result = distill_skills(
+            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
@@ -484,12 +507,15 @@ def main() -> int:
             os.chdir(old_cwd)
 
     payload = [result.__dict__ for result in results]
+    payload.append({"task": "memory_to_skill", **skill_result.__dict__})
     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")
+        skill_detail = f": {skill_result.reason}" if skill_result.reason else ""
+        sys.stdout.write(f"memory_to_skill: {skill_result.action}{skill_detail}\n")
     return 0
 
 

package/skills/memory-config/SKILL.md

@@ -19,6 +19,7 @@ When this skill is triggered, inspect the user's request text. If there is no co
 - "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.
+- "skill/distill/extract a skill/memory-to-skill": procedural-memory distillation — enable or tune it here, or use the dedicated `/memory-to-skill` skill to review and install candidates.
 - "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.
@@ -145,6 +146,11 @@ model = ""
 min_interval_hours = 24
 input_dir = ".memsearch/memory"
 output_file = ".memsearch/USER.md"
+
+[plugins.opencode.memory_to_skill]
+enabled = false
+min_occurrences = 3   # how many times a workflow must recur before it is distilled
+paths = []            # where installed skills are copied; empty = ask the user
 ```
 
 Provider rules:
@@ -192,6 +198,7 @@ Prompt overrides:
 summarize = ""
 project_review = ""
 user_profile = ""
+memory_to_skill = ""
 ```
 
 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.

package/skills/memory-to-skill/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: memory-to-skill
+description: "Turn workflows from your MemSearch memory into reusable skills. Use when the user asks to make/create/extract/distill a skill from what they just did or from past work, review skill candidates, install a distilled skill, or 'turn this into a skill'. Manages MemSearch procedural-memory candidates under .memsearch/skill-candidates/, not OpenCode's own skills system."
+---
+
+You manage MemSearch's **procedural memory**: skills distilled from the work you
+repeat — a third layer beside the daily journals (episodic) and PROJECT.md /
+USER.md (semantic). State once that this is MemSearch skill distillation, not
+OpenCode's built-in skills system.
+
+Stages: **0** memory journals → **1** candidate (`.memsearch/skill-candidates/`,
+a git-tracked store that keeps evolving) → **2** installed (an agent skill dir).
+Candidates are never installed automatically; installing is always a human step.
+
+## Intent routing
+
+- "make/turn this into a skill", "from what we just did" → **A. Capture now**.
+- "what skills / review candidates / install X" → **B. Review & install**.
+- "mine my history / find recurring workflows" → **C. Distill from history**.
+- "enable / configure / how eager" → **D. Configure**.
+- Unclear or empty → run **B**'s `list`; if empty, offer A or C.
+
+## A. Capture what you just did (0→1→2)
+
+You already have the context, so **draft the skill yourself** — do not call the
+background distiller for this. Write a SKILL.md **body** (markdown, no
+frontmatter): imperative numbered steps for the recurring task, concrete commands
+and paths, no secrets, self-contained.
+
+**Be exact — do not guess.** You have the live session for what you just did, so use the real commands, paths, and output, not approximations. If a detail is uncertain, verify it (re-read the relevant files or the transcript) or keep that step general — a wrong command is worse than a vague one. Then persist it as a candidate:
+
+```bash
+printf '%s' "## <title>\n\n1. ...\n2. ..." | memsearch skills add \
+  --name "<short-slug>" \
+  --description "<what it does AND when it should trigger — lead with the verbs a user types>" \
+  --body-file -
+```
+
+`add` handles slugging, standard frontmatter, meta.json, and the git commit — no
+LLM is involved. Then show it to the user and install it (see **B**). Finally,
+check whether background distillation is on; if not, offer to enable it (so
+recurring workflows get captured automatically going forward) — do not force it.
+
+## B. Review & install candidates (1→2)
+
+```bash
+memsearch skills list            # add -j for sources / installed paths
+```
+
+Before recommending or installing, skim the candidate's body: if a step looks uncertain or loosely summarized, re-check it against the source (open the transcript if needed) or flag it to the user and let them decide — installing copies the candidate as-is, so this is the last chance to catch a wrong step.
+
+Pick one, resolve where to install (ask if unset), then install:
+
+```bash
+memsearch config get plugins.opencode.memory_to_skill.paths 2>/dev/null || echo "[]"
+memsearch skills install <name> --path .agents/skills
+```
+
+If the list is **empty**, background distillation is likely off or has not run.
+Offer the user a choice: capture from recent work now (**A**), distill from
+history (**C**), or enable the background pass (**D**).
+
+## C. Mine history for recurring workflows (0→1)
+
+To pull skills out of past work (not just the current session), read the recent
+journals yourself — they live in `.memsearch/memory/*.md` — and look for
+multi-step procedures that recur across several sessions. Draft each genuinely
+reusable one and persist it with `memsearch skills add` (one call per skill), the
+same way as **A**. Use your own judgment: only propose procedures that recur and
+generalize, not one-offs from a single day.
+
+**Drill into the original before drafting.** The journal bullets are a lossy summary; the exact commands, flags, and paths live in the original conversation. OpenCode stores transcripts in its session database (not a file), and the journal anchor carries a `session:` id (and `turn:` when present). Run `python3 __INSTALL_DIR__/scripts/parse-transcript.py <session_id>` (add `--turn <id>` when the anchor has one) to read the original turns with their tool calls — that is where the executed commands and output live. Write the skill from that. If the shown excerpt feels incomplete, skim nearby turns in the same original source before committing to exact commands or paths. If you cannot read it or confirm a detail, keep the step general or omit it — never fabricate.
+
+The background pass mines automatically when enabled, but it can only see the summaries; doing it here on demand lets you read the original transcripts, so the result is more accurate.
+
+## D. Configure
+
+```bash
+memsearch config get plugins.opencode.memory_to_skill.enabled 2>/dev/null || echo "false"
+# enable the background pass (do not enable silently)
+memsearch config set plugins.opencode.memory_to_skill.enabled true --project
+# how eagerly history-mining distils (default 3; lower = more eager)
+memsearch config set plugins.opencode.memory_to_skill.min_occurrences 3 --project
+# pre-set install targets (otherwise you are asked at install time)
+memsearch config set plugins.opencode.memory_to_skill.paths '[".agents/skills"]' --project
+```
+
+Note: `enabled` only gates the **background** (session-end) pass. The explicit
+commands above (`skills add`, `skills install`) always work, and you can mine history (C) directly.
+
+## Install paths
+
+- `.agents/skills` — **project-local (recommended)**: a skill from this project's
+  memory is usually most relevant here.
+- `~/.agents/skills` — global: available across all your projects.
+- a custom path, or several (one skill can be installed to multiple dirs).
+
+Each agent reads skills from its own directory: Claude Code `.claude/skills/`;
+Codex and OpenCode `.agents/skills/` (the shared standard, also read by Cursor
+etc.); OpenClaw `.openclaw/skills/`. Claude Code does **not** read `.agents/skills/`.
+Install to multiple paths to cover several agents.
+
+## Guardrails
+
+- Never enable the feature, change install paths, or install a candidate without
+  the user's go-ahead.
+- Do not hand-edit the store; create candidates with `memsearch skills add` and let
+  the git-tracked store at `.memsearch/skill-candidates/` keep history.