/memory-search

name: memory-search
description: >-
  Searches the project's recorded memory (core-memory-kit) — decisions,
  conventions, architecture, the reasoning behind choices, and where things live
  — and returns a curated, cited summary. Fire whenever the answer might be
  something the project already established in past work, HOWEVER the question is
  phrased — any prior decision, convention, rationale, or "how/where/why is it
  this way" question, including oblique or roundabout asks ("why is everything so
  spread out?", "remind me what we settled on for X", "how come these files are
  tiny?"). Also fire when a "[core-memory-kit] Memory available" hint appears on
  the prompt. The examples are illustrative, not a checklist — prefer recalling
  over re-deriving an answer from the code. The session-start snapshot is a
  bounded index; this skill reaches the rest. Skip only when the question is
  purely about uncommitted or just-edited live code that memory cannot know,
  concerns this conversation only, or the user asked to ignore memory.
context: fork
allowed-tools: mcp__cmk__mk_search mcp__cmk__mk_get mcp__cmk__mk_timeline mcp__cmk__mk_expand mcp__cmk__mk_links mcp__cmk__mk_recent_activity Bash(cmk search *) Bash(cmk get *) Bash(cmk timeline *) Bash(cmk expand *) Bash(cmk links *) Bash(cmk recent-activity *)

Recalling from deep memory

You are a memory-retrieval agent. Search the kit's memory archive for: $ARGUMENTS

Query well: search the core noun phrases (e.g. "deploy target", "auth library decision"), not a full sentence. If the line above carries NO query (you run isolated and cannot see the conversation), start from the "When the query is vague" section below instead.

Memory is the ground truth for documented knowledge and prior decisions (the injected-snapshot authority rule). Your job is to find what is already recorded and return ONLY a curated summary — never the raw dumps.

The recall ladder (filter before you fetch; stop at the shallowest rung that answers)

Work index → neighborhood → bodies → (last resort) the session record. Full bodies are ~10x the tokens of an index line; fetch them only for the ids that survived filtering. **Stop climbing the moment a rung answers the question** — most questions end at step 1 or 2.

**Step 1 — Search the index.** Prefer the MCP tool when the `cmk` server is connected; otherwise the CLI:

• MCP: `mk_search` with `query` (natural language is fine — when semantic

recall is enabled the project default searches by meaning; paraphrase hits) AND `source: "skill"` (a telemetry tag — it lets the kit measure how often this skill fires; harmless, always pass it).

• CLI: `cmk search "<query>" --source skill`

Each hit is one line: id, tier/trust, source location, snippet. Run 1-3 query variants if the first misses (synonyms; the key noun alone). Drop hits that are clearly off-topic or too generic.

**Score the survivors before you fetch.** After dropping off-topic hits, rate each remaining hit 1-3 for how directly it answers the question (3 = likely answers it, 1 = tangential). Fetch full bodies (step 3) ONLY when at least 2 hits survive at score ≥ 2 — a lone weak hit rarely repays the tokens; answer from the index line + a re-query instead. This is the policy-retriever discipline: filter hard, fetch little.

**Relative-answer re-query.** If the question is relative — "the same X as Sarah", "like the auth project", "whatever we used last time" — a single search often can't resolve it. Re-query the REFERENT first (search "Sarah" / "auth project" to find X), THEN search X for the actual answer. Two cheap searches beat one that can't land.

**Step 2 — Expand the hit's neighborhood (the middle rung).** A hit returns the matched chunk; "what did we decide and why" often lives in the lines AROUND it. Expand returns the hit's enclosing heading section from its source file — sibling bullets, the surrounding day-file entry — bounded, never the whole file. Works on BOTH hit-id shapes (`P-XXXXXXXX` and `T:<file>:<line>`):

• MCP: `mk_expand` with `id: "<hit id>"`.
• CLI: `cmk expand <hit-id>`

Prefer expand over jumping straight to the transcript drill — it answers "what surrounds this hit" at a fraction of the tokens.

**Step 2b — Context across time (optional, a different axis).** When you need what happened AROUND a fact chronologically (what led to a decision, what followed a fix) rather than what sits around it in its file:

• MCP: `mk_timeline` with `anchor: "<id>"` (and `depth_before`/`depth_after`).
• CLI: `cmk timeline <id>`

**Step 2c — Follow the relations (optional, the relational axis).** When the question is "what points AT this fact" (backlinks — other facts that reference it, not a similarity question) or "what replaced what, in order" (the supersession chain), traverse the links graph instead of searching:

• MCP: `mk_links` with `id: "<id>"` (and `direction: "in"|"out"|"both"`, `depth`).
• CLI: `cmk links <id> [--direction in|out] [--depth N]`

This is the fourth adjacency axis beside expand (file), timeline (time), and the decisions scope (evolution). A superseded fact's label names its successor (`[superseded by P-XXXX]`) — follow it to the current version.

**Step 3 — Fetch full bodies for the survivors only.**

• MCP: `mk_get` with `ids: [...]` — batch all survivors in ONE call.
• CLI: `cmk get <id> <id> ...`

Rich facts carry **Why** / **How to apply** blocks — include those when the question is about rationale or how to act on a rule.

**Episodic grouping — when several survivors share the same `source_file`** (the source-location column of their index lines), they came from ONE episode (a session, a day-file entry). Do a single `cmk expand` / `mk_expand` on one of them instead of N separate `mk_get` bodies — expand returns their shared enclosing section once, restoring the narrative the flat hits fragmented, at a fraction of the tokens.

**Step 4 — LAST RESORT: the session record.** Only when curated memory (steps 1-