# Coalent

> Coalent is a real-time, provenance-invalidated cognitive cache for AI agents and RAG (Python: `pip install coalent`, zero-dependency core). It caches the *understanding* an LLM extracts from sources — keyed by query MEANING — retains the raw evidence with every unit (so a hit that under-covers a query falls back to retrieval instead of answering thin), and invalidates surgically by provenance the moment a source changes. It is the freshness-and-reuse layer ABOVE retrieval (bring any retriever: vector DB, hybrid search, GraphRAG, tools, APIs) — deliberately the OPPOSITE of GraphRAG's build-the-whole-graph-upfront tax: lightweight, independent units, built lazily only when a query needs one, refreshed by dirtying a single unit.

## New in v0.6 — the pool read path (opt-in) + a default-OFF behavioral stack
The DEFAULT read path is unchanged: a v0.5 user who upgrades and touches nothing gets v0.5 behavior (modulo one bugfix in the v0.5 pool-*preview* stale-serve marker; if you never set `serve="pool"` it never affected you). Everything below is opt-in.

- **`read_path="pool"`** (default `"unit"`) — the claim-pool-first read path: EVERY read is answered by budget-packing the globally-ranked fresh-claim pool; units remain the ownership/freshness/build/provenance skeleton. Hand `result.context["pool"]` (the packed, attributed payload) to your answerer; `result.pool` lists served claims in served order (owner + score). Measured (n=605 news benchmark, strict grading, frozen held-out queries): **0.731 accuracy @ 981 mean context tokens** = naive k9's accuracy (0.711 @ 1311) at ~25% fewer tokens, and naive's best measured point (k12 0.731 @ 1729) at ~43% fewer. Gold-claim rank in pool order p50/p75/p90 = 1/6/15 (claim-present queries, `reranker=None`). CIs overlap naive = PARITY at fewer tokens, NOT an accuracy win.
- **`serve_budget`** — `None` resolves to **1000 on the pool path** (the measured operating point) and **600 on the unit path** (v0.5 preserved). Explicit values win; `<= 0` raises. Header tokens count against the budget.
- **`serve_gate=None`** — pool serve-vs-build decision. Explicit float = absolute (reproducible benches); `None` adapts against the pool's own null-shaped noise ceiling. Replay-gate verified: 605/605 serve decisions on both arms, zero builds, zero LLM spend.
- **`pool_header`** — per-source-group attribution line. `None` → built-in default `## {unit.query[:60]}` (falls back to `[source: {artifact_id}]`). This is a MEASURED accuracy ladder (n=605, strict): opaque id 0.641 (153 refusals) → query-title default 0.678 (136; ships) → caller metadata callable "[title | source | date]" **0.731** (101; the documented golden path — see recipe below). The gap is a unit-metadata limit (outlet/date live only in YOUR corpus metadata), not header format; an ingest-time metadata field is a v0.7 item. A raising callable is swallowed (group serves headerless — attribution degrades, serving never breaks); once a callable is set the built-in default does NOT take over on empty returns.
- **Behavioral stack (ALL default-OFF; nothing runs unless switched on):**
  - `residual_spans=True` — build-time sentence audit keeps fact-bearing source sentences the extractor missed as tier-2 spans ON THE UNIT (never in the pool); a span outranking every fresh claim by `span_margin` serves as a labeled side channel inside the same `serve_budget`.
  - Refusal fallback — every read gets a deterministic `Result.read_id` (64-read ring buffer). When YOUR answerer refuses over the served payload, call `report_refusal(read_id)` → an attributed retry payload from residual spans (up to 2 spans, floor `span_serve_floor=0.35`), or `None`. `report_success(read_id)` is the symmetric confirm. Measured: payload delivered on 91/91 first-pass refusals; net refusals 91 → 61 (−33%); zero newly-wrong answers. CAVEAT: flips ~20% of NATURAL refusals unconditionally (33% when the payload contains the gold string; the 68% lab figure holds only for span-derived questions).
  - Append-only repair — span serves + raw fallbacks count toward `lossy_threshold` (default 2); a lossy-marked unit repairs on its next rebuild touch by APPENDING missing facts (claims never dropped while the source hash is unchanged). Spans self-retire on recapture.
  - `query_keys=True` (REQUIRES `read_path="pool"` — loud `ValueError` otherwise) — a fallback-rescued read attaches the successful span as a provisional alternate key; `report_success` confirms it durable (serde-persisted). A confirmed key scores `max(content_sim, key_sim)` and counts only at/above `key_floor=0.85`. Measured: keyed-class first-pass 0% → 61% on mild paraphrases (n=18, SMALL), controls untouched. CAVEATS: keys do NOT move final accuracy on diverse rewordings (value = first-pass conversion + fallback round-trips −70%); sibling-article key collisions are real in dense same-topic corpora (3/605 observed, answers still correct) — raise `key_floor` there.
  - Full-stack measured (n=605, same store): final 0.769 @ 1003 tok vs same-store default 0.737 @ 982 = **+3.1 pts at +2.1% tokens**, refusals −33%, zero newly-wrong answers. Requires wiring `report_refusal`/`report_success` — the cache never sees your answerer.
