# How Semantica's ContextGraph Differs from Standard RAG Stacks: 8 Key Architectural Differences

> Discover how Semantica's ContextGraph goes beyond standard RAG stacks. Explore 8 key architectural differences, including unified semantic search and causal modeling, for advanced AI applications.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: architecture
- Published: 2026-09-13

---

**Semantica's ContextGraph extends beyond traditional Retrieval-Augmented Generation by replacing flat vector stores with an in-memory graph structure that unifies semantic search, temporal validity tracking, causal decision modeling, and knowledge graph analytics in a single coherent framework.**

Semantica is an open-source AGI framework developed by semantica-agi that reimagines context management for large language models. Unlike conventional RAG pipelines that rely solely on vector similarity searches over isolated text chunks, the `ContextGraph` class implements a **semantic-plus-relational** knowledge base where entities, decisions, and their relationships coexist as first-class citizens.

## From Flat Vectors to Graph Structures

Standard RAG stacks rely on flat vector stores such as FAISS or Qdrant to return the most similar text chunks for a query. In [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py), the `ContextGraph` class instead implements an in-memory **GraphStore** that maintains nodes and edges alongside vector embeddings.

According to the source code at line 55, the graph is built from conversation entities, decisions, and external knowledge, creating a unified structure where retrieval candidates exist within a web of relationships rather than as isolated vectors.

## Hybrid Retrieval with Graph Traversal

While standard RAG performs embedding-based nearest-neighbor searches that return raw text chunks, Semantica's retrieval pipeline adds a critical post-processing step. The `handle_retrieve_context` function in [`semantica_mcp/mcp/tools/retrieval.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/retrieval.py) (line 20) performs the initial vector search but then enriches results by pulling **one-hop graph neighbours** for each hit.

This hybrid approach merges semantic embedding distances with graph-structural signals such as edge weights and path lengths, providing relational context that pure vector similarity cannot capture.

## Temporal Validity and State-Aware Queries

Traditional RAG systems return chunks based purely on similarity scores without considering when information was valid. The ContextGraph addresses this through dedicated temporal fields.

In [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py) (line 27), nodes and edges carry `valid_from` and `valid_until` timestamps. This allows the graph to answer "state at" queries and close validity windows when information is retracted, enabling time-travel queries across the knowledge base.

## Causal Reasoning and Decision Tracking

Where standard RAG treats documents as independent text, Semantica implements dedicated edge types for causal modeling. The source code at line 32 of [`context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/context_graph.py) defines edge types including `CAUSED`, `INFLUENCED`, and `PRECEDENT_FOR`.

These edges feed into a decision-tracking subsystem that records, queries, and analyzes decision precedents, allowing the system to understand not just what information exists, but how decisions influenced outcomes.

## Knowledge Graph Analytics

Standard RAG provides only similarity scores. When initialized with `advanced_analytics=True`, the ContextGraph instantiates algorithms for centrality analysis, community detection, node embeddings, path finding, and link prediction (line 41 of [`context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/context_graph.py)).

These capabilities transform the retrieval layer from a simple search index into an analytical engine capable of discovering hidden relationships and structural patterns in the knowledge base.

## Rich Metadata and Provenance Workflows

