query_decisions
Retrieve architecture decisions connected to code by filtering on type, symbol, file path, tag, or time. Answers why a design was chosen.
Instructions
Query the decision knowledge graph. Filter by type, subproject, code symbol, file path, tag, or time. Returns decisions linked to code — "why was this architecture chosen?" answered with the actual decision record. Use service_name to filter by a specific subproject within the project. By default returns auto-approved + human-approved decisions (review_status NULL or "approved"); use include_pending to also return the review queue, or review_status to fetch a specific tier. Each row carries cluster_ids when the decision belongs to any topical cluster, and the response includes a clusters_summary keyed off those ids. Read-only. Returns JSON: { decisions: [{ id, title, type, content, tags, review_status, cluster_ids? }], clusters_summary?, total_results }. Set output_format: "toon" for lossless TOON encoding — cheaper LLM tokens on tabular payloads. Hard-capped by memory.recall.timeoutMs (default 5000 ms); on timeout returns { decisions: [], total_results: 0, degraded: true }.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Filter by tag | |
| type | No | Filter by decision type | |
| as_of | Yes | Only decisions active at this ISO timestamp | |
| limit | No | Max results (default: 50) | |
| search | No | Full-text search query (FTS5 with porter stemming) | |
| verify | No | Staleness verification (default: true). When true, each decision linked to a `symbol_id` is checked against the live index + git history; rows whose code was deleted/renamed or materially changed since `created_at` are flagged with `verification` ("symbol_missing" | "code_changed") and `stale: true`. Pass false to skip the check entirely. | |
| order_by | No | Result ordering. "recency" (default): valid_from DESC. "created_at": created_at DESC. "heat": time-decay scoring biased toward frequently-recalled + fresh decisions. When heat is disabled in config, "heat" gracefully degrades to "recency". | |
| file_path | Yes | Filter by linked file path | |
| symbol_id | Yes | Filter by linked symbol FQN | |
| git_branch | No | Branch filter. "current" (default) → current branch + branch-agnostic decisions. "all" → every branch. Any other value → that specific branch + branch-agnostic decisions. | |
| index_only | No | Progressive disclosure (default: false). When true, each decision is returned WITHOUT its full `content` — just id, title, type, code anchors, tags, and a ~1-line `summary`. Pick the relevant ids cheaply, then pull full content with `get_decision`. Pure token-saver. | |
| service_name | No | Filter by subproject name (e.g., "auth-api") | |
| verification | No | Filter by verification verdict (implies verify). "stale" returns any flagged row (symbol_missing OR code_changed); "ok" returns only verified-fresh rows. Omit to return all rows annotated in place. | |
| output_format | No | Output format. "json" (default) returns JSON, "markdown" returns LLM-friendly fenced markdown (tool-specific), "toon" returns Token-Oriented Object Notation — 30-60% fewer tokens on tabular data, fully lossless. | |
| review_status | No | Restrict to a single review tier (overrides default + include_pending). Use "pending" to fetch the review queue. | |
| include_pending | No | Also return decisions in the review queue (review_status="pending"). Default: false — only auto-approved and approved rows are returned. | |
| include_invalidated | No | Include invalidated decisions (default: false) |