trw_recall
Retrieve prior engineering learnings relevant to your current task by searching with keywords and filtering by tags, impact, or status.
Instructions
Retrieve prior learnings relevant to your current task.
Use when:
You are about to work in an unfamiliar area of the codebase.
You suspect a bug has been seen before and want prior root-cause notes.
You want a narrow tag/impact slice before spawning a subagent.
See Also: trw_learn, trw_session_start.
Results are ranked by combined relevance (query match on summary/tags/detail) and utility (impact, type-aware recency decay, prior feedback). Context boosts prioritize entries matching your current domain, phase, and team.
Output: RecallResultDict with fields {learnings: list[{id, summary, detail?, tags, impact, ...}], count: int, query: str, ceremony_hint?: str}.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Optional tag filter — only return entries matching these tags. | |
| as_of | No | Optional ISO-8601 instant (PRD-CORE-194). Time-travel recall — returns records whose validity window contained T. Malformed values raise a clean validation error. Default None = open records only. | |
| query | No | Search query (keywords matched against summaries/details). Use "*" to list all (auto-enables compact mode). | |
| topic | No | Optional topic slug from knowledge topology. When provided, only returns learnings belonging to that topic cluster. | |
| status | No | Optional status filter — 'active', 'resolved', or 'obsolete'. | active |
| compact | No | When True, return only essential fields per learning. When None (default), auto-enables for wildcard queries. | |
| shard_id | No | Optional shard identifier for receipt attribution. | |
| min_impact | No | Minimum impact score filter (0.0-1.0). Use 0.7 for high-impact only. | |
| max_results | No | Maximum learnings to return (default 25, 0 = unlimited). | |
| token_budget | No | Optional max token ceiling for the serialized result. Must be > 0. When omitted, a sane default cap is applied so a recall can never overflow the context window (anti-collapse guard). | |
| include_tiers | No | Optional tier scope (PRD-CORE-185). Project entries are ALWAYS included; this flag only controls whether machine-local USER-tier entries are added on top. None (default) and any list containing "user" federate the user tier when a user-scope store is present; ["project"] (no "user") restricts to project-only. A user-only query is intentionally not expressible -- the project tier is the local source of truth and is never excluded. | |
| ultra_compact | No | When True, return only ``{learnings, count, ceremony_hint}`` with each learning reduced to ``{id, summary}``. | |
| include_superseded | No | When True, also return superseded records, ranked strictly below open ones (each flagged superseded/invalidated_by). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| count | No | ||
| query | No | ||
| compact | No | ||
| context | No | Shape of the context dict returned by ``collect_context()`` and embedded in ``RecallResultDict``. Both keys are optional — populated only when the corresponding YAML file exists in the ``.trw/context/`` directory. | |
| patterns | No | ||
| learnings | No | ||
| max_results | No | ||
| tokens_used | No | ||
| ceremony_hint | No | ||
| tokens_budget | No | ||
| total_matches | No | ||
| total_available | No | ||
| tokens_truncated | No | ||
| duplicates_collapsed | No | ||
| topic_filter_ignored | No | ||
| topic_filter_warning | No |