While standard vector stores limit metadata to payload fields, both nodes and edges in the ContextGraph expose arbitrary `metadata` and `properties` dictionaries with safe loaders that prevent duplicate keys (line 18 of [`context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/context_graph.py)).

Additionally, nodes can be exported to and edited as canonical Markdown documents (line 12), enabling version-controlled provenance workflows that treat graph entities as human-readable, editable documents rather than opaque binary vectors.

## Implementation Deep Dive

The core implementation resides in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py), which provides the in-memory graph structure, temporal handling, and analytics engine. The retrieval integration is handled in [`semantica_mcp/mcp/tools/retrieval.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/retrieval.py), where the hybrid search logic merges vector results with graph neighbours.

Session management in [`semantica_mcp/mcp/session.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/session.py) binds these components together through helpers like `get_vector_store()`, `get_graph()`, and `get_embedder()`, ensuring the retrieval tool operates against the active ContextGraph instance.

## Practical Implementation Examples

The following examples demonstrate how to leverage the ContextGraph's extended capabilities beyond standard RAG:

### Building the Graph with Analytics

```python
from semantica.context import ContextGraph

graph = ContextGraph(
    advanced_analytics=True,
    centrality_analysis=True,
    community_detection=True,
    node_embeddings=True,
)

```

### Adding Typed Nodes and Causal Edges

```python

# Add a decision node with entities

graph.add_node(
    node_id="loan_approval_001",
    node_type="decision",
    content="Approved",
    category="loan_approval",
    confidence=0.95,
    entities=["customer_123", "property_456"],
)

# Create causal relationship

graph.add_edge(
    source_id="customer_123",
    target_id="loan_approval_001",
    edge_type="INFLUENCED",
    weight=0.9,
)

```

### Hybrid Retrieval with Graph Context

```python
from semantica_mcp.mcp.tools.retrieval import handle_retrieve_context

results = handle_retrieve_context({
    "query": "What influences loan approvals?",
    "top_k": 5,
})

print(results["results"])        # Vector search results

print(results["graph_context"])  # Enriched 1-hop neighbours

```

### Temporal State Queries

```python
from datetime import datetime

active_nodes = [
    n for n in graph.nodes.values()
    if n.is_active(at_time=datetime(2024, 5, 1))
]
print(f"Active nodes on 2024-05-01: {len(active_nodes)}")

```

### Markdown Export and Edit Workflows

```python

# Export to editable Markdown

md = graph.export_node_markdown("loan_approval_001")
print(md)  # Front-matter + body

# Apply updated version

updated_md = md.replace("confidence: 0.95", "confidence: 0.97")
graph.apply_node_markdown("loan_approval_001", updated_md)

```

## Summary

- **Graph Structure**: Replaces flat vector stores with an in-memory `ContextGraph` combining nodes, edges, and embeddings in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py).
- **Hybrid Retrieval**: Merges vector similarity with one-hop graph neighbour traversal in [`semantica_mcp/mcp/tools/retrieval.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/retrieval.py).
- **Temporal Awareness**: Supports `valid_from`/`valid_until` timestamps for time-bounded queries, unlike static RAG chunks.
- **Causal Modeling**: Implements decision tracking via typed edges (`CAUSED`, `INFLUENCED`, `PRECEDENT_FOR`).
- **Advanced Analytics**: Optional KG algorithms (centrality, community detection) available when `advanced_analytics=True`.
- **Provenance**: Supports Markdown export/import for version-controlled editing of graph entities.

## Frequently Asked Questions

### What makes Semantica's ContextGraph different from a standard vector database?

Standard vector databases store embeddings as flat indexes optimized for similarity search. Semantica's ContextGraph, implemented in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py), maintains an in-memory graph structure where nodes and edges coexist with vector embeddings, enabling relational traversal, temporal filtering, and causal reasoning that vector-only stores cannot provide.

### How does the hybrid retrieval work in practice?

The `handle_retrieve_context` function in [`semantica_mcp/mcp/tools/retrieval.py`](https://github.com/semantica-agi/semantica/blob/main/semantica_mcp/mcp/tools/retrieval.py) first performs a traditional vector similarity search, then augments the results by traversing one-hop neighbours in the graph. This merges semantic relevance with structural importance signals like edge weights and relationship types, returning both `results` (vector matches) and `graph_context` (related entities).

### Can the ContextGraph handle time-sensitive information?

Yes. Unlike standard RAG where chunks are eternally valid, ContextGraph nodes and edges include `valid_from` and `valid_until` timestamps (line 27 of [`context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/context_graph.py)). The `is_active()` method allows querying the graph state at specific moments, supporting automatic invalidation of outdated information and historical state reconstruction.

### How does Semantica track decisions and causal relationships?

The graph supports dedicated edge types—`CAUSED`, `INFLUENCED`, and `PRECEDENT_FOR`—defined in [`semantica/context/context_graph.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/context/context_graph.py). These edges connect decision nodes to their influencing factors, creating an auditable trail of how conclusions were reached. The decision-tracking subsystem can analyze these paths to identify precedents and causal factors during retrieval.