# Cymatix Context

> Cymatix Context is an open-source (Apache-2.0), local-first context engine for LLM agents. It keeps a persistent SQLite knowledge store of your codebase and documents, and serves token-budgeted context through a CLI, an MCP server, an OpenAI-compatible proxy, and an HTTP API, with no model inference on the default retrieval path. Every response carries a know/miss contract that tells the agent whether it may answer from the retrieved context.

Cymatix Context is software you install and run locally (`pip install cymatix-context`, Python 3.11+). It is not a hosted API: cymatixcontext.com is the documentation site, and the engine itself listens on `http://127.0.0.1:11437` on the user's machine. Every page on this site is also available as Markdown: send `Accept: text/markdown`, or append `index.html.md` to a page URL. To load every page below in one request, fetch [llms-full.txt](https://cymatixcontext.com/llms-full.txt).

**When to use Cymatix Context**

- An agent needs grounded context from one specific local codebase or document set, repeatedly, across many turns, under a hard token budget.
- The agent must know whether it can answer at all: each response is either `know` (grounded, answer from it) or `miss` with a `reason` (do not answer from the store; reread the `refresh_targets` or escalate).
- Before an edit or a destructive operation, the agent needs to check that what it knows is still fresh and get a list of files to reread (`task_type: "edit"`).
- The retrieval path must stay offline and model-free: data never leaves the machine, and retrieval never waits on an LLM.
- An existing OpenAI-compatible client should get project context injected transparently, without code changes.

**When not to use it**

- General world knowledge, web search, or questions not covered by the ingested corpus (a `miss` with `abstain` means the answer is not in the store).
- As a hosted, multi-tenant service: there is no public API endpoint to call.
- Do not use the `confidence` number as a trust signal yet; branch on `found` and `reason`.

**How an agent should call it**

1. Install and ingest: `pip install "cymatix-context[embeddings,cpu,mcp]"`, `python -m spacy download en_core_web_sm`, then `cymatix ingest path/to/project --recursive`.
2. CLI (no server needed): `cymatix packet "<question>" --task-type explain --json` for an agent-safe evidence bundle, or `cymatix query "<question>" --json` for an assembled context window.
3. MCP (Claude Code, Codex, Gemini CLI, Antigravity): run `cymatix-server`, then register `python -m cymatix_context.mcp_server` with `CYMATIX_MCP_URL=http://127.0.0.1:11437`. Call `cymatix_context_packet` or `cymatix_document_query`.
4. HTTP: `POST http://127.0.0.1:11437/context/packet` with a JSON body such as `{"query": "...", "task_type": "edit"}`.
5. OpenAI-compatible proxy: set `OPENAI_BASE_URL=http://localhost:11437/v1`; context is injected into `/v1/chat/completions` requests.
6. Honor the contract: on `miss`, never answer from the store. The package ships a prompt fragment for this: `cymatix_context.agent_prompt.full_fragment()`.

## Docs

- [Wiki home](https://cymatixcontext.com/wiki/index.html.md): What Cymatix Context is, why it is built this way, and a map of every page
- [Getting Started](https://cymatixcontext.com/wiki/getting-started/index.html.md): Requirements, which extras to install, the four-command quickstart, and three workflows
- [Agent Contract](https://cymatixcontext.com/wiki/agent-contract/index.html.md): The know/miss blocks, the reason vocabulary, and how an agent should branch on them
- [MCP and IDE Integration](https://cymatixcontext.com/wiki/mcp-and-ide-integration/index.html.md): MCP server setup, the default tool surface, and per-host configuration
- [HTTP API](https://cymatixcontext.com/wiki/http-api/index.html.md): Every endpoint, request bodies, and security knobs for the local FastAPI server
- [CLI](https://cymatixcontext.com/wiki/cli/index.html.md): The `cymatix` commands, their flags, and which one to reach for
- [Configuration](https://cymatixcontext.com/wiki/configuration/index.html.md): TOML settings, environment overrides, and shipped defaults
- [Troubleshooting](https://cymatixcontext.com/wiki/troubleshooting/index.html.md): Common install and retrieval problems and their fixes

## Concepts

- [Pipeline](https://cymatixcontext.com/wiki/pipeline/index.html.md): The seven-stage retrieval pipeline
- [Retrieval Dimensions](https://cymatixcontext.com/wiki/retrieval-dimensions/index.html.md): The retrieval signals and which ship on by default
- [Architecture Map](https://cymatixcontext.com/wiki/architecture-map/index.html.md): How the modules fit together
- [Lexicon](https://cymatixcontext.com/wiki/lexicon/index.html.md): Canonical terms and their legacy aliases
- [Observability](https://cymatixcontext.com/wiki/observability/index.html.md): Metrics, OpenTelemetry export, and dashboards

## Project

- [Source code](https://github.com/mbachaud/Cymatix-Context): GitHub repository
- [Package](https://pypi.org/project/cymatix-context/): PyPI project page
- [About](https://cymatixcontext.com/about/index.html.md): Who builds Cymatix Context and how the project works
- [Contact](https://cymatixcontext.com/contact/index.html.md): Issues, Discord, email addresses, and security reports
- [Contributing](https://cymatixcontext.com/contributing/index.html.md): How to contribute code, docs, or benchmarks

## Optional

- [Benchmarks and Receipts](https://cymatixcontext.com/wiki/benchmarks-and-receipts/index.html.md): Measured results and how to reproduce them
- [Roadmap and Releases](https://cymatixcontext.com/wiki/roadmap-and-releases/index.html.md): Release highlights and the deferred ledger
- [Hosting](https://cymatixcontext.com/hosting/index.html.md): Self-hosting and managed hosting options
- [Privacy](https://cymatixcontext.com/privacy/index.html.md): What the site and the software do with your data
- [Sitemap](https://cymatixcontext.com/sitemap.xml): Every page on this site