Core use cases

Eight use cases, one artifact

The eight use cases below share the same .rlat file and the same architecture. They differ only in which surface of rlat they lean on most.

• Ground an LLM with verified citations
• Bootstrap any assistant in seconds
• Make skills knowledge-aware
• Give an assistant durable memory
• Keep your knowledge portable and local-first
• Inspect what your knowledge contains
• Let the knowledge model improve itself
• Compose without rebuilding

Ground an LLM with verified citations

Trust the answer without checking the LLM's work. Every passage rlat returns carries its source file, character offset, content hash, and a live drift status against the file on disk — drift meaning the file changed since the model was built. Your assistant composes its response from passages that have been mechanically verified, not from what the model happens to remember.

What you get

• Hits with full provenance. Every result carries its text, source file, character offset and length, content hash, and drift status. The text is sliced live from the source file — drift is detected because hashes are checked, not assumed.
• Drop the drifted with one flag. rlat search --verified-only filters out any hit whose content hash no longer matches the source. Use it whenever the model is older than the underlying files and you would rather have fewer truthful hits than more stale ones.
• Honest confidence on every retrieval. The Python evidence() operation returns confidence metrics: the top-1 cosine score (is retrieval working at all?), the gap to the second hit, how many distinct sources back the answer, and the fraction of supporting evidence that has drifted. Use these to gate whether a downstream LLM should answer or refuse.
• Grounding modes for LLM-facing output. rlat search --format context --mode {augment|knowledge|constrain} (and the same flag on rlat skill-context) stamps a directive at the top of the markdown telling the consumer LLM how to treat the passages — see the next section for the three modes.
• Name-aliasing protection. --strict-names extracts distinctive proper nouns, acronyms, and alphanumeric IDs from the question and checks each appears in at least one retrieved passage. It catches the failure mode where a question references a fake or adjacent product but the corpus only describes a similarly-named real one — a score cannot tell those apart on a paraphrase-rich corpus; the name check can.
• Multi-hop research that produces a grounded answer. For cross-file synthesis questions, the deep-research skill drives a plan → retrieve → refine → synthesize loop natively in your Claude Code session — no API key, your subscription covers the LLM hops. The same loop is exposed as rlat deep-search for programmatic, agent, and CI consumers (an Anthropic API key is required there). On the Microsoft Fabric corpus, under a relaxed rubric, the loop measured 92.2% answerable accuracy at 0% hallucination — the same numbers apply to both surfaces because it is the same loop.

Run

rlat search my-project.rlat "how does the encoder cache work" --verified-only
rlat search my-project.rlat "auth flow" --format context        # markdown for an LLM prompt
rlat deep-search my-project.rlat "explain the auth flow with rationale"  # multi-hop, synthesised answer

Why it matters

Hallucinated citations are the failure mode that consequences hang on — legal briefs, medical advice, regulatory filings, audit reports. rlat makes them structurally detectable: every retrieved passage carries a source path, character offset, and content hash, so the consumer can verify where evidence came from and whether it has drifted. For compliance work, pair --mode constrain with --strict-names so a question about a non-existent product gets a refusal rather than a confident wrong answer.

Bootstrap any assistant in seconds

Stop re-explaining your project on every new chat. rlat generates an extractive primer — a compact summary of the project — and your assistant loads it at session start. Conversations don't begin cold, and the assistant doesn't invent details to fill the gap.

What you get

• One command from clone to full context. rlat init-project auto-detects docs/, src/, and top-level Markdown, builds the knowledge model, and writes a primer. A new contributor — or your future self after weeks away — gets the assistant briefed in under a minute.
• Targeted evidence sections. rlat summary --query "auth" --query "billing" adds an evidence block per query, so a primer covers the topics you actually ask about, not just the corpus average.
• Stays current — manually or live. rlat refresh re-ingests a local-mode model against its recorded source paths, atomically. rlat watch runs the same refresh on every save (debounced, silent by default, auto-discovers *.rlat in the current directory) so the model stays fresh without you remembering to refresh.
• Works with any assistant. Claude Code, Cursor, command-line LLMs, agents in any IDE — anywhere a project-context file gets loaded.

