Semantica Review: Audit Trails for AI Agent Decisions

Originally published on andrew.ooo — visit the original for any updates, code snippets that aged out, or follow-up posts.

TL;DR

Semantica is an MIT-licensed Python layer that sits underneath your LLM, vector store, and agent framework, turning what your agent knows and decides into a queryable knowledge graph with regulator-grade provenance attached. Key facts:

• 8,793 GitHub stars, 901 forks, 104 open issues/PRs; repo opened June 25, 2025, and pushed to on the day of writing (August 18, 2026)
• Current release v0.6.5 (August 11, 2026); pip install semantica; Python 3.8+, MIT license
• Deterministic by design — graph construction, reasoning, and provenance need no LLM at all. That is the whole pitch.
• Decision Intelligence: record_decision(), add_causal_relationship(), trace_decision_chain(), exportable as W3C PROV-O for regulator submission
• Polyglot storage: RDF triple stores (Oxigraph, Blazegraph, Jena, RDF4J) and property graphs (Neo4j, FalkorDB, Apache AGE, Neptune), plus six vector backends — swappable without code changes
• The honest catch: it's pre-1.0 with a bus factor of roughly one, the Rete engine's condition matcher is explicitly "intentionally simple" and unfit for a production compliance gate, and a security PR fixing privately disclosed zip-slip, SQL-injection, SSRF, XSS and SPARQL-injection findings was still open as of August 18, 2026.

If you ship agents that make consequential decisions someone will later audit, Semantica is the most complete open-source attempt at that problem right now. If you just want better recall for a chatbot, it is enormous overkill.

What is Semantica?

The project describes itself as "Graph-Native Infrastructure for Context and Accountable AI Systems," with a cheekier subtitle right under it: the open source Palantir for AI agents.

The problem it targets is narrow and real. Most agents store embeddings, not meaning. A vector store can tell you which chunk of text is similar to a query, but not why the agent approved a loan, which source document that approval rested on, what earlier decision caused it, or what changed downstream. In a demo that gap is invisible. In lending, healthcare, or insurance, it's a compliance exposure — an underwriting agent's decision has to survive a regulator's "why" months after the model that produced it was deprecated.

Semantica's answer is to make the context and the decision first-class graph objects rather than log lines. Every fact carries W3C PROV-O lineage back to its source. Every decision is a node with causal edges to its causes and effects. Conflicting facts from different sources get flagged instead of silently overwritten. And the graph supports point-in-time snapshots, so you can replay what the agent knew on a given date without reprocessing anything.

The project is refreshingly explicit about what this does not mean. A README callout states that Semantica offers system-level explainability, not foundation-model explainability — it will never tell you what happened inside the LLM's weights. It explains everything outside the model: inputs, context, applied policies, the decision produced, and the full execution trail. That's an unusually honest boundary in a space where "explainable AI" is usually stretched until it means nothing.

Quick Reference

Why it's trending now

Two things converged in mid-2026. Agents graduated from chat demos into workflows that touch money and health records, so the people signing off on them are now risk and compliance teams rather than engineering managers. And "agent memory" matured enough that the obvious version — dump everything into a vector index — visibly stopped being sufficient.

Semantica rides the second wave of that realization: not how do I recall more, but how do I prove what was recalled and what it caused. The repo has shipped fast to match — v0.5.1 in June, v0.6.0 in July, v0.6.5 on August 11 — with recent releases adding Databricks Unity Catalog and Snowflake connectors that pull tables straight out of a lakehouse into a lineage-tracked graph, no CSV export hop in between. That's a squarely enterprise feature set, and it explains why the star curve steepened.

The Decision Intelligence layer

This is the part that differentiates Semantica from every other graph-memory library, so it's worth showing in full. A decision is not a log entry; it's a node with a lifecycle:

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

app_id = graph.record_decision(
    category="credit_application",
    scenario="Personal loan, $85k income, 31% DTI, 3yr employment",
    reasoning="Income meets threshold; employment stable; no adverse credit events",
    outcome="proceed_to_underwriting",
    confidence=0.88,
    metadata={"applicant_id": "A-7291"},
)
uw_id = graph.record_decision(
    category="loan_underwriting",
    scenario="Underwriting review for A-7291",
    reasoning="DTI within policy; clean 36-month credit history",
    outcome="approved",
    confidence=0.94,
)

# relationship_type must be CAUSED, INFLUENCED, or PRECEDENT_FOR
graph.add_causal_relationship(app_id, uw_id, relationship_type="CAUSED")

Once decisions are in the graph, you interrogate them:

chain     = graph.trace_decision_chain(uw_id)                      # full causal ancestry
similar   = graph.find_similar_decisions("31% DTI loan", max_results=5)  # precedent search
impact    = graph.analyze_decision_impact(uw_id)                   # downstream influence map
compliant = graph.check_decision_rules({"category": "loan_underwriting"})  # policy gate

