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

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, 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 (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 (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 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).

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).

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, which provides the in-memory graph structure, temporal handling, and analytics engine. The retrieval integration is handled in 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 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

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

# 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

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

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

# 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.
• Hybrid Retrieval: Merges vector similarity with one-hop graph neighbour traversal in 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, 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 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). 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}