git:20260908.4ad9ee4 to git:20261020.abd5022

10 added, 40 removed. Audit A to A.

---

name: memory-recall

- description: "Search and recall relevant memories from past sessions via memsearch. Use when the user's question could benefit from historical context, past decisions, debugging notes, previous conversations, or project knowledge -- especially questions like 'what did I decide about X', 'why did we do Y', or 'have I seen this before'. Also use when you see `[memsearch] Memory available` hints injected via SessionStart or UserPromptSubmit. Typical flow: search for 3-5 chunks, expand the most relevant, optionally deep-drill into original transcripts via the anchor format. Skip when the question is purely about current code state (use Read/Grep), ephemeral (today's task only), or the user has explicitly asked to ignore memory."

- allowed-tools: Bash

+ description: "Search and recall relevant memories from past sessions via MemSearch. Use for past decisions, debugging notes, previous conversations, and project knowledge, especially when the context includes a MemSearch memory hint. Skip purely current-code questions or when the user asks to ignore memory."

---

- You are a memory retrieval agent for memsearch. Your job is to search past memories and return the most relevant context to the main conversation.

- ## Project Collection

- Collection: !`bash -c 'root=$(git rev-parse --show-toplevel 2>/dev/null || true); if [ -n "$root" ]; then bash __INSTALL_DIR__/scripts/derive-collection.sh "$root"; else bash __INSTALL_DIR__/scripts/derive-collection.sh; fi'`

- ## Your Task

- Search for memories relevant to: $ARGUMENTS

+ Search memories relevant to the user's current question. The plugin's tools resolve the requesting session's checkout and configured collection, and recover pending capture before recall.

## Steps

- 1. **Search**: Run `memsearch search "<query>" --top-k 5 --json-output --default-collection <collection name above>` to find relevant chunks.

- - If `memsearch` is not found, try `uvx memsearch` instead.

- - Choose a search query that captures the core intent of the user's question.

- 2. **Evaluate**: Look at the search results. Skip chunks that are clearly irrelevant or too generic.

- 3. **Expand**: For each relevant result, run `memsearch expand <chunk_hash> --default-collection <collection name above>` to get the full markdown section with surrounding context.

- 4. **Deep drill (optional)**: If an expanded chunk contains transcript anchors (HTML comments with session info), and the original conversation seems critical:

- - If the anchor contains `turn:`, run `python3 __INSTALL_DIR__/scripts/parse-transcript.py <session_id> --turn <turn_id> --context 3` to retrieve the original conversation around that turn.

- - If the anchor only contains `db:` / `session:` with no turn cursor, run `python3 __INSTALL_DIR__/scripts/parse-transcript.py <session_id> --limit 10` to retrieve the most recent turns from the SQLite database.

- - If the anchor format is unfamiliar (e.g. `transcript:`, `rollout:` instead of `db:`), try reading the referenced file directly to explore its structure and locate the relevant conversation by the session or turn identifiers in the anchor.

- 5. **Return results**: Output a curated summary of the most relevant memories. Be concise — only include information that is genuinely useful for the user's current question.

- ## When unsure what to search

- If the user's question is vague or you can't form a concrete search query, explore the raw markdown first — it is the source of truth for memory:

- - `ls -t .memsearch/memory/ | head -10` — recent daily logs

- - `grep -h "^## " .memsearch/memory/*.md | sort -u | tail -40` — session headings across all days

- - `cat .memsearch/memory/<YYYY-MM-DD>.md` — read a specific day

- Once a concrete topic jumps out, go back to `memsearch search` with a specific query.

+ 1. Use `memory_search` with a concrete query and `top_k: 5`. It returns text containing a JSON array of objects with `chunk_hash`, `content` and `source`. When calling through `execute`, return the search result and inspect its text before selecting hashes. Evaluate relevance before expanding results.

+ 2. Use `memory_get` with the most promising `chunk_hash` values to read full Markdown sections.

+ 3. For claims requiring original dialogue, use `memory_transcript` with `session_id`, `turn_id` and `db_path` from the expanded `session:` / `turn:` / `db:` anchor. Set `context: 3`; for an anchor without a turn, use `limit: 10`.

+ - If OpenCode transcript lookup fails after an upgrade, distinguish an incompatible host/plugin pair, an unavailable database or session/turn, and an incomplete V1-to-V2 database migration. See [OpenCode diagnostics](../memory-config/references/opencode.md), also used by `memory-config`. Check the referenced conversation only; a lookup failure does not justify scanning unrelated transcripts.

+ - Keep existing markdown and `session:` / `turn:` / `db:` anchors unchanged. Return useful search/expand results with the L3 limitation stated. If host migration is needed, direct the user to OpenCode's migration guidance; do not migrate the database or rewrite anchors during recall. Do not describe a summary as verified original dialogue.

- ## Output Format

+ 4. Return a concise account of relevant facts with dates and source files. Distinguish journal summaries from verified dialogue. If nothing relevant is found, say so.

- Organize by relevance. For each memory include:

- - The key information (decisions, patterns, solutions, context)

- - Source reference (file name, date) for traceability

+ If the query is unclear, inspect recent daily Markdown files under `.memsearch/memory/` to identify a topic, then search. Avoid unrelated memory and transcript scans. A capture-pending diagnostic means new memories may still be recovering; existing Markdown/search results remain useful.

- If nothing relevant is found, simply say "No relevant memories found."

+ These tools require OpenCode V2. V1 users pin the published `@zilliz/memsearch-opencode@0.3.17`. Plugin 0.4.0 supports OpenCode >=2.0.32 <3. OpenCode's own database migration remains user-owned.