Coalent

Real-time, provenance-invalidated context for AI agents & RAG.

Build understanding once. Reuse it everywhere. Keep it fresh — automatically.

📖 Documentation · coalent.ai · 💬 Discord

Quickstart · What's new in v0.7 · Gate ladder · Bring your own stack · MCP · LangChain · Benchmark · CLI

Your agent re-reads the same sources on every call — and the moment a source changes, every cached answer is silently wrong.

Coalent builds the *understanding* once, caches it by what the query means, and invalidates it surgically the instant an underlying source changes. As correct as re-reading everything, at a fraction of the cost — and never stale.

Why Coalent

Every context layer is forced to trade off three things. Coalent is built to hold all three at once:

• 🧠 Extractive understanding, not chunks. It caches a *query-independent* set of atomic, source-grounded claims your LLM extracted — keeping every number and fact — so one cached unit answers many *different* later questions. The raw evidence is retained with each unit, so a hit that under-covers a query falls back to retrieval instead of answering thin.
• ♻️ Reuse across queries, agents — and documents. A semantic cache keyed by query *meaning*: ask again, or from another agent, and it's a warm hit. Cross-unit recall pools claims across units to answer multi-hop questions whose evidence spans documents — at zero extra LLM calls.
• 🌿 Fresh by provenance. Every unit remembers the exact sources it used. When one changes, only the units that actually used it go stale — precisely, automatically, and lazily.

Coalent sits above retrieval — bring any retriever (vector DB, hybrid search, GraphRAG, tools, APIs). It's the freshness-and-reuse layer, not another retriever — deliberately the *opposite* of GraphRAG's build-the-whole-graph-upfront tax: lightweight, independent units, built lazily only when a query actually needs one, and refreshed by dirtying a single unit (no graph surgery).

New in v0.7 — the self-healing release. The failure chain: when a read fails,

your agent calls repair(read_id) and the cache re-extracts what its build missed —

permanently. Measured on the same frozen 605-question rig: 0.826 vs 0.774 for

the strongest v0.6 configuration, **+5.3 points at an identical ~983-token serving

budget, final refusals −69%. And the default read path flips to pool**: under a

semantic embedder the read path resolves to "pool" automatically (read_path="unit"

stays the byte-identical escape hatch). See What's new in v0.7.

