OpenCortyx: The Knowledge Layer for AI

1. 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. JSON, XML and YAML are mapped exactly as you define, not guessed by a model. PDFs, Word, Markdown, HTML and email are read and extracted. All of it is searched together.
• 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.

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.

2. Architecture

OpenCortyx runs as a single Docker stack on your machine or server:

• NebulaGraph holds the knowledge graph: every node (assets, chunks, rows, entities, claims, decisions, memories) and every typed edge between them.
• Qdrant holds the search surfaces: node and attribute vectors plus BM25 keyword documents.
• PostgreSQL is the control plane: collections, pipelines, mappings, runs and the ontology.
• Redis queues work between the API and the ingestion, extraction, embedding and maintenance workers.
• Models: a local vLLM server on an NVIDIA GPU, a model already running on your machine (Ollama, LM Studio), or a hosted API (OpenAI, Anthropic, Groq, Azure, Together). Embeddings run on CPU inside the stack.

The dashboard (Next.js, port 3000), REST API (FastAPI, port 8000) and MCP server (port 8001) all sit on top of the same graph.

3. Ingestion

Sources are routed by shape, so each is read the way it should be:

• Documents (PDF, Word, Markdown, HTML, email) are parsed, chunked and extracted by a model into entities, claims, topics and relationships.
• Records (JSON, JSONL, XML, YAML) are walked into nodes deterministically, following the schema mapping you define in the Mapper.
• Tables (SQL databases, CSV, Parquet, Excel) are catalogued as tables, columns and rows, with keys and foreign keys becoming edges.

Ingestions are re-runnable from databases, object storage and local folders, on demand, on a schedule or in real time. Every derived fact keeps its source and confidence. Ids in your data are kept as attributes, never used to merge records; the Resolution Engine decides whether two records are the same thing, keeps both values and flags conflicts for review. Anything that fails lands in Quarantine instead of disappearing.

4. Answering a question

1. Understand. Classify the question (lookup, semantic, relationship, multi-hop, temporal, aggregation) and pick the retrieval surfaces that help.
2. Retrieve. Run vector, attribute, BM25, identifier, fuzzy, metadata, entity-resolution and graph-traversal retrieval in parallel.
3. Fuse and rerank. Combine the ranked lists with reciprocal rank fusion, then rerank.
4. Build context. Collapse duplicate evidence, keep every source, and fit the model’s context window.
5. Answer or abstain. Generate an answer that cites its sources, verify it against the context, and abstain when the evidence is not there.

The same pipeline serves the dashboard’s AI Assistant, the REST API (POST /api/v2/answer, POST /api/v2/context) and the MCP tools.

5. 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. Models are chosen in the dashboard under Models.

6. 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" }
    }
  }
}

MCP tools

• opencortyx_search: ranked, cited context from the knowledge graph.
• opencortyx_answer: a grounded answer with citations, or an abstention.
• opencortyx_graph_query: query nodes and relationships directly.
• opencortyx_remember and opencortyx_recall: store and retrieve decisions, facts and preferences across sessions.
• opencortyx_propose: propose a change that a person approves in the Review Queue.

Every call runs as the caller’s API key, and the MCP server only accepts the hostnames you allow.

7. Status and license

OpenCortyx is in beta. The core loop (ingest, extract, retrieve, answer, MCP) works end to end. Extraction quality depends on the model you run. Not built yet: PII masking, SSO/SCIM, text-to-SQL, change-data-capture, and image or audio ingestion.

OpenCortyx is source-available under the OpenCortyx Community License: free for individuals, education, research, non-commercial use, and commercial teams of up to 5 people. Larger commercial use requires a commercial license.