query_decisions
Retrieve architecture decisions and tech choices linked to source code by filtering the decision knowledge graph. Query why code was designed a certain way using filters like type, subproject, symbol, file, tag, or time.
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 |
|---|---|---|---|
| type | No | Filter by decision type | |
| service_name | No | Filter by subproject name (e.g., "auth-api") | |
| symbol_id | Yes | Filter by linked symbol FQN | |
| file_path | Yes | Filter by linked file path | |
| tag | Yes | Filter by tag | |
| search | No | Full-text search query (FTS5 with porter stemming) | |
| as_of | Yes | Only decisions active at this ISO timestamp | |
| include_invalidated | No | Include invalidated decisions (default: false) | |
| include_pending | No | Also return decisions in the review queue (review_status="pending"). Default: false — only auto-approved and approved rows are returned. | |
| review_status | No | Restrict to a single review tier (overrides default + include_pending). Use "pending" to fetch the review queue. | |
| git_branch | No | Branch filter. "current" (default) → current branch + branch-agnostic decisions. "all" → every branch. Any other value → that specific branch + branch-agnostic decisions. | |
| 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". | |
| limit | No | Max results (default: 50) | |
| 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. |