Semantica Setup: Self-Host an Auditable AI Context Graph

Semantica is an open source Python layer that sits underneath your LLM and vector store and gives an agent the one thing embeddings cannot: a queryable graph of what it knows, what it decided, and where every fact came from. The repo picked up roughly 970 stars in a day this week, taking it past 4,300 total, on a pitch blunt enough to fit on a badge: the open source Palantir for AI agents. Setup is a single pip command, and about ten minutes gets you from install to a decision you can export as a regulator-ready audit file.

• One install ships the lot: library, CLI, MCP server and REST API in the same package, on Python 3.8 or newer.
• Graph construction, reasoning and provenance are deterministic and need no LLM, so the layer slots under whatever model you already run.
• Every decision becomes a graph node with causal links plus a W3C PROV-O trail you can export as Turtle.
• v0.6.0 shipped on July 21, 2026 with Databricks ingestion and a SQLite-backed vector store. License is MIT.

What is Semantica and why is it trending?

Most agent memory today is a pile of vectors. You embed documents, you retrieve the nearest neighbours, and the model writes something plausible. That works right up to the moment somebody asks why the agent approved a loan, flagged a patient chart, or picked one vendor over another, because a similarity score is not a reason and a vector index has no record that a choice was ever made.

RelatedDesktop Commander Setup: Give Claude Terminal Control

Semantica goes at that gap. It builds a knowledge graph from your sources, records each agent decision as a first-class node with causes and downstream effects attached, tracks W3C PROV-O provenance on every fact, and runs deterministic reasoning over the result using forward chaining, a Rete network, Datalog or SPARQL. Nothing in that list calls a language model, which is the whole point: the explanation has to hold up without another black box generating it.

The trending spike is partly positioning. Palantir Foundry owns the phrase "decision intelligence" in regulated industries and costs accordingly, and a self-hostable MIT project claiming the same primitives is going to get clicked. The repo leans into it, aiming squarely at finance, healthcare, legal, government and defence teams who cannot ship a black box and cannot hand their data to somebody else's SaaS to get one. It is also on Trendshift, which tends to amplify a good day into a very good one.

How do you install Semantica on Windows, macOS or Linux?

It is a pure pip install and behaves the same on all three. Python 3.8 or newer is the only hard requirement:

# core install
pip install semantica
# or pull in every optional backend at once
pip install semantica[all]

Check the install before you build anything on it. The CLI ships with the package, so there is no second thing to set up:

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

Running semantica on its own opens a startup dashboard, and semantica --help prints the grouped command reference. The groups cover the full pipeline: ingest, parse, extract, kg, reason, decision, temporal, provenance, ontology, embed, deduplicate, validate, export, visualize, pipeline, server, explorer, mcp, doctor, shell, init and watch.

Storage backends are opt-in extras rather than dependencies, which keeps the base install light. Grab only the ones you actually plan to use:

pip install semantica[graph-neo4j]           # Neo4j property graph
pip install semantica[tripletstore-oxigraph] # embedded RDF store
pip install semantica[vectorstore-qdrant]    # Qdrant vectors
pip install semantica[llm-litellm]           # OpenAI, Anthropic, Gemini, Ollama and more

How do you record your first auditable decision?

This is the ten-minute payoff and the API most people come for. A context graph is one object, and a decision is one call against it:

from semantica.context import ContextGraph

graph = ContextGraph(advanced_analytics=True)

decision_id = graph.record_decision(
    category="vendor_selection",
    scenario="Choose cloud provider for HIPAA workload",
    reasoning="AWS offers BAA, mature HIPAA tooling, and existing team expertise",
    outcome="selected_aws",
    confidence=0.93,
)

chain     = graph.trace_decision_chain(decision_id)
similar   = graph.find_similar_decisions("cloud vendor", max_results=5)
impact    = graph.analyze_decision_impact(decision_id)
compliant = graph.check_decision_rules({"category": "vendor_selection"})

