Open Knowledge Infrastructure for AI
Connect your data, and relationships into one intelligent knowledge
that gives AI agents the context they need to understand, reason, and act.
Own Your AI
Every answer shows exactly where it came from, or says "I don't know." Self-hosted, so your data
never leaves your machine. No vendor lock-in, no black boxes — you control the models, the data,
and the infrastructure.
Website ·
Documentation ·
Install ·
How it works ·
Discord
Add a JSON file and choose Extract knowledge → each record becomes a node of its kind (programme, projects, risks) → open the mapping detection wrote → explore the graph in place → ask the Assistant, which answers with the records it rests on. Recorded end to end in the real product. Watch it in full quality (MP4).
Three promises
- One question across all your data. SQL databases, data lakes (S3, GCS, Azure Data Lake),
CSV, Parquet and Excel are read as tables, columns and rows. In JSON, XML and YAML, detection
finds the records at any depth, what identifies and names each, and how they link, and you correct
it in the Mapper. PDFs, Word, Markdown, HTML and email are read by their layout. All of it is
searched together, and questions about rows are answered with SQL over all of them.
- Every answer shows its proof, or abstains. Each piece of evidence names the asset it came
from, in the chat, the API and MCP. When the evidence isn't there, OpenCortyx says so instead of
guessing. Evaluations measure groundedness and abstention on your own questions.
- Humans stay in charge. Doubtful matches, conflicting values, new document versions and newly
discovered types wait in the Review Queue until a person decides. Nothing is overwritten.
How it's different
Memory tools such as Mem0, Supermemory and Graphiti remember what your users and agents said.
OpenCortyx answers from what your data says: tables, records and documents together, with
citations and human review. The two work well side by side.
License: MIT. Free for any use, including commercial. Details
What it does
- Add data, then choose what the graph gets: a table's or a JSON file's structure only, its
knowledge (one record, one node, with its identifier, name, text and dates, picked from the
columns' values), or the whole data. The data itself is always kept and read with SQL.
- Structure it your way: define node types, relationships and extractors in the dashboard,
including one that reads people, places and how they connect with your own model; every derived
fact keeps its source and confidence.
- Retrieve with evidence: hybrid search (vector, BM25, entity graph, multi-hop, structured
catalogue) fused and reranked. An entity found in many assets lists them ranked for the
question. Sources show only the records an answer rests on, grouped by file; the rest of what
was retrieved stays one click away.
- Browse the graph at any scale: workspace → sources → tags → assets → what each asset
contains, opened in place 100 at a time, so even a very large graph stays readable. The
workspace carries your name or your organisation's, set in Settings.
- Every record stays itself: ids in your data are kept as attributes, never used to merge
records; whether two records are the same thing is decided by the Resolution Engine, which groups
them under one master node, keeps both values and flags conflicts for review instead of
overwriting.
- Serve agents: a built-in MCP server gives Claude, Cursor, VS Code and other clients search,
answers, memory and governed write-back.
- Run anywhere: NebulaGraph holds the graph, Qdrant its search surfaces, Postgres the control
plane, and all three start with the stack. Connect a model already running on your machine
(Ollama, LM Studio, vLLM), Hugging Face Inference, or a hosted API.
Install
The only requirement is Docker with at least 8 GB of memory
available to it and about 10 GB of free disk.
macOS, Linux, WSL
curl -fsSL https://raw.githubusercontent.com/opencortyx/OpenCortyx/main/install.sh | bash
Windows (PowerShell)
irm https://raw.githubusercontent.com/opencortyx/OpenCortyx/main/install.ps1 | iex
The installer downloads the latest release, generates secrets, picks a model backend, starts the
stack and waits until it is healthy. Then open http://localhost:3000 and create your admin account.
Until the first stable release it installs the newest beta. To follow beta releases after that, set
OPENCORTYX_CHANNEL=beta for the installer, or run bin/opencortyx update --channel beta.
From a clone
git clone https://github.com/opencortyx/OpenCortyx.git
cd OpenCortyx
bin/opencortyx up # Windows: bin\opencortyx up
Choosing a model
Models are chosen in the dashboard under Models, one default per role (generation, extraction,
utility, embedding, rerank). No .env setting is involved.
| Setup | Generation model on the Models page |
|---|
| Ollama, LM Studio or vLLM on the same machine | OpenAI-compatible, http://host.docker.internal:11434/v1, Model ID from ollama list |
| Hugging Face Inference | HuggingFace Inference, your HF token, a Model ID such as Qwen/Qwen3-4B-Instruct-2507 |
| OpenAI, Anthropic, Groq | The provider, its API key and a Model ID such as gpt-4o-mini |
| Azure, Together | OpenAI-compatible, the provider's Base URL and API key |
A new workspace starts with a small built-in generation model (Qwen3-0.6B, on CPU inside the
stack), so the Assistant answers from the first file; connect a larger model for better and faster
answers. Embeddings and reranking also run on CPU inside the stack. OpenCortyx does not start a
model server of its own. See docs/models.md.
Features
AI Assistant: answers grounded in your data, with the records
each answer rests on grouped by the file they came from, and everything else retrieved one click
away under "Other evidence".
Assets: every ingested document, record set and table, with
its format, size, content fingerprint and everything derived from it.
Graph: the knowledge graph as a tree you open in place:
workspace, sources, tags, assets, and the records and entities each one holds.
Mapper: what detection found in your tables and JSON,
in sentences you can correct: what each record is, what identifies and names it, the fields it
carries into the graph and what it links to.
Ingestion: re-runnable ingestions from databases,
object storage and local folders, on demand, on a schedule or in real time.
Review Queue: decide on doubtful matches, conflicting
values, new document versions and newly discovered types. Nothing changes until you do.
System Health: a live check of the API,
database, worker and models, with suggested fixes.
The sidebar shows the pages used every day: Assistant, Add data, Connections, Customize, Runs,
Assets, Graph and Review. The rest are a click away inside them (Customize holds Mappings,
Extractors, Saved setups and Scheduled syncs; Settings holds Users, Models and System health), or
all in the sidebar with FULL_UI=1.
| Area | What you get | Guide |
|---|
| Discover | Assets, Lineage | discover.md |
| Trust | Curation, Nodes & Relationships, Review Queue, Evaluations, Quarantine | trust.md |
| Integration | Add data, Connections, Ingestion, Mapper, Custom Extractors, Pipelines, Runs | integration.md |
| Intelligence | AI Assistant, Conversations, MCP tools | intelligence.md |
| Administration | Users & Access, Models, System Health, Settings | administration.md |
How it works
flowchart LR
subgraph Sources
D[Documents]
R[JSON / XML / YAML]
T[Tables and databases]
end
Sources --> I[Ingestion<br/>mapping + pipeline]
I --> G[(NebulaGraph<br/>nodes · edges)]
I --> V[(Qdrant<br/>vectors · keyword documents)]
G --> Q[Retrieve · fuse · rerank<br/>ground · cite or abstain]
V --> Q
Q --> W[Dashboard]
Q --> API[REST API]
Q --> MCP[MCP server]
MCP --> A[Claude · Cursor · VS Code]
Sources are routed by shape: documents are chunked and extracted by a model, records are walked
into nodes deterministically, and tables are catalogued as tables, columns and rows. Every node
and edge lands in NebulaGraph and every searchable surface in Qdrant, while Postgres keeps the
control plane: collections, pipelines, mappings, runs and the ontology. A question runs several
retrievers in parallel, fuses and reranks their results, and answers only from evidence it can cite. The full walkthrough, with diagrams of
the data model and the answer pipeline, is in docs/how-it-works.md.
| Layer | Technology |
|---|
| Web | Next.js 15, React 19, TypeScript, Tailwind CSS |
| API and workers | Python 3.11, FastAPI, SQLAlchemy 2, Celery |
| Storage | NebulaGraph (graph) · Qdrant (vectors + BM25) · PostgreSQL 16 (control plane) |
| Queue | Redis |
| Models | Any OpenAI-compatible server, Hugging Face Inference or a hosted API; fastembed for embeddings |
Usage
bin/opencortyx up start (pull release images or build) and wait until healthy
bin/opencortyx up --build rebuild images from your checkout
bin/opencortyx status service status
bin/opencortyx doctor check Docker, database, model server and embeddings
bin/opencortyx logs [service] follow logs
bin/opencortyx connect claude KEY register the MCP server with Claude Code
bin/opencortyx backup | restore back up or restore every store (database, graph, vectors)
bin/opencortyx update move to the latest release and restart (--channel beta for betas)
bin/opencortyx version print the installed version
bin/opencortyx down stop (data is kept)
bin/opencortyx reset delete all data
Connect an AI client (MCP)
Create an API key in the dashboard under Users & Access, then:
bin/opencortyx connect claude ax_your_key # Claude Code
bin/opencortyx connect cursor ax_your_key # prints the config for ~/.cursor/mcp.json
Or add it to any MCP client by hand:
{
"mcpServers": {
"opencortyx": {
"type": "http",
"url": "http://localhost:8001/mcp",
"headers": { "X-API-Key": "ax_your_key" }
}
}
}
Tools include opencortyx_search, opencortyx_answer, opencortyx_graph_query,
opencortyx_remember, opencortyx_recall and opencortyx_propose. See the
full tool list.
Running in production
- Network: services listen on
127.0.0.1. Put a TLS reverse proxy in front of the dashboard
(3000), API (8000) and MCP server (8001), set PUBLIC_WEB_URL and PUBLIC_API_URL, and add the
proxy hostname to MCP_ALLOWED_HOSTS. Step by step: docs/installation/server.md.
- Secrets:
bin/opencortyx init generates unique secrets; the API refuses to start without
JWT_SECRET. Keep .env out of version control.
- Backups: schedule
bin/opencortyx backup and test restores. See docs/BACKUP-RESTORE.md.
- Updates:
bin/opencortyx update; migrations run automatically before the API starts.
- Resources: every container has a memory limit and rotated logs. See docs/memory-budget.md.
- Health:
bin/opencortyx doctor, GET /health, and Prometheus metrics at GET /metrics.
See SECURITY.md for reporting vulnerabilities and hardening notes.
Repository layout
apps/api FastAPI service, Celery workers, Alembic migrations, tests
apps/web Next.js dashboard and its Playwright end-to-end tests
apps/mcp MCP server
bin/ opencortyx command (bash and PowerShell)
docker/ container support files
docs/ user and contributor documentation
examples/data sample documents and datasets
scripts/ check-memory-budget.py (see docs/memory-budget.md)
compose.yaml the stack (compose.dev.yaml adds live reload for development)
Status
OpenCortyx is in beta. The core loop (ingest, extract, retrieve, answer, MCP) works end to end.
Extraction quality depends on the model you run; small local models produce fewer structured
entities than larger ones. Not built yet: PII masking, SSO/SCIM, text-to-SQL, change-data-capture,
and image or audio ingestion. Plans and requests are tracked in GitHub issues.
Community and contributing
License
OpenCortyx is released under the MIT License. Third-party components keep their own
licenses.
One of them is copyleft: the API image includes PyMuPDF and
pymupdf4llm, licensed under the GNU AGPL v3 (or a
commercial license from Artifex). OpenCortyx uses them to turn PDFs into Markdown. Running or
self-hosting OpenCortyx is unaffected. If you distribute a modified OpenCortyx, or offer one as a
network service, without sharing its source code, the AGPL applies to that combined work: share the
source, obtain a commercial PyMuPDF license, or remove the two packages.
