Memory Search

Purpose / When to Activate

Activate when an agent needs to find relevant memory but does not know the exact file path, domain, or DEC ID.

This skill locates memory — it does not load it. After results are returned, the agent invokes

memory-retrieve

to load the specific files.

Use cases:

• "Which decisions relate to database connection pooling?" → Mode A (frontmatter: domain=infrastructure, tags contains database)
• "Where did we discuss pool exhaustion?" → Mode B (full-text keyword: "pool exhaustion")
• "What decisions are related to DEC-42?" → Mode C (cross-reference: DEC-42 → related_to + mentions)

---

Process

Mode A — Frontmatter Search

Search YAML frontmatter fields across

decisions/DEC-*.md

files.

1. Accept query as field-value pairs:

   {domain: "infrastructure", level: "operational"}

   and/or

   {tags: ["connection-pooling"]}

   and/or

   {related_to: ["DEC-5"]}

   and/or

   {status: "active"}

2. Grep frontmatter blocks (between

   ---

   delimiters) of all

   decisions/DEC-*.md

   files
3. Match files where ALL specified fields match (AND logic)
4. Extract

   id

   ,

   title

   , and matched field values from each hit
5. Rank by: exact tag match > domain match > level match
6. Return top 10 results

Mode B — Content Search

Full-text keyword search across ALL memory files.

1. Accept query as 1-3 keywords (e.g.,

   "pool exhaustion"

   ,

   "scoring formula"

   )
2. Grep all files under

   contexts/memory/

   for keyword matches
3. For each hit, extract:

   • file_path

     (relative to

     contexts/memory/

     )

   • id

     from frontmatter (if present)

   • title

     from first

     #

     heading

   • excerpt

     — the matching line ± 1 line of context (~50 tokens)
4. Rank by: number of keyword matches > file recency (

   updated_at

   )
5. Return top 10 results
6. Never return more than ~2,000 tokens total

Mode C — Cross-Reference Search

For a given DEC ID, find all files that reference it + traverse

related_to

(depth 1).

1. Accept query as a single DEC ID (e.g.,

   DEC-42

   )
2. Direct mentions: grep all files under

   contexts/memory/

   for the literal string

   DEC-42

3. Frontmatter

   related_to

   : grep

   related_to:

   lines in

   decisions/DEC-*.md

   for the target ID
4. Outbound relations: read the target file's own

   related_to

   field → list those DEC IDs
5. Deduplicate and merge results into a single list
6. For each result, extract:

   file_path

   ,

   id

   ,

   title

   ,

   relevance

   (direct_mention | related_to_inbound | related_to_outbound)
7. Rank: related_to_inbound > related_to_outbound > direct_mention
8. Return all results (typically <15 files)

---

Quality Checks

• Never loads full file content — only returns paths, IDs, titles, and short excerpts
• Total output stays under ~2,000 tokens
• Mode A searches frontmatter only (fast, structured)
• Mode B searches content (slower, broader — use sparingly)
• Mode C is bounded to depth 1 (no recursive graph traversal)
• Results are always ranked by relevance
• Never modifies any file

---

Outputs

search_results

— ranked list of memory file references:

- file_path: decisions/DEC-42.md
  id: DEC-42
  title: "Use connection pooling for database access"
  relevance: related_to_inbound  # or: frontmatter_match | content_match | direct_mention | related_to_outbound
  excerpt: "prevents connection exhaustion under load"  # ~50 tokens max, absent in Mode A

Agent receives this list and decides which files to load via

memory-retrieve

.

---

Non-Goals

This skill must NOT:

• Load full file contents (that is

  memory-retrieve

  )
• Modify any memory files (that is

  memory-ingest

  )
• Make decisions about which results to act on (that is the agent's job)
• Perform recursive graph traversal beyond depth 1
• Search outside

  contexts/memory/

Memory-search finds. Memory-retrieve loads. The agent decides.