Run

rlat init-project                                # auto-detect, build, primer
rlat summary my-project.rlat -o .claude/resonance-context.md
rlat summary my-project.rlat \
  --query "encoder caching" --query "drift detection" \
  -o .claude/resonance-context.md

Why it matters

Every cold session is a tax. A primer paid once and refreshed on demand collapses the cost of rebuilding context from per-conversation to per-corpus-change. The assistant arrives knowing what the project is, so the conversation starts where the last useful one left off.

Make skills knowledge-aware

An Anthropic skill is a static instruction bundle by default. rlat skill-context makes it adaptive — each invocation injects markdown evidence retrieved against the user's actual question, drawn from a knowledge model the skill author chose.

What you get

• A first-class skill primitive. rlat skill-context is designed to be the body of a skill !command block. It returns markdown, so the skill's SKILL.md doesn't post-process anything.
• Multi-query in one call. --query is repeatable — pass a skill-author preset query and the user's live query in one invocation. The token budget truncates later blocks first, so the preset survives if the budget shrinks.
• Three grounding modes. --mode augment (the default) tells the LLM to treat passages as primary context blended with its training. --mode constrain tells it to answer only from the passages and refuse otherwise — load-bearing for fact extraction, compliance, regulatory, and audit skills. --mode knowledge treats passages as a supplement to training.
• Drift-aware injection. Every passage carries a drift indicator, and --verified-only drops any passage whose source has drifted or gone missing — so a skill never silently serves stale knowledge.
• Per-passage citation anchors. Output is labelled with each passage's source file and character offset, so the assistant can cite back into your source files at exact coordinates.
• Works on existing knowledge models. Any .rlat file already serves a skill — no per-skill encoder, no skill-specific build, no separate index.

Run

# Inside a skill SKILL.md, in a !command block:
rlat skill-context fabric.rlat \
  --query "Fabric workspace authentication and service principal patterns" \
  --query "$USER_QUERY" \
  --top-k 8 --token-budget 2000

Why it matters

A skill about Fabric lakehouses without rlat injects the same instructions whether the question is about workspace setup, ingestion patterns, or Delta merge semantics. With rlat skill-context, each question retrieves different evidence from the same knowledge model. The skill's static instructions frame the workflow; the knowledge model supplies the specifics. Full walkthrough on the skills page.

Give an assistant durable memory

Conversations that accumulate, not conversations that vanish. rlat memory keeps the lessons of past sessions as a small, queryable store — and grows more confident in the lessons that keep paying off.

What you get

• A flat confidence store, not a log. Memory holds a small set of lessons — short statements about what tends to work — and each lesson carries a confidence on a four-step ladder (low → medium → high → verified) that rises as the lesson keeps proving useful.
• Hands-free capture, mechanical housekeeping. A session-end hook records what was learned (deduplicated, credential- scrubbed); one mechanical command — rlat memory consolidate — re-derives confidence from outcomes and prunes the weak rows. You are never asked to rate, tag, or file anything.
• Confidence orders recall. When several lessons are equally relevant, the more confident one surfaces first, and every recalled lesson shows its confidence so a low-confidence guess is never mistaken for a verified fact.
• A few commands you touch by hand. rlat memory add writes a lesson directly, rlat memory list and rlat memory recall inspect the store, and rlat memory gc is a filtered escape hatch for manual deletion.
• Three world content classes, each with a published receipt. Stable facts about the world the knowledge model covers — a capacity, a version, a region, a policy — where the newest value per subject wins (receipt). Standing constraints — hard rules served in full on every context serve, never retrieved by similarity (receipt). And tried-and-falsified findings — served with their verdict, so an assistant stops re-recommending dead ends (receipt).
• Capture is opt-in, two ways. On a subscription: the rlat-learn skill — say "remember this" and the assistant extracts world facts through the same four gates, with you approving each one (no API key). Unattended: rlat memory install-hooks --mine wires the session hooks (RLAT_MINE_ATTRIBUTES=1, needs a key) and durable world facts you state in passing land automatically. Either way the extractor's GATE 4 drops facts about you — only facts about the knowledge model's world are kept (receipt).

