get() is the one method you'll use. It embeds the query, serves a semantically-matching fresh unit, or retrieves + synthesizes a new one — always with the raw evidence retained.
Signature
ctx = cache.get(
query,
*,
namespace=None, # optional tenant/filter scope
related=3, # fold in up to N related units (0 to disable)
strategy=None, # override the ContextStrategy for this call
)
Just pass the question — the cache is keyed by the query's meaning, so similar phrasings reuse the same understanding.
Result
ctx.context # minimum decision-relevant payload: {"understanding": {...}, "raw": [...]}
ctx.understanding# the full structured understanding (dict)
ctx.evidence # all retained raw chunks — always reachable for specifics
ctx.raw_text # those chunks as one string
ctx.cache_hit # True if served from cache, False if just built
ctx.coverage # 0–1: how well the unit covers the query
ctx.escalated # True if it pulled fresh raw to cover the query
ctx.needs_retrieval # True when coverage fell below the floor — a hint to widen (v0.5)
ctx.recalled # list[RecalledClaim] — cross-unit claims surfaced for multi-hop (v0.4)
ctx.confidence # semantic match strength of the hit
ctx.related # list[Related] — cross-unit reuse (see below)
ctx.unit_id # the cached unit's id
ctx.namespace # the namespace this read used
coverage and escalated are New in v0.3 — they expose the semantic coverage gate, so you can tell when a cached hit fell back to fresh raw to cover the query.
recalled is New in v0.4. When the matched unit under-covers the query, cross-unit recall pools per-claim memory across all fresh units and surfaces the bridge facts a single unit can't — answering multi-hop questions at zero extra LLM calls. It's empty when recall didn't fire (single-hop hits, or a non-semantic embedder). When it does fire, those claims are also injected into the payload as ctx.context["understanding"]["recalled_claims"], so the LLM sees them without any extra plumbing.
New in v0.5 Under serve="pool" — the experimental pool-serving preview — the payload is the token-budgeted, globally-ranked fresh-claim pool, and renderers read it at ctx.context["pool"]. See Context intelligence for the full pool-serving reference.
Field reference
| Field | Type | Meaning |
|---|---|---|
context | dict | What to hand the LLM: projected understanding + raw (per strategy). |
understanding | dict | Full summary / claims / entities / facts. |
evidence | list[Chunk] | All retained raw — always reachable for specifics. |
cache_hit | bool | Served from cache vs. freshly built. |
coverage | float | Query terms represented in the unit (drives escalation). |
escalated | bool | Fresh raw was pulled because the hit under-covered. |
needs_retrieval | bool | New in v0.5 Coverage fell below the floor — a hint that this read would benefit from wider retrieval. |
recalled | list[RecalledClaim] | New in v0.4 Cross-unit claims surfaced for multi-hop: claim, score, unit_id. Empty when recall didn't fire. |
related | list[Related] | Related units: unit_id, relation, understanding, score. |
Examples
# the common case
ctx = cache.get("what is our leave policy?")
# multi-tenant isolation
ctx = cache.get("vacation rules", namespace="acme-corp")
# always include raw, and skip related expansion
from coalent import ContextStrategy
ctx = cache.get("leave policy", related=0, strategy=ContextStrategy.CONTEXT_RAW)
Next
- Context intelligence — coverage, escalation, strategies, related.
- Data model — every field on the supporting types.