Cymatix Context

Coordinate-index engine for LLM agents. Retrieves, weighs, and compresses your codebase into a context window — without a single LLM call on the retrieval path.

Formerly helix-context — renamed July 2026. As of 0.8.5 the old surface (the helix_context import, helix* CLI names, HELIX_* env vars, helix.toml) has been removed — see Migrating from helix-context.

The name comes from the engine's cymatics stage: each term is hashed (MD5) into one of 256 bins and given a small Gaussian spread, and query and candidate are compared as the resulting 256-dimensional vectors. It's a cheap, deterministic, model-free term transform — "cymatics" is a mnemonic for that binned spectrum, not a claim of signal-processing semantics (nearby bins are hash placement, not related meaning). It's 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. The /fingerprint endpoint exposes the binned vector directly.

Proof (30 seconds)

Token economics — compressor disabled (default LLM-free config), N=15 query shapes, May 2026:

In multi-turn sessions, the session delivery register elides already-seen documents — observed 37× reduction on repeated retrievals within a conversation (~40% token savings on typical multi-turn work). Both multi-turn figures are unverified design estimates — from ad-hoc session traces, not a receipted benchmark; a production cymatix_session_tokens_saved_total counter to measure them is pending.

Reproducer: python benchmarks/bench_rag_vs_sike_tokens.py against your own knowledge store.

Caveat: the "vs standard RAG" denominator (top-5 @ 1500 tokens) is a configurable baseline, and the 37× multi-turn figure is elision of already-delivered documents, not compression of new content — and it remains an unverified design estimate pending the cymatix_session_tokens_saved_total counter. The decision-useful claim is equal-or-better task completion at fewer input tokens; a same-harness baseline/ablation frontier (BM25 / BGE-M3 / BM25+dense RRF / Cymatix full / Cymatix minus-cymatics), paired with correctness, is future work — not yet published.

External benchmark — EnterpriseRAG-Bench (Onyx, 500 questions over a ~500K-document enterprise corpus).

Shipped-defaults operating point (0.9.0, 2026-08-20) — what an untouched install does today. The default retrieval path is fully algorithmic — dense, SPLADE, and PKI all default-off since 2026-08-15..19, each flip receipt-gated (the optional cross-encoder rerank has always shipped default-off) — measured on the 829K-fragment ERB bed at full needle power:

