DEV Community: Denis MacPherson

Chaos Cypher v0.6.0: Memory for Agents That Says Who Said It

Denis MacPherson — Fri, 30 Oct 2026 15:21:11 +0000

An agent that works with you for a week learns a lot, and almost all of it is gone the next time it starts. The usual fixes are a notes file it rereads or a vector store it searches, and neither can tell you who said a thing, when, or what it replaced.

Chaos Cypher v0.6.0 is the agent-memory release. It has three themes: memory for agents, retrieval that reads the question, and sources you can keep current. It also carries breaking changes for MCP clients, custom domain plugins and databases from before the core entity types, so if you run any of those, read the upgrade notes before you pull the image.

Memory for agents

Five new MCP tools let an agent hand Chaos Cypher a sentence or a note in plain words and get it back later as facts with where they came from:

remember stores the text as a source of type memory. It is kept whole and searchable at once, and its facts are extracted against the entities the graph already knows, so a later "Pierre" lands on the same Pierre node. A text that looks like a key or a password is refused and nothing is stored.
recall answers in the shape of the question — an entity card, a grouped list, a relation chain, or a digest — with every fact tagged [who DATE], [doc TITLE] or [pack NAME].
forget previews the matches first, then removes one memory and the facts only it stated, and leaves an audit row with the counts — never the text.
list_memories and digest show what is stored and what a window of time added, replaced and forgot.

A later memory on a single-valued relation (where someone lives) replaces the earlier fact and keeps it as history, and recall(as_of=…) shows the facts as they stood on a date.

Three things make this practical on a small local setup:

No embedding model required. With search.enable_vector_search: false, the CLI, the Python API and chaoscypher mcp make no embedding call; search answers with keyword results and every memory tool works.
Several agents, one database. One chaoscypher mcp -m write per agent can share a database on the same machine and a local disk. No write is lost; a write that cannot get the lock in 60 seconds answers one fixed "database is busy" line instead of hanging.
Nothing is dropped when linking is slow. remember stores the memory before it links it into the graph; if the model does not answer in time, the memory is kept as a note, says why, and links later.

chaoscypher mcp --profile memory serves only these five tools, which keeps a small model's tool list short, and chaoscypher memory export writes memories to a .ccx package another database can load. The Memory guide walks through it.

In plain terms: your agent can now keep what it learns between sessions, and every fact it recalls tells you who said it and when.

Retrieval that reads the question

Before chat builds its graph context, it now decides what kind of question it was asked: a lookup, an aggregate (everything sharing a relation with a named entity), a path (how two named things are connected) or a global question. An aggregate gets the entity's relationships grouped by label, each with the sentence that states it; a path gets the shortest relation chains between the two entities, each hop with its sentence. The default router uses rules, with no extra model call.

The graph is also handed to the model in a tighter shape (40 triples instead of 200 by default), an identity resolver merges one entity written under two names after every commit, and hybrid search gains a real keyword half: chunks now have a full-text index.

In plain terms: chat looks for the kind of evidence your question needs, and shows the model the sentences behind it rather than a wall of triples.

Sources you can keep current

Paste a documentation site's address and each of its pages is imported as its own source under one site, found through the site's llms.txt, its sitemaps, or a three-link-deep crawl that never leaves the address you gave. Check for updates re-fetches every page: unchanged pages are left alone, changed ones re-imported in place, new ones added, and a page the site no longer lists is marked Gone from site, never deleted. Pages you left out stay out. The crawler sends its own user agent and honours robots.txt. See Import a Docs Site.

In plain terms: a docs site becomes one source you can refresh, and your citations keep pointing at the page they came from.

Also in this release

Nothing that says something is deleted by a filter. Entities and relationships the extraction filters used to drop are now kept with a flag (unevidenced, low_plausibility) when they carry a description or evidence.
Pinned decoding by default: temperature 0 and seed 42 for chat and extraction, so re-imports and retries give the same output for the same input (only Ollama honours the seed). Regenerate still gives a different answer.
Security: the PyPI packages carry PEP 740 attestations, chat runs only the tools it offered the model, and a failed MCP tool call answers a fixed sentence and a code, never the error's own text.

Upgrading

Upgrade with the published image:

docker pull ghcr.io/chaoscypherinc/chaoscypher:0.6.0

or pip install -U chaoscypher-cli. Before you swap the image, drain the queue (wait for /api/v1/queue/stats to report 0 pending). Eighteen migrations run on first start, six of them needs_confirmation. Read Breaking changes and Upgrade advisory in the v0.6.0 changelog first if you run custom domain plugins, MCP clients that match error strings, API clients that threshold the hybrid search score, or a database extracted before the core entity types — that last one is not migrated in place: export with v0.5.0, upgrade, then import.

New here? The ten-minute quickstart runs the whole stack locally with Ollama, and nothing leaves your machine unless you choose.

Build It Once, Mount It Anywhere: One Knowledge Package, Any MCP Client

Denis MacPherson — Fri, 30 Oct 2026 15:17:52 +0000

The local AI stack has a runtime, a model format, a model hub, and an agent protocol. It does not yet have a portable knowledge layer. The graph you spent an afternoon building is trapped in whichever app built it, and the assistant you actually work in cannot see it.

chaoscypher mount is the smallest thing we could ship that fixes that. One command pulls a knowledge package, imports it into a database of its own, indexes it, and serves it over MCP. Put that command in an assistant's config and the assistant has the knowledge every time it launches.

This post builds a package on one machine, moves it to another, and mounts the same file into two different assistants, with the same command ready for any other MCP client. Nothing about the package changes between them.

What You'll Build

A knowledge graph extracted from a set of documents, exported as a single .ccx file
That file mounted into Claude Desktop and Claude Code on a second machine
The same multi-hop question answered by both, each citing from the same evidence base

The package format is CCX, an open, documented format with a standalone reader. What travels is the graph, the source text, the chunks, and the citations. What does not travel is any dependency on the machine that built it.

Step 1: Build the graph, then export it

On the build machine, run Chaos Cypher and add your documents. The ten-minute quickstart covers this with Ollama; the previous post does it with Claude doing the extraction. Either way you end up with a graph in a database.

Export it:

chaoscypher graph package export --output research.ccx

The default export carries everything a mount needs: templates, entities, relationships, sources, chunks, and citations. The archive is deterministic and checksummed, so the same graph produces the same bytes and a tampered file fails validation on the other side.

Copy research.ccx to the second machine however you like, or publish it to the Lexicon Hub with chaoscypher push research.ccx and pull it by name.

Step 2: Mount it

On the second machine, install the CLI:

pipx install chaoscypher-cli

Then mount the package once, without serving, to see what it does:

chaoscypher mount ./research.ccx --no-serve

This is the real output for a package built from fourteen of Chaos Cypher's own architecture pages:

Importing: archdocs.ccx
✓ Mounted ./archdocs.ccx → database archdocs: 177 entities, 205 relationships, 14 sources, 178 citations
Indexing for search with the local embedding model (Qwen/Qwen3-Embedding-0.6B); the first use downloads it.
✓ Indexed 14 sources and 177 nodes for search

Serve it with: chaoscypher mcp --database archdocs

Three things happened. The package went into a database named after it, so it does not mix with anything else on the machine. The sources and citations came along, not just the entities, which is what keeps answers traceable. And a mount.json marker was written with the package's SHA-256, so the next mount of the same file skips the import.

That last point is the whole design. An MCP host runs its server command on every launch. mount is safe to run on every launch.

There is no chaoscypher setup in this step either. Mounting needs no chat or extraction model; the assistant's own model asks the questions. With vector search on (the default) the mount is indexed for semantic search with the configured embedding model (by default a local one, downloaded on first use); if vector search is off, it is keyword-searchable only.

Step 3: Mount it into your assistants

The command is the same each time. Only the config file changes.

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "research": {
      "command": "chaoscypher",
      "args": ["mount", "/home/me/research.ccx"]
    }
  }
}

Claude Code:

claude mcp add research -- chaoscypher mount /home/me/research.ccx

Any other MCP client. The MCP user guide has the Cursor configuration alongside Claude's; for any client that launches a stdio MCP server, point its server list at the same chaoscypher mount command. The knowledge on the other end is identical.

If the package came from the Hub, replace the path with the reference:

"args": ["mount", "acme/research"]

Step 4: Ask both the same question

Pick a question that needs two hops, so the graph has something to do:

Which components depend on the queue client, and which ADR governs changing it?

Each assistant calls graphrag_search. The tool embeds the question, seeds a Personalized PageRank walk from the closest entities, and fuses two evidence lists: the chunks the top entities were cited from, and the chunks a hybrid keyword-and-vector search would return. The response carries the graph context and the chunks with aliases the assistant uses for inline citations.

Because the citations traveled inside the package, every assistant cites from the same sources and chunks the graph was built from. Each host's model picks which chunks to cite; the evidence it picks from is identical. Two assistants, one set of receipts.

In plain English: you built the knowledge once. Every assistant that mounts it gets the same facts and the same evidence, without re-reading a single document.

Why a mount and not an import

Chaos Cypher already had chaoscypher graph package load, which merges a package into the database you are working in. That is the right tool when you want the knowledge in your graph, alongside everything else you have built.

A mount is different in two ways. It goes into its own database, so it cannot collide with your work and can be thrown away with chaoscypher db delete. And it is idempotent, so it belongs in a config file rather than a runbook.

The metaphor is deliberate. You mount a volume; you do not copy its contents into your home directory.

What it does not do yet

A mount is read-only by default. Pass --mode write if you want the assistant to be able to add to the mounted database, but the package on disk does not change when it does. There is no unmount command; deleting the database is the unmount. And the default export leaves embedding vectors out, so with vector search on, the mounting machine re-embeds the package with whatever embedding model is configured there; that happens once, on the first launch, and takes a moment. With vector search off, nothing is embedded and the mount is keyword-only. Pass --embeddings at export time if both machines use the same model and you want to skip it.

Next steps

The Mount command reference lists every option and the mount-versus-load comparison.
Packages compose. An axiomatize.yaml can merge several packages into one served database with chaoscypher compose. That is a post of its own.
If you publish a package to the Hub, the same mount line works for everyone who pulls it.

GraphRAG with Ollama in 10 Minutes: The Local-First Quickstart

Denis MacPherson — Mon, 28 Sep 2026 14:50:48 +0000

You don't need a cloud API key to try GraphRAG. Ten minutes, one document, and a laptop with a decent GPU (or none at all, for the first few steps) is enough to see a full knowledge graph form and answer a question with a citation you can click through to the source page.

