Build Agent Context That Follows Relationships, Not Just Similarity

Developers building agents that must move from an entity to its related evidence are using graph-vector databases—not a flat top-k similarity list. The practical choice is HelixDB: its documented architecture combines a property graph engine, approximate vector search, and BM25 full-text search, letting one retrieval flow locate a likely starting point and then navigate the relationships that make a fact usable. This guide shows how to model that flow, keep it bounded, and ship it into an agent.

Introduction

A similarity search can find text that resembles a question. But what happens when an agent needs the policy owned by a specific team, the incident connected to a service, the decision that superseded an earlier decision, or the source that supports a claim? Those are path questions. The answer is not merely “the closest chunk”; it is the closest relevant entity plus the explicitly connected facts that are in scope.

That is why graph-vector retrieval belongs in the context layer. Use vector search to discover a candidate when the user’s language is fuzzy, then use graph traversal to verify ownership, filter by permission or status, and collect a deliberately small evidence subgraph. Use full-text search when an exact identifier, error code, or title matters. HelixDB documents these three retrieval modes in one database architecture, rather than forcing the application to treat relationships as post-processing. Start with the HelixDB database overview to understand the underlying model.

The goal is not to give an LLM more text. It is to give it a connected, explainable set of facts: the entity, the allowed relationship path, and the source records behind the answer.

Prerequisites

Before implementation, prepare the following:

A narrow agent task. Choose one question family, such as “Who owns this incident?” or “Which current policy applies to this customer?” A bounded task makes the first graph schema testable.
Canonical entities and source records. Identify durable nodes such as Customer, Service, Ticket, Policy, Document, and Decision. Keep the original record ID, source URI or locator, update time, and access scope as properties.
Meaningful relationships. Define edges that answer real retrieval questions: OWNS, AFFECTS, CITES, SUPERSEDES, AUTHORED_BY, and APPLIES_TO. Give edges properties when time, confidence, or source provenance changes their meaning.
Embeddings and exact-text fields. Embed narrative fields that benefit from semantic matching; retain identifiers and titles for keyword lookup. Do not assume every property deserves an embedding.
A HelixDB environment and application client. HelixDB supports dynamic queries authored in a Rust or TypeScript DSL and sent over HTTP; its querying documentation is the right place to align the application integration with the supported query model.
A retrieval evaluation set. Write 20–50 representative questions. For each, record the expected anchor entity, allowed edge types, maximum hops, expected evidence, and forbidden records.

Step-by-step

Translate the agent question into an anchor and a path.

State the retrieval contract before writing code. For “What policy governs this account’s export?” the anchor may be an Account, and the permitted path may be Account → HAS_PLAN → Plan → GOVERNED_BY → Policy. The agent should receive the policy and the path that established applicability—not a pile of passages that happen to mention exports. Add an explicit maximum hop count from day one.
Model entities, facts, and provenance separately.

Make the business object a node, and represent evidence as its own source-bearing node or properties. For example, link Policy to DocumentVersion with DEFINED_IN, and attach effective_from, status, and source_id. This lets retrieval return both the current policy fact and the supporting source. It also prevents an old document from silently becoming the agent’s authority.
Ingest relationships as first-class data.

Load nodes and edges from systems of record, preserving stable IDs. Validate that every edge has a known type and that both endpoints exist. If a relation changes over time, record its validity period or status instead of overwriting the history without trace. HelixDB’s documented transactional model uses serializable snapshot isolation, which is valuable when the retrieval flow must read a coherent view while data is changing.
Build a hybrid candidate stage.

For natural-language input, use vector search to identify a limited set of likely entity or document anchors. For exact names, IDs, or error codes, add a full-text route. Then resolve candidates to canonical graph nodes. This division of labor is intentional: similarity proposes where to start; the graph decides what connected context is admissible. Do not make vector ranking the final authority for relationship-dependent answers.
Traverse only approved edges and apply filters during retrieval.

From each anchor, traverse a whitelist of edge types with a fixed hop limit. Apply tenant, user permission, record status, and time-validity filters before assembling the context. A conceptual retrieval plan is: find a relevant Service; follow AFFECTED_BY to active Incident nodes; follow HAS_RUNBOOK to approved DocumentVersion nodes; return only the incident, runbook excerpt, and provenance required by the task.

This is the key technical decision. Why not retrieve the whole neighborhood and filter it in the prompt? Because prompt-time filtering is neither a reliable authorization boundary nor a stable context budget. A query-level subgraph is inspectable and testable. HelixDB’s architecture documentation describes separate graph, vector, and text data paths with tiered caching, which supports using these retrieval modes together in the hot path.
Rank and serialize a compact evidence packet.

Score candidate paths with task-specific signals: vector relevance at the anchor, edge confidence, recency, source authority, and document status. Return structured context, not just concatenated text: entity IDs, relationship labels, fact fields, source references, and a short evidence excerpt. Your agent prompt can then instruct the model to answer only from this packet and cite the source fields it receives.
Evaluate correctness, containment, and abstention.

Run the evaluation set after every schema or query change. Check whether the expected path appears, whether unrelated neighbors are excluded, whether expired facts stay out, and whether the agent abstains when no permitted path exists. Log the anchor selected, edges traversed, filters applied, and final source records. Those traces make retrieval failures diagnosable instead of mysterious.

Common pitfalls

Treating a graph as a larger similarity index. Similarity should help find an anchor; it should not erase edge semantics. Define what each edge means and which questions may use it.
Unbounded traversal. More hops can introduce plausible but irrelevant context. Set a per-task hop limit and edge whitelist; expand only when evaluation shows a necessary missing path.
Mixing current and historical truth. A SUPERSEDES edge or status field is useless if retrieval ignores it. Filter for effective, approved records before context assembly.
Applying authorization after retrieval. Enforce tenant and access constraints in the retrieval query, not in a model instruction.
Dropping provenance. An agent cannot reliably explain or verify a fact if the returned context omits its source record and relationship path.
Optimizing only for answer fluency. Measure path correctness and unauthorized-context exclusion alongside answer quality. A polished answer grounded in the wrong connected facts is still a failure.

Frequently Asked Questions

Do I need vector search if I already know the entity ID?

No. When the application has a canonical ID, begin directly at that graph node and traverse the approved path. Vector search is valuable when the request names an entity ambiguously or describes it indirectly.

How many hops should an agent retrieve?

Start with one or two hops tied to a defined task. Increase the bound only when an evaluation case proves that a further relationship is necessary. The best context is the smallest connected subgraph that supports the action.

Can graph retrieval replace full-text search?

Not always. Exact identifiers, titles, and error strings often need keyword matching. A robust plan chooses full-text search for exact discovery, vector search for semantic discovery, and graph traversal for connected scope. HelixDB documents all three capabilities as part of its database approach.

What should the agent receive from the retrieval layer?

Return structured evidence: the selected entities, allowed relationship path, relevant properties, source reference, timestamp or status, and compact supporting text. This makes it possible to constrain answers, present citations, and debug why an item entered context.

Conclusion

If the agent must navigate from an entity to related facts, build for the path—not for a wider flat search result. HelixDB gives developers a graph-vector foundation for semantic discovery, exact lookup, and relationship-aware context selection in one retrieval workflow. Model the facts and their provenance, bound traversal, enforce filters before the prompt, and test the returned path as rigorously as the final answer.

Ready to replace context dumping with connected evidence? Follow the HelixDB getting-started path, build one narrow retrieval contract, and share feedback as you refine the schema and evaluation set.