# How Semantica's AgentContext Combines Vector Search and Graph Traversal for Hybrid Retrieval

> Discover how Semantica's AgentContext merges vector search and graph traversal for advanced hybrid retrieval. Learn about its unique ContextRetriever and hybrid alpha weighting.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-09-09

---

**The `AgentContext` class unifies dense vector similarity search with knowledge graph traversal through a `ContextRetriever` that blends cosine-based nearest-neighbor results with graph-expanded entities using a configurable `hybrid_alpha` weighting coefficient.**

The `semantica-agi/semantica` repository implements a sophisticated hybrid retrieval system that allows AI agents to leverage both semantic embedding spaces and structured graph relationships. By combining these two complementary approaches, Semantica enables agents to retrieve context that matches vector similarity while also capturing relational knowledge through graph hops.

## Architecture of the Hybrid Retrieval System

The hybrid retrieval capability rests on three composable components that work together inside `AgentContext`.

### Core Components

- **VectorStore**: Stores dense embeddings of raw text, decisions, and artifacts. Provides fast semantic similarity via cosine-based nearest-neighbor search.

- **Knowledge Graph (`ContextGraph`)**: Stores entities, relationships, and bi-temporal facts. Enables graph-native lookups including BFS/DFS traversal, centrality analysis, and path-finding.

- **ContextRetriever**: Orchestrates the hybrid pipeline. This component queries the vector store, optionally expands results by traversing the graph up to `max_expansion_hops`, and normalizes scores from both sources according to the `hybrid_alpha` parameter.

In [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) (lines 90-105), the constructor initializes these components:

```python
def __init__(self, vector_store, knowledge_graph=None, **retriever_config):
    self._vector_store = vector_store
    self._knowledge_graph = knowledge_graph
    
    if knowledge_graph:
        self._retriever = ContextRetriever(**retriever_config)

```

## The Hybrid Retrieval Workflow

The retrieval process follows a structured pipeline that fuses vector and graph signals into a unified relevance score.

### Initialization and Configuration

When instantiating `AgentContext`, the retriever configuration determines how vector and graph results blend. According to [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) (lines 98-110), the system accepts:

- `use_graph_expansion` (default `True`): Controls whether graph hops are performed
- `max_expansion_hops` (default `2`): The depth of BFS expansion
- `hybrid_alpha` (default `0.5`): The blend factor where `0` favors pure vector scores and `1` favors pure graph signals

### Vector Search Phase

The retrieval begins with semantic similarity search. As documented in [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) (lines 11-15), the `ContextRetriever.retrieve` method first calls the vector store's `search` method to obtain the top-k nearest neighbors based on cosine similarity.

### Graph Expansion Phase

If `use_graph_expansion` is enabled, the retriever invokes graph utilities including `PathFinder`, `CentralityCalculator`, and other KG analytics tools to explore related entities up to the configured hop limit (`self.max_expansion_hops`). This expansion captures structurally relevant nodes that may not match the vector query semantically but are relationally significant.

### Score Normalization and Blending

Both vector and graph results undergo normalization to a 0-1 range. The final relevance score is computed using the formula found in [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) (lines 31-34):

```python
final_score = hybrid_alpha * graph_score + (1 - hybrid_alpha) * vector_score

```

The `HybridSimilarityCalculator` class (instantiated in [`context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/context_retriever.py) lines 58-60) handles this weighted combination, allowing developers to tune whether semantic similarity or graph structure dominates the ranking.

## Decision-Aware Embedding Pipeline

When `decision_tracking` is enabled, the system enriches vector embeddings with graph-derived features before storage. In [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py) (lines 74-80), the `DecisionEmbeddingPipeline` incorporates node2vec embeddings, centrality metrics, and community tags into the vector representation. This allows subsequent retrieval to benefit from both semantic and structural signals even during the initial vector search phase.

## Practical Implementation

Here is a complete implementation demonstrating hybrid retrieval configuration:

```python
from semantica.context import AgentContext, ContextGraph
from semantica.vector_store import VectorStore

# Initialize components

vs = VectorStore(backend="faiss", dimension=1536)
kg = ContextGraph(advanced_analytics=True)

# Configure hybrid retrieval

ctx = AgentContext(
    vector_store=vs,
    knowledge_graph=kg,
    graph_expansion=True,
    max_expansion_hops=3,
    hybrid_alpha=0.6,  # 60% graph influence, 40% vector

    decision_tracking=True,
)

# Store content (vectorized and graphed)

mem_id = ctx.store(
    "Alice approved the Acme renewal in Q1 2024",
    conversation_id="conv_001",
    extract_entities=True,
    extract_relationships=True,
)

# Hybrid retrieval

results = ctx.retrieve("Who approved the Acme contract?", max_results=5)

for r in results:
    print(f"[{r.score:.2f}] {r.content}")
    print(f"  ↳ Related entities: {[e['id'] for e in r.related_entities]}")

```

The `ctx.retrieve` call (implemented in [`semantica/context/agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/agent_context.py) lines 78-86) forwards to `self._retriever.retrieve`, returning `RetrievedContext` objects containing merged content, blended relevance scores, and related graph entities.

## Summary

- **AgentContext** serves as the high-level façade that composes `VectorStore`, `ContextGraph`, and `ContextRetriever` components.
- **Hybrid retrieval** works by executing vector similarity search first, then expanding results via graph traversal up to `max_expansion_hops`.
- **Score blending** uses the formula `hybrid_alpha * graph_score + (1 - hybrid_alpha) * vector_score` to weigh semantic versus structural relevance.
- **Decision-aware embeddings** enrich vectors with graph features (centrality, communities) when `decision_tracking` is enabled.
- Configuration occurs at initialization through parameters like `hybrid_alpha`, `use_graph_expansion`, and `max_expansion_hops` in [`agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/agent_context.py).

## Frequently Asked Questions

### How does the hybrid_alpha parameter affect search results?

The `hybrid_alpha` parameter controls the weighting between vector similarity and graph structure in the final ranking. Set to `0.5` by default, values closer to `1.0` prioritize graph relationships and traversal depth, while values closer to `0.0` favor pure semantic similarity from the vector store. This allows tuning for domain-specific needs where either relational structure or semantic meaning is more predictive of relevance.

### What graph algorithms does Semantica use during the expansion phase?

During graph expansion, the `ContextRetriever` instantiates several algorithm classes including `PathFinder` for BFS/DFS traversal and `CentralityCalculator` for network analysis (see [`context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/context_retriever.py) lines 62-68). These utilities enable exploration of entity relationships, calculation of node importance, and detection of community structures that inform the retrieval scoring.

### Can I use AgentContext with only vector search and no graph component?

Yes. The `knowledge_graph` parameter is optional in the `AgentContext` constructor. If no graph is provided, the system operates in vector-only mode without invoking the `ContextRetriever`'s graph expansion logic. However, enabling the graph requires setting `graph_expansion=True` and providing a `ContextGraph` instance to unlock hybrid retrieval capabilities.

### Where does the actual retrieval method forward the query?

The `AgentContext.retrieve` method (lines 78-86 in [`agent_context.py`](https://github.com/semantica-agi/semantica/blob/main/agent_context.py)) forwards the query to `self._retriever.retrieve`, which implements the hybrid pipeline in [`semantica/context/context_retriever.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_retriever.py). This design keeps the high-level API clean while delegating the complex orchestration of vector and graph operations to the specialized retriever component.