Every serious AI deployment eventually hits the same wall: the agent does something unexpected, and nobody can explain why. There is no record of what the agent knew, what it decided, or what caused it to choose one path over another. The agent lived entirely inside a context window, and now that window is gone.
The Problem With Stateless AI
Vanilla LLM applications pass a conversation history as a flat text blob. This works for simple chatbots, but it fails in three ways for production AI systems:
- No structure: facts, decisions, and reasoning are all mixed together as unstructured text.
- No persistence: memory resets when the context window is full or a new session starts.
- No traceability: you cannot query 'why did the agent approve this request last Tuesday?'
Retrieval-Augmented Generation (RAG) helps with persistence but not structure. A vector store gives you similarity search, not causal chains. It cannot tell you that Entity A influenced Decision B, which changed Relationship C.
What a Context Graph Is
A context graph is a structured, queryable, persistent graph of the entities, relationships, and decisions that matter to an AI agent. Think of it as the agent's working memory made tangible: a data structure you can inspect, query, and reason over.
In Semantica, every node in the graph is an entity with typed relationships. Every relationship has a temporal validity window: it was true from time A to time B. Every decision is a first-class node with provenance, confidence, and causal links to the entities that drove it.
from semantica import ContextGraph
# Initialize with temporal support
graph = ContextGraph(temporal=True)
# Add entities with rich metadata
graph.add_entity("customer_alice", type="customer",
metadata={"tier": "enterprise", "since": "2023-01"})
graph.add_entity("support_ticket_42", type="ticket",
metadata={"severity": "high", "sla_hours": 4})
# Add a typed, time-bounded relationship
graph.add_relationship(
"customer_alice", "owns", "support_ticket_42",
valid_from="2026-05-15T09:00:00Z",
valid_to=None, # still active
)
# Query the graph at a specific point in time
snapshot = graph.query_at("2026-05-16T12:00:00Z")
print(snapshot.entities_for("customer_alice"))Decisions as First-Class Citizens
What sets Semantica apart from a standard knowledge graph is the DecisionTracker. Instead of just storing facts, you store the agent's conclusions, along with the reasoning that led to them.
from semantica import DecisionTracker
tracker = DecisionTracker(graph)
decision = tracker.record_decision(
decision_id="escalate_ticket_42",
outcome="escalate_to_engineering",
confidence=0.92,
reasoning="SLA at 87% capacity; customer tier is enterprise; precedent: 3 similar cases escalated",
entities_involved=["customer_alice", "support_ticket_42"],
)
# Find similar past decisions for validation
precedents = tracker.find_similar_decisions(
context={"severity": "high", "tier": "enterprise"},
top_k=5,
)Why This Matters in Production
Context graphs solve three real production problems at once. First, explainability: every decision has a traceable lineage you can surface in an audit log. Second, consistency: agents make decisions informed by established precedent rather than re-hallucinating answers. Third, handoffs: when a new agent or human takes over, the full context transfers cleanly.
Getting Started
Semantica is open source, MIT-licensed, and installable in one line. The context graph works alongside any LLM or agent framework: it is a library, not a platform. Start with pip install semantica and check the quickstart guide in the docs.