Run

rlat memory add "user prefers TypeScript over Python" --polarity prefer
rlat memory recall "what tech stack does the user prefer"
rlat memory list

Why it matters

With capture enabled — one command, rlat memory install-hooks --mine — the file accumulates validated world facts and lessons, and each one's confidence moves with real outcomes. What it does not do is silently delete things: automatic suppression was tested and falsified, and the record is published (R4), so corrections stay explicit — you state the new fact or delete the old one. The full model — what gets captured, the confidence ladder, and how forgetting stays careful — is on the claim system page; the hooks, daemon, and command table are on Memory & sessions.

Keep your knowledge portable and local-first

Your knowledge stays yours. A knowledge model is a single .rlat file, your source files stay where they are, and nothing leaves your machine unless you explicitly send it.

What you get

• Single-file portability. One .rlat packages embeddings, source coordinates, drift hashes, an optional ANN index, and — in bundled mode — the source text itself. Copy it, version it, share it; it works anywhere Python 3.11 or newer runs.
• Three storage modes for three trust models.
  • bundled — the source text is packed inside the archive. Fully self-contained; ship it without the source files.
  • local (the default) — the source text stays on disk and the archive resolves it via --source-root. No duplication; ideal when the source is a git repo you already version.
  • remote — the source text lives behind an HTTP base URL with SHA-pinned manifests. Read-only rlat freshness confirms upstream hasn't changed; rlat sync applies an incremental delta when it has.
• Fully offline after first install. rlat install-encoder downloads the encoder once. After that, build and search need zero network access. Pair with a local LLM for an end-to-end private stack.
• Field-only sharing. Ship a .rlat with the vectors but without the source text — recipients see and can search the semantic structure of a private corpus without reading your raw text.
• No telemetry, no accounts, no cloud. Everything is a local Python package.

Run

rlat install-encoder                                       # one-time
rlat build ./docs ./src -o my-project.rlat                 # local mode (default)
rlat build ./docs -o handout.rlat --store-mode bundled     # self-contained

Why it matters

The same artifact serves a hobbyist on a laptop, a consultant carrying client knowledge between engagements, a research team archiving a paper corpus, and a regulated-industry team where data egress is policy. The .rlat format is a single-file unit of distribution — versionable, diffable, hand-offable, archivable. Decision guide on the storage modes page.

Inspect what your knowledge contains

See the structure of what you know — and what you don't. Most retrieval tools are opaque: documents in, results out, no way to understand the model in between. rlat exposes the semantic structure of the corpus as a first-class interface.

What you get

• rlat profile — per-source-file passage counts, drift counts grouped by verified / drifted / missing, encoder identity, band info. "How healthy is this knowledge model?" in one command.
• rlat compare — cross-knowledge-model thematic alignment plus asymmetric coverage: a single centroid-cosine number for how aligned two corpora are, and how much of each is covered by the other. Always uses the base band.
• Python inspection operations — locate reports how dense the corpus is around a point in semantic space; neighbors finds the passages nearest a given one; near_duplicates surfaces accidental redundancy; corpus_diff tracks per-passage changes across two snapshots; drift lists every passage whose source has changed.

Run

rlat profile my-project.rlat                       # text summary
rlat profile my-project.rlat --format json         # structured
rlat compare a.rlat b.rlat --format json

Why it matters

Inspecting the corpus before trusting it is the discipline that keeps a retrieval system honest. rlat's inspection operations are derived mechanically from the embeddings themselves — cosine similarity, content-hash equality, clustering — not from heuristics or LLM-judged labels.

Let the knowledge model improve itself