- **`reranker`** (`Callable[[str, list[str]], list[float]] | None = None`) — serving ORDER only; serve/build/floor decisions always read the pre-rerank cosine, so a bad reranker can degrade order but never cause a false serve, a skipped build, or a broken null refusal.
- **`claim_index`** — BYO pool storage (ClaimIndex protocol; built-in numpy/pure-python; per-namespace factory form).
- **New events**: pool_gate, pool_served, pool_masked_stale, pool_budget_overrun, rerank_failed, rebuild_triggered_by_read, build_triggered_by_gap, unit_marked_lossy, unit_repaired, residual_served, residual_fallback, key_attached, key_confirmed, key_fired. Retained: source_changed, unit_built, unit_rebuilt, stale_read_prevented, admission_reuse, widen_unavailable.
- **Result contract on the pool path** (unit path untouched): `understanding = {"claims": [...]}` with NO `summary` key; `unit_id` = owner of the top-ranked served claim; `confidence` = pre-decision pool coverage; `coverage` = final post-build/post-S2; `evidence = []` on a non-escalated serve (cite via `drill(unit_id)`); `recalled = []`; `pool` = served claims in served order; `cache_hit` = zero synthesis calls ran this read.
- **`stats()` pool additions**: pool_serves, probe_reads, admission_reuses, retrievals, rebuilds_by_read, builds_by_gap, serve_gate_effective, pool_noise_ceiling, pool_claims_fresh, pool_claims_total, avg_units_per_serve, pool_mask_rate, pool_scan_slow.
- **Constructor guards (fail loud)**: `query_keys=True` with `read_path != "pool"` raises; `read_path="pool"` with the lexical `HashingEmbedder` raises (claim cosine collapses to keyword overlap) — set `OPENAI_API_KEY` or pass `embedder=`.
- **DEPRECATED**: `serve="pool"` (the v0.5 preview) — works verbatim in 0.6, NEVER auto-mapped to `read_path="pool"`, removal v0.7. The 12 unit-path read knobs (`hit_threshold`, `hit_margin`, `route_by_claim`, `recall_*`, `select_floor`, ...) are INERT on the pool path, fully functional on the default path; DeprecationWarning v0.7, removal v0.8.
- The v0.7 default flip (pool becomes default) is NOT claimed: of five pre-registered gates only the replay gate has passed.

v0.5 recap (all still available, default off): `preset="multi_hop"` (arms cross-unit recall + hop-2 bridge, calibrated thresholds) · `widen_chunks`/`widen_on_admission`/`source_fetcher` (miss-triggered builds read the dominant source, never at ingest) · `provenance_admission` (pre-build containment probe) · `split_by_artifact` · `adaptive_hit` · `fast="auto"` (numpy-accelerated identical reads) · `on_event`. v0.4 recap (the defaults): extractive understanding (`extract=True` — atomic claims, not prose) + cross-unit recall (`cross_unit_recall=True`, surfaced as `result.recalled` on the unit path).