find_similar_decisions() is the sleeper feature. Precedent search over your own decision history is exactly what a human reviewer does manually — "have we approved something like this before, and what happened?" — and almost nothing in agent tooling exposes it as an API.

The export path is the point of the whole exercise:

from semantica.provenance import ProvenanceManager
from semantica.export import RDFExporter

prov = ProvenanceManager(storage_path="./audit.db")
prov.track_entity("patient_P4821",
                  source="ehr/medication_orders_2024.json",
                  metadata={"extractor": "NamedEntityRecognizer"})

RDFExporter().export(kg, "audit_trail.ttl", format="turtle")

PROV-O is the format most compliance frameworks already accept, so the output is something you hand to an auditor rather than a bespoke report you build yourself.

Context graphs vs. vector RAG

The README ships a comparison table, and it's a fair one rather than a strawman:

The practical difference is traversal. Embeddings find text that reads similar; a graph finds a person three hops from a contract through an employment edge and a signing edge, where no chunk of text mentioned both. Add graph.state_at("2024-01-01") and you have replay — what you need when someone asks whether the agent could have known a fact at decision time.

Architecture

Semantica is a real pipeline, not one library with a marketing name. Every stage is an independently importable module:

Sources → Ingest → Parse → Normalize → Split → Extract → Conflict Detection → Deduplication
   → Knowledge Graph → [ Ontology · Reasoning · Provenance · Decisions ] → Enriched KG
   → Vector Store + Polyglot Graph Store (RDF & LPG) → Export / Visualize / REST · MCP · CLI

Ingestion covers local files (PDF, DOCX, PPTX, XLSX, HTML, CSV, JSON, XML), web pages with robots.txt compliance, RSS, REST APIs, five SQL databases, Parquet and Arrow, Git repos, IMAP/POP3 email, Kafka/RabbitMQ/Kinesis/Pulsar streams, MCP resources, and the Databricks/Snowflake connectors. Chunking is entity-, relation-, and ontology-aware rather than fixed-width — that's what "GraphRAG-native" means here in practice.

The governance layer is where the standards pile up: SHACL constraint validation, OWL generation, SKOS vocabulary management with a visual editor, and rule-based inference via forward chaining, a Rete network, Datalog, and SPARQL. Exports go out as RDF, OWL, Parquet, Cypher, or JSON-LD.

Getting started

pip install semantica          # core
pip install "semantica[all]"   # everything

semantica doctor
# Python 3.11.9         pass
# semantica 0.6.5       pass
# faiss vector store    pass
# Config file           pass    ~/.semantica/config.yaml

The doctor command is a nice touch in a project with this many optional extras — [agno], [crewai], [llm-litellm], [graph-neo4j], [graph-falkordb], [graph-apache-age], [graph-amazon-neptune], [tripletstore-oxigraph], [vectorstore-qdrant], [vectorstore-pinecone], [db-snowflake], [db-databricks], [ingest-parquet], [ingest-arrow], [viz], [watch], [explorer]. Plan on reading that list rather than guessing.

A minimal graph looks like this:

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

graph = ContextGraph(advanced_analytics=True)
graph.add_node("acme_corp",  "Organization", name="Acme Corp", industry="SaaS")
graph.add_node("alice_chen", "Person",       name="Alice Chen", role="CTO")
graph.add_edge("alice_chen", "acme_corp", edge_type="works_for", since="2019-03-01")

neighbors = graph.get_neighbors("acme_corp", hops=2)
snapshot  = graph.state_at("2024-01-01")

ctx = AgentContext(vector_store=VectorStore(backend="faiss"), knowledge_graph=graph)
ctx.store("Alice approved the Acme renewal in Q1 2024", conversation_id="conv_001")
retrieved = ctx.retrieve("who approved the Acme contract?")

For production the docs are blunt: don't ship a local pip install. Use Docker or Kubernetes, set SEMANTICA_SECRET_KEY, put a persistent graph store behind it, and point the vector store at a hosted backend.

Performance

The published numbers come from v0.5.0 on a 118,000-node production graph (AMD EPYC, 64 GB RAM):

Credit where due: the README flags that the dedup and candidate-generation figures are historical CHANGELOG measurements rather than automated test assertions, and points you at pytest tests/vector_store/test_performance_benchmarks.py -s to measure your own data. Treat the 6,000× as "an index was added where a scan used to be," not a portable benchmark.

Integrations

Native plugin bundles cover Claude Code, Cursor, Codex CLI, Windsurf, Cline, Continue, VS Code, and OpenClaw, plus an MCP server for any MCP-compatible client, a REST API, and first-class Agno and CrewAI support. LLM access runs through LiteLLM — OpenAI, Anthropic, Gemini, Mistral, Groq, Cohere, Bedrock, Ollama, DeepSeek — though the core graph, reasoning, and provenance paths don't call a model at all. The Agno integration is the interesting one for multi-agent setups: one shared context graph across an entire agent team, instead of each agent hoarding disconnected memory.

Honest limitations