The corpus audits its own shape — and can grow from trusted sources. Inspecting (above) shows you the structure; this is the step that acts on it. A knowledge model can flag the questions it can't answer, the documents that contradict each other, and the web-fetched facts that have gone stale — and, with your approval, fill a gap from verified outside sources. Detection is free and needs no API key; nothing changes without your say-so, and your source files are never edited.

The serve surfaces carry what the model has learned, too: rlat search --format context and the agent-session injection serve standing constraints and falsified findings with their measured framings — "Standing constraints for this environment" and "Tried and falsified". One honest boundary: the model never silently suppresses its own claims — automatic suppression was tested and falsified (R4); corrections stay explicit.

What you get

• rlat audit --shape — the corpus's stored self-audit: under-served demand gaps plus same-topic cross-document contradiction candidates, demand-ranked. --external lists the web-fetched facts to re-check.
• Four free skills — rlat-gap-scan (what the corpus can't answer), rlat-contradictions (documents that disagree), rlat-refresh-facts (web facts gone stale), and rlat-curate (a human gate on every change). Each runs on the AI assistant you already use — no API key.
• Verified growth — a fact only lands when two independent sources agree, and it lands with its source links at a trust tier set by where it came from (you ≥ verified-external ≥ corpus).

Run

rlat audit my-project.rlat --shape                          # gaps + contradiction candidates
rlat audit my-project.rlat --shape --min-cosine 0.85 --with-text   # live, judge-ready
rlat audit my-project.rlat --external --format json         # web-fetched facts to re-check

Why it matters

A knowledge base decays — questions go unanswered, old pages linger and conflict with new ones, fetched facts age. The self-improvement loop turns that maintenance from a manual chore into something the model surfaces for you. The full tour — the six stages, the safety rules, and the API-key question — is on the Self-improvement page.

Compose without rebuilding

Reshape what you have; don't re-encode raw text every time. rlat composes across knowledge models at query time, so you can change retrieval behaviour without rebuilding.

What you get

• compose — a federated, read-only view across several knowledge models. A query routes against all of them and results are unified. Useful when you want to query across corpora without merging them on disk.
• merge — a write-out merge that semantically de-duplicates. Useful when you want one permanent artefact spanning multiple sources.
• unique / intersect — set algebra over knowledge models: the passages in A that aren't in B, or the passages in both, based on a cosine threshold.

Run

from resonance_lattice.store import archive
from resonance_lattice.rql import compose, merge, unique

a = archive.read("docs.rlat")
b = archive.read("src.rlat")

view = compose(docs=a, code=b)             # query both corpora at once, no write
n_unique = merge(a, b, "merged.rlat", dedupe_threshold=0.95)  # writes the artefact, returns unique-passage count
docs_only = unique(a, b, threshold=0.85)   # what's in docs that isn't in src

Why it matters

A corpus is rarely just one source. compose lets you query across knowledge models without maintaining a meta-archive; merge lets you commit to a single one when that is what your workflow needs.

The lensed-knowledge surface

Beyond retrieving raw passages, rlat can earn and store insights — cited summaries built from the corpus — and apply a saved perspective, a lens, when ranking results. rlat search retrieves over both the source layer and the insight layer and labels every hit with the layer it came from. Pass --source-only to restrict a query to raw passages, or --lens <file> to apply a perspective. The full model — insights, lenses, audit, and trace — is on the claim system page.

What rlat does not do

Honest about scope so you can plan around it:

• No retrieval-time knobs. No reranking, no lexical sidecar, no query-prefix tuning, no auto-mode router. A single recipe — gte-modernbert-base 768d CLS+L2 dense cosine. Empirically validated to match or beat tuned alternatives; see the benchmarks page.
• No HTTP server. The CLI is the primary surface, with the Python API underneath it.
• No algebraically-exact forget. To remove specific knowledge, rebuild with the source subset you want and ship the new .rlat — atomic and auditable, at the corpus granularity rather than the per-passage granularity.

Where to go next