w-winter/dot314/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.

If original_session is missing or stale

A session transcript's original_session frontmatter may point to a materialized indexing path rather than the live Pi session JSONL. If that path does not exist, use relative_session plus Pi's configured session directory.

For Pi sessions:

• relative_session: pi/<session-path>.jsonl
• live path: <PI session dir>/<session-path>.jsonl

Resolve the Pi session dir using Pi's documented precedence:

1. --session-dir if known from the command/session context
2. PI_CODING_AGENT_SESSION_DIR if set
3. sessionDir in Pi settings
4. default: ~/.pi/agent/sessions

Example:

relative_session: pi/--Users-ww-project--/session-id.jsonl

with the default session dir maps to:

~/.pi/agent/sessions/--Users-ww-project--/session-id.jsonl

If the effective session dir cannot be determined, try the default path first, then ask the user for their Pi session directory rather than assuming the qmd original_session path is still valid.

Filtering transcript output is fine:

qmd get "qmd://sessions/path/to/session-transcript.md" --full | grep -iE 'USER:.*(error|bug|regression)'

Session search playbook

Ask for narrowing clues when memory is vague

If the request is fuzzy, ask for:

• approximate timeframe
• which agent/tool produced the session
• repo or project involved
• remembered phrase, error text, or tool name

After 2-3 bad searches, stop iterating blindly and ask for more context.

Exact session search

Start here when you have hard clues. Use --files first to avoid wasting tokens on snippets. If lexical search returns an obvious hit, inspect it immediately instead of escalating to query.

qmd search -c sessions --files 'rp_exec' -n 20
qmd search -c sessions --files 'apply_edits' -n 20
qmd search -c sessions --files 'git rebase' -n 20
qmd search -c sessions --files 'search block not found' -n 20

If lexical search returns many same-score candidates because the clue is broad or common, do not keep repeating broad lexical searches. Tighten the query with a more distinctive phrase, tool name, error string, or timeframe clue, or switch to qmd query --intent ....

Escalate when lexical search is weak

Use query, add intent, and scope to sessions when exact search is weak or the request is conceptual. Keep --files on unless you specifically need snippets.

qmd query --intent "Pi/Codex/Claude agent sessions about git trouble during implementation work" \
  -c sessions \
  --files \
  -n 10 \
  "git rebase gone wrong"

Mixed exact + fuzzy session search

qmd query -c sessions --files $'intent: agent sessions about broken code edits in RepoPrompt workflows
lex: apply_edits rp_exec "oldText" "search block not found"
vec: session where file edits failed repeatedly and the agent had to retry'

Browse after narrowing

qmd ls sessions
qmd ls sessions/claude
qmd ls sessions/pi

Inspect with session-view

session-view lives at ~/.pi/agent/skills/text-search/scripts/session-view.

Use it when a session transcript points you at an original_session and you need exact raw-session details. It also accepts RepoPrompt AgentSession-*.json files when you want the compressed RP-side view plus its codexRolloutPath. For Codex sessions, session-view strips the leading injected AGENTS/environment preamble through </environment_context> before rendering the transcript.

# Default: prose-only; omit tool calls and tool result/output blocks
session-view /absolute/path/to/original/session.jsonl
 
# Opt-in: include assistant tool invocations with full arguments
session-view --include-tool-calls /absolute/path/to/original/session.jsonl
 
# Escalate only when tool outputs are evidence
session-view --include-tool-calls --include-tool-results /absolute/path/to/original/session.jsonl
 
# RepoPrompt AgentSession JSON
session-view ~/Library/Application\ Support/RepoPrompt/Workspaces/.../AgentSessions/AgentSession-ABC123.json

You can also inspect the latest local session directly:

# Default: prose-only; omit tool calls and tool result/output blocks
session-view --latest pi
session-view --latest codex
session-view --latest claude
session-view --latest rp
 
# Opt-in: include full tool-call arguments
session-view --include-tool-calls --latest pi

Default rendered output looks like this:

USER: message
 
ASSISTANT: response text

With --include-tool-calls, assistant tool invocations are rendered with full JSON arguments:

ASSISTANT:
  [tool_name]
    {
      "path": "file.txt"
    }

If you opt in to tool results with --include-tool-results, you'll also see bounded output blocks:

TOOL [name]: ✓ truncated_output

Example workflows

Find a specific session with hard clues

# 1. Start with lexical search and compact path output
qmd search -c sessions --files 'git rebase' -n 20
 
# 2. Inspect the transcript
qmd get "qmd://sessions/path/to/session-transcript.md" --full
 
# 3. If exact details matter, recover full tool calls from original_session
session-view --include-tool-calls /absolute/path/to/original/session.jsonl

Escalate when lexical search is weak

qmd query --intent "Pi/Codex/Claude sessions about git trouble during coding work" \
  -c sessions \
  --files \
  -n 20 \
  "git rebase gone wrong"

Supplemental helper: analyze-sessions.sh

Location: ~/.pi/agent/skills/text-search/scripts/analyze-sessions.sh

Use it for time-windowed or operational reporting rather than ranked corpus search.