A security fix was in flight, not merged. PR #1079, open as of August 18, 2026, addresses a private disclosure covering tarball path-traversal (zip-slip) in backup restore, raw interpolation in the DB exporter's SQL, a DNS-rebinding TOCTOU in the shared SSRF guard, stored XSS in HTML report generation, and SPARQL injection in one triple-store backend. The fixes look thorough and the disclosure process worked as intended — but if you pull v0.6.5 today, that's what you're pulling. Don't point it at untrusted archives or user-controlled query fragments until it lands.

The Rete engine isn't production-ready for compliance gates. The README says so directly: the alpha-node condition matcher is "intentionally simple in this release," and you should validate match_patterns() output against your real rule set before wiring it into anything that gates a decision. PR #1077 is implementing proper alpha/beta matching with a Token model. Until then, the rules engine is a promising component inside an otherwise strong provenance story, not the compliance brain.

The API is still settling. The README's own flagship audit-trail recipe has to manually remap ContextGraph.to_dict()'s {nodes, edges} shape into the {entities, relationships} shape RDFExporter expects; issues #1080 and #1081 exist to add a to_kg_dict() adapter. Several ingestors — DuckDB, Elasticsearch, Google Drive, HuggingFace, MongoDB, Pandas — ship but aren't re-exported from the top-level namespace, so you import them by full path. This is a v0.6.5 project and it feels like one.

Bus factor. One maintainer accounts for roughly 1,813 contributions; the next-highest human contributor is at 232. Enormous velocity, concentrated risk. MIT licensing means you can fork, but that's a mitigation, not a plan.

Scope. Fourteen top-level modules, four reasoning engines, eight graph backends, six vector backends, and two warehouse connectors is a lot of surface for a pre-1.0 project. Expect some modules to be far more battle-tested than others, and verify the ones you depend on.

Who should use it — and who shouldn't

Use it if: you build agents in a regulated domain and need to answer "why did the AI do that?" in a format an auditor accepts; your data already sits in Databricks or Snowflake and you want a governed knowledge graph without a third-party SaaS hop; your context problem is relational (entities, contracts, precedents) rather than textual; or you need multiple agents sharing one coherent context layer.

Skip it if: you want better chat recall — a vector store plus a memory library costs a tenth as much to operate; you have no compliance requirement, because the provenance machinery is pure overhead without one; you need a stable 1.0 API today; or nobody on your team wants to learn SHACL, OWL, and SPARQL, which are load-bearing here, not optional garnish.

Alternatives

Cognee is the closest neighbor — also Python, also graph-plus-vector memory — but aimed at improving agent recall, not at producing regulator-ready audit trails. Graphiti (Zep) does temporally-aware knowledge graphs for agent memory with a tighter surface and no governance layer. Neo4j with LangChain gets you a property graph and nothing above it — you build provenance, ontology, and decision records yourself. Palantir Foundry is the honest commercial comparison the tagline invites: mature, supported, and priced accordingly.

Semantica's differentiator across all of them is decision records as first-class graph objects plus standards-based provenance export, with no LLM in the deterministic path.

FAQ

Is Semantica free and open source?
Yes — MIT licensed, pip install semantica, fully self-hostable. There's a commercial arm at getsemantica.ai offering on-prem deployment, SLA support, and professional services for regulated industries, but the library isn't crippled to sell it.

Does Semantica require an LLM?
No. Graph construction, reasoning, and provenance are entirely deterministic. LLM providers are available through semantica.llms and LiteLLM for extraction tasks that benefit from them, but the audit-critical paths don't call a model.

Can Semantica replace my vector database?
It doesn't have to. It ships adapters for FAISS, Qdrant, Weaviate, Milvus, Pinecone, and PgVector and is designed to sit alongside your existing stack, adding decision records, causal reasoning, provenance, and conflict detection on top.

Does it work with Claude Code, Cursor, or MCP clients?
Yes — native plugin bundles for Claude Code, Cursor, Codex CLI, Windsurf, Cline, Continue, VS Code, and OpenClaw, plus a full MCP server and a REST API.

Is it production-ready?
Partially. The ingestion, knowledge-graph, provenance, and storage layers look solid; the Rete rules engine is explicitly flagged as not yet suitable for gating production decisions, and a security-hardening PR was still open on August 18, 2026. Pilot it, pin your version, and track that PR before putting it in a regulated path.

How does it compare to plain GraphRAG?
GraphRAG improves retrieval. Semantica includes GraphRAG-style entity-aware chunking and graph retrieval, then adds the layers GraphRAG has no opinion about: decision records, causal chains, W3C PROV-O provenance, SHACL/OWL governance, conflict detection, and bi-temporal time travel.

Sources

• semantica-agi/semantica on GitHub — README, architecture, module reference (accessed August 18, 2026)
• Semantica releases — v0.6.5, August 11, 2026
• PR #1079: fix(security) — privately disclosed zip-slip, SQLi, SSRF, XSS, SPARQLi findings
• Semantica documentation
• W3C PROV-O specification