Receipt: benchmarks/dogfood/erb/receipts/sema_readgate_829k_n469.json. Latency honesty (disclosed in the CHANGELOG, #374): turning dense off costs p50 latency — dense's ANN gate was load-bearing as a candidate-list cap — ×2.5–2.6 at 100k fragments, shrinking to ×1.09–1.38 at the 829k operating point; the mitigation (a lex-branch candidate cap) has not yet landed.

All-encoders-on 0.8.x operating point (July 2026, no longer the shipped default) — scored under ERB's official judge protocol and submitted to the leaderboard. These numbers were measured under additive fusion + dense + SPLADE ON, a configuration that no longer ships by default (every layer remains available opt-in):

Context for those numbers: the corpus was ingested as 829,131 fragments on a single consumer desktop, and retrieval ran with zero LLM calls on the retrieval path. The claim is that operating point — local, LLM-free, at scale — not a leaderboard win. Quote the delivery and correctness numbers as a pair: gold-document delivery was 55% at 829K-fragment scale (82% at 50K) under that same all-encoders-on config, and delivery is not a graded pass — end-to-end correctness is the 41.6% above. When the gold document was delivered, the answer was correct 79% of the time, so retrieval breadth at extreme scale, not answer synthesis, is the current ceiling. The end-to-end judge protocol has not yet been re-run on the 0.9.0 shipped defaults — the delivered-basis table above is the retrieval-layer measurement of the shipped world. Full methodology + repro: docs/benchmarks/2026-07-10-erb-blob-829k-reproduction.md.

Scale caveat: the 829K-fragment operating point above runs the unsharded engine. The sharded path (corpora split across shard DBs) currently trails unsharded by ~31pp recall@10 / ~30pp MRR on the xl bed — dense recall and co-activation are not yet at parity across shards (#275). "Local-first at scale" is a demonstrated research operating point on the unsharded engine, not yet a turnkey general substrate for sharded corpora.

Fusion: Reciprocal Rank Fusion has been the default ranker since 2026-07-06 — measured +12pp gold-document delivery over the legacy additive accumulator on the hardest internal bed (0.74 vs 0.62).

Agent contract (shape stable; confidence calibration experimental): every /context response carries know { found, confidence } (grounded — you may answer) or miss { reason, escalate_to } (not found — don't answer from the knowledge store). Stale results downgrade to miss(reason="stale"|"cold"|"superseded") via the freshness gate. The contract shape is stable and load-bearing, but the confidence scalar is under active recalibration — on current internal beds it is not yet a reliable trust signal (#287, #239). Rely on found / reason today; treat confidence as provisional.

Get started

Requires Python 3.11+. Core install is dependency-light (FastAPI + SQLite, no torch):

pip install cymatix-context
python -m spacy download en_core_web_sm     # ingest tagger model (with the cpu extra)

Pick extras for the features you turn on:

pip install "cymatix-context[embeddings,cpu,mcp]"   # recommended working set

Then:

# 1. Ingest your project
cymatix ingest path/to/your/project/ --recursive

# 2. Optional: dense backfill (only used if you opt in to dense recall with
#    [retrieval] dense_embedding_enabled = true — default off since 2026-08-15)
python scripts/backfill_bgem3_v2.py genomes/main/genome.db

# 3. Query from the CLI — no server needed
cymatix query "how does the splice step work?"

# 4. Or start the proxy for IDE / agent integration
cymatix-server            # binds to 127.0.0.1:11437
curl -s http://127.0.0.1:11437/health

Full setup (extras matrix, GPU detection, tray): docs/SETUP.md.

Usage

Three surfaces, same retrieval primitives, same JSON shapes:

# CLI — no server, no daemon, subprocess-drivable
cymatix query    "what does the splice step do?" --json
cymatix packet   "edit the splice step" --task-type edit --json
cymatix gene get abc123 --json
cymatix neighbors "splice step" --k 10 --json
cymatix refresh-targets "edit the splice step" --json
cymatix status
cymatix diag corpus

# HTTP — agent-safe packet with verified / stale_risk / refresh_targets
curl -s http://127.0.0.1:11437/context/packet \
  -H "content-type: application/json" \
  -d '{"query": "how does the freshness gate demote stale docs?"}'

Configuration lives in cymatix.toml. Env vars use the CYMATIX_* prefix:

CYMATIX_GENOME_PATH=genomes/dogfood/genome.db cymatix-server
CYMATIX_OTEL_ENABLED=1 CYMATIX_OTEL_ENDPOINT=localhost:4317 cymatix-server

Full CLI reference: docs/clients/cli.md. MCP tool schemas: docs/api/mcp-tools.md.

Pipeline (2 minutes)

Seven stages per turn, all LLM-free except optional splice:

  query
    │
    ▼
┌──────────────┐
│ 0. Classify  │  rule-based: decoder mode + assembly cap
└──────┬───────┘
       ▼
┌──────────────┐
│ 1. Extract   │  heuristic keyword + entity extraction
└──────┬───────┘
       ▼
┌──────────────┐  FTS5 BM25 + tags (+ opt-in BGE-M3 dense)
│ 2. Retrieve  │  + 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
└──────┬───────┘
       ▼
┌──────────────┐  token budget + legibility headers (fired tiers,
│ 5. Assemble  │  confidence ◆/◇/⬦, compression ratio) +
│   + Stage 7  │  freshness gate (stale/cold/superseded → miss)
└──────┬───────┘  + session delivery (elide already-seen docs)
       ▼
┌──────────────┐
│ 6. Persist   │  query+response → knowledge store (background)
└──────┘───────┘
       ▼
   know { } or miss { }

• know/miss contract (shape stable; confidence experimental): know means the context is grounded, agent may answer. miss means don't answer from the knowledge store — escalate via escalate_to tools or refetch from refresh_targets. The confidence scalar is under active recalibration (#287, #239) — rely on found / reason, treat confidence as provisional.
• Caller model class: /context accepts caller_model_class: "generic" | "small_moe" | "frontier" to select render branch (ordering, assembly cap, decoder mode). See docs/api/context-endpoint.md §7.

IDE + MCP integration

{
  "mcpServers": {
    "cymatix-context": {
      "command": "python",
      "args": ["-m", "cymatix_context.mcp_server"],
      "cwd": "/absolute/path/to/your/project",
      "env": { "CYMATIX_MCP_URL": "http://127.0.0.1:11437" }
    }
  }
}

models:
  - name: Cymatix (Local)
    provider: openai
    model: gemma3:e4b
    apiBase: http://127.0.0.1:11437/v1
    apiKey: EMPTY
    roles: [chat]
    defaultCompletionOptions:
      contextLength: 128000
      maxTokens: 4096

OPENAI_BASE_URL=http://localhost:11437/v1 your-app

Knowledge store management

[genome]
path = "genomes/main/genome.db"   # relative to the cymatix run directory

Backup (safe while running — WAL mode):

cp genomes/main/genome.db backups/genome-$(date +%Y%m%d).db

BGE-M3 backfill (one-time, after install):

python scripts/backfill_bgem3_v2.py genomes/main/genome.db

Security

The proxy binds to loopback (127.0.0.1:11437) by default, but a loopback bind is not authentication — any process on the same host can reach the port. Two opt-in knobs harden the mutating surface (both default-off; an untouched config behaves exactly as before):

[server]
admin_token = "your-secret"              # /admin/*, /ingest, /consolidate demand "Authorization: Bearer your-secret" (401 otherwise)
swap_db_roots = ["F:/cymatix/genomes"]   # /admin/swap-db may only open paths under these roots (403 otherwise)

Since 2026-08-19 (#351) the server also logs a prominent NETWORK-EXPOSED ADMIN SURFACE warning at startup when [server] host is non-loopback while admin_token is empty (warning only — the bind is honored), and [budget] neutralize_control_tags defaults on: retrieved content containing the literal <cymatix: string is escaped to <cymatix: at assembly time so an ingested document cannot forge the genuine no-match/slate control tags (receipt-gated flip — delivered basis and window bytes measured identical across arms; set it to false to opt out).

Details: docs/config-reference.md, [server].

Observability

scripts\setup-grafana-telem.ps1     # Windows
scripts/setup-grafana-telem.sh      # Linux / macOS

Dashboard: http://localhost:3000/d/cymatix-overview. Full surface: docs/architecture/OBSERVABILITY.md.

Migrating from helix-context

As of 0.8.5 the old helix surface has been removed — this is a clean break. The table below maps each removed name to its replacement. If you are still on the old names, migrate to the right-hand column, or pin cymatix-context<0.8.5 (0.8.0 keeps the aliases), or the last helix-context release, until you can.

The knowledge-store file format is unchanged — existing genome.db files work as-is, no re-ingest needed.

Gotchas

• Knowledge store path is genomes/main/genome.db (not project root). Delete to start fresh.
• BGE-M3 backfill only matters if you opt in to dense recall ([retrieval] dense_embedding_enabled = true; default off since 2026-08-15 — four-scale receipts measured dense displacing gold from delivery). With dense on, embedding_dense_v2 IS NULL until you run scripts/backfill_bgem3_v2.py.
• Fusion mode defaults to "rrf" (since 2026-07-06; +12pp gold delivery vs additive on the hardest bed). "additive" remains as the legacy accumulator, scheduled for condition-gated removal. Under RRF the abstain gates run ratio-only.
• Sharded scale gap: the sharded adapter currently trails the unsharded engine by ~31pp recall@10 on xl (dense recall and co-activation not yet at parity) — #275. Prefer the unsharded engine for accuracy-sensitive corpora until this is closed.
• Session delivery (session_delivery_enabled = true) tracks delivered docs per session, elides repeats. ~40% token savings on multi-turn (unverified design estimate — pending the cymatix_session_tokens_saved_total counter). Pass ignore_delivered: true in /context body for benchmarks.
• know/miss contract requires the agent prompt fragment to be honored — without it, frontier models confabulate. Import cymatix_context.agent_prompt.full_fragment().
• Naming lexicon: biology terms (gene, genome, ribosome) have canonical software equivalents (document, knowledge store, compressor). Both work in code; new code uses software terms. See docs/ROSETTA.md.

Testing

python -m spacy download en_core_web_sm    # once; ingest-path tests skip without it (#313)
python -m pytest tests/ -m "not live" -v   # ~4,165 tests, no external services

Documentation

Acknowledgments

Built on: spaCy NER · Howard 2005 TCM · Stachenfeld 2017 SR · SQLite FTS5 BM25 · BGE-M3 · Kompress · Headroom

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.