query_decisions
Query the decision knowledge graph to find architectural decisions linked to code. Filter by type, subproject, file, tag, or time to understand why code was designed that way.
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) |