Those four reads are the interesting part. trace_decision_chain walks the causal ancestry, find_similar_decisions is precedent search over past choices, analyze_decision_impact maps what downstream depended on this one, and check_decision_rules runs the decision against your policy gate. Link decisions to each other with add_causal_relationship, which accepts one of three relationship types: CAUSED, INFLUENCED or PRECEDENT_FOR.

To see any of this rather than print it, the browser workbench installs from the same package and needs no Node.js:

pip install "semantica[explorer]"
semantica-explorer --graph my_graph.json
# Dashboard opens at http://127.0.0.1:8000

How do you connect it to Claude Code, Cursor or a REST client?

There is a built-in MCP server, so any MCP client picks up the graph as a tool set. Start it directly or through the installed entry point:

python -m semantica.mcp_server
# or via the installed entry point
semantica-mcp

Then point your client at it. The config block is the standard shape used by Claude Desktop, Cursor, Windsurf, Cline and VS Code:

RelatedAgent Reach Setup: Give Your AI Agent Web Access

{
  "mcpServers": {
    "semantica": { "command": "python", "args": ["-m", "semantica.mcp_server"] }
  }
}

Twelve tools come across that link, including extract_entities, record_decision, find_precedents, get_causal_chain, run_reasoning and export_graph. If you would rather talk HTTP, the same capabilities sit behind a REST backend on port 8000:

python -m semantica.server   # port 8000

curl -X POST http://localhost:8000/api/enrich/extract \
  -H "Content-Type: application/json" \
  -d '{"text": "Apple CEO Tim Cook announced record earnings."}'

How does it compare with a vector database or plain model memory?

Read that as complement rather than replacement. Semantica keeps your vector store in the loop and even ships adapters for FAISS, Qdrant, Weaviate, Milvus, Pinecone and PgVector. What it adds is the layer above retrieval, and if your agent never has to justify itself, you do not need that layer.

What are the gotchas before you rely on it?

Four, and the project is refreshingly upfront about most of them. First, a local pip install is not a deployment. The README says to use Docker or Kubernetes in production, set SEMANTICA_SECRET_KEY, and point the graph and vector layers at persistent backends rather than the embedded defaults. Take that seriously, because the in-memory defaults are what make the quick start feel so fast.

Second, the headline performance numbers deserve a squint. The 6,000x node-search figure comes from a 118,000-node graph on an AMD EPYC box with 64 GB of RAM, and the repo notes that the deduplication and candidate-generation figures are historical measurements from the changelog rather than assertions in the test suite. Third, the docs carry an explicit caveat on the Rete condition matcher and tell you to validate it against your own rule set before production. A rules engine you have not tested against your rules is not a compliance control.

Fourth, weigh the age against the ambition. The repo opened in June 2025 and sits in the low thousands of stars, which is a young project by any measure, while the README invokes Palantir, defence deployments and classified data governance. The engineering surface is genuinely broad, covering four RDF stores, four property graph databases, six vector stores, Databricks and Snowflake. Broad surfaces on young projects mean some paths are far better travelled than others, so pilot the one backend you care about before betting a compliance workflow on it.

Our take

The interesting claim here is not the graph, it is the determinism. Plenty of projects will build you a knowledge graph; Semantica is betting that the value sits in being able to reconstruct a decision without asking a model to narrate it after the fact, and that bet looks correct as regulators start asking agent operators for reasons rather than logs. Whether this particular repo is the thing that wins is a separate question from whether the category is real, and the category is clearly real.

For now the honest read is that it is an unusually complete v0.6.0 with more surface area than a project this young can plausibly have hardened everywhere. That is fine for what most readers will do with it this week, which is install it, record a few decisions, wire the MCP server into their editor, and see whether a queryable decision history changes how they build. One pip command to find out is a fair price.

Original analysis by GenZTech. Tool documentation: semantica-agi/semantica on GitHub.