New in v0.6.1 — the MCP server: coalent-mcp puts the cache one line away from Claude Code, Cursor, or any MCP client (Use it from Claude Code / Cursor), and [`langchain-coalent`](#langchain) makes your existing LangChain stack the cache's substrate. Both additive-only.

v0.6 — the pool read path (read_path="pool"): every read serves the token-budgeted, globally ranked fresh-claim pool. Measured on the same benchmark: 0.731 accuracy @ 981 context tokens — naive's best measured accuracy (top-12: 0.731 @ 1,729) at ~43% fewer tokens. Plus the default-OFF behavioral stack, measured at −33% refusals and +3.1 pts on the same store.

Install

pip install coalent          # the core has zero required dependencies

Quickstart

Runs as-is — StubSynthesizer needs no API key, so you can feel the loop in ten seconds:

from coalent import SemanticCache, InMemoryRetriever, StubSynthesizer

1. Any retriever — a vector DB, a tool, an API. (In-memory here for the demo.)

retriever = InMemoryRetriever() retriever.add("confluence:hr", "Leave policy: 21 days of annual leave per year.")

2. Build the cache. Swap StubSynthesizer for a real LLM below.

cache = SemanticCache(retriever, StubSynthesizer())

3. Ask. The first call builds understanding and caches it; the next is a warm hit.

result = cache.get("what is our leave policy?") print(result.context["understanding"]) print(result.cache_hit) # False (cold) -> True on the next call

4. A source changed? Only the units that used it go stale — surgically.

cache.source_changed("confluence:hr", text="Leave policy: now 25 days.")

the next matching read rebuilds just that one unit, lazily

(The no-key demo above runs the classic unit read path — with no semantic embedder available, the cache says so loudly and falls back. Wire a real embedder, as below, and the default becomes the measured pool read path.)

Wire in a real model — any text-in / text-out LLM works. In v0.4 the synthesizer builds extractive understanding by default (query-independent atomic claims that keep every fact), and the cache does cross-unit recall — both on automatically:

from coalent import SemanticCache, LLMSynthesizer, OpenAIProvider, OpenAIEmbedder

cache = SemanticCache( retriever, LLMSynthesizer(OpenAIProvider(), model="gpt-4o-mini"), # extract=True by default (v0.4) embedder=OpenAIEmbedder(), # match queries by MEANING (recommended for real use) )

^ with a semantic embedder, v0.7 resolves the default read path to "pool" — the

measured path. Pass read_path="unit" for the pre-0.7 unit default, byte-identical.

Multi-hop across documents? recall is already on; raise its trigger to bridge units:

SemanticCache(retriever, synth, embedder=..., recall_threshold=0.7)

The pool read path — the DEFAULT since v0.7 (whenever a semantic embedder is available): every read serves the budget-packed, globally ranked fresh-claim pool instead of one routed unit. Attribution is the one thing to wire: a 3-line pool_header callable mapping each unit to [title | source | date] from your own corpus metadata. This is the measured golden path — on a 605-question news benchmark (strict grading), 0.68 accuracy with the bare built-in header vs 0.73 with this callable, same store, same queries:

DOC_META = {  # your corpus metadata, keyed by artifact id

"docs:azure-refresh": {"title": "Azure region refresh", "source": "CloudWire", "date": "2026-05-02"}, }

def pool_header(unit) -> str: # the [title | source | date] golden path — 3 lines meta = DOC_META.get(unit.evidence[0].artifact_id if unit.evidence else "") return f"[{meta['title']} | {meta['source']} | {meta['date']}]" if meta else f"[source: {unit.id}]"

cache = SemanticCache(retriever, synthesizer, embedder=OpenAIEmbedder(), pool_header=pool_header) # pool is the resolved default (v0.7) result = cache.get("which regions got the refresh?") result.context["pool"] # the packed, attributed claim payload — hand it to your answer model

Runnable no-API-key demo, including the refusal loop: examples/pool_read_path.py.

Use it from Claude Code / Cursor (MCP)

coalent-mcp serves fresh, attributed facts from a Coalent cache to any MCP client — and the facts are invalidated the instant their source changes. One line to wire it into Claude Code:

pip install "coalent[mcp,openai]"

claude mcp add coalent -- coalent-mcp --cache-factory my_cache:build

(Cursor / Claude Desktop / any MCP client: register the same coalent-mcp ... command in its MCP config.)

Bring your own cache (`--cache-factory module:function`) — the primary mode. Your factory returns a fully constructed SemanticCache: your vector DB, your embedder, your LLM, every knob. The server adds protocol glue only — and the glue is measured to add zero quality loss: factory mode reproduced the library's own benchmark result byte-identically (0.710 on a 100-question validation run drawn from our n=605 news benchmark — identical CIs, 100/100 serves, 98/100 answer payloads byte-equal to the library run).

# my_cache.py — importable from the directory you launch in

from coalent import (SemanticCache, LLMSynthesizer, OpenAIProvider, OpenAIEmbedder, SQLiteCognitionStore)

def build() -> SemanticCache: return SemanticCache( my_vector_retriever, # YOUR vector DB / retriever LLMSynthesizer(OpenAIProvider()), # YOUR synthesis model embedder=OpenAIEmbedder(), # YOUR embedder read_path="pool", residual_spans=True, query_keys=True, # the behavioral stack, opt-in as ever pool_header=my_metadata_header, # [title | source | date] — the measured golden path store=SQLiteCognitionStore("kb.db"), # persistence is yours too )

Freshness here is signal-driven: your ingestion pipeline calls the source_changed tool when a document changes and the affected facts invalidate immediately. (Adding --watch DIR alongside the factory also fires it on file edits — invalidation only; it never ingests into your index, and it matches only when your artifact ids equal the watch-relative paths.)

Zero-config folder mode (`--watch DIR`) — the demo wedge. Point it at a folder of docs and you get the recommended v0.6 deployment (pool path, residual spans, query keys, SQLite persistence, automatic [path | modified date] attribution) with no code at all:

claude mcp add coalent --env OPENAI_API_KEY=$OPENAI_API_KEY -- coalent-mcp --watch ./docs

Every read rescans the watched files (mtime + content hash) before serving — you cannot get a stale answer after saving a file — and an untouched folder restarts fully warm. The honest number: on the same 100-question validation run, folder mode scored 0.46 vs 0.71 for a factory-built cache (40 vs 18 refusals) — the measured cost of the generic paragraph chunker and on-demand keyhole builds. Use it to feel the freshness loop in a minute; bring your own stack for production quality. One regime note: a question about a *just-added* file can honestly refuse from a warm cache until a read triggers that file's first build — a refusal, never a stale or wrong answer.

One shared cache for many agents (`--transport http`).

COALENT_MCP_TOKEN=<secret> coalent-mcp --cache-factory my_cache:build --transport http --port 8765

One long-lived process, many concurrent MCP clients, ONE shared cache — shared compounding, no store races (validated: two concurrent clients matched the sequential reference on all 20 reads, zero duplicate builds). When COALENT_MCP_TOKEN is set, every request must carry Authorization: Bearer — bind localhost or trusted networks. Corollary for stdio: each stdio launch is its own process, so never point two apps at the sa