pmm-query

name	pmm-query
description	Query memory — context-first recall with deep traversal across vectors, graph, and taxonomy when needed. Trigger on: "pmm-query", "/pmm-query", "query memory", "search memory", "recall", "what did we decide about", "find in memory", "look up", "what do we know about", or any request to search or recall information from memory files.

pmm-query

Explicit memory recall. Context-first — answers from already-loaded files before any agent dispatch. Supports free-text questions, attribution filters, date ranges, file scoping, deep traversal, and prose or dump output.

Query: $ARGUMENTS

If $ARGUMENTS is empty, ask the user what to search for before proceeding.

---

Routing Table

Map question type to target file(s):

Question type	Target file(s)
Decisions / decided / ratified	decisions.md
Preferences / style / how user works	preferences.md
Tone / voice / reasoning / lens	voices.md
Recent work / latest / just shipped	last.md, progress.md
Relationships / how things connect	graph.md, vectors.md
History / arc / timeline	timeline.md
Rules / directives / standing instructions	standinginstructions.md
People / tools / systems	assets.md
Facts / long-term / background	memory.md
Processes / workflows	processes.md
Mistakes / lessons / errors	lessons.md
Categories / naming / taxonomy	taxonomies.md
Ambiguous / broad	all active files

---

Execution

Step 1 — Parse Query

Extract from $ARGUMENTS:

• Keyword / question — everything that is not a filter or modifier
• Attribution filter — by namespace:name (e.g. by user:raffi, by agent:leith)
• Date filter — since YYYY-MM-DD or before YYYY-MM-DD
• File scope — in <filename> (e.g. in decisions, in lessons) — search only that file
• Deep flag — presence of the word deep → set deep=true, remove from keyword
• Dump flag — presence of the word dump → set dump=true, remove from keyword

Step 2 — Context-First Routing

Read memory/config.md for Session Start mode.

If Mode: lazy — memory files are already in context (injected by the SessionStart hook). Execute Steps 3–8 directly in the main context window without dispatching any agent. Tier 1 files are in-context. For Tier 2 files (graph.md, vectors.md, taxonomies.md, assets.md), use the Read tool to load the relevant file before searching — do not load all four, only what the routing table requires.

If Mode: eager — fall through to Agent Dispatch at the end of this document.

Step 3 — Search

For each target file (respecting routing table and any in <file> scope):

1. Check or Read the file (Tier 1 = already in context; Tier 2 = Read on demand)
2. Match entries containing the keyword (case-insensitive)
3. Apply attribution filter: only include entries where the line or nearby heading contains [namespace:name] matching the filter
4. Apply date filter: only include entries whose date prefix (YYYY-MM-DD) satisfies ≥ since or ≤ before
5. Collect all matches with their source file

Read memory/config.md to confirm which files are active. Skip deactivated files.

Step 4 — Deep Traversal

Skip if deep=false.

Expand the result set using similarity, graph, and taxonomy data. Run regardless of whether Step 3 found results.

4a — Vector cluster expansion (vectors.md):

1. Read (or use in-context) vectors.md
2. Find clusters whose name or member list contains the keyword
3. Collect all member concepts from matched clusters
4. Find similarity lines ([[A]] ↔ [[B]] | score: ...) where A or B matches — collect the paired concept if score ≥ 0.6
5. Search all active files for each expanded concept. Tag new matches [via vectors]

4b — Graph edge traversal (graph.md):

1. Read (or use in-context) graph.md
2. Find edges where the keyword appears in either node ([[keyword]])
3. Collect neighbour nodes (one hop only)
4. Search all active files for each neighbour. Tag new matches [via graph]

4c — Taxonomy broadening (taxonomies.md):

1. Read (or use in-context) taxonomies.md
2. Find categories or classifications containing the keyword
3. Collect sibling terms in those categories
4. Search all active files for each sibling. Tag new matches [via taxonomy]

Deduplicate — results already found in Step 3 should not be listed again.

Step 5 — Full File Escalation (T3)

If Steps 3 and 4 returned no results:

1. Read memory/config.md for the Active Files list
2. For each active file loaded with tail:N, header, or skip at session start: re-read the file in full using the Read tool
3. Search the full content for the query keyword
4. If matches found, collect them and proceed to Step 7 (format output)
5. If still no matches, proceed to Step 6 (git fallback)

Step 6 — Beyond-Window Gate

Only if Steps 3, 4, and 5 together returned no results.

Check memory/config.md for ## Recall Beyond Window → Mode:

If Mode: prompt — present AskUserQuestion with three options:

• Yes, search git history — dispatch a minimal git-history agent (no file reads; memory is in context):

  Run: git log --all --grep="<keyword>" --oneline
  For each matching commit: git show <hash> -- memory/
  Return the relevant lines and which commit they came from.
  

  Use the Readonly Agent Model from config (default: haiku). Incorporate results into Step 8 output tagged (from git history, commit <hash>).

• Yes, and don't ask me again — same dispatch, then update memory/config.md: replace - Mode: prompt under ## Recall Beyond Window with - Mode: auto

• No — return: No record found in the current memory window.

If Mode: auto — silently dispatch the minimal git-history agent (no file reads; same prompt as above).

Step 7 — Cross-Reference Enrichment

Skip if deep=true (graph.md was already traversed in Step 4b).

Otherwise: if results mention a named entity (person, tool, system, concept) that also appears in graph.md or assets.md:

• Read those files if not already in context
• Append a Related context: note (1–2 lines) if it genuinely enriches the result
• Do not bloat — only include if it adds something the main results don't already say

