Getting started

Install rlat

rlat requires Python 3.11 or newer. The base install is small (~250 MB) and CPU-only — only the build path needs the heavier machine-learning extras.

pip install rlat[build]
# or, if you're on uv:
uv pip install 'rlat[build]'

The [build] extra pulls in transformers, torch, and onnxscript. Once you have a .rlat, querying it needs only the base install — run pip install rlat (no extras) on another machine and you can search a knowledge model someone else built.

Try a prebuilt knowledge model

Five prebuilt knowledge models live on HuggingFace, ready to query in seconds — no encoder install, no build step. The remote-mode models pin to their source repository at a commit SHA and fetch source on demand (SHA-verified at query time); the bundled-mode model packs its source inside the archive.

# base install is enough — no [build] extras needed to query
pip install rlat huggingface_hub

# pick the corpus that fits your work
hf download tenfingers/python-stdlib-rlat python-stdlib.rlat --local-dir .

# query it — the first hit caches cited source files locally; warm queries are sub-20ms
rlat search python-stdlib.rlat "asyncio Task cancellation" --top-k 5 --format context

All five are encoded with the same gte-modernbert-base 768d recipe, so retrieval quality matches anything you build locally. Sub-20ms warm-query receipts are on the Benchmarks page. To index your own project instead, keep reading.

Stage the encoder

The first rlat build stages the encoder automatically. To pre-stage it (for offline builds or CI):

rlat install-encoder

This downloads Alibaba-NLP/gte-modernbert-base from Hugging Face, exports it to ONNX, and — on Intel CPUs — converts it to OpenVINO. The cache lives at ~/.cache/rlat/encoders/<revision>/.

Build your first knowledge model

Two ways. Pick one.

Option A — rlat init-project

Run this in the root of a project that has docs/, src/, or top-level Markdown files:

cd my-project/
rlat init-project

It auto-detects sources, builds <cwd-name>.rlat in the current directory, and writes a context primer to .claude/resonance-context.md for AI-assistant integration.

[init] detected sources:
  - docs
  - src
  - README.md
[init] output: my-project.rlat
[build] 14 files; chunking …
[build] 39 passages; encoding (runtime=torch, batch=32) …
[build] wrote my-project.rlat (1.20 MB, 39 passages from 14 files)
[summary] wrote .claude/resonance-context.md (1856 chars, ~464 tokens)

Option B — rlat build (full control)

rlat build ./docs ./src -o my-project.rlat \
  --store-mode local \
  --kind corpus

There are three storage modes; local is the default. The CLI reference covers the trade-offs.

Run your first query

The everyday call — output is LLM-ready markdown you pipe into Claude / Cursor / your assistant:

rlat search my-project.rlat "how does retrieval work" --format context --top-k 5

<!-- rlat-mode: augment -->
> Grounding mode: augment. Use the passages below as primary context …

<!-- docs/architecture.md:84+12 score=0.836 verified -->
## Indexing

<!-- docs/architecture.md:12+73 score=0.820 verified -->
This project does dense retrieval with cosine similarity over unit-norm embeddings.

<!-- src/retrieval.py:0+50 score=0.805 verified -->
def build_index(passages):  return faiss.HNSW(passages)

The comment lines are stable citation anchors — your assistant can preserve them in its answer. The rlat-mode directive at the top tells the consumer LLM how to weight the passages (augment / knowledge / constrain).

Without --format context you get the plain inspector view:

0.836  docs/architecture.md:84+12  [verified]  ## Indexing
0.820  docs/architecture.md:12+73  [verified]  This project does dense retrieval …
0.805  src/retrieval.py:0+50       [verified]  def build_index(passages): …

Four columns: cosine score, source coordinate, drift status, preview. The status is per passage — if you edit architecture.md, that file's hits show drifted until you run rlat refresh.

rlat search retrieves over two layers: the source layer (the raw passages from your files) and the insight layer (earned, cited summaries — see the claim system page). Every hit is labelled with the layer it came from. To restrict a query to source passages only, pass --source-only; to apply a saved perspective, pass --lens <file>.

For machine-readable JSON:

rlat search my-project.rlat "..." --format json

Teach it your world

The knowledge model knows your files. It does not know your rules. Tell it one:

rlat capture-attribute my-project.rlat "Deploys to prod happen Tuesday only." --kind constraint

Now re-run a query:

rlat search my-project.rlat "when can I deploy?" --format context

<!-- rlat-mode: augment -->
> Grounding mode: augment. Use the passages below as primary context …

Standing constraints for this environment:
- Deploys to prod happen Tuesday only.

<!-- SOURCE docs/release.md:212+88 score=0.741 verified -->
The release pipeline promotes builds from staging …

The rule now precedes every passage. Constraints are always served — they render right after the grounding directive on every query rather than depending on a similarity match. rlat lens is where you review or remove what the file has learned.

Give the corpus to an AI assistant

rlat init-project already wrote .claude/resonance-context.md — a markdown primer with three sections (Landscape / Structure / Evidence) that you paste into your assistant's system prompt. Regenerate it after meaningful corpus changes:

rlat summary my-project.rlat -o .claude/resonance-context.md

Keep the model in sync

When you edit source files, the on-disk content drifts from what was indexed. Four ways to recover:

# live: a silent watch loop — debounced refresh on every save
pip install rlat[watch]            # one-time
rlat watch                         # auto-discovers *.rlat in the current dir

# manual: re-ingest changed files in place (atomic — old archive intact until success)
rlat refresh my-project.rlat

# query-time guard: return only verified hits
rlat search my-project.rlat "..." --verified-only

# revisit earned insights whose source drifted — keep or retire each
rlat reverify my-project.rlat

rlat watch runs the same incremental delta-apply as rlat refresh, on a debounce timer triggered by filesystem events. It is silent by default — startup confirms what is being watched, then the loop falls quiet; errors are loud. --once is the CI / pre-commit shape.

Inspect a knowledge model

rlat profile my-project.rlat              # human-readable summary
rlat profile my-project.rlat --format json # JSON for scripts / dashboards
rlat profile big-corpus.rlat --no-drift    # skip the drift walk on huge corpora

Compare two corpora

rlat compare project-old.rlat project-new.rlat

Reports centroid_cosine (a single thematic-alignment number) and asymmetric mutual coverage. It uses the base band — the band every knowledge model shares — so any two corpora compare correctly.

Where things go wrong

• rlat: command not found — pip did not put the script on PATH. From a source checkout, run pip install -e .[build]; otherwise check python -m resonance_lattice.cli.app --help.
• error: <path> is not a valid v4.1 knowledge model — the file is corrupted or is not a .rlat. Run file <path> to confirm it is a ZIP archive.
• error: local-mode knowledge model has no recorded source_root — the model was built without recording where its sources came from. Pass --source-root <dir> to override.
• First query is slow (~1 second) — encoder cold-start. Later queries in the same process are sub-20ms warm.
• A hit shows drifted — the source file changed since build. Run rlat refresh.
• A hit shows missing — the source file was deleted. rlat refresh rebuilds without it.

What's next

You now have the day-one workflow. From here: