memory-search

---
name: memory-search
description: "Search project memory files with ranked results. Use when 'search memory', 'find in memory', 'what do I know about X', 'recall X', or when the user asks to find specific information across memory files."
mode: [all]
effort: low
version: 1.0.0
tier: [core]
---

# Memory Search v0 — Ranked grep across memory files

Fast ranked search across project memory files (`~/.claude/projects/*/memory/`).
Returns results ranked by relevance (frontmatter type + severity + recency).

Inspired by ruflo's embedding cache pattern — v0 uses ripgrep with frontmatter
parsing for ranking. Future v1 will use SQLite FTS5, v2 will add Ollama embeddings.

## When to Use

- User asks "what do I know about X?" or "search memory for Y"
- User says "recall", "find in memory", "memory search"
- Before starting work that might overlap with existing knowledge
- When `/atlas memory-search <query>` is invoked
- When `knowledge-builder` or `memory-dream` need to check for duplicates

## Execution Steps

1. **Identify memory directories** for the current project:
   ```bash
   MEMORY_DIR=$(find ~/.claude/projects/ -maxdepth 2 -name "memory" -type d 2>/dev/null | head -5)
   ```
   Also check project-local `memory/` if it exists in cwd.

2. **Run ripgrep** with JSON output for structured parsing:
   ```bash
   rg --json -i -l "<query>" $MEMORY_DIR | head -30
   ```

3. **For each matching file**, extract frontmatter metadata:
   ```bash
   head -10 <file> | grep -E "^(name|type|description):"
   ```

4. **Rank results** by these weights (highest first):
   | Factor | Weight | Logic |
   |--------|--------|-------|
   | **Type match** | 3x | `feedback` > `project` > `lesson` > `reference` > `user` |
   | **Severity** | 2x | ⭐⭐⭐⭐⭐ = 5, ⭐⭐⭐ = 3, etc. (from filename or content) |
   | **Recency** | 1x | File mtime — newer = higher rank |
   | **Match density** | 1x | More matches in file = higher rank |

5. **Display results** as a ranked table:
   ```
   🔍 Memory Search — "<query>" (N results)
   ──────────────────────────────────────────
   # │ Score │ Type     │ File                          │ Match Preview
   1 │ 8.5   │ feedback │ feedback_ci_verify_before_...  │ "Iron Law LAW-CI-VERIFY-001..."
   2 │ 6.2   │ lesson   │ lesson_alembic_idempotent_...  │ "alembic crashes on duplicate..."
   3 │ 4.0   │ project  │ project_gms_pilot_approved_... │ "Sprint 1 Day 2 shipped..."
   ```

6. **If user wants details**, read the top result(s) with `Read` tool.

## Quick Reference

```bash
# Search all memory dirs for a keyword
rg -i -l "keyword" ~/.claude/projects/*/memory/ | head -20

# Search with context (3 lines around match)
rg -i -C 3 "keyword" ~/.claude/projects/*/memory/ | head -50

# Search by frontmatter type
rg -l "^type: feedback" ~/.claude/projects/*/memory/ | xargs rg -l "keyword"

# Search recent files only (last 7 days)
find ~/.claude/projects/*/memory/ -name "*.md" -mtime -7 | xargs rg -l "keyword"
```

## Limitations (v0)

- **No semantic search** — exact keyword match only (v2 will add embeddings)
- **No index** — scans files on every query (v1 will add SQLite FTS5)
- **Ranking is heuristic** — based on type + severity + recency, not relevance scoring
- **Cross-project** — searches ALL project memory dirs (may return noise from other projects)

## Upgrade Path

| Version | Mechanism | Effort | Benefit |
|---------|-----------|--------|---------|
| **v0** (this) | ripgrep + frontmatter parsing | 2h | Works now, zero dependencies |
| **v1** | SQLite FTS5 (`~/.atlas/runtime/memory.db`) | 6-8h | Structured queries, faster for large memory sets |
| **v2** | Ollama embeddings (VM 551 GPU) | 16-24h | Semantic search ("things like X") |

## Verification

```bash
# Test: search memory for a known term
rg -i -c "CI" ~/.claude/projects/*/memory/*.md | sort -t: -k2 -rn | head -5
# Expected: several files with match counts

# Test: frontmatter extraction
head -5 ~/.claude/projects/*/memory/feedback_ci_verify_before_merge_mandatory.md
# Expected: name, description, type fields visible
```