This is the fast version. If you want the reasoning behind running everything locally -- privacy, VRAM presets, multi-GPU load balancing -- that's in Build a Private AI Knowledge Graph That Never Leaves Your Machine. This post is the "just show me" version: install, upload, watch the graph build, ask a question, done.

What You'll Build

By the end of this walkthrough you'll have:

Chaos Cypher running locally via Docker
A local LLM (Ollama) doing the entity extraction and chat
One document imported, chunked, and embedded
A knowledge graph of entities and relationships extracted from that document
A chat answer with a citation that traces back to the exact chunk it came from

Nothing leaves your machine. No OpenAI key, no Anthropic key, no usage bill.

Step 1: Install Ollama and Start the Model Download

Grab Ollama from ollama.com for your platform, then pull the default chat/extraction model in a terminal:

ollama pull qwen3:30b-instruct

This is the long pole of the whole setup -- roughly 18-20 GB. Kick it off now and let it run in the background while you do the next steps; indexing and search don't need it, only extraction and chat do.

If you're on a smaller GPU or just want to see the pipeline move faster for this first run, point ollama_chat_model at a smaller qwen3 tag instead -- you can always switch to the full model afterward from Settings.

Step 2: Start Chaos Cypher

docker run -d --name chaoscypher \
  -p 80:80 \
  -p 443:443 \
  -v chaoscypher-data:/data \
  ghcr.io/chaoscypherinc/chaoscypher:latest

On Linux Docker Engine (not Docker Desktop), add --add-host=host.docker.internal:host-gateway so the container can reach Ollama on your host -- Docker Desktop resolves this automatically.

Open http://localhost. A startup page shows each service (Nginx, Cortex, Valkey, Neuron) coming online -- usually 30-60 seconds. Set a username and password on first run, and you land on the Dashboard.

Step 3: Upload a Document

Go to Sources in the sidebar and drag in a PDF, DOCX, or text file -- a 10-20 page document is a good first run so you can watch the whole pipeline complete in a couple of minutes.

Indexing starts immediately (chunking + embedding for search) and finishes in about 30 seconds per 100 pages -- this step downloads a small embedding model (~600 MB) the first time, but doesn't need Ollama at all. Once indexing finishes, a Review dialog proposes an extraction domain (technical, medical, legal, and so on) detected from the content. Click Confirm to queue entity extraction.

If the Ollama model pull from Step 1 is still running, the source will sit at extracting until it finishes -- indexing and search still work while you wait.

Step 4: Watch the Graph Form

Once extraction commits, open Graph in the sidebar. You'll see nodes for the people, organizations, concepts, and events the model found in your document, connected by edges representing the relationships it inferred between them. For a 100-page document on a 30B-class model, expect roughly 5-10 minutes of extraction time.

Click any node to see its properties, its connections, and the source text it was extracted from -- that link back to source evidence is the same mechanism the chat citations use in the next step.

Step 5: Ask a Cited Question

Open Chat, start a new conversation, and ask something specific about the document you just uploaded. Chaos Cypher retrieves the relevant chunks and graph context, hands them to your local model, and streams back an answer with citations attached to the sentences that came from your source.

Click a citation and it jumps straight to the exact chunk in the source document the sentence was grounded in -- not a link to "the document," the specific paragraph. That's the difference between an AI answer you have to take on faith and one you can verify in a click.

Where to Go From Here

That's the whole loop: install, upload, extract, ask, verify. A few directions once you're comfortable with it:

Bigger documents, bigger graphs. Upload a set of related documents as a single archive (a zip) and the graph connects entities across everything inside it. Today each separate upload builds its own graph; cross-source entity resolution is on the roadmap, not in the box.
Tune for your hardware. The VRAM preset table and multi-instance GPU setup in the privacy-first deep dive cover getting the most out of local hardware.
Mix local and cloud. Keep chat and search local for privacy, and switch just the extraction pass to a cloud provider if you want maximum quality on a hard document -- it's a single settings change, same pipeline either way.

In plain English: you can run a real knowledge graph, end to end, on your own machine, in about the time it takes to read this post.

Claude Built Its Own Knowledge Graph. No Local LLM Was Involved.

Denis MacPherson — Mon, 28 Sep 2026 14:50:30 +0000

Every GraphRAG tool I know of has the same shape: the server owns a language model, and the server calls it to turn documents into a graph. That is fine when you have a GPU and a model you like. It is a problem when the best model you have access to is the one already sitting in your editor, and it has no idea your knowledge base exists.

Chaos Cypher's MCP server flips the direction. The assistant on the other end of the connection does the extraction. Claude Code reads the chunks, decides what the entities and relationships are, submits them back, and commits the graph. The server never calls a model. When it is done, the same assistant can ask the graph questions it could not have answered from its context window.

This post walks through that flow end to end with Claude Code. It works the same way from Claude Desktop, Cursor, or any MCP client whose model can follow a short set of instructions.

What You'll Build

Chaos Cypher's MCP server connected to Claude Code, in write mode
A knowledge graph built from a folder of your own markdown, extracted by Claude itself
A persistent graph on your disk that survives closing the session
A multi-hop question answered from the graph, with citations back to the sentences that support it

The only model involved is the one Claude Code is already using. Chaos Cypher computes the chunk embeddings locally with sentence-transformers on CPU, and nothing else runs a model.

Step 1: Install the CLI and connect it to Claude Code

The MCP server ships in the standalone CLI:

pipx install chaoscypher-cli

The CLI needs Python 3.14 or newer. Then register the server with Claude Code in write mode, because building a graph means adding documents:

claude mcp add chaoscypher -- chaoscypher mcp --mode write

That is the whole setup. There is no chaoscypher setup step here on purpose: the wizard configures a chat and extraction model for the server, and this flow does not use one.

Step 2: Ask Claude to build the graph

Open Claude Code in a project that has some prose in it — design notes, ADRs, meeting notes, a docs folder. Then ask:

Add every markdown file under docs/ to the Chaos Cypher knowledge graph, extract the entities and relationships yourself, and tell me the quality grade when you're done.

Here is what happens next, tool by tool. You can watch it in Claude Code's tool log.

add_document takes a file path (or a URL), chunks the text, and embeds the chunks locally. By default it only indexes; it does not ask the server to extract anything. The tool description tells the assistant exactly what to do next, which is why a one-line prompt is enough.

confirm_extraction clears the domain gate. Chaos Cypher auto-detects an extraction domain for each source — technical, scientific, legal, and so on — and parks the source until someone confirms it. Claude confirms it, or overrides it if you told it to.

get_extraction_tasks returns the plan: how many chunk groups there are and the extraction instructions, including the output format Claude is expected to produce.

get_extraction_chunks fetches the text of a chunk group with numbered sentences. This is the part that matters for trust. Every entity and relationship Claude submits has to point at the sentence numbers that support it.

submit_chunk_extraction is where Claude does the work. The format is a compact line protocol rather than JSON, one entity per line with its properties following, then one relationship per line:

E|Alice Smith|Person|Alice; A. Smith|0.95|S1|Lead engineer on the ingest service
P|0|role|Lead Engineer
E|Ingest Service|Component|ingest-svc|0.9|S1-S2|Handles uploads and chunking
R|0|1|works_on|0.9|S1|Alice Smith leads the ingest service

The S1 and S1-S2 fields are sentence references. On the server, an evidence validator checks each one against the numbered text. An entity that does not appear in the sentence it cites is dropped, and the drop is counted so you can see it later.

finalize_extraction deduplicates entities across chunks, matches them to templates, writes the citations, and commits the graph. It returns a quality grade on a 0 to 100 scale with the breakdown behind it.

That is the whole loop. For a folder of thirty markdown files it takes Claude a few minutes, and the tool log shows every submission.

In plain English: Claude reads your documents in numbered chunks, writes down what it found and which sentences prove it, and Chaos Cypher checks the receipts before committing anything.

Step 3: Look at what it built

The graph is an ordinary Chaos Cypher database in your data directory. Start the local server and open it:

chaoscypher serve

Every entity is typed, every relationship has a justification, and every one of them links back to the source chunk and the sentence Claude cited. The source page shows the pipeline for each file: loaded, chunked, extracted, indexed, with the quality breakdown and a count of anything the evidence check rejected.

If a relationship looks wrong, you can edit or delete it here. The graph is yours to correct, not a black box you have to trust.

Step 4: Close the session. Open a new one. Ask a hard question.

This is the part that makes the whole thing worth doing. Quit Claude Code and start it again. The context window is empty. The graph is not.

Using the Chaos Cypher graph, which components depend on the queue client, and which ADR governs changing it?

Claude calls graphrag_search. That tool embeds the question, finds the entities closest to it, runs Personalized PageRank over the graph from those seeds, and pulls two kinds of evidence: the chunks that the top-ranked entities were cited from, and the chunks a plain vector search would have returned. The two lists are fused with Reciprocal Rank Fusion and handed back with the graph context, so the answer names the components, the ADR, and the chunks each fact came from.

A question like that needs two hops: from the queue client to the things that depend on it, and from there to the decision record that governs them. Vector search over chunks tends to return the three chunks that mention "queue client" and stop. The graph walks the edges.

Chaos Cypher also degrades honestly. If the embedding model is unavailable the tool falls back to keyword search and says so in the response's retrieval mode, rather than returning nothing.

Why this is different

Three things make client-driven extraction more than a party trick.

The server needs no model. The assistant you already pay for, or the local one you already run in your editor, does the extraction. A laptop with no GPU can build a graph with Claude doing the reading.

The evidence check runs on the server, not in the prompt. Whatever the assistant submits is validated against the numbered sentences before it is committed. The graph records what was rejected and why. You do not have to trust the model's confidence number; you can look at the sentence.

The graph outlives the session. It sits in a SQLite database on your disk. It is inspectable in the UI, exportable as a .ccx package, and available to the next session, the next tool, or the next machine.

What it does not do yet

Extraction quality is the assistant's quality. A weak model will submit weak extractions; the evidence check catches fabrications, not shallow reading. The server also rate-limits submissions per source (100 per minute by default) and caps each submission's size, so a very large corpus is best fed in batches. And add_document takes one file at a time; for a whole folder, the assistant loops, or you zip the folder and add the archive.

Next steps

The full tool list, with the client-driven extraction limits, is in the MCP user guide.
Once the graph is built, export it as a .ccx package and mount it into another assistant with one command. That is the next post.

Chaos Cypher v0.5.0: Mount a Knowledge Package Straight Into Your MCP Host

Denis MacPherson — Mon, 28 Sep 2026 14:49:57 +0000

