Cymatix Context

Same query, same answer: deterministic RAG for agents. Retrieves, weighs, and compresses your codebase and documents into a context window — without a single LLM call on the retrieval path.

One SQLite knowledge store on your own machine, a seven-stage pipeline, and an explicit know / miss contract on every response, so an agent can tell grounded context from a miss instead of guessing. The engine's namesake cymatics stage — an MD5-binned 256-dimensional term spectrum — is a candidate-reordering signal that has not yet been isolated against hashed bag-of-words or random-bin controls; treat it as an experimental cheap feature, not a proven one.

Get started

Python 3.11+. The core install is dependency-light (FastAPI + SQLite, no torch); extras add what you turn on — cpu (spaCy ingest tagging), mcp, embeddings (opt-in dense recall, pulls torch), ast, otel, launcher-tray, all. Full extras matrix, GPU detection, and three worked workflows: Getting Started · docs/SETUP.md.

pip install "cymatix-context[cpu,mcp]"               # recommended working set, no torch
python -m spacy download en_core_web_sm              # ingest tagger model

cymatix ingest path/to/your/project/ --recursive     # 1. build the store
cymatix query "how does the splice step work?"       # 2. ask it — no server
cymatix packet "edit the splice step" --task-type edit --json   # 3. agent bundle
cymatix-server                                       # 4. proxy on 127.0.0.1:11437

Dense recall is off by default since 2026-08-15 (receipts); add the embeddings extra only if you opt back in.

Proof

Three numbers, each with a receipt:

• Public leaderboard. On EnterpriseRAG-Bench (Onyx; every entry judged by GPT-5.4), Cymatix scores Overall 33.93% — Correctness 42.2%, Completeness 42.74%, Document Recall 50.7% — rank 23 of 26 as of the 2026-09-18 update. That entry was measured on v0.6.3/0.6.4 (v0.6.3 is the frozen external-validation snapshot) with zero LLM calls on the retrieval path. Later versions have not been resubmitted.
• Retrieval since then. On the 947,531-chunk ERB bed, the shipped defaults now deliver the gold document in 66.8% of 470 questions. That is our own retrieval-layer metric on our own bed build — related to, but not the same as, the leaderboard's Document Recall column — and not a judged end-to-end score, so it does not replace the leaderboard number. Receipt: v0.10.0 witness.
• Token cost. On that same bed, a shipped-default packet is 8,345 tokens on average (tokenizer-counted, table below).

Packet cost at scale. These are tokenizer-counted (tiktoken o200k_base) means over 500 EnterpriseRAG questions on the 947,531-chunk bed, using saved packets:

