Text Search

text-search

Use qmd to search indexed text corpora such as session logs, notes, docs, and logs. For indexed content, use qmd for discovery instead of raw grep.

First checks

Before searching, confirm what is indexed:

qmd status
qmd collection list
qmd context list

Do not assume collection names, paths, or contexts.

Core rule

For indexed corpora, use qmd for discovery.

Do not use grep/find/jq/cat directly on indexed files to search for meaning. This is especially important for session JSONL, which is noisy and hard to interpret raw.

Shell usage is still fine for:

• filtering tool output after discovery
• housekeeping and file targeting
• non-indexed content
• helper scripts in this skill

Choose the right qmd command

For exact clues, start with qmd search.

• Use qmd search for exact clues: tool names, error strings, repo names, JSON fields, literal phrases
• Use qmd query when lexical search is weak, the request is conceptual, or you want hybrid retrieval + reranking
• Use qmd vsearch only when you specifically want pure semantic similarity

qmd search '"toolName":"rp_exec"'
qmd search 'apply_edits'
qmd query "OAuth redirect flow"
qmd vsearch "the session where we changed direction"

Operational notes:

• qmd query may trigger local model startup or model downloads, so it is not always the fastest first step
• For session discovery, prefer --files first so you get compact path output instead of long snippets

Build better queries

Use --intent when the request is ambiguous

intent is a steering hint. Use it when the same words could refer to multiple things or when the user remembers the topic better than the exact wording.

qmd query --intent "Pi/Codex/Claude agent sessions about repo editing failures" \
  -c sessions \
  "apply_edits error"

Use structured query documents for important searches

Multi-line query documents are useful when you have both exact clues and fuzzy memory.

• lex: exact terms, phrases, identifiers, JSON fields
• vec: natural-language meaning
• hyde: what the answer likely looked like
• intent: optional steering context

qmd query $'intent: agent sessions about RepoPrompt edits and patch failures
lex: apply_edits rp_exec "search block not found"
vec: debugging failed file edits in agent sessions
hyde: The agent tried to edit a file several times, the edit did not match, and it switched to a narrower or different approach'

Operational details:

• The first typed query gets 2x fusion weight, so put the strongest signal first
• expand: must stand alone; do not mix it with typed lines
• lex queries support quoted phrases and exclusions such as -sports or -"test data"

Useful output and tuning flags

qmd query --files -n 20 "agent session about flaky tests"
qmd query --json -n 10 "session where we redesigned the search flow"
qmd query --json --explain -c sessions "apply_edits error"
qmd query -C 20 --min-score 0.3 -c sessions "OAuth redirect flow"

Use:

• --files for compact discovery output and path-based follow-up
• --json for structured inspection when you need scores/snippets
• --explain when ranking looks wrong
• -C, --candidate-limit to reduce reranking work
• --min-score to drop weak matches
• -c, --collection to scope the search

For session hunting, --files is usually the best first output mode.

Retrieval commands

qmd get "#abc123"
qmd multi-get "docs/*.md" --json
qmd ls sessions
qmd ls sessions/claude

Use get, multi-get, and ls to retrieve or browse content after discovery.

For session discovery, use this inspection path:

# 1. Discover a session transcript
qmd search -c sessions --files 'apply_edits' -n 5

# 2. Read the session transcript directly
qmd get "qmd://sessions/path/to/session-transcript.md" --full

Each session transcript includes original_session metadata in frontmatter. When exact commands, SQL, edits, or ad-hoc code matter, recover them from the original session JSONL with session_ask or session-view --include-tool-calls. Add --include-tool-results only when tool outputs are evidence.

If qmd is missing

npm install -g @tobilu/qmd
qmd --version
qmd status

Sessions

Agent session transcripts are indexed as the sessions collection.

The sessions collection is a corpus of agent session transcripts generated from session JSONL via session-view. It is optimized for readable search. Very large sessions may be split across multiple transcript documents; use the original_session metadata when you need exact raw-session recovery.

Required workflow

Use this three-step process:

1. Discover candidate sessions with qmd or analyze-sessions.sh
2. Inspect the session transcript with qmd get
3. Recover exact raw-session details only when needed via original_session + session_ask or session-view --include-tool-calls

Do not try to understand a session from raw JSONL snippets alone.

Inspecting session transcript paths

Use one reliable inspection path:

# Read the session transcript directly
qmd get "qmd://sessions/path/to/session-transcript.md" --full

If the transcript is enough, stop there.

If exact raw-session details matter:

# 1. Read the transcript and note its `original_session` frontmatter
qmd get "qmd://sessions/path/to/session-transcript.md" --full

# 2. Recover exact tool-call details from the original session
session-view --include-tool-calls /absolute/path/to/original/session.jsonl

Or use session_ask against that original_session path when you want targeted recovery without reading the whole session.