---
name: memory-search
description: Search the user's persistent memory directory for relevant past observations. Invoke proactively before answering any question that touches past project work, prior decisions, workflow preferences, or named entities (projects, services, repos, infrastructure) that may have been recorded earlier. Use when the request mentions named projects, past decisions ("how did we", "what did we decide", "remember when"), or any subject likely to have history. Also invoke when the user asks "what do you remember about X" or similar.
version: 1.0.0
---

# memory-search

Search the persistent memory directory under `$HOME/.claude/projects/<dev-slug>/memory/` for relevant past observations.

`<dev-slug>` is computed from `$HOME/Development` with `/` replaced by `-`. For the current user it resolves at runtime — compute it rather than hardcoding paths.

## When to invoke

**Proactively, before answering**, whenever the conversation touches:
- A named project, service, repo, or piece of infrastructure
- A past decision ("how did we", "what did we decide", "remember when", "we agreed", "we chose")
- A workflow preference (deploy patterns, container tooling, theme, build choices)
- A user-recall request ("what do you remember about X")

The always-loaded `MEMORY.md` index is for orientation only. For retrieval, search.

## How to search

```bash
MEM_DIR="$HOME/.claude/projects/$(printf '%s' "$HOME/Development" | sed 's|/|-|g')/memory"

# 1. List files matching keywords
grep -ril '<keyword>' "$MEM_DIR" --exclude-dir=archive

# 2. Show matching lines with context
grep -in -C 1 '<keyword>' "$MEM_DIR"/*.md
```

Iterate. Try multiple keyword variants — a query about "the cert flow" should also try "certification", "endorsement", "badge". Agents are good at refining greps; use that.

For broader semantic matches, fall back to reading `MEMORY.md` then opening the most plausible files in full.

## What to do with results

- Read the full file(s) of the strongest matches before answering
- Cite the memory by filename when you use it
- If a memory contradicts what you'd otherwise say, trust the memory but verify against current code/state — memories are point-in-time observations
- If you find an outdated memory, flag it for the user; don't silently update it (writes are deferred to session boundaries per `~/.claude/CLAUDE.md`)

## Excluded paths

- `archive/` — superseded files; don't search these unless explicitly asked about historical state