# OpenCortyx: The Canonical Reference Guide
The Knowledge Layer for AI

## 1. SEO & Indexing Metadata

* SEO Title: OpenCortyx Docs: The Knowledge Layer for AI
* Meta Description: Technical reference for OpenCortyx, the knowledge layer for AI: architecture (NebulaGraph, Qdrant, PostgreSQL control plane), ingestion, cited answers, install and Model Context Protocol (MCP) setup.
* Canonical URL: https://www.opencortyx.com/docs/
* Organization: OpenCortyx Core Team
* Open Graph Title: OpenCortyx Architecture & Technical Reference
* Twitter Title: OpenCortyx: The Knowledge Layer for AI

## 2. Overview

* Status: Beta (v0.1.0)
* License: Source-available (OpenCortyx Community License)
* Deployment: Self-hosted with Docker
* Interfaces: Dashboard, REST API, Model Context Protocol (MCP)

OpenCortyx connects your data, documents, systems, and relationships into one intelligent knowledge layer that gives AI agents the context they need to understand, reason, and act. Every answer shows exactly where it came from, or says "I don't know." Self-hosted, so your data never leaves your machine.

## 3. Three Promises

1. **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.
2. **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.
3. **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.

## 4. Architecture

```
  Sources: documents · JSON/XML/YAML · tables and databases
        |
        v
  Ingestion (mapping + pipeline)
        |
        +--> NebulaGraph (nodes, edges)
        +--> Qdrant (vectors, BM25 keyword documents)
        |
        v
  Retrieve · fuse · rerank · ground · cite or abstain
        |
        +--> Dashboard   +--> REST API   +--> MCP server --> Claude, Cursor, VS Code
```

| 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 | vLLM or any OpenAI-compatible endpoint; fastembed for embeddings |

## 5. Ingestion

* **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 defined in the Mapper.
* **Tables** (SQL databases, CSV, Parquet, Excel) are catalogued as tables, columns and rows; keys and foreign keys become edges.

Every derived fact keeps its source and confidence. Ids in your data are kept as attributes, never used to merge records; the Resolution Engine keeps both values and flags conflicts for review. Failures land in Quarantine instead of disappearing.

## 6. Answering a Question

1. **Understand**: classify the question (lookup, semantic, relationship, multi-hop, temporal, aggregation).
2. **Retrieve**: run vector, attribute, BM25, identifier, fuzzy, metadata, entity-resolution and graph-traversal surfaces.
3. **Fuse and rerank**: reciprocal rank fusion, then rerank.
4. **Build context**: deduplicate evidence, keep sources, fit the context window.
5. **Answer or abstain**: cite sources, verify against the context, abstain when evidence is missing.

## 7. Install

Requires Docker with at least 8 GB of memory and about 10 GB of free disk.

```bash
curl -fsSL https://raw.githubusercontent.com/opencortyx/OpenCortyx/main/install.sh | bash
```

```powershell
irm https://raw.githubusercontent.com/opencortyx/OpenCortyx/main/install.ps1 | iex
```

Then open http://localhost:3000 and create your admin account.

## 8. MCP Setup

```json
{
  "mcpServers": {
    "opencortyx": {
      "type": "http",
      "url": "http://localhost:8001/mcp",
      "headers": { "X-API-Key": "ax_your_key" }
    }
  }
}
```

Tools: `opencortyx_search`, `opencortyx_answer`, `opencortyx_graph_query`, `opencortyx_remember`, `opencortyx_recall`, `opencortyx_propose`.

## 9. Status and License

Beta. The core loop (ingest, extract, retrieve, answer, MCP) works end to end. Not built yet: PII masking, SSO/SCIM, text-to-SQL, change-data-capture, and image or audio ingestion.

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.