v0.5.0 is the first feature release since v0.4.0: 30 commits since v0.4.3, 19 of them changing product code. Two themes run through it. Knowledge in motion — a package you build can be mounted straight into an MCP host as a one-line config entry, or stacked with other packages into a single database your agent queries. And measurement — two benchmark boards that score local models pass/fail without a judge model, a /leaderboard page that blends them into one Overall score, and model pickers in the app that read the same numbers.

`chaoscypher mount` — a package, served over MCP, in one command

The gap this closes: you build a knowledge graph on one machine, export it as a .ccx package, and then have to write a setup script on the other machine before an assistant can use it.

chaoscypher mount is one idempotent command. It resolves a .ccx — a local file, or a Lexicon Hub owner/name — imports it into a database of its own (templates, knowledge, workflows and sources, chunks and citations), indexes it for search, and hands that database to the stdio MCP server. A mount.json SHA-256 marker makes every later launch skip the import, which is the property that matters: the command belongs directly in an MCP host's config rather than in a setup script that runs once and is never thought about again.

It is first-run-safe. No chat or extraction model is needed on the serving side, because the host's model asks the questions. All output goes to stderr, since stdout is the JSON-RPC channel.

In plain English: you can paste one command into Claude Desktop's config and the graph is there, with its citations, on every launch.

`chaoscypher compose` now works on CCX 3.0

