Relation-Aware Retrieval for RAG: Choosing How to Retrieve Referenced Documents
Use search to find a starting record, explicit relations to inspect its links, and section reads to retrieve the relevant context in AKB.
Key takeaways
- Search for a seed record: Hybrid semantic and keyword search finds candidate documents; similarity alone may miss explicitly referenced evidence.
- Follow recorded links deliberately:
akb_relationsor graph navigation reveals maintained typed relations, and the agent chooses which permitted resources to read. - Read only the needed context: Use document and section tools to inspect relevant passages and confirm the linked record is current and relevant.
When an incident-response query finds a runbook but misses the postmortem and timeline explaining how a procedure changed, the agent may have only part of the evidence. Similarity-based search can return multiple related files, but similarity alone may miss records that are explicitly cited or linked. AKB offers hybrid search and separately maintained relations, so the agent can find a starting record, inspect its links, and choose what to read next.
Choosing a Retrieval Method
Choose the lookup based on what the agent needs to find. The tools are distinct: search returns candidates, while relation and section tools support deliberate follow-up reads. AKB's Key Concepts and MCP Tools (selection) describe the current concepts and tools (checked November 9, 2026).
| Need | Method | What it helps the agent do |
|---|---|---|
| Find an initial record from a question or topic | Semantic and keyword search (akb_search) | Retrieve candidate records using meaning and terms together. |
| Find an exact identifier, such as an incident code | Literal grep (akb_grep) | Match a known string in supported searchable text. |
| Follow a recorded dependency or citation | Explicit relations (akb_relations, akb_graph) | Inspect maintained typed links from a known record; the agent selects which linked resources to open. |
| Inspect relevant context inside a found document | Heading and section reads (akb_drill_down, akb_get) | Locate the relevant heading or read the document and its section context. |
A runbook-to-postmortem workflow
- Find the current runbook: Search the incident or procedure topic with
akb_searchand select a candidate runbook. - Inspect its relation to the postmortem: Call
akb_relationson the runbook, or navigate its graph, and identify a recorded citation or dependency to a postmortem. This inspects explicit links; it does not infer missing ones. - Read and validate the evidence: Open the authorized postmortem with
akb_getor useakb_drill_downto read the relevant section, then confirm the document revision and that its content is relevant to the procedure. The agent orchestrates these steps: a search call alone does not traverse all citations, and external links are not automatically ingested.
What AKB's Relations and Storage Provide
AKB supports maintained, explicit typed relations between knowledge items, including dependencies and citations. akb_relations inspects links for a known resource, while akb_graph supports graph navigation; these structured relations are scoped to the same vault. Operators, agents, or configured external workflows maintain the relationships; AKB's core provides storage and retrieval. Document revision history helps agents inspect how a referenced source changed.
For exact strings, akb_grep searches supported searchable text, not arbitrary binary file contents. Linked resources remain permission-scoped when read: the existence of a relation never grants access.
Frequently Asked Questions
If a runbook references a postmortem, will hybrid search automatically retrieve and read it?
No. Hybrid search finds candidate records but does not automatically traverse every citation or guarantee multi-hop context. First find a seed record, then use akb_relations or graph navigation to inspect recorded links, and choose authorized linked resources to read with akb_get or akb_drill_down.
When is it worth maintaining explicit links between records?
Maintain typed relations when agents often need to follow a known dependency, citation, or other meaningful connection from one record to another. Search can still find similar files, but explicit links make those recorded connections inspectable and let the agent choose relevant follow-up reads.
Pull related records too
See how AKB links documents and helps agents inspect related context through MCP tools.