Chaos Cypher Knowledge Engine

Turn your documents into a knowledge graph you can inspect, search, chat with, and take with you — all running on your own machine.

Chaos Cypher is a local-first GraphRAG platform — knowledge you can see, trust, and own. Point it at your sources (documents, audio, video, images, pasted text, web pages — 30+ formats, auto-detected), and it extracts entities and relationships into a knowledge graph you can actually see and explore — not a black-box vector blob. Search it, chat with it, refine it, and export the result as a portable Lexicon knowledge package (.ccx) you can back up, share, or load into another instance.

Why Chaos Cypher

• Local-first GraphRAG — sources → extraction → graph → search & chat, with embeddings generated on your own system. Bring your own LLM, or run fully offline with Ollama.
• Inspectable knowledge graphs — every entity and relationship is visible and traceable back to its source. You can correct extractions, not just trust them.
• Portable knowledge packages — import and export your graph as a self-contained package. Your knowledge is yours to move, version, and keep.
• MCP server built in — plug Claude Desktop, Cursor, or any MCP client straight into your graph: 36 tools for search, traversal, and graph building.
• Self-hosted control — you choose where data lives and which models touch it. The all-in-one container runs the whole stack on hardware you control.

Feature highlights

Core intelligence

• Knowledge graph canvas — typed, filterable, zoomable from corpus overview down to a single entity and its sources
• GraphRAG search — graph traversal fused with vector search (Personalized PageRank + Reciprocal Rank Fusion), plus keyword, semantic, and hybrid modes
• AI chat with citations — answers grounded in your content, traceable back to the sources that produced them

Data foundation

• Quality analysis — score graph richness on a 0–100 scale, with breakdowns that flag weak sources
• 30+ source formats — PDF, DOCX, Markdown, HTML, EPUB, audio (MP3/WAV/FLAC), video (MP4/MKV/MOV), images, ZIP archives, and more
• Mix-and-match LLMs — Ollama, OpenAI, Anthropic, or Gemini, configurable per operation

Automation & integration

• Automations — visual workflow builder with triggers and conditional logic
• MCP server — 36 tools for Claude Desktop, Cursor, ChatGPT, and other MCP clients
• Plugin system — drop-in Python document loaders, extraction domains, and workflow tools

What data leaves your machine?

By default, nothing leaves your machine except the LLM calls you configure. Embeddings are computed locally; your documents, graph, and exports stay on disk in a Docker volume you own. If you point Chaos Cypher at a hosted LLM provider (OpenAI, Anthropic, Gemini), the text sent for extraction and chat goes to that provider — choose a local model like Ollama to keep everything on-device.

Read the Self-Hosted Threat Model for exactly what Chaos Cypher defends against, what it accepts by design, and how to harden a LAN or internet-facing deployment.

📸 See It in Action

A quick tour — from dropping in a document to asking a question and tracing the answer back to the exact highlighted sentence in your source:

▶️ Watch the full tour (with audio-free narration captions) on chaoscypher.com.

Dashboard — your knowledge base at a glance: entity and relationship counts, quality and density scores, and a live graph preview.

Knowledge graph — every source becomes an explorable, color-coded graph. Pan, zoom, search, and filter to see exactly what was extracted.

Entities — inspect any extracted entity: typed, directional relationships ranked by importance, with stats and provenance back to the source document.

Sources — each document gets a transparent pipeline view: loaded → cleaned → chunked → extracted → indexed, plus per-source entity distribution.

Chat — ask questions in plain language and get GraphRAG answers with inline entity citations you can click through to the graph.

🚀 Quick Start

Prerequisites: Docker (with Compose). That's it for end users — embeddings run locally on CPU. You'll also want an LLM provider; Ollama keeps everything on-device.

Run the published container (recommended)

The recommended install path is the all-in-one image published to the GitHub Container Registry:

docker run -d --name chaoscypher \
  -p 80:80 \
  -p 443:443 \
  -v chaoscypher-data:/data \
  --add-host=host.docker.internal:host-gateway \
  ghcr.io/chaoscypherinc/chaoscypher:latest

# Then open http://localhost  (443 is published so HTTPS works if you enable TLS)

Prefer Compose? Save this as docker-compose.yml and run docker compose up -d:

name: chaoscypher
services:
  chaoscypher:
    image: ghcr.io/chaoscypherinc/chaoscypher:latest
    container_name: chaoscypher
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - chaoscypher-data:/data
    extra_hosts:
      # Lets the container reach an Ollama running on the host (Linux engines
      # don't resolve host.docker.internal without this)
      - "host.docker.internal:host-gateway"
    restart: unless-stopped
volumes:
  chaoscypher-data:

The image is built and pushed on every vX.Y.Z release by .github/workflows/publish-ghcr.yml.

Install the CLI from PyPI

Terminal-first? The standalone CLI installs with pipx (or plain pip):

pipx install chaoscypher-cli
chaoscypher setup                 # wizard: pick an LLM provider
chaoscypher source add paper.pdf

All four Python packages (chaoscypher-core, -cortex, -neuron, -cli) are published to PyPI on every release — chaoscypher-core gives you the same extraction and search engine as an embeddable library. See the developer quickstart.

Build from source (alternative / development)

Clone and build the all-in-one image locally — no published image required:

git clone https://github.com/chaoscypherinc/chaoscypher.git
cd chaoscypher
make docker-up      # builds + starts the all-in-one container
# Open http://localhost

Try it in about 5 minutes

The quickstart covers this in detail — import and search work within about 5 minutes; extraction and chat come online once your LLM provider is set up (for Ollama, after a one-time model download).

1. Start the app with one of the paths above and open http://localhost.
2. Create your single-user login on the first-run setup page.
3. Pick an LLM provider in Settings — point at a local Ollama model to stay fully offline, or add an API key for OpenAI / Anthropic / Gemini.
4. Add a source — upload a document or paste text. Chaos Cypher extracts entities and relationships in the background (watch progress in the Queue Monitor).
5. Explore the graph — open the knowledge graph view to see what was extracted, search across it, and chat with your sources.
6. Export a knowledge package when you're happy with the result, so you can back it up or load it elsewhere.

Development setup (with hot-reload)

For contributors who need per-service hot-reload (requires Python 3.14+, Node.js 22+, and uv 0.11+ — uv replaces pip and reads the committed uv.lock):