Once a knowledge base holds more than a few dozen documents, "search everything" stops being what you want. You want the answer from these papers, this client's files, that project's notes, and you want to know the graph behind the answer came from those documents and nothing else.

Chaos Cypher v0.7.0 adds that: document tags that follow one rule everywhere, search scoped to a tag set, and a one-line summary for every document you add. v0.7.1 followed a day later with fixes to the MCP tool schemas.

Tags, under one rule

A tag is trimmed and lower-cased, then may use only a-z, 0-9, :, _ and -, must start with a letter or digit, and is at most 64 characters. A document carries at most 32.

The same rule, with the same refusal text, holds in every place you can tag:

  • MCP: add_document, add_site, and the new tag_document tool, which adds, removes or replaces a document's tags and answers with its tags after.
  • REST API: tags on uploads, batch and URL import, and PATCH /api/v1/sources/{id}/tags to add, remove or replace by name.
  • CLI: --tag on source add, and the new chaoscypher source tag.
  • Packages: a package's keywords become tags on import (a keyword the rule refuses is skipped with a warning).

A site's tags reach every page, including pages a later refresh finds.

In plain terms: you label documents once, the same way from any tool, and the labels stick.

Search inside a tag set

MCP search_chunks and graphrag_search, chaoscypher source search and GET /api/v1/sources take tags and match (any or all). The web UI's sources list gets a tag filter with the same any/all choice.

Two details matter more than they look:

  • The filter runs inside the search, before the result limit. A scoped search returns a full page of results, not the scraps left after filtering an unscoped one. A tag set no document carries returns nothing; it never falls back to searching everything.
  • In MCP graphrag_search, the graph under a tag scope comes only from the tagged documents — seeds, neighbours and relationships alike. An entity you made by hand, one no document backs, or a relationship that only an untagged document states is left out.

This also fixes search_chunks with a source scope coming back short: it used to search everything and drop other documents' chunks afterwards. Every chunk in those replies now carries source_title.

In plain terms: when you ask about a set of documents, the answer and the graph behind it come from that set, and you can see which document each piece came from.

One-line summaries

When a model is configured, each document you add gets a one-line summary written by that model once it is indexed: one call, limited to 60 seconds, never retried, and no placeholder text when it fails. Turn it off with source_processing.import_summaries: false. For documents added earlier, chaoscypher source summarize --missing fills in the gaps.

You can also type a summary yourself (--summary, the summary field, or MCP summary), up to 300 characters. Summaries show in the sources list, source list, the new MCP list_documents tool and the API's source responses, and travel in packages as abstract. Package import and compose build never call a model.

In plain terms: every document gets a sentence saying what it is, so an assistant listing your documents can pick the right ones without opening each.

Two new MCP tools (46 in all)

  • tag_document — add, remove or replace a document's tags, and optionally set its summary.
  • list_documents — documents newest first, with title, summary, tags and date added, filtered by tags and paged, without calling a model.

The MCP guide has the details, and Sources — Tags and Sources — Summaries cover the rest.

v0.7.1: MCP schemas that match the code

v0.7.0 checks a tool's arguments against its advertised schema before the tool runs. That exposed create_template, whose schema listed only six property types, so datetime, integer, float, url, email, json, node_reference and node_reference_list were refused. v0.7.1 lists every property type, describes each property the way templates store it, and builds the enums in the MCP and workflow tool schemas from the same definitions the code uses, so they cannot fall behind again. confirm_extraction now lists its six filtering presets.

Upgrading 

docker pull ghcr.io/chaoscypherinc/chaoscypher:latest pip install -U chaoscypher-cli

Read this before you swap the image:

  • Let the queue go idle first. Stop new submissions and wait until /api/v1/queue/stats reports 0 pending tasks on every queue. The worker cannot negotiate payload versions yet, so draining first is the safe default.
  • Migration 0026 renames tags to fit the rule, and may ask first. Existing tags are lower-cased and every run of other characters becomes one - (Work Docs → work-docs); tags that then share a name are merged into the oldest. When it would change any tag, 0026 waits and lists every rename and merge — on the upgrade page, in chaoscypher db migrate status and in MCP upgrade_status — until you apply it. Renames and merges are not reversed on downgrade. An automatic backup of the database is taken before it applies.
  • chaoscypher upgrade asks before a data-changing or held migration. Scripts pass --yes.
  • Composed databases: a compose build --no-clean onto a pre-0.7 build whose tags don't fit the rule stops until 0026 is confirmed on the composed database (chaoscypher compose run chaoscypher db migrate apply). A clean build, the default, is unaffected.

The full list, including the API's new 422/409 answers for tag names, is in the changelog.

Try it

New to Chaos Cypher? The ten-minute quickstart runs it locally with Ollama: your documents and the graph built from them stay on your machine. Add a few documents with --tag, then ask your assistant to search just that tag.