chaoscypher

# Chaos Cypher Knowledge Engine

[![License: AGPL-3.0](https://img.shields.io/github/license/chaoscypherinc/chaoscypher?color=blue)](LICENSE)
[![Release](https://img.shields.io/github/v/release/chaoscypherinc/chaoscypher)](https://github.com/chaoscypherinc/chaoscypher/releases)
[![PyPI](https://img.shields.io/pypi/v/chaoscypher-cli?label=PyPI)](https://pypi.org/project/chaoscypher-cli/)
[![Docs](https://img.shields.io/badge/docs-chaoscypher.com-7b2ff7)](https://chaoscypher.com)
[![Discussions](https://img.shields.io/github/discussions/chaoscypherinc/chaoscypher)](https://github.com/chaoscypherinc/chaoscypher/discussions)

**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](https://ollama.com/).
- **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](https://modelcontextprotocol.io/) client straight into your graph:
  [36 tools](https://chaoscypher.com/docs/user-guide/mcp) 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](https://chaoscypher.com/docs/user-guide/knowledge-graph)** —
  typed, filterable, zoomable from corpus overview down to a single entity and
  its sources
- **[GraphRAG search](https://chaoscypher.com/docs/user-guide/search)** — graph
  traversal fused with vector search (Personalized PageRank + Reciprocal Rank
  Fusion), plus keyword, semantic, and hybrid modes
- **[AI chat with citations](https://chaoscypher.com/docs/user-guide/chat)** —
  answers grounded in your content, traceable back to the sources that produced
  them

**Data foundation**

- **[Quality analysis](https://chaoscypher.com/docs/user-guide/quality)** —
  score graph richness on a 0–100 scale, with breakdowns that flag weak sources
- **[30+ source formats](https://chaoscypher.com/docs/user-guide/sources)** —
  PDF, DOCX, Markdown, HTML, EPUB, audio (MP3/WAV/FLAC), video (MP4/MKV/MOV),
  images, ZIP archives, and more
- **[Mix-and-match LLMs](https://chaoscypher.com/docs/getting-started/configuration)** —
  Ollama, OpenAI, Anthropic, or Gemini, configurable per operation

**Automation & integration**

- **[Automations](https://chaoscypher.com/docs/user-guide/automations)** —
  visual workflow builder with triggers and conditional logic
- **[MCP server](https://chaoscypher.com/docs/user-guide/mcp)** — 36 tools for
  Claude Desktop, Cursor, ChatGPT, and other MCP clients
- **[Plugin system](https://chaoscypher.com/docs/user-guide/domains)** —
  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](packages/docs/docs/security/self-hosted-threat-model.md)
> 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:

![Animated walkthrough: upload a document, watch entities extract, explore the knowledge graph, ask a question, and trace the cited answer to the highlighted source sentence](packages/docs/static/img/demo.gif)

> ▶️ Watch the full tour (with audio-free narration captions) on
> [chaoscypher.com](https://chaoscypher.com).

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

![Dashboard showing entity and relationship counts, quality metrics, and a graph preview](packages/docs/static/img/screenshots/app-dashboard.png)

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

![Knowledge graph view with color-coded entity clusters around their source documents](packages/docs/static/img/screenshots/app-graph-default.png)

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

![Entity connections view listing typed relationships sorted by importance](packages/docs/static/img/screenshots/app-entity-connections.png)

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

![Source overview with pipeline flow stages, extraction counts, and entity distribution](packages/docs/static/img/screenshots/app-source-overview.png)

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

![Chat answering a question with a ranked entity list and clickable entity citations](packages/docs/static/img/screenshots/app-chat.png)

---

## 🚀 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](https://ollama.com/)
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:

```bash
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`:

```yaml
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`](.github/workflows/publish-ghcr.yml).

### Install the CLI from PyPI

Terminal-first? The standalone CLI installs with
[pipx](https://pipx.pypa.io/) (or plain pip):

```bash
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](https://pypi.org/project/chaoscypher-core/) on
every release — `chaoscypher-core` gives you the same extraction and search
engine as an embeddable library. See the
[developer quickstart](https://chaoscypher.com/docs/developer-guide/quickstart).

### Build from source (alternative / development)

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

```bash
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](https://chaoscypher.com/docs/getting-started/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](https://ollama.com/) 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](https://docs.astral.sh/uv/) 0.11+ — uv replaces pip and
reads the committed `uv.lock`):

```bash
make install      # First-time setup (packages + hooks + Docker test image)
make doc