compose was a pre-3.0 prototype, and it failed quietly in three separate ways: the merger read a data/*.json layout that no package has, so every build produced 0 entities; up launched a Cortex entrypoint that exited 0 at import time; and down could not stop a detached server.

The merger now imports each resolved package into a real runtime database through CcxImporter — templates, knowledge, sources, chunks, citations and IRIs intact — counts totals from that database, records its inputs in composition.json, and runs a best-effort embedding and vector indexing pass afterwards. up launches Cortex the way serve does, logs to <output>/server.log, watches the child through a startup grace period and fails with the log tail if it dies. --detach records compose.pid and refuses to stack a second live server. down does SIGTERM then SIGKILL with the configured grace, cleans stale records, and says "nothing running" instead of claiming success.

Two new subcommands come with it. compose init [--name] [PACKAGES…] writes a starter axiomatize.yaml and refuses to overwrite one without --force. compose mcp builds the composition if its database is missing, then replaces the process with chaoscypher mcp on the composed database — stdio passes straight through and the host sees one pid.

In plain English: several knowledge packages, one database, one server your agent queries — and the commands now tell you the truth about whether it is running.

Citations into audio and video now carry timestamps

The audio and video loaders joined Whisper's transcript and threw the segment times away, so a citation into a recording could say which file but never when. Chunks now carry the seconds of the recording they came from, the way PDF chunks carry a page number, and the position travels everywhere a chunk goes: GraphRAG provenance and vector chunks, search_chunks, summarize, the search-engine dicts and chat citation resolution. The interface renders them as time badges — "12:34" beside a chunk number, "At 1:27–2:13" on a chat citation chip.

Two benchmark boards, scored without a judge

chaoscypher benchmark gains an instruction-probe tier: 65 probes across five sections, one per extraction instruction, each with a passage constructed so the correct extraction is unambiguous and checkable by eye. Probes call the real extractor with the real prompts, settings pins and line parser, so a pass means the product could use the output. A "carrier" tier splices each probe into a real ~3,000-character extraction group from the corpus, testing production density rather than production length.

The second board is grounded chat. Every labelled question is scored by pure functions: the answer names the terms a correct concise answer must contain, carries no names or numbers the retrieved context does not support, leads with the right entity when two are confusable, declines when the sources cannot answer, and passes a completion gate. A judge model is now optional rather than required. The fixture is War and Peace Book One — 113,934 characters against a ~7.7k retrieval window, so a question is answered from retrieval and not from the whole corpus — with 80 labelled questions covering single-hop, paraphrase, multi-hop across chapters, fine-grained confusable pairs, and out-of-scope questions with decoys.

/leaderboard blends the two: Model, Overall, Extraction, Chat, VRAM and Speed. Overall is 0.6 × extraction + 0.4 × chat, and the weights are written into the exported data rather than recomputed per page, so the leaderboard, the homepage teaser and the app's model pickers agree. Each score shows its counts, its pass rule, the retrieval floor and the run time.

In plain English: the numbers are produced by checks you can read, and every page that shows them shows the same ones.

The measurement work found two things that made every earlier number suspect

This is the part worth reading even if you never run a benchmark.

Extraction truncation was invisible four layers deep — and a truncated extraction scores higher than a complete one. Measured twice, independent of thinking mode: gemma4:31b scored 72.09 truncated against 67.02 complete, and qwen3.8:27b under a forced 300-token budget scored 76.49 against 71.25. Core computed the signal correctly the whole time; it died on the way to anyone who could act on it. The CLI ingest path received the metrics dict from extract_single_chunk and discarded it, so every chaoscypher load dropped truncation on the floor and chaoscypher source get reported a clean ingest for a source whose chunks were cut off. A new get_source_counters validates against the same allowlist the increment uses, so the read and write sets cannot drift, and the leaderboard warns by name about any model whose extraction did not run to completion.

Benchmark runs advertised determinism they never applied. Temperature and seed were pinned behind hasattr guards keyed on field names LLMSettings does not have, so both assignments silently no-opped while the result row recorded seed=42, temperature=0.0. Five identical runs spanned 3.5 score points before the fix and are byte-identical after it. Two product defects surfaced with it: there was no seed plumbing anywhere (LLMSettings.seed is new and applied by the Ollama provider; the default stays None, so nothing changes unless you pin it), and thinking_for_extraction was read by the schema extractor but never passed by the path every chaoscypher load takes.

In plain English: if you compared local models on an earlier release, compare them again.

Preset chat defaults that can actually call tools

phi4:14b does not advertise tool calling in its Ollama manifest, and the product chat loop always passes the graph tools — so anyone on the 16 or 20 GB preset failed on the first turn with ToolCallingNotSupportedError. Those tiers now ship qwen3.5:9b, which scores 57/80 on the Book One chat board and is the strongest model under 14B on it. The 24 GB preset moves to qwen3.8:27b (62/80) and 32/48 GB to qwen3.6:35b-a3b (63/80) — the top scorers that fit each tier with 4 GB of context headroom. The previous default, qwen3:30b, had never been benchmarked; the board measured the instruct variant.

An existing install keeps whatever its settings.yaml already names. Both model pickers in the app are now generated from the leaderboard data, and a model that cannot call tools, or whose chat run timed out, lands in a "Not recommended" group.

Other fixes worth knowing about

Exported packages carried zero node templates. _templates() dropped every is_system template, and extraction files entities under system templates — so every mounted, loaded or composed entity arrived untyped.
A CLI-built package silently lost every citation across a load or mount: package export hard-coded include_sources=False on the false premise that the CLI has no sources repository.
Ollama ignored llm_request_timeout. A model that produced zero bytes sat 75 minutes at 100% GPU. The timeout is now the httpx read timeout, so silence fails on both the streaming and non-streaming paths while a progressing generation never trips it.
The \| escape the extraction prompt documents never worked — the parser split on every | and unescaped afterwards, so an entity named Rostov \| Bolkonsky & Sons produced one field too many and the whole line was dropped.
Entity lines survived neither a missing nor a doubled aliases field — 740 + 18 such lines across the saved probe runs. parse_entity_line now anchors on the confidence and sentence-reference pair instead of counting fields from the left.
python -m chaoscypher_cortex.main start built the app and exited 0 — no if __name__ == "__main__" guard, and that is the exact command both chaoscypher serve and compose up run.

Upgrading

One migration, 0007_chunk_media_timestamps, is additive only — two nullable REAL columns on document_chunks, classified safe_auto, so it applies on startup with automatic migrations enabled. There are no breaking changes to the product API.

docker pull ghcr.io/chaoscypherinc/chaoscypher:0.5.0

Or, if you run the Python packages directly:

pip install -U chaoscypher-core chaoscypher-cortex chaoscypher-neuron chaoscypher-cli

Starting fresh:

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

Three things to read before you upgrade

Two defaults flipped toward carrying more data. chaoscypher package export and graph package load now include sources, chunks and citations unless you pass --no-sources. Exported packages are correspondingly larger, and loading one costs an inline search-indexing pass. This is the fix for silently losing every citation across a package round-trip, but it does change the size and timing of both commands.
Packages exported before this release carry no node templates, and if they were built by the CLI, no sources. Re-export them to get typed entities and citations on the far side.
The MCP benchmark tool payloads changed shape late in this release. The benchmark tools are new in v0.5.0, so nothing released is broken — but if you built a client against main while the extraction-probe track was landing, re-read the payloads. get_benchmark_task now returns task_id; probe_id is a deprecated alias kept for one release. submit_benchmark_output no longer returns a verdict — nothing is scored until finish_benchmark. And each stage is answered exactly once: re-submitting is refused with TASK_FINAL.

Next steps

If you keep knowledge packages, re-export them and try chaoscypher mount against an MCP host — that is the shortest path from a built graph to an assistant that can query it.
If you picked a local model from the app's dropdown before this release, check it against /leaderboard. The truncation and determinism fixes above changed what the numbers mean.

Full details in the changelog. Chaos Cypher is AGPL-3.0 and local-first: the graph, the chat, and the import and export paths all run on your own machine. Repo: https://github.com/chaoscypherinc/chaoscypher

Citation Click-Through: How Chaos Cypher Traces Every Answer to Its Source

Denis MacPherson — Fri, 25 Sep 2026 14:51:36 +0000

Most AI chat answers ask you to take them on faith. There's no way to tell which sentence came from your documents and which one the model filled in from its own training. Chaos Cypher takes a different position: every claim in a chat answer that's grounded in your knowledge graph carries a citation, and every citation is a link you can click.

The Problem With Black-Box Answers

Ask a chatbot a question about your own documents and you get an answer that reads well and might be completely right -- or quietly wrong in a way you'd only catch by re-reading the source yourself. The confidence of the answer tells you nothing about how well-grounded it is. That gap between "sounds right" and "is right" is the core trust problem with RAG-backed chat, and it only gets worse as your knowledge graph grows past what you can hold in your head.

What Click-Through Looks Like

Ask Chaos Cypher a question in Chat and the streamed answer arrives with small inline markers next to the sentences it pulled from your sources -- a document icon for text, a thumbnail for an image chunk. Hover one and a tooltip shows the source it came from, the page number, and a validation badge: Verified when the cited sentence was actually found in that chunk, Invalid when it wasn't.

Click the marker and you land on that source's detail page with the exact chunk highlighted -- not "somewhere in this document," the specific paragraph the sentence was grounded in. Answers that pulled from a scanned page or image work the same way: the marker is a thumbnail, and clicking it opens the full image.

Why This Matters More Than a Nice-to-Have

This closes the loop that most RAG chat interfaces leave open. Instead of trusting a generated answer wholesale, you can verify any individual sentence in a click -- confirm it against the source, catch a citation that doesn't hold up, or just read more context around the fact you asked about. It's the same underlying link between graph and source text that powers node detail pages in the graph view; chat citations are that mechanism surfaced at the point where you're actually reading an answer.

In plain English: if Chaos Cypher tells you something, you can check it -- one click, straight to the sentence.

Try It

Ask a question about a document you've already imported and look for the citation markers in the answer. If you haven't imported anything yet, the GraphRAG with Ollama in 10 minutes quickstart gets you from zero to a cited answer in about ten minutes, fully local.

GraphRAG Teardown: What the Graph Actually Adds to Naive RAG

Denis MacPherson — Fri, 25 Sep 2026 14:51:30 +0000

Take three well-known AI agent papers -- chain-of-thought prompting, ReAct, and Reflexion -- drop them into a knowledge base, and ask a question that spans all three: "How does Reflexion's self-reflection loop relate to chain-of-thought prompting?"

Naive vector RAG will hand you a competent paragraph about chain-of-thought. The connection you actually asked about -- that ReAct interleaved chain-of-thought-style reasoning traces with actions, and that Reflexion layered verbal self-reflection on top of ReAct-style agents, with two authors carrying across both papers -- is spread across three documents and stated explicitly in none of them.

This post is a teardown of both retrieval paths over exactly that corpus. Not a leaderboard: a walk through what each one mechanically does, where the vector path stalls, and where the graph earns its keep.

What This Post Is (And Isn't)

This is a mechanism teardown, not a benchmark. You will not find a table here claiming Chaos Cypher scores X% against a baseline's Y%. Retrieval quality depends enormously on corpus, chunking, embedding model, and question shape, and a number produced by us on a corpus chosen by us would tell you very little.

What you will find: the exact retrieval steps both paths take, the real relationships in this three-paper corpus that separate them, and the retrieval statistics Chaos Cypher emits on every query so you can run the same comparison on your own documents and read the receipts yourself.

It's worth stating the honest version of the research picture up front. The most thorough public analysis of this question -- When to use Graphs in RAG: A Comprehensive Analysis for Graph Retrieval-Augmented Generation (the GraphRAG-Bench paper, ICLR 2026) -- exists precisely because graph retrieval frequently underperforms vanilla RAG on many real-world tasks. Its contribution is mapping when graph structure pays off: the benefit concentrates in complex, multi-hop reasoning, and largely evaporates on simple fact retrieval, where a well-tuned vector index is already the right tool.

That matches our own position, and it's why Chaos Cypher fuses the two rather than replacing one with the other. The graph is not a better vector index. It answers a different question.

In plain English: graphs help with questions that require connecting things, not with questions that require finding one thing.

The Corpus and the Question

Three papers, all publicly available:

Paper	arXiv	Venue
Chain-of-Thought Prompting Elicits Reasoning in Large Language Models (Wei et al.)	2201.11903	NeurIPS 2022
ReAct: Synergizing Reasoning and Acting in Language Models (Yao et al.)	2210.03629	ICLR 2023
Reflexion: Language Agents with Verbal Reinforcement Learning (Shinn et al.)	2303.11366	NeurIPS 2023

The relationships between them are real and checkable. ReAct builds directly on chain-of-thought reasoning, interleaving reasoning traces with actions rather than producing reasoning alone. Reflexion builds on that line of work, adding a verbal self-reflection buffer that feeds an agent's own failures back into its next attempt. And the author lists overlap: Shunyu Yao and Karthik Narasimhan appear on both ReAct and Reflexion.

Now the question: "How does Reflexion's self-reflection loop relate to chain-of-thought prompting?"

Note what makes this hard. No single chunk in any of the three papers contains the answer. The chain runs chain-of-thought → ReAct → Reflexion, and each link lives in a different document.

Round 1: What Naive Vector RAG Does

The naive path is three steps, and it is genuinely good at what it does:

Embed the question into a vector.
Compare that vector against every chunk embedding by cosine similarity.
Return the top k closest chunks.

Ask our question and the retrieved chunks will be dominated by passages that talk like the question. The phrase "self-reflection" pulls hard toward Reflexion's abstract and method section. "Chain-of-thought prompting" pulls toward the Wei et al. paper. You get strong chunks from both ends of the chain.

What you almost certainly do not get is the middle. ReAct is the load-bearing link -- it's what connects reasoning traces to acting agents -- but a ReAct passage doesn't necessarily sound like a question about Reflexion and chain-of-thought. Its vocabulary is its own: interleaving, action space, observation. Lexical and semantic similarity to the query is mediocre, so it ranks below chunks that merely restate the question's own terms.

The failure mode is worth naming precisely: vector search has no representation of the fact that these three documents are related. It sees text, scores text, returns text. Two chunks that describe the same idea in different vocabulary are far apart; two chunks that share vocabulary but no actual relationship are close together. There is no edge between ReAct and Reflexion in a vector index, because a vector index has no edges at all.

And it fails quietly. There's no error, no "I found the endpoints but not the path." You get a fluent answer built from the two ends of a three-link chain, and it reads exactly as confident as a complete one would.

In plain English: vector search finds text that sounds like your question, which is not the same as text that answers it.

Round 2: What GraphRAG Does

Chaos Cypher's GraphRAG pipeline runs seven steps. The graph half and the vector half both run, and the last step merges them.

Step 1 — Embed the query. Identical starting point to the naive path.

Step 2 — Match seed entities. Before touching document chunks, the query vector is compared against entity embeddings in the knowledge graph. Entities clearing a cosine-similarity floor (seed_similarity_threshold, default 0.3) become seeds, up to a seed_limit. For our question, expect seeds like Reflexion, self-reflection, and chain-of-thought prompting -- the anchor points, not the answer.

Step 3 — Personalized PageRank. Standard PageRank finds globally important nodes. Personalized PageRank restarts its random walk at your seeds, turning a global importance score into a query-specific relevance score. Chaos Cypher runs rustworkx's compiled power iteration with a damping factor of 0.85 (ppr_damping), in-process -- no external graph database. Seed weights come from the Step 2 similarity scores, so the walk is biased toward the entities that actually matter for this question.

This is where ReAct surfaces. It was never a strong seed, because it isn't semantically close to the query. It scores well because it sits structurally between two entities that are -- one or two hops from both Reflexion and chain-of-thought. The top ppr_top_k entities (default 20) carry forward.

Step 4 — Assemble graph context. Seeds, discovered entities, and the relationship triples connecting them are collected into a structured context (capped by max_triples, default 200) and passed to the model alongside the text. The model gets the map, not just the territory. On this corpus, extraction should yield edges along the lines of Reflexion --builds_on--> ReAct, ReAct --extends--> chain-of-thought prompting, Shunyu Yao --authored--> ReAct, Shunyu Yao --authored--> Reflexion -- the exact labels depend on what extraction pulled from your documents, which is the subject of the limitations section below.

Step 5 — Retrieve provenance chunks. The first of two retrieval paths. For every entity the graph surfaced, Chaos Cypher looks up which document chunks that entity was originally extracted from. This is what makes the graph auditable rather than decorative: the ReAct passage arrives with the evidence for why it was retrieved.

Step 6 — Retrieve vector chunks. The second path is ordinary hybrid search -- semantic plus keyword -- across all chunks. This is the naive path, running unchanged, inside the graph pipeline. It catches relevant passages that never produced graph entities.

Step 7 — Merge and rank. Two independently ranked lists, two incompatible scoring scales. Chaos Cypher merges them with Reciprocal Rank Fusion (Cormack, Clarke & Buettcher, 2009), which discards raw scores and uses only rank position: each chunk scores the sum of 1 / (k + rank) across every list it appears in, with k = 60 per the original paper.

The property that matters: a chunk appearing in both lists collects from both. A passage ranked 5th by provenance and 8th by vector search will often outrank one that's 1st by vector search and absent from provenance. Evidence confirmed by two independent signals beats evidence confirmed by one.

In plain English: the graph finds the path between the things you asked about, the vector index finds text that sounds like your question, and fusion trusts what both agree on.

Reading the Receipts

The part that makes this a teardown rather than a story: every GraphRAG query returns a retrieval_stats block alongside its results. Six fields, all observable:

Field	What it tells you
`mode`	Which pipeline actually ran (see below)
`seed_entities_found`	How many graph entities anchored the walk
`ppr_entities_explored`	How many entities PageRank scored
`provenance_chunks`	Chunks retrieved via graph provenance
`vector_chunks`	Chunks retrieved via hybrid search
`deduplicated`	Chunks the two paths agreed on and were merged

mode is the honest one. The pipeline degrades rather than failing, and it tells you which rung it landed on:

full_graphrag -- seeds found, PageRank succeeded. Graph context, provenance chunks, vector chunks, fusion.
vector_only -- embeddings worked, but no graph seeds matched (or PageRank produced nothing). Hybrid search, no graph context.
keyword_only -- no embeddings available. SQLite full-text keyword search.

This is the number to watch when you evaluate GraphRAG on your own corpus. A query returning vector_only did not get any graph benefit, whatever the answer looked like -- and if most of your queries come back vector_only, your graph isn't the problem, your extraction is. Likewise, a deduplicated count near zero means the two paths found completely disjoint evidence, which is usually a sign the query was single-hop and the graph half was along for the ride.

In plain English: don't take our word for whether the graph fired -- the response tells you.

Where the Graph Doesn't Help

Being straight about this is more useful than a win column.

Single-hop fact lookup. "What damping factor does PageRank use?" needs one chunk. The graph adds latency and nothing else. This is the GraphRAG-Bench finding in miniature, and it describes a lot of real queries.

Small or unstructured corpora. Three papers is enough to demonstrate a citation chain; a single document with no cross-references gives PageRank nothing to walk. Below a few interlinked documents, expect vector_only most of the time.

Extraction quality is the ceiling. The graph is only as good as the entities and relationships pulled out of your text during import. Miss the Reflexion --builds_on--> ReAct edge at extraction time and no amount of clever retrieval invents it. When GraphRAG disappoints, the fix is usually upstream in extraction, not in retrieval.

Very large graphs skip PageRank entirely. There's a max_graph_nodes ceiling (default 50,000) on how much graph gets loaded for a walk. Past it, the pipeline skips PPR rather than stalling on a query.

The seed threshold is a real gate. Nothing clears 0.3 cosine similarity, nothing seeds, and you're in vector_only no matter how rich the graph is. Vocabulary mismatch between your question and your extracted entities shows up here first.

In plain English: the graph is a specialist, and a system that pretends otherwise is selling something.

Run It Yourself

Both halves are separately observable in a running instance, which is the point:

The naive path alone: the search bar exposes keyword, semantic, and hybrid modes directly. semantic is textbook vector RAG -- use it as your baseline.
The full path: ask the same question in Chat, which retrieves through GraphRAG, and compare what gets cited. Every citation clicks through to the exact source chunk, so you can check whether the middle of the chain actually showed up.
Programmatically: the graphrag_search MCP tool runs the whole pipeline and returns graph_context, chunks, and retrieval_stats as structured data -- the cleanest way to diff retrieval paths across a question set.

The three papers above make a good starter corpus precisely because you already know the right answer, which makes a wrong one easy to spot.

If you want the conceptual version of why multi-hop breaks vector search, that's Why Your RAG Chat is Missing Half the Answers. If you don't have an instance running yet, GraphRAG with Ollama in 10 minutes gets you from zero to a cited answer, fully local.

The CCX Open Format: A Portable Spec for Knowledge Graphs

Denis MacPherson — Fri, 25 Sep 2026 14:50:48 +0000

A knowledge graph you cannot take with you is not really yours. You can love the tool that built it, and still want the guarantee that the graph outlives the tool -- readable in five years, on a machine that has never heard of the software that produced it.

That guarantee only exists if the file format is written down.

So we wrote it down. CCX -- Chaos Cypher eXchange, the .ccx file Chaos Cypher already exports -- now has a published draft specification and a standalone reader library you can install and use with no Chaos Cypher anywhere in the picture:

pip install ccx-format        # import name: ccx

The reader is Apache-2.0 and lives in its own repository (chaoscypherinc/ccx, PyPI) -- deliberately more permissive than Chaos Cypher itself, because a format nobody can implement against is a format nobody adopts.

What This Changes For You

If you use Chaos Cypher, nothing you do changes today. Export still works the way it did; the file you get is the same file.

What changed is what that file means. Before, .ccx was an implementation detail -- whatever our exporter happened to write, readable by whatever our importer happened to accept. Now it is a documented artifact with a schema, a validator, and a second piece of software that reads it. Your export is no longer a bet on us staying in business.

In plain English: your .ccx file is now a document with a spec behind it, not just a save file.

What's Actually In a Package

A .ccx file is a ZIP archive with a fixed layout:

mimetype                              # first entry, uncompressed
manifest.json                         # metadata + member inventory
context.jsonld                        # the JSON-LD context, carried inline
knowledge.jsonld                      # the default graph
graphs/<namespace>.<name>.jsonld      # additional named graphs
sources.jsonl                         # source and chunk records
shapes.ttl                            # optional SHACL shapes
assets/sha256/<hex>                   # content-addressed assets
signatures/manifest.sig               # optional detached signature

Four decisions in there are worth pulling out, because they are the ones that make the file trustworthy rather than merely readable:

The archive is deterministic. Entry timestamps are pinned to 1980-01-01 and file modes to 0644, so the same inputs produce a byte-identical archive. You can checksum an export and mean something by it.

The media type is in the first bytes. The first entry is always an uncompressed file named mimetype containing application/vnd.ccx+zip -- the same trick EPUB uses. A file identifies itself without being unpacked.

Everything is checksummed twice. Every graph and asset in the manifest carries both a SHA-256 and a SHA-512 digest, and integrity verification requires both to match. Readers also enforce hard limits before inflating anything -- at most 100,000 entries, 512 MiB per entry, 2 GiB total -- so a malicious package cannot zip-bomb a consumer.

Remote contexts are forbidden. A conformant reader rejects any http(s):// JSON-LD @context reference anywhere in the package, and loads graphs with network access disabled. This is the rule we are most opinionated about: a package must be fully interpretable offline, forever, with no live server anywhere in the chain. It is a security property, not a style preference.

The knowledge itself lives in knowledge.jsonld as JSON-LD nodes, with relationships either attached directly to their subject or reified as standalone Relationship resources when they carry properties of their own. Sources and retrieval chunks live in sources.jsonl, one JSON object per line, with chunks pointing back into retained full text by character offset -- which is what lets a citation survive the trip.

In plain English: it's a ZIP with a strict layout, checksums on everything, and a hard rule that it never needs the internet to be read.

Reading a Package Without Chaos Cypher

This is the part that makes "open" mean something. Install the reader and open any .ccx file:

import ccx

pkg = ccx.open_package("my-graph.ccx")
report = pkg.validate()
print(report.ok, report.classes)   # e.g. True ('core', 'sources', 'shapes')

There is a CLI too -- ccx inspect, ccx validate, and ccx pack -- so you can check a package without writing any code at all.

Note what validate() hands back: not a boolean, but a report with errors, warnings, and a set of conformance classes. Those classes are the format's honesty mechanism.

Class	Granted when
`core`	The container, manifest, context, and graphs all check out.
`sources`	`sources.jsonl` parses and every chunk offset is in range against its text asset.
`shapes`	`shapes.ttl` is present, parses as Turtle, and declares at least one SHACL shape.
`embeddings`	The manifest declares embeddings and every included sidecar is present.
`signed`	The manifest declares signatures and at least one verifies offline.

The classes above core are independent capabilities, not a stack, and absence is never an error -- a package is judged only on what it claims by actually shipping the relevant artifacts. A package with no embeddings is not a failing package; it simply is not granted the embeddings class. A package that claims embeddings and ships them broken does not fail validation either: it collects warnings and the class is withheld. So a consumer can ask "does this package have verifiable sources?" and get a straight answer, instead of parsing it and finding out.

A typical full Chaos Cypher export validates as core, sources, shapes.

In plain English: any Python program can open a .ccx file, and the validator tells it exactly which parts of the package it can trust.

Producing One From Chaos Cypher

Nothing new here, but for completeness -- the graphical path is Settings → General → Import & Export: pick which components to include, click Export, and the browser downloads the .ccx.

For a single document's worth of knowledge rather than the whole graph, use Export Source in that source's action menu on the Sources page.

CLI users get the same thing with more control:

# Whole graph, default components
chaoscypher graph package export --output my-research.ccx --title "My Research"

# Templates and lenses only, no entities -- a shareable schema
chaoscypher graph package export --no-knowledge --no-workflows -o schema-only.ccx

# Include embedding vectors (off by default -- only useful for same-model migration)
chaoscypher graph package export --embeddings -o full.ccx

# Load one back
chaoscypher graph package load my-research.ccx

Imports are an upsert by IRI, not a copy: Chaos Cypher mints locally scoped identifiers and preserves foreign ones on re-export, so loading a package twice does not duplicate its contents.

In plain English: two clicks in Settings, or one command in the terminal, and you have a package.

The Honest Limits

This is draft 1 of a 3.0 spec, and there is a difference between "documented" and "finished." The things we would want to know if we were reading someone else's format announcement:

We are not calling it a standard. There is one reference implementation, written by us. A format with a single implementation is a documented format, and that is all we are claiming. That word is available to us when a second, independent implementation exists -- not before.
The spec is revised in place while draft status holds. The revision marker at the top of the spec page identifies the exact text a tool was written against; check it rather than assuming.
Workflows do not round-trip today. The chaoscypher.workflows graph member currently carries workflow trigger rows only, not full workflow definitions, and our own importer skips that member with a warning. It is in the package and it is not yet useful; we would rather say so than let you discover it.
Signatures are specified but not emitted. The format defines detached ed25519 and sigstore signatures with offline, fail-closed verification, and reserves post-quantum format names. Chaos Cypher does not produce signed packages yet, so the signed class is currently unreachable from our exports.
Embeddings are opt-in and model-bound. They ship as Parquet sidecars and are off by default, because a vector is only useful to someone running the same embedding model.

In plain English: the file format is written down and stable enough to build against; the parts that are not finished are named above rather than left for you to trip over.

What We Want From This

The interesting question is not whether Chaos Cypher can read its own files. It is whether anything else can.

So the specific thing that would make this real: one independent implementation. A loader that pulls a .ccx into LlamaIndex or LangChain. An exporter that writes one out of Obsidian. A validator in another language. Any of those, written by someone who is not us, is the difference between a documented format and a shared one.

If you are building in this space, the spec page is the whole contract and the reader is the reference. Both are open, and issues and questions on either are genuinely welcome -- draft 1 is exactly the stage where the spec should be argued with.

If you just want your own graph to be portable: it already is. That was the point.

Running Chaos Cypher fully locally with Ollama? See the local-first setup guide -- packages work identically there, and never touch a network.

ChaosCypher v0.4.3: When a Clean Restart Lost More Work Than a Crash

Denis MacPherson — Tue, 22 Sep 2026 20:35:42 +0000

v0.4.3 adds nothing new. No new features, no breaking API changes, no schema migrations: 54 commits since v0.4.2, 23 of them changing shipped code. Most of them are in the queue and the extraction pipeline, and most of those share one trait. The work was lost, counted twice, or quietly downgraded, and nothing reported it.

A clean restart was worse than `kill -9`

Stopping a worker gracefully destroyed work that a hard kill would have recovered.

On shutdown, the drain's CancelledError arm wrote terminal status="cancelled" to the tasks it interrupted. That is exactly the status the requeue script and retry_task refuse to resurrect. So the recovery contract ran backwards: a SIGKILL left the task recoverable, and a polite restart finished it off.

It was one of four queue-recovery defects in this release that each looked like a working system:

Crash recovery spent two units of the retry budget per cycle. requeue_atomic.lua bumped attempts on top of the worker's own claim-time increment, so a max_tries=5 task with retry_on_crash=True got 3 dispatches, not 5, and then went terminal reporting "crashed after 5 attempts". The affected operations are the four crash-retryable ones with no owning resource: execute_workflow, execute_step, export_graph, export_by_sources. For those, the queue budget is the only recovery layer.
A lapsed heartbeat could never be refreshed. refresh_heartbeat issued an EXPIRE, which is a silent no-op on a key that has already expired. A 31-second stall condemned a multi-hour task as abandoned, and the reconciler requeued it for duplicate execution. It is now a SET with EX.
A re-delivered chunk task could finish the job one chunk early. The short-circuit that made re-running an extraction chunk safe only caught a completed row. A row still in running went straight through, so two deliveries produced two terminal writes and two job-counter bumps. Both transitions are now guarded updates that return a rowcount, and the handler bails out before the billable LLM call when it loses the claim.

In plain English: if you restart workers, or your machine stalls for half a minute, queued work now comes back the number of times it was promised to, and only once.

Graph edges that explained themselves by thinking out loud

Every relationship ChaosCypher extracts carries a justification: the evidence the model gave for linking two entities. You can inspect it, and it is part of why the graph is checkable rather than taken on trust. That only works if the justification is evidence.

Some weren't. One parent_of edge at confidence 0.9 explained itself with "I will link 9 to 3 via interacts_with". That is the model deliberating, stored as if it were the reason the edge exists. Justifications that carry reasoning markers are now blanked, and the rest are trimmed to two sentences on a sentence or word boundary, so no fragment survives.

In plain English: when you read why an edge exists, you now get a reason or nothing, not the model's scratchpad.

One MCP sandbox bypass, and a read-only mode that wasn't

MCP add_document skipped its sandbox containment whenever content was supplied. The tool schema says that supplying content means the file is never loaded. Nothing implemented that: file_path was read from disk on every path and reached the loader uncontained. A caller supplying both got an arbitrary-file read that reached /data/credentials.json. The containment and dotfile guards are now unconditional, in the server and in the processor's mirror of it.

chaoscypher mcp honoured a read-only install only when you typed the flag. The guard read the --mode flag rather than the effective setting, so the documented Claude Desktop invocation against a read-configured install still handed the external client the destructive apply_upgrade tool. The guard now reads the configured mode, and an explicit --mode write still overrides it.

Also closed: the API-key selector and bearer-token throttle defects found in a post-merge sweep; decode_session rejects non-ASCII input; summarize gets the untrusted-document fence its five sibling handlers already had; and CHAOSCYPHER_ALLOW_USER_PLUGINS=0, the documented Docker kill switch for user plugins, now actually reaches all five plugin-loading services. Before, no service declared it, so the loader always saw its default.

In plain English: if you point an AI assistant at ChaosCypher over MCP, it can no longer read files outside the sandbox, and "read-only" means read-only however you launch it.

Settings that silently did nothing

Every configured trigger filter matched everything. list_triggers deferred the filters and actions columns the dispatcher reads, so a trigger scoped to one source fired on every source. The .ccx exporter and GET /workflows/{id}/triggers were losing the same keys.
A rejected workers.yaml value collapsed the Operations queue from 8 concurrent slots to 1, because a bad value fell through to a boolean instead of the worker type's default.
The commit-time orphan filter ignored the source's own settings and always dropped orphans, even for minimal or unfiltered sources and rows with protect_orphans=True.
The queue reset promised cancellation and delivered dead letters. It now runs cancel_all_tasks first, so running tasks stop instead of landing in the dead-letter set.

The API stops freezing on Cancel All

POST /queue/cancel-all ran a synchronous connect → SELECT → commit → disconnect on the event loop, once per task. After a large import that is thousands of cycles inside one request with no awaits, and Cortex served nothing else in the meantime. All four call sites now go through a worker thread. The same treatment went to per-chunk progress writes on the worker. A commit that lost the SQLite writer lock could park the loop for up to 60 seconds and starve the heartbeat refresher, which is how live tasks started to look abandoned.

The vision-page fan-out went from up to 4000 sequential round trips (bounded by vision_max_pages, default 2000) to 2. The changelog has the rest of the round: projections and unprojected reads fixed across the stuck-source sweep, step progress, queue stats and chaoscypher source search. These describe what the code was doing, not a benchmark.

Upgrading

No migrations apply. Drain the queue before you swap the image: stop new submissions and wait for /api/v1/queue/stats to report 0 pending on all queues. Don't run mixed versions against the same queue.

docker pull ghcr.io/chaoscypherinc/chaoscypher:0.4.3

Or, if you run the Python packages directly:

pip install -U chaoscypher-core chaoscypher-cortex chaoscypher-neuron chaoscypher-cli

Starting fresh:

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

Next steps

If you use MCP with a read-configured install, upgrade first. That is the fix with the widest reach.
If you set trigger filters, check your automations after upgrading. Triggers you scoped to one source now fire only on that source.

Full details in the changelog. ChaosCypher is AGPL-3.0 and local-first: the graph, the chat, and the import and export paths all run on your own machine. Repo: https://github.com/chaoscypherinc/chaoscypher

Automate Your Knowledge Pipeline: Triggers, Workflows, and AI Tools

Denis MacPherson — Fri, 18 Sep 2026 14:46:49 +0000

Most knowledge management tools treat you like a filing clerk. Upload a document, wait for extraction, manually review entities, fix errors, tag things, connect things. Then do it all again for the next document. And the next. And the next fifty.

This is fine when you have ten documents. It falls apart at a hundred. It becomes genuinely painful at a thousand. The bottleneck is never the AI -- it's the human loop. Every document requires your attention, your judgment calls, your clicks. The extraction might take thirty seconds. Your review and cleanup take ten minutes.

Chaos Cypher's workflow engine exists to close that gap. You define a processing pipeline once -- what to extract, how to validate it, where to send notifications -- and every new document flows through it automatically. No babysitting. No repetitive clicking. You set the rules, the system follows them.

This isn't a cron job bolted onto the side. It's a proper workflow engine with event-driven triggers, conditional branching, step-to-step data passing, and composable AI tools. Let me walk you through how it works.

A Concrete Workflow: Auto-Processing Research Papers

Abstractions are boring. Let's look at a real workflow you might build: automatically processing research papers as they're uploaded.

Here's the pipeline:

Trigger: Extraction commits new entities to the graph (node.create event fires) -- the signal that a freshly uploaded paper has finished processing. (You can also invoke the workflow manually or through the API.)

Step 1 -- AI Prompt: Summarize the document in three sentences. The ai.prompt tool sends the document text to your configured LLM with instructions to produce a concise summary. If the document is long, it automatically chunks the text and processes sections in parallel, then merges the results.

Step 2 -- AI Extract JSON: Pull out structured metadata. Authors, publication date, journal name, key findings, methodology type. The ai.extract_json tool takes the document text and a JSON schema defining exactly what you want, then returns validated structured data. It retries if the extraction doesn't match the schema.

Step 3 -- Conditional: Check if this is a clinical study. The logic.conditional tool evaluates whether {{steps.extract_metadata.extracted_data.methodology_type}} equals "clinical_trial". If true, the workflow branches to run additional medical-domain extraction. If false, it skips ahead.

Step 4 -- HTTP Request: Post a notification to a Slack webhook with the summary from Step 1 and the metadata from Step 2. The http.request tool sends a POST to your webhook URL with a JSON body containing {{steps.summarize.result}} and {{steps.extract_metadata.extracted_data}}.

Notice the {{steps.summarize.result}} syntax. That's the interpolation engine at work. Every step's output is keyed by the step's ID -- reference it as {{steps.<step_id>.<field>}} from any later step. The IDs here (summarize, extract_metadata) are placeholders: IDs are instance-specific, so check a step's actual ID in the builder (or via GET /api/v1/workflows/{id}) before wiring references -- and re-check after importing a workflow, because the export format does not carry step IDs, so import assigns fresh ones and cross-step references in configurations must be updated. You can reference {{inputs.<field>}} for the data the workflow was invoked with, {{steps.extract_metadata.extracted_data.authors}} for a nested field from a previous step, or even {{steps.check_clinical.branch_taken}} to see which conditional path was followed. The interpolation preserves types too -- if a previous step returned a number, you get a number, not the string "42".

This entire pipeline runs without human intervention. Upload a PDF, walk away, come back to a summarized, metadata-tagged, conditionally-processed document with a Slack notification waiting for you.

Under the Hood: 10 Built-In Tools

The workflow engine ships with ten built-in tools organized into five categories. Each tool has a defined input schema and output schema, so the system validates your configuration before anything runs.

Category	Tools	What They Do
AI	`ai.prompt`, `ai.extract_json`, `ai.vector_search`, `ai.generate_embedding`	LLM interactions with chunking support, structured JSON extraction with schema validation and retries, semantic search across your knowledge graph, vector embedding generation for entities
Data	`data.extract`, `data.merge`	Pull values from nested objects using dot-notation paths (`user.addresses.0.city`), merge multiple dictionaries with shallow or deep strategies
Logic	`logic.conditional`, `logic.loop`	If/then branching with safe expression evaluation, iterate over collections with configurable limits
HTTP	`http.request`	External API calls with all HTTP methods, bearer/basic auth, configurable timeouts, and SSRF protection that blocks localhost access
Templates	`templates.list`	Query your knowledge graph schema to discover available node templates

Three details that make these reliable enough to run unattended: ai.prompt automatically chunks documents that exceed the model's context window, processes the chunks in parallel, and merges the results; ai.extract_json validates the LLM's output against your JSON schema and retries on mismatch; and http.request validates URLs before sending (https/http only, localhost blocked against SSRF) while supporting all standard methods and auth schemes. ai.vector_search is the interesting one for graph-aware pipelines -- workflows can semantically query existing knowledge, enabling steps like "find entities similar to what we just extracted and check for duplicates."

How Triggers Work

Triggers are the entry point for automated workflows. They listen for events in the system and fire workflows when conditions are met.

Event sources define what happened. Two are live today: node.create (a new node was committed to the graph) and edge.create (a new relationship was committed) -- both fire on the extraction-commit path. Other event sources, like file-upload and import-complete, are selectable in the builder but not yet emitted by the engine. The system ships with a built-in auto-embedding trigger -- nodes created when an extraction commits to the graph automatically get vector embeddings generated.

Filters let you narrow the scope, using exact key-value matching against the event data. A trigger on node.create with a filter {"entity_type": "node"} fires only for node events. The node.create payload currently carries entity_type and entity_id, so filters on other keys (like a template id) can never match -- the engine logs a warning when a trigger is wired to a structurally impossible filter.

Statistics tracking gives you visibility. Every trigger execution records success/failure status, execution time, and error messages. You can see your success rate, average execution time, and recent execution history -- useful for debugging workflows that occasionally fail.

The "Expose as AI Tool" Feature

Here's where things get composable. Any workflow can be exposed as a callable AI tool by setting expose_as_ai_tool: true and defining input/output schemas. Once exposed, that workflow appears alongside the built-in tools and can be used as a step in other workflows.

Think about what this enables. You build a workflow that extracts and validates medical terminology. You expose it as a tool. Now your "process research papers" workflow can call it as Step 3 instead of hardcoding medical-domain logic. You have a workflow that enriches person entities by cross-referencing external APIs? Expose it, and any other workflow can use it.

Workflows calling workflows. Each one focused on a single job, composed together into pipelines of arbitrary complexity. The step type workflow (alongside system_tool and user_tool) tells the engine to execute another workflow as a step, passing inputs and receiving outputs just like any other tool.

Workflow Portability

Workflows export to a version-stamped, self-describing JSON file -- the definition, all steps, all configurations, no hidden state, no implicit database IDs. Import validates the version and resolves every referenced tool against the target instance's registry before creating anything, so a missing tool produces a clear error instead of a broken workflow. Export from your laptop, import on a server, share with a colleague.

Try It Yourself

The fastest way to see the workflow engine in action is to look at the export format. Here's a minimal workflow that summarizes documents on upload:

{
  "version": "1.0",
  "workflow": {
    "name": "Summarize on Upload",
    "description": "Auto-summarize new documents when uploaded",
    "input_schema": {
      "type": "object",
      "properties": {
        "document_text": {
          "type": "string",
          "description": "The document content to summarize"
        }
      },
      "required": ["document_text"]
    },
    "output_schema": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string",
          "description": "Three-point summary of the document"
        }
      }
    }
  },
  "steps": [
    {
      "step_number": 1,
      "name": "Summarize Document",
      "tool_type": "system_tool",
      "tool_id": "ai.prompt",
      "configuration": {
        "prompt": "Summarize this document in 3 key points:\n\n{{inputs.document_text}}",
        "output_format": "text"
      }
    }
  ]
}

This is everything the system needs. The version field ensures forward compatibility. The input_schema and output_schema define the contract. The steps array contains the pipeline.

Each step specifies its tool_type (system_tool, user_tool, or workflow), a tool_id that references a registered tool, and a configuration object whose shape matches the tool's input schema. The {{inputs.document_text}} template variable gets resolved at execution time with the inputs the workflow was invoked with.

To wire it up, create a trigger with the event source (like node.create), link it to your workflow, and optionally add filters. From there the engine scales with you: steps can declare depends_on, continue_on_error, max_retries (per-step, falling back to the workflow-level default), and timeout_seconds; imports handle name conflicts (fail/skip/rename) and can land inactive for a test run first. The workflows API reference documents the step fields and import options.

One more thing worth knowing before you trust a pipeline to run unattended: every run produces an execution record -- status, inputs, outputs, per-step timing, and which step failed and why. When a workflow fails at 3am, you don't guess. You look at the execution detail, see that Step 3 timed out after 120 seconds waiting for the LLM, and adjust accordingly.

What's Next

The workflow engine is designed to grow. The tool system uses a plugin architecture -- the same pattern that powers Chaos Cypher's loader plugins, domain plugins, and LLM providers. Custom tool plugins in Python shipped: drop a *_plugin.py file in data/plugins/tools/ implementing tool_id, category, name, description, input_schema, and an execute method, and it auto-registers on startup (user plugins even override built-ins with the same tool_id). See the tool plugins guide for the full interface.

More trigger event sources are coming as the platform grows. Scheduling (run a workflow every Tuesday at 9am) and webhook triggers (fire a workflow from an external system) are natural extensions of the existing event-driven architecture.

If you've built an interesting automation workflow -- whether it's a multi-step research pipeline, a quality assurance checker, or an integration with external tools -- I'd genuinely like to hear about it. The export format makes sharing straightforward: export your workflow, share the JSON, and someone else can import it and adapt it to their use case. That's the whole point of portability.

For the full API reference and detailed configuration options, check out the workflow documentation. The built-in system workflows (like auto-embedding on node create) are also good starting points -- export them and study the step configurations to see how the engine's own automation is wired together.

From Obsidian Vault to AI-Powered Knowledge Graph in Minutes

Denis MacPherson — Fri, 18 Sep 2026 14:46:28 +0000

Open your Obsidian graph view and look at it honestly: every line on that screen is a link you typed by hand. The person mentioned in forty notes but never [[linked]], the concept that appears under three different names, the two projects connected by a decision you wrote down once and forgot -- none of it shows up. Your vault knows more than its graph does.

Chaos Cypher adds the missing layer. It reads the Markdown itself, extracts entities and relationships with an LLM, and makes the whole vault searchable and chat-ready -- without requiring a single connection to be pre-linked. Your manual wiki-links stay exactly what they are: deliberate structure. The AI-discovered layer sits alongside them, surfacing the connections you never typed.

The Workflow

No plugin required -- the archive loader does the work:

Zip the notes you want to analyze. Start with a focused folder of at least ~10 notes rather than the entire vault, and leave out private notes you don't want processed.
Upload the ZIP (or TAR.GZ) as a source. The archive loader recognizes Markdown-heavy projects, strips frontmatter, preserves heading structure, and sends each note through the same pipeline used for PDFs and web pages. Smaller archives are processed by the generic loader, which keeps frontmatter intact -- bundle at least ten notes to engage the Markdown handler's frontmatter stripping.

Confirm the detected domain. Indexing (chunking + local embeddings) takes seconds and immediately enables semantic search and RAG chat. After indexing, Chaos Cypher analyzes your notes and proposes an extraction domain -- review and confirm (or override) it in the dialog, and extraction starts.
Wait for extraction. Extraction builds the graph: typed entities and relationships pulled from the prose itself.
Explore what the AI found. People mentioned across multiple notes, concepts that appear under different headings, projects connected by shared decisions, recurring themes that were never explicitly linked -- now visible, navigable, and traceable back to the exact notes they came from.

Ask questions. "What decisions led to the current architecture?" or "Where do my notes on attention mechanisms and retrieval overlap?" -- answered with citations back to your own notes, not the internet.

Scripting the Import

The steps above walk through the UI, but the same pipeline is reachable without opening a browser.

For developers: POST /api/v1/sources takes a multipart file upload and runs it through the identical loader dispatch the UI uses -- point it at your vault archive and it works the same way. POST /api/v1/sources/batch accepts a list of files if you're importing several exports at once, which is handy wired into a nightly vault-backup job: export, POST the archive, let indexing and extraction pick it up. In plain English: anything the "Upload" button does, a script can do too, over HTTP.

For CLI users: the same import is one command:

chaoscypher source add my-vault.zip

source add isn't Obsidian-specific -- it's the general-purpose source-loading command, and it routes to the archive loader the same way the web UI does whenever it sees a .zip or .tar.gz. There's no separate "import vault" subcommand, because none is needed. In plain English: if you'd rather stay in the terminal, one command gets your vault into the graph.

A Few Tips for a Good First Pass

Keep filenames and headings descriptive -- they become context the extractor uses.
If your vault has a specialized vocabulary, review the extracted graph and then tune domains or templates to match it.
Everything runs locally if you pair it with Ollama -- your journal never leaves your machine.

This workflow shines wherever the value isn't only in the notes but in the relationships between them: research notes, project journals, meeting archives, long-running personal knowledge bases.

What's Next

A first-class Obsidian importer -- reading vaults directly, preserving wiki-links as graph edges alongside the AI-discovered ones -- is on the roadmap. If that's your use case, tell us how you'd want it to work; vault structures vary wildly and real examples shape the design.

Extract Smarter: How Domain-Aware AI Builds Better Knowledge Graphs

Denis MacPherson — Fri, 11 Sep 2026 14:47:08 +0000

Most AI extraction tools treat every document the same way. Upload a medical paper or a legal contract and you get the same generic entity types, the same vague relationships, the same disappointing graph. Chaos Cypher takes a different approach: it detects what kind of document you uploaded and adapts its entire extraction pipeline to match.

The Problem with Generic Extraction

Here's a sentence you might find in a clinical document:

Patient with hypertension started on lisinopril 10mg daily. The ACE inhibitor is contraindicated with potassium supplements. Side effects include dry cough and dizziness.

A generic extraction pipeline -- the kind most tools use -- will pull out a handful of entities and connect them with whatever relationship labels the LLM feels like inventing. You might get "Lisinopril" typed as an Item, "Hypertension" as a Concept, and "Dry Cough" as another Concept. The relationships between them? Probably related_to and influences. Maybe associated_with if you are lucky.

This is the "garbage in, garbage out" of knowledge graphs. It's not that the AI failed to read the text. It read it fine. The problem is that nobody told it what to look for, what types are valid, or what the relationships between those types should mean.

The graph you get is technically correct and practically useless. You cannot query "which drugs treat hypertension" because the system does not know what a Drug is. You cannot find contraindications because related_to could mean anything. Every edge in the graph carries the same semantic weight as a shrug.

Now run the same sentence through Chaos Cypher with the medical domain active:

Lisinopril becomes a Drug with dosage form and mechanism of action as properties
Hypertension becomes a Condition
Dry Cough and Dizziness become Side Effects
Potassium Supplements gets recognized as a Drug (because supplements have drug interactions too)

The relationships are just as precise: treats, contraindicated_with, produces_side_effect. Each one is typed, directional, and constrained. A treats edge must start from a therapeutic agent (Drug, Treatment, Procedure, Protocol, or Guideline) and land on a clinical target (Condition, Symptom, Side Effect, Pathogen, or Patient Population). A Side Effect can never treat a Drug. The LLM isn't guessing -- it's following a schema.

That's what domain-aware extraction does. It turns a language model from a general-purpose pattern matcher into a domain specialist.

How It Works: Upload to Knowledge Graph

The workflow is straightforward. You upload a document. Chaos Cypher figures out what domain it belongs to, loads the right extraction rules, proposes the domain for your confirmation, then runs the pipeline. You don't need to configure anything upfront -- though you can override the detected domain if you want.

:::info Update (June 2026)
Since the domain-confirmation gate shipped, auto-detection proposes a domain and parks the source awaiting your one-click confirmation before the (potentially hour-long) extraction runs. You can accept, override the proposed domain, or pass auto_confirm at upload to restore the fully hands-off behavior described below.
:::

Here's what happens behind the scenes:

Detection -- Chaos Cypher samples up to ~12,000 characters drawn from the beginning and the middle of your document and scores it against all registered domains simultaneously. Each domain has weighted keyword groups, regex patterns, and file type signals. The highest-scoring domain wins.
Guidance injection -- The winning domain's extraction rules get injected into the LLM prompt. This includes entity type definitions, relationship constraints, exclusion rules (what not to extract), and worked examples of correct extractions.
Strict type enforcement -- The LLM is instructed to only use entity types from the domain's template list. After extraction, a code-level filter drops any entity whose type does not match a known template. No hallucinated types survive.
Relationship validation -- Each relationship is checked against source/target type constraints. A treats relationship must flow from a therapeutic agent like a Drug, Treatment, or Procedure to a clinical target like a Condition or Symptom. Anything else gets rejected.
Quality scoring -- Extracted entities and relationships are scored by domain relevance. Domain-specific types like Drug and Condition score higher than generic fallbacks. This surfaces the most valuable parts of your graph.

Chaos Cypher ships with 19 built-in domains, each tuned for a different category of document. A sample:

Domain	Typical Entity Types	Best For
Medical	Drug, Condition, Symptom, Procedure, Side Effect	Clinical documents, pharmaceutical literature
Technical	Module, Class, Function, Endpoint, Design Pattern	API docs, codebases, technical specifications
Legal	Statute, Case, Party, Obligation, Legal Principle	Contracts, court opinions, regulatory filings
Financial	Company, Financial Instrument, Market Event, Regulation	Earnings reports, market analysis, SEC filings
Scientific	Hypothesis, Method, Finding, Dataset, Organism	Research papers, experiments, academic publications
Cybersecurity	Threat Actor, Vulnerability, Malware, Attack Technique	Threat intel, incident reports, CVE research
Generic	Person, Organization, Event, Concept, Location	General-purpose fallback for any content

The rest cover historical, literary, theological, investigative, political, design, intelligence, news, educational, philosophical, biographical, and reference material — the full list with every entity type is in the docs.

Every domain uses strict entity type enforcement by default. The medical domain defines 20 entity types. The technical domain has 18. These aren't suggestions -- they're the only types the LLM is allowed to produce. That constraint is what separates a clean, queryable graph from a noisy soup of ad-hoc labels.

Under the Hood: Domain Detection and Extraction Quality

How Detection Works

Domain detection runs a scoring algorithm across all registered domains simultaneously. Each domain defines its detection rules in a JSON-LD config file with three signal types:

Weighted keyword groups. The medical domain has six keyword groups: clinical_core (weight 1.2), pharmaceutical (weight 1.0), diagnostic (weight 0.9), anatomy (weight 0.8), procedures (weight 0.9), and clinical_terms (weight 0.8). Each keyword match boosts the confidence score by per_keyword_boost * weight. A document full of "diagnosis", "treatment", and "symptoms" racks up points fast in the clinical_core group, while scattered mentions of "cardiac" and "pulmonary" add smaller anatomy-weighted boosts.

Regex patterns. Keywords catch common terms, but patterns catch domain-specific notation. The medical domain matches dosage expressions like \d+\s*(mg|mcg|ml), ICD codes like ICD-10:J45, and prescription abbreviations like b.i.d. and p.r.n.. Each pattern match carries its own weight -- dosage notation at 1.4x, ICD codes at 1.5x. A single ICD code in a document is a strong medical signal.

File and document type signals. File extensions (.py for technical) and document type metadata (medical_document, openapi) provide additional boosts.

The final confidence score is compared against a per-domain minimum threshold. Medical requires 0.4 minimum confidence. The generic domain has a threshold of 0.0 -- it always matches as a fallback, but with the lowest possible score (0.1), so any specialized domain that passes both its own minimum threshold and the registry's absolute confidence floor of 1.0 will win. The floor exists so weak, ambiguous matches fall back to the broad generic schema instead of locking in a wrong domain.

How Domains Shape Extraction Quality

Detection picks the right domain. But the real value is in what happens next -- the selected domain controls the extraction pipeline at five points:

Entity guidance tells the LLM what to extract and what to skip. The medical domain says "include dosage information as properties on drug entities" and explicitly excludes standalone dosage numbers, study references ("Figure 1"), and administrative codes.
Strict type enforcement gives the LLM a closed list of valid types -- the medical domain allows exactly 20. Anything outside that list gets dropped in post-processing. No more "Medical Concept" or "Health Thing" cluttering your graph.
Relationship constraints validate source and target: treats must flow from a therapeutic agent like a Drug, Treatment, or Procedure to a clinical target like a Condition or Symptom. A Symptom that "treats" a Drug fails validation. This catches the most common extraction error -- reversed or nonsensical edges.
Compatibility groups handle deduplication: "Hypertension" extracted as a Condition in one chunk and a vaguer type in another can be merged because both belong to the clinical group -- no duplicates, no lost type precision.
Property type mapping rescues mistyped entities: "Severity" extracted as a standalone node gets absorbed into the right Condition as a severity property instead of floating as an orphan.

In plain English: the domain is a contract. The LLM does the reading, but the domain decides what counts as a valid entity, a valid relationship, and a valid graph -- and everything that breaks the contract is filtered out before it reaches you.

Try It Yourself

Every built-in domain is just a JSON-LD file. No Python, no compilation, no framework code. If you need a domain for your field that doesn't exist yet, you can create one in about 20 minutes: drop a file in data/plugins/domains/, define your detection signals and your vocabulary, restart, done.

Say you want a startup domain for pitch decks and funding announcements. The skeleton is just three parts -- how to recognize the content, what entities exist, and how they're allowed to connect:

{
  "@type": "ExtractionDomain",
  "name": "startup",
  "strict_entity_types": true,

  "detection": {
    "confidence": { "base_score": 0.2, "per_keyword_boost": 0.12 },
    "keywords": {
      "funding": {
        "terms": ["series A", "series B", "seed round", "venture capital",
                  "valuation", "term sheet", "cap table", "pre-money"],
        "weight": 1.3
      }
    },
    "patterns": [{ "regex": "\\$\\d+[MBK]\\s+(seed|series|round)", "weight": 1.5 }]
  },

  "templates": {
    "node_templates": [
      { "id": "startup_company", "name": "Company" },
      { "id": "startup_round", "name": "Funding Round" }
    ],
    "edge_templates": [
      { "id": "startup_raised", "name": "raised",
        "source_types": ["Company"], "target_types": ["Funding Round"] }
    ]
  }
}

Detection has an absolute confidence floor of 1.0 -- a domain that scores below it loses to the generic fallback, so give a new domain enough keyword surface to clear it, or force the domain at upload while you tune detection. (The skeleton above clears it: eight keywords at a 0.12 boost and 1.3 weight put a keyword-rich article at roughly 1.45 before patterns even fire.)

Upload a TechCrunch article and watch the detection engine propose it at the confirmation step: confirm, and Companies and Funding Rounds appear in your graph, connected only by the relationships you allowed.

The full walkthrough -- weighted keyword groups, named-referent flags, entity properties, inverse relationships, and a complete worked example -- lives in the docs: start with Custom Domains, then Building Extraction Domains for the whole schema, including normalization keywords, compatibility groups, property absorption, and extraction-density tuning. The built-in medical domain is the most comprehensive reference -- study it when you want the full picture.

What's Next

We're planning more specialized domains -- supply chain, environmental science, and music theory are on the shortlist. But the real potential is in what users build. Every field has its own vocabulary, its own entity types, its own relationship patterns. A materials scientist cares about Crystal Structure, Synthesis Method, and Property. A genealogist needs Person, Family, Vital Record, and Census Entry. A cybersecurity analyst -- who already has a built-in domain -- might want to fork it and add types specific to their organization's threat model.

If you build a domain for your field, share it. A JSON-LD file is small, portable, and easy to review. Drop it in data/plugins/domains/ and it works. No pull request required to use it, but we would love to include community domains in the built-in set for others to benefit from.

Domains work identically whether you're running locally with Ollama or with a cloud provider. Start with the skeleton above, test it on your documents, and iterate from there.

DEV Community: Denis MacPherson

Chaos Cypher v0.6.0: Memory for Agents That Says Who Said It

Memory for agents

Retrieval that reads the question

Sources you can keep current

Also in this release

Upgrading

Build It Once, Mount It Anywhere: One Knowledge Package, Any MCP Client

What You'll Build

Step 1: Build the graph, then export it

Step 2: Mount it

Step 3: Mount it into your assistants

Step 4: Ask both the same question

Why a mount and not an import

What it does not do yet

Next steps

GraphRAG with Ollama in 10 Minutes: The Local-First Quickstart

What You'll Build

Step 1: Install Ollama and Start the Model Download

Step 2: Start Chaos Cypher

Step 3: Upload a Document

Step 4: Watch the Graph Form

Step 5: Ask a Cited Question

Where to Go From Here

Claude Built Its Own Knowledge Graph. No Local LLM Was Involved.

What You'll Build

Step 1: Install the CLI and connect it to Claude Code

Step 2: Ask Claude to build the graph

Step 3: Look at what it built

Step 4: Close the session. Open a new one. Ask a hard question.

Why this is different

What it does not do yet

Next steps

Chaos Cypher v0.5.0: Mount a Knowledge Package Straight Into Your MCP Host

chaoscypher mount — a package, served over MCP, in one command

chaoscypher compose now works on CCX 3.0

Citations into audio and video now carry timestamps

Two benchmark boards, scored without a judge

The measurement work found two things that made every earlier number suspect

Preset chat defaults that can actually call tools

Other fixes worth knowing about

Upgrading

Three things to read before you upgrade

Next steps

Citation Click-Through: How Chaos Cypher Traces Every Answer to Its Source

The Problem With Black-Box Answers

What Click-Through Looks Like

Why This Matters More Than a Nice-to-Have

Try It

GraphRAG Teardown: What the Graph Actually Adds to Naive RAG

What This Post Is (And Isn't)

The Corpus and the Question

Round 1: What Naive Vector RAG Does

Round 2: What GraphRAG Does

Reading the Receipts

Where the Graph Doesn't Help

Run It Yourself

The CCX Open Format: A Portable Spec for Knowledge Graphs

What This Changes For You

What's Actually In a Package

Reading a Package Without Chaos Cypher

Producing One From Chaos Cypher

The Honest Limits

What We Want From This

ChaosCypher v0.4.3: When a Clean Restart Lost More Work Than a Crash

A clean restart was worse than kill -9

Graph edges that explained themselves by thinking out loud

One MCP sandbox bypass, and a read-only mode that wasn't

Settings that silently did nothing

The API stops freezing on Cancel All

Upgrading

Next steps

Automate Your Knowledge Pipeline: Triggers, Workflows, and AI Tools

A Concrete Workflow: Auto-Processing Research Papers

Under the Hood: 10 Built-In Tools

How Triggers Work

The "Expose as AI Tool" Feature

Workflow Portability

Try It Yourself

What's Next

`chaoscypher mount` — a package, served over MCP, in one command

`chaoscypher compose` now works on CCX 3.0

A clean restart was worse than `kill -9`