| name | search-memory |
| description | Deep cross-memory search using parallel subagents. Use when asked broad conceptual questions like "what do we know about X", "have we solved X before", "find anything about X" — questions that could live in multiple memory files. Simple lookups (single known file) still use --search directly. |
| allowed-tools | Agent, Read, Grep |
| effort | medium |
Skill: search-memory
Description
Parallel subagent search across all memory categories. Spawns 4 agents simultaneously — one per category group — then aggregates their findings into a single ranked answer.
Trigger phrases:
- "what do we know about [X]"
- "have we seen [X] before"
- "search memory for [X]"
- "find anything about [X]"
- "check if we've dealt with [X]"
- Any question where the answer could live in 2+ memory files
Simple queries → skip this skill, use --search directly:
- "what's in lessons.md" → Read the file
- "grep for X in error-lookup" → Grep directly
- Known single-file lookups → no parallel needed
Memory Categories
| Agent | Files it searches |
|---|
| Agent A — Knowledge | lessons.md, decisions.md, regret.md |
| Agent B — Errors & Guards | error-lookup.md, critical-notes.md, guard-patterns.md |
| Agent C — Project State | project_status.md, code-map.md (if exists), your_journey_plan.md (if exists) |
| Agent D — Live Context | session_journal.md (last 20 entries), todo.md, tasks/velocity.md, tasks/skill_scores.md |
Memory root: [MEM] = value read from the current project's MEMORY.md
Steps
Step 0 — Resolve [MEM] (required before anything else)
Before searching, confirm the memory root is configured:
- Check if
[MEM] is defined in the current session context (set by Start Session or CLAUDE.md)
- If not known, look for it in the project's CLAUDE.md: grep for
\[MEM\] or memory path definition
- Verify at least one anchor file exists at the resolved path:
lessons.md or error-lookup.md
If [MEM] cannot be resolved or anchor files are missing — STOP:
⚠ Memory root not configured.
[MEM] is not set or the memory files don't exist yet.
Run: Start Session
This pulls your memory from GitHub and initializes [MEM] for this session.
If this is a new project, run Start Session once to set up your memory root.
Do not proceed to Step 1 until [MEM] resolves to a real path with at least one memory file present.
Step 1 — Extract the query
Identify the search term from the user's question. If vague ("that thing we fixed"), ask one clarifying question.
Step 2 — Launch 4 parallel agents
Spawn all 4 in a single message (they run concurrently):
Agent A prompt:
Search for "[QUERY]" across these memory files:
- [MEM]/lessons.md
- [MEM]/decisions.md
- [MEM]/regret.md
Use Grep to search each file for the query term and related terms.
Return: file name, matching line(s), and a 1-2 sentence summary of what was found.
If nothing found, return "No match in [file]".
Do not read whole files — grep only.
Agent B prompt:
Search for "[QUERY]" across these memory files:
- [MEM]/error-lookup.md
- [MEM]/critical-notes.md (or rules/critical-notes.md if not in memory root)
- [MEM]/guard-patterns.md
Use Grep to search each file for the query term and related terms.
Return: file name, matching line(s), and a 1-2 sentence summary of what was found.
If nothing found, return "No match in [file]".
Do not read whole files — grep only.
Agent C prompt:
Search for "[QUERY]" across these memory files:
- [MEM]/project_status.md
- [MEM]/java_reference.md (if exists)
- [MEM]/js_functions.md (if exists)
- [MEM]/html_css_reference.md (if exists)
Use Grep to search each file for the query term and related terms.
Return: file name, matching line(s), and a 1-2 sentence summary of what was found.
If nothing found, return "No match in [file]".
Do not read whole files — grep only.
Agent D prompt:
Search for "[QUERY]" across these memory files:
- [MEM]/session_journal.md (last 30 lines only — use Read with offset to get tail)
- [MEM]/todo.md
- [MEM]/tasks/velocity.md (if exists)
Use Grep + Read(limit) to search each file for the query term and related terms.
Return: file name, matching content, and a 1-2 sentence summary of what was found.
If nothing found, return "No match in [file]".
Step 3 — Aggregate results
Collect all 4 agent responses. Synthesize into:
## Memory search: "[QUERY]"
### Lessons / Decisions / Regret
[Agent A summary — or "Nothing found"]
### Errors / Guards / Critical Notes
[Agent B summary — or "Nothing found"]
### Project State / Reference
[Agent C summary — or "Nothing found"]
### Recent Context / Todo
[Agent D summary — or "Nothing found"]
---
**Bottom line:** [1-2 sentences: what we know, what we tried, what to watch out for]
Step 4 — Offer to jump to source
If any agent found a specific match, offer:
"Found in [file] — want me to read the full section?"
Notes
- Launch all 4 agents in ONE message — they must run in parallel, not sequentially
- If a file doesn't exist, the agent skips it silently (no error)
- Agents search only — they never write, edit, or modify memory files
- For kit memory root: read
[MEM] path from MEMORY.md or CLAUDE.md at session start
- This skill pairs with
act — search first, then act on what's found