Step 8 — Format Output

Branch A — Prose mode (default, dump=false):

Synthesize a narrative answer from all collected results.

Rules:

• Write in concise, direct prose — answer the question, don't describe what files say
• Weave evidence from multiple source files into a coherent response
• Cite sources inline as parentheticals: (decisions.md), (timeline.md, 2026-03-17)
• Preserve attribution tags inline where relevant: [user:raffi]
• For deep-mode results, note provenance naturally: "A related concept, X (via graph), also shows..."
• For git history results: "(from git history, commit abc1234)"
• End with a single Sources: footer line listing all files that contributed
• If no results after all fallbacks: No record found in the memory files.
• No header block, no match counts — start directly with the narrative

<synthesized narrative answering the user's question, citing sources inline>

Sources: decisions.md, timeline.md, graph.md

Branch B — Dump mode (dump=true):

PMM Query Results
=================
Query: <original query>
Filters: <attribution filter> | <date filter> | <file scope> (or "none" if no filters)
Mode: <deep+dump | dump>
Found: N result(s) in M file(s)

--- <filename>.md ---
<verbatim matching entry, including attribution tag if present>

--- <filename>.md [via vectors] ---
<entry found through vector cluster/similarity expansion>

--- <filename>.md [via graph] ---
<entry found through graph edge traversal>

--- <filename>.md [via taxonomy] ---
<entry found through taxonomy broadening>

[Related context]
<brief enrichment from graph.md/assets.md, if applicable>

• Group results by source file
• Show the full entry (heading + body), not just the matching line
• Preserve attribution tags verbatim
• Tag deep traversal results with provenance
• Git history fallback: --- git history (commit abc1234) ---
• If no results: No record found in the memory files.
• No preamble — start directly with PMM Query Results

---

Agent Dispatch (eager mode)

Used only when Mode: eager.

Dispatch a general-purpose agent using the Readonly Agent Model from memory/config.md (default: haiku). Replace <project-root> with the actual project root path and <user-query> with $ARGUMENTS.

Query PMM memory files. This is a READ-ONLY task — do not edit any files.

Project root: <project-root> User query: <user-query>

Step 1 — Parse Query

Extract from the user query:

• Keyword / question — core search term
• Attribution filter — by namespace:name
• Date filter — since YYYY-MM-DD or before YYYY-MM-DD
• File scope — in <filename>
• Deep flag — word deep present
• Dump flag — word dump present

Step 2 — Route to Relevant Files

If file scope is set, search only that file. Otherwise use the routing table:

• Decisions / ratified → decisions.md
• Preferences / style → preferences.md
• Tone / voice / lens → voices.md
• Recent work / latest → last.md, progress.md
• Relationships → graph.md, vectors.md
• History / timeline → timeline.md
• Rules / standing → standinginstructions.md
• People / tools → assets.md
• Facts / background → memory.md
• Processes / workflows → processes.md
• Mistakes / lessons → lessons.md
• Categories / naming → taxonomies.md
• Ambiguous / broad → all active files

Read <project-root>/memory/config.md to confirm active files. Skip deactivated files.

Step 3 — Search

For each target file:

1. Read the file
2. Match entries containing the keyword (case-insensitive)
3. Apply attribution filter if set
4. Apply date filter if set
5. Collect matches with source file noted

Step 4 — Deep Traversal (deep=true only)

4a — vectors.md: Find clusters/similarities containing keyword (score ≥ 0.6). Tag results [via vectors].

4b — graph.md: Find edges containing keyword, collect one-hop neighbours. Tag results [via graph].

4c — taxonomies.md: Find categories containing keyword, collect siblings. Tag results [via taxonomy].

Deduplicate against Step 3 results.

Step 5 — Full File Escalation (T3)

If Steps 3 and 4 returned no results:

1. Read memory/config.md for the Active Files list
2. For each active file loaded with tail:N, header, or skip at session start: re-read the file in full using the Read tool
3. Search the full content for the query keyword
4. If matches found, collect them and proceed to Step 8 (format output)
5. If still no matches, proceed to Step 6 (git fallback)

Step 6 — Fallback Chain

If Steps 3+4+5 return no results:

1. Check timeline.md and last.md
2. Run: git log --all --grep="<keyword>" --oneline
3. For matching commits: git show <hash> -- memory/ — extract relevant lines
4. If still nothing: return No record found in the memory files.

Never hallucinate past context.

Step 7 — Cross-Reference Enrichment

Skip if deep=true. Otherwise: if results mention a named entity in graph.md or assets.md, append a brief Related context: note (1–2 lines max) if it adds meaningful information.

Step 8 — Format Output

Prose mode (dump=false): synthesized narrative with inline citations and Sources: footer.

Dump mode (dump=true): structured PMM Query Results block with verbatim entries grouped by file, provenance tags on deep-traversal results.

Return the formatted output as a string. Do not write to any file.

Output the agent's return value verbatim.

---

Notes

• Context-first path is the default when session_start: lazy (hook-loaded sessions). This eliminates agent dispatch for in-window queries.
• Agent dispatch is the fallback for eager mode or unwired sessions — file reads happen inside the agent.
• Phase 4 Recall in the main session handles implicit recall mid-conversation. This skill is the explicit, filterable version.
• Model selection follows Readonly Agent Model in memory/config.md (default: haiku). No reasoning required for read-only traversal.
• Attribution tags ([user:name], [agent:name], [system:process]) identify who originated each piece of information. Always preserve and surface them.
• For the full memory file reference, see references/core.md.