@zilliz/memsearch-opencode 0.3.4 → 0.3.5

package/package.json

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

package/prompts/memory_to_skill.txt

@@ -0,0 +1,59 @@
+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.
+
+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"
@@ -388,7 +388,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 +478,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 +500,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,103 @@
+---
+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. 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
+```
+
+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.
+
+The background pass does this automatically when enabled; doing it here on demand
+uses your own reasoning and needs no provider configuration.
+
+## 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.