## New in v0.6.1 — the MCP server + langchain-coalent (additive; both read paths untouched)
- **`coalent-mcp`** (`pip install "coalent[mcp]"`, mcp SDK >= 2.0) — the Coalent MCP server for any MCP client (Claude Code / Claude Desktop / Cursor). PRIMARY mode = `--cache-factory module:function`: your factory returns a fully user-constructed SemanticCache (your vector DB / embedder / LLM / every knob); the server adds only the protocol, and it is MEASURED byte-identical to the library (0.7100 strict = the library's own 0.7100 on the same 100 benchmark questions; 100/100 served, 0 errors, 98/100 payloads byte-equal). Zero-config mode = `--watch DIR` (recommended v0.6 deployment over a folder; auto `pool_header` "[path | modified date]"; requires OPENAI_API_KEY; measured honest cost: 0.46 vs factory's 0.71 on the same questions — use the factory when you have a real index). Transports: stdio default (client-launched; single-writer — never point two stdio servers at one store) or `--transport http` (one long-lived process, many agents, ONE shared compounding cache; validated: 2 concurrent clients × 20 interleaved reads identical to sequential, zero duplicate synthesis; optional COALENT_MCP_TOKEN bearer auth). SEVEN tools: get_context, report_refusal, report_success, source_changed (BYO freshness signal — invalidates derived facts immediately, hash-skips unchanged text), list_sources, cache_stats, refresh. Folder freshness = scan-before-serve: you cannot get a stale answer after saving a file (probed at the answer level — mid-run edits flipped served answers on the very next read; zero stale serves observed). Benign gate-regime note: a question about a JUST-ADDED file can honestly refuse from a warm pool until a build fires for it — nothing stale is ever served. Claude Code one-liner: `claude mcp add coalent -- coalent-mcp --cache-factory my_cache:build` (or `--watch ./docs`).
- **`langchain-coalent`** 0.1.0 (`pip install langchain-coalent`; deps coalent>=0.6 + langchain-core>=0.3 ONLY — no langchain-community, no langgraph) — BYO-first LangChain integration: `create_coalent_cache(my_vectorstore, llm=my_chat_model, embeddings=my_embeddings, **knobs)` builds a cache over your UNCHANGED LangChain stack (every SemanticCache knob passes through — new library knobs work the day they ship; pool path auto-selected only when you supplied a semantic embedder); `CoalentRetriever(cache=)` = drop-in BaseRetriever (payload as Document; metadata read_id/sources/cache_hit); `CoalentVectorStoreRetriever(vs, k=)` = any VectorStore/BaseRetriever as Coalent's substrate (artifact id from metadata["artifact_id"] → "source" → Document.id → "id" → sha1 fallback — give documents a `source`); runnable offline refusal-loop example in the LangGraph shape.
- **`SemanticCache.has_source(artifact_id) -> bool`** — cheap provenance pre-check for change-feed adapters (don't fire source_changed for never-read files).

## Recommended setup (v0.6)
```python
# The measured pool operating point + the behavioral loop:
cache = SemanticCache(retriever, synth, embedder=OpenAIEmbedder(),
                      read_path="pool",
                      pool_header=my_header,     # "[title | source | date]" from YOUR metadata — the 0.731 rung
                      residual_spans=True,       # span capture + refusal fallback (default OFF)
                      query_keys=True)           # durable keys from confirmed rescues (default OFF)

r = cache.get("what did the report say about Q3 revenue?")
answer = my_llm(r.context["pool"])               # the packed, attributed claim payload
if is_refusal(answer):                           # YOUR refusal detector; one retry is the measured regime
    retry = cache.report_refusal(r.read_id)      # None when no span clears the floor
    if retry is not None:
        answer = my_llm(r.context["pool"] + "\n\n" + retry)
        if not is_refusal(answer):
            cache.report_success(r.read_id)      # confirms the rescue -> durable query key
```
The `pool_header` golden-path recipe (this exact shape measured 0.731):
```python
meta = {art["artifact_id"]: art for art in corpus}
def my_header(unit) -> str:
    aid = unit.evidence[0].artifact_id if unit.evidence else ""
    art = meta.get(aid)
    if art is None:
        return f"[source: {aid or unit.id}]"   # emit your own fallback — empty return serves HEADERLESS
    return f"[{art['title']} | {art['source']} | {art['published_at'][:10]}]"
```

## Install
- `pip install coalent` — core, zero required dependencies
- `pip install "coalent[openai]"` — OpenAI provider + embeddings (recommended; required in practice for the pool path)
- `pip install "coalent[mcp]"` — the `coalent-mcp` server (add `,openai` for folder mode)
- `pip install langchain-coalent` — the LangChain integration (its own package)
- extras: `anthropic`, `qdrant`, `chroma`, `pgvector`, `redis`, `server`, `langgraph`, `mcp`, `fast` (numpy), `dev`

## Core usage (default unit path — unchanged from v0.5)
```python
from coalent import SemanticCache, LLMSynthesizer, OpenAIProvider, OpenAIEmbedder, InMemoryRetriever

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

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

result = cache.get("how much annual leave?")   # the ONE read method
result.context["understanding"]                # query-relevant slice (claims + facts)
result.recalled                                # cross-unit claims (multi-hop; unit path)
result.cache_hit                               # False (cold) -> True on a similar later query
result.coverage                                # 0..1: how well the unit covered the query
result.read_id                                 # v0.6: handle for report_refusal/report_success

cache.source_changed("confluence:hr", text="Leave policy: now 25 days.")  # surgical invalidation
cache.stats()                                  # units, hit_rate, escalation_rate, pool_* counters, ...
```

## Constructor knobs — v0.6 additions (defaults as shipped)
- `read_path="unit"` — `"unit"` = byte-identical v0.5 ladder; `"pool"` = claim-pool-first serving.
- `serve_budget=None` — → 600 unit / 1000 pool. Packed payload tokens, headers counted. The one knob most users touch.
- `serve_gate=None` — explicit float = absolute; `None` = adaptive against the pool's noise ceiling.
- `pool_header=None` — → built-in `## {query[:60]}` / `[source: id]`. Wire your metadata (golden path above).
- `reranker=None` — BYO serving-order callable; never affects serve/build/floor decisions.
- `claim_index=None` — → built-in pool storage; BYO adapter or per-namespace factory.
- `residual_spans=False` — the whole tier-2 machinery (capture, side-channel serving, refusal fallback, lossy marking, append-only repair).
- `span_tau=0.62` — build-time capture: fact-bearing sentence w/ max claim cosine below this becomes a span.
- `span_margin=0.0` — read-time: span must outrank the best fresh claim by this to serve.
- `span_serve_floor=0.35` — `report_refusal` retry floor (min span-query cosine).
- `lossy_threshold=2` — span serves + raw fallbacks before a unit is marked lossy (→ append-only repair).
- `query_keys=False` — behavioral alternate keys from confirmed rescues (requires the pool path).
- `key_floor=0.85` — min key-query cosine for a key to count at all; raise in dense same-topic corpora.
Unchanged v0.5 knobs keep their positions, defaults, and (on the unit path) exact meaning: preset, hit_threshold, adaptive_hit, hit_margin, coverage_floor, understanding_weight, route_by_claim, coverage_scorer, coverage_ceiling, relevance_gate, cross_unit_recall, recall_threshold, recall_limit, recall_bridge, bridge_limit, select_floor (deprecated), residual_floor, residual_limit, widen_chunks, source_fetcher, widen_on_admission, provenance_admission, split_by_artifact, serve (deprecated preview), fast, on_event, strategy, store, freshness.

## The read paths
UNIT PATH (default; the v0.5 gate ladder, firing order): 0) `provenance_admission` (off) pre-build containment probe · 1) `hit_threshold` (auto ~0.33 OpenAI; `adaptive_hit` self-calibrates) → MISS builds · 2) `hit_margin` (0.0 off) ambiguity guard · 3) freshness (dirty/expired → re-materialize) · 4) coverage = MAX per-claim cosine · 5) `cross_unit_recall` (ON) MaxSim claim pooling, `recall_bridge` hop-2 (preset="multi_hop") · 6) `coverage_scorer`/S2 (off) · 7) `coverage_floor` (auto ~0.28) → ESCALATE to raw (the RAG floor) · 8) `select_floor` (deprecated). Build-time: `residual_floor` number-span safety net; `widen_chunks`; `split_by_artifact`.
POOL PATH (`read_path="pool"`): every read ranks the global fresh-claim pool (query cosine), packs into `serve_budget` under per-source attribution headers, and serves; `serve_gate` decides serve-vs-build; below `coverage_floor` attributed raw chunks are appended (escalation raw carries `[source: {artifact_id}]`). Stale units' claims are masked the moment a source changes. Dedup collapses only a unit's OWN rephrasings — cross-owner near-duplicates survive as corroboration (per-source questions need the owner's attributed copy). Freshness/provenance/build semantics are identical on both paths.

## Why it doesn't serve the wrong answer (docs: https://coalent.ai/docs/wrong-answers)
- Matching ≠ sufficiency (unit path): the hit gate scores the WHOLE unit (blended 0.7·topic + 0.3·seed, floor ~0.33 OpenAI) = "right territory"; coverage is the MAX SINGLE-CLAIM cosine (floor ~0.28) = "does any one claim actually answer this". Topic similarity is diffuse, fact similarity is sharp — a sick-leave query matches a vacation-policy unit's territory but NO single claim, so it escalates instead of answering thin.
- The gate is a statistical filter, not a proof; the STACK is the guarantee: gates filter most insufficient hits → the payload is attributed atomic claims, so a near-miss serve produces an HONEST refusal (measured 95% refusal honesty on unanswerable questions vs naive top-k 85–88%) → the opt-in refusal loop (report_refusal/report_success) repairs (refusals 91 → 61, −33%, zero newly-wrong).
- Escalation vs rebuild: escalation = COVERAGE failure → append attributed raw (`[source: id]`) to the payload, no LLM call, cache NOT mutated — the RAG floor (never less context than plain RAG, never empty). Rebuild = FRESHNESS failure → re-synthesize the unit before serving (one synthesis call, cache mutated). Coverage gaps do NOT trigger rebuilds (same-extractor-same-loss: re-running the same extractor reproduces the same gap); persistent extraction loss is repaired by the behavioral loop (lossy mark → append-only repair).
- Pool-path gate miss = ONE probe retrieval classified per artifact: CONTAINED (provenance proves coverage — zero synthesis; all-contained = structural admission, duplicate-unit prevention) · STALE-OWNED / THIN (rebuild that unit in place) · NOVEL (build a source-anchored unit); ≤3 synthesis ops/read. Empty vs warm cache = same algorithm, different statistics (empty: everything NOVEL; warm: mostly CONTAINED/STALE-OWNED).
- Serve gate (pool path): explicit float = ABSOLUTE; `None` = adaptive against the pool's null-shaped noise ceiling (p95 of provenance-disjoint max claim cosines, ≤24 fixed-seed probe units), clamped to [coverage-floor default, +0.27] (~0.28–0.55 OpenAI); recalibrates at the END of a build read, at most every 16 builds; decision reads PRE-RERANK cosine only; reuse bypass: seed cosine ≥0.9 = same question again → forced serve (a stale reuse match re-materializes first). Live value: stats()["serve_gate_effective"].
- `widen_chunks` fixes the build-time keyhole: widened units read median 23 chunks of their source vs 2 keyhole; rebuild churn 460 → 31.
- NO pool-path recall step: the pool scan IS cross-unit by construction; cross-unit recall is the UNIT path's multi-hop mechanism (v0.4, gate 5) and `result.recalled` stays `[]` on the pool path.
- Measured honesty row: route@1 ≈ 1.00 · misattribution ~0–2% (naive answerer's own noise; the historical high reading was a benchmark bug — documented) · 95% null honesty.

## Which knob for which workload
- `read_path="pool"` (v0.6) → token-efficient serving at naive parity — the measured 0.731 @ 981 operating point; wire `pool_header` for per-source questions.
- `residual_spans=True` + `report_refusal`/`report_success` (v0.6) → refusal-heavy answer loops / extraction tails — refusals −33% measured, zero newly-wrong.
- `query_keys=True` (v0.6) → repeat traffic with paraphrased revisits — first-pass conversion + fewer fallback round-trips (NOT a final-accuracy lever on diverse rewordings).
- `preset="multi_hop"` (v0.5, unit path) → multi-hop / cross-document questions.
- `widen_chunks` (v0.5) → real-document corpora / cold starts — build from the whole source, not the retrieval keyhole.
- `provenance_admission` + `adaptive_hit` (v0.5) → long-running caches.
- `hit_margin > 0` → contradiction/collision-heavy corpora (unit path; costs rebuilds).
- `residual_floor` → messy prose where the extractor may drop a number (build-time, both paths).
- `coverage_scorer` (S2) → high-stakes ambiguity (one judge call per borderline read).
- `extract=False` + `cross_unit_recall=False` → exact v0.3 behavior.

## The pieces (bring your own stack)
- Retriever — one method `retrieve(query, *, namespace=None) -> list[Chunk]`. `InMemoryRetriever`, `FunctionRetriever`, `CompositeRetriever`, extend `BaseVectorRetriever`, or adapters `QdrantRetriever`/`ChromaRetriever`/`PgVectorRetriever` (bring-your-own-client). `Chunk(artifact_id, text, version="")`; `artifact_id` is what freshness keys on.
- Synthesizer — `LLMSynthesizer(provider, *, model=, extract=True, instruction=, fields=, depth=0.5)` (structured, citation-grounded). `JSONPassthroughSynthesizer` (no LLM — caches structured tool/API JSON as-is). `StubSynthesizer` (offline/tests).
- Embedder — `OpenAIEmbedder` (recommended), `FunctionEmbedder(fn)` (any local model; no torch in Coalent's deps), `HashingEmbedder` (zero-dep lexical fallback — semantic features auto-disable; the POOL PATH REFUSES to construct under it). `default_embedder()` auto-picks OpenAI when `coalent[openai]` + `OPENAI_API_KEY` present.
- Providers — `OpenAIProvider`, `AnthropicProvider`, `StubProvider`.
- Stores (restart-safe) — `InMemoryCognitionStore`, `SQLiteCognitionStore`, `RedisCognitionStore`. v0.6 writes the legacy store format by default; a store that never opts into the behavioral stack is byte-identical v0.5 JSON, and new unit fields are written only when set — a v0.6 store rolls back cleanly to v0.5 (earned spans/keys are dropped on a v0.5 load).

## Benchmark — v0.6 pool path (news corpus, n=605; every number from a logged run)
Rig: 609 real news articles, 605 frozen held-out queries, gpt-4.1-mini answerer, STRICT grading (normalized gold containment in the answer), identical embedder both arms, naive's own token-scaling curve measured on the same stream.
- **Headline: parity with naive RAG at fewer tokens — NOT an accuracy win.** Pool 0.731 @ 981 mean context tokens vs naive k9 0.711 @ 1311 (~25% fewer tokens) and naive k12 (best measured) 0.731 @ 1729 (~43% fewer / 57% of the budget). All CIs overlap.
- Serving ranks: gold-claim rank in final pool order p50/p75/p90 = 1/6/15 (percentiles over claim-present queries only; `reranker=None`).
- Behavioral stack: final 0.769 @ 1003 vs same-store default 0.737 @ 982 = +3.1 pts at +2.1% tokens; refusals 91 → 61 (−33%); zero newly-wrong answers. (Same-population comparison; requires wiring report_refusal/report_success.)
- Header ladder (same frozen store/queries/grader): opaque 0.641 → shipping default 0.678 → metadata callable 0.731. The 0.731 headline row used the metadata header; the shipping query-title default grades 0.678 on this corpus.
- v0.5 anchor held: 0.699 @ ~1036 (CIs overlap v0.6's 0.731 @ 981). Naive anchors reused from the pre-registered sweep, not re-bought. Token counts are packed-context tokens, not total round-trip tokens.
- Economics (v0.5 build-layer pilot, same corpus): build spend ~$0.14–0.20 per ~600-read stream (gpt-4o-mini); break-even ≈ 4–5 reads/source; widened units read median 23 chunks vs 2 keyhole; rebuild churn 460 → 31.
- HONEST LIMITS (part of the claim set): natural-refusal flip ~20% unconditional / 33% payload-contains-gold (the 68% lab figure is span-derived questions only) · sibling-article key collisions 3/605 (raise `key_floor` in dense same-topic corpora) · keys don't move final accuracy on diverse rewordings · store-build variance is real (headline comparisons are same-population by design) · build completeness 604/609 on this corpus.
- ANTI-CLAIMS: we do NOT claim to beat naive RAG on accuracy (a pre-registered 430-token decisive found no beat and no dominance region); we do NOT claim compression (naive's own curve reaches the same accuracy given more tokens — the value is token efficiency at parity + freshness/provenance + behavioral compounding); we make NO claim about conversational/agent-memory workloads (everything is measured on news/document corpora with factual queries); the v0.7 default flip is NOT earned (only the replay gate of five has passed).

## Benchmark — structured regime (SYNTHETIC TEMPLATES; v0.4-era, still current for the unit path)
- 64 sources × 3 seeds = 192 reads/condition, real OpenAI embeddings, deterministic number+attribute check, shared real dense top-5 retriever, graded escalation-off.
- Accuracy: PARITY with naive RAG across 4 answer models (95% CIs overlap): 4o-mini 0.81=0.81, 4.1-mini 0.90/0.85, 4o 0.90/0.87, 4.1 0.99/0.97 — at ~47 context tokens/read vs naive's 126.
- Routing: route@1 ≈ 1.00. Misattribution ~0–2% (= naive's own answerer noise; a historical high misattribution reading was a benchmark bug — contradictory duplicate sources — found/fixed/documented).
- Multi-hop: naive 0% -> Coalent 100% (cross-unit recall, zero extra LLM calls) — a TEMPLATE-FIXTURE result; see the news benchmark for real-world numbers.
- Economics: build ~430 tokens / ~4s per source once -> break-even ≈ 4–5 reads/source.

## Integrations & ops
- **MCP server (v0.6.1)** — `coalent-mcp --cache-factory my_cache:build` (BYO, primary) or `--watch ./docs` (zero-config); stdio or `--transport http`; seven tools. See "New in v0.6.1" above; docs: https://coalent.ai/docs/mcp
- **LangChain (v0.6.1)** — `langchain-coalent`: `create_coalent_cache` / `CoalentRetriever` / `CoalentVectorStoreRetriever` + the refusal-loop pattern. Docs: https://coalent.ai/docs/langchain
- `make_cognition_node(cache)` — a LangGraph node: state -> `{context: fresh understanding}`.
- `build_mcp_tools(cache)` — expose the cache as in-process MCP tool SPECS over `cache.get()` (predates and complements the full `coalent-mcp` server).
- Change events: `source_changed`, `source_deleted`; connectors for GitHub / Jira / deploy / CDC + `verify_github_signature`.
- CLI: `coalent ls | show <id> | invalidate <source> | stats` — a redis-cli for the cognition cache (over a SQLite store).

## Docs
- Full documentation: https://coalent.ai/docs — concepts, freshness & provenance, retrievers, synthesizers, the gate ladder, the pool read path (context intelligence), persistence, benchmark, and worked examples.
- Claude Code & MCP (v0.6.1): https://coalent.ai/docs/mcp · LangChain (v0.6.1): https://coalent.ai/docs/langchain
- Upgrade guide (v0.5 -> v0.6): https://github.com/Vectorlink-Labs/coalent/blob/main/UPGRADE-0.5-to-0.6.md
- Upgrade guide (v0.4 -> v0.5): https://github.com/Vectorlink-Labs/coalent/blob/main/UPGRADE-0.4-to-0.5.md