The 7,000 budget is a characters-over-four estimate, so a full 12-seat packet runs about 19% over it. The shipped default cuts about a third of these queries to 6 seats (#430), so its real average is at or below the 12-seat row. See the write-up and its receipt. Multi-turn session delivery elides documents a session has already received; its savings are an unverified design estimate pending the cymatix_session_tokens_saved_total counter.

Internal benchmark board (retrieval layer, shipped defaults). Every row is one committed receipt; beds differ, so compare rows only down a column's meaning, never as one averaged score. Delivered = gold document inside the delivered window; r@12 = gold in the top-12 score map; final r@12 = gold in the top-12 final order.

The 947k row is the v0.10.0 release witness (a5a5dbef). It exactly reproduces the v0.9.2 witness, which in turn exactly reproduced the frozen floor-12 reference. The other rows are the beta witness sweep at 21606a0 (2026-09-04, shipped cymatix.toml, PYTHONHASHSEED=0, CYMATIX_DISABLE_LEARN=1). v0.10.0 adds only opt-in delivery and migration features, and these rows have not been re-run on it. MULoc moves by a few needles between hash seeds (0.443–0.449 across receipts). The weak rows are real: FinanceBench, CosQA and library-docs retrieval are open problems, not tuned-away ones.

Release-by-release history (the 0.9.x default flips and their paired receipts), the modeled May 2026 token-economics table, older end-to-end runs, the sharded gap (#275), and the dense-off latency disclosure (#374) all live on Benchmarks and Receipts.

Opt-in: full-text companion profile (v0.10.0+)

Experimental. It keeps complete stored chunks and appends up to four question-ranked chunks from the same selected sources. It needs v0.10.0 or later; earlier versions log an unknown-key warning and ignore these settings. Enable it explicitly in cymatix.toml:

[budget]
full_text_delivery = true
expression_tokens = 25000
companion_chunks = 4
context_max_chars = 100000

For packet API/CLI/MCP calls, request max_genes=12 (CLI: --max-docs 12). Structured packets expose supplements in companions, with their own freshness labels. It costs roughly twice the tokens of the default packet (see the table above); the compressed defaults are unchanged. Settings, experimental evidence, and limitations.

Pipeline

Seven stages per turn, all LLM-free except the optional splice. Stage by stage, and where the model boundary actually sits: Pipeline.

  query
    ▼
  0. Classify   rule-based: decoder mode + assembly cap
    ▼
  1. Extract    heuristic keyword + entity extraction
    ▼
  2. Retrieve   FTS5 BM25 + tags (+ opt-in BGE-M3 dense) + synonym expansion
    │           + co-activation + SR + cymatics 256-bin spectrum scoring,
    ▼           ranked via RRF (default) or additive fusion
  3. Re-rank    CPU classifier scores (optional)
    ▼
  4. Splice     Headroom Kompress (CPU) or LLM compressor (optional)
    ▼
  5. Assemble   token budget + legibility headers (fired tiers, confidence
  + Stage 7     ◆/◇/⬦, compression ratio) + freshness gate (stale/cold/
    ▼           superseded → miss) + session delivery (elide seen docs)
  6. Persist    query+response → knowledge store (background)
    ▼
  know { } or miss { }

Surfaces

Three ways in, same retrieval primitives, same JSON shapes. Direct MCP needs neither the model proxy nor the tray — a healthy headless server is sufficient. Configuration lives in cymatix.toml; env vars use the CYMATIX_* prefix. Reference: CLI · HTTP API · MCP and IDE Integration · Configuration.

The know/miss contract

• know { found, confidence } — the context is grounded; the agent may answer.
• miss { reason, escalate_to } — don't answer from the knowledge store; escalate, or refetch from refresh_targets. The freshness gate downgrades stale / cold / superseded results into a miss.
• The shape is stable; the confidence is provisional. The contract shape is load-bearing, but the confidence scalar is under active recalibration and is not yet a reliable trust signal on current internal beds (#287, #239) — rely on found / reason. Full semantics: Agent Contract.

Gotchas

• Knowledge store path is genomes/main/genome.db, not the project root. Delete it to start fresh; it auto-creates on first use.
• The synonym map is critical. "No relevant context" usually means the query keywords don't map to the tags assigned at ingest — add them under [synonyms].
• Session delivery (session_delivery_enabled = true) elides already-delivered documents per session; the ~40% multi-turn saving is an unverified design estimate. Pass ignore_delivered: true in the /context body for benchmarks.
• Sharded scale gap. The sharded path trails the unsharded engine by ~31pp recall@10 / ~30pp MRR on the xl bed (#275) — prefer unsharded for accuracy-sensitive corpora.
• The agent prompt fragment is load-bearing. Without it, frontier models confabulate past a miss. Import cymatix_context.agent_prompt.full_fragment().

Observability

Optional Grafana/Tempo/Loki sidecar: scripts\setup-grafana-telem.ps1 (Windows) or scripts/setup-grafana-telem.sh (Linux/macOS), dashboards at localhost:3000. Full surface: docs/architecture/OBSERVABILITY.md · wiki: Observability.

Documentation

The wiki is the narrative documentation — 15 pages, Troubleshooting included, also rendered at https://cymatixcontext.com/wiki/. Questions, and arguments about the receipts: Discord.

Built on spaCy NER, SQLite FTS5 BM25, BGE-M3, Kompress, Headroom, and the Howard 2005 TCM / Stachenfeld 2017 SR literature — full attributions in NOTICE.

How this was built

Cymatix Context is architected and QA-directed by Michael Bachaud. Implementation, refactoring, draft documentation, and test generation are produced by AI coding agents under spec- and benchmark-gated review. The human owns the product thesis, architecture selection, acceptance criteria, experiment design, and falsification authority; the models own the code production.

License

Apache-2.0. See NOTICE for third-party attributions.