How a knowledge model improves itself
A knowledge model can audit its own shape — find gaps, contradictions, and stale facts — and, with your approval, grow from trusted outside sources. The detection runs free, on the AI assistant you already have; nothing is changed behind your back.
New to rlat? Start with What is rlat? first. This page is the detailed tour of the self-improvement loop: what each stage does, the commands and skills that drive it, when (if ever) you need an API key, the options you control, and the honest limits.
This loop is the corpus half of self-improvement — keeping what your documents say complete, consistent, and current. The other half is your world: capturing the stable facts, standing constraints, and tried-and-failed findings of your own environment. That half lives on the Claims page.
Six stages
The whole thing is one loop. The expensive part — reading the corpus to decide what's wrong with it — is done by cheap maths first, so the AI only ever judges a short list, never the whole corpus.
.rlat.The one rule to remember: rlat surfaces; it does not silently edit. Detection and judging show you findings; growing the model (steps 3–6) only happens with your approval, and never touches your original source files.
The corpus audits its own shape (free, no AI)
Every time you build or refresh a model, rlat
computes a small shape report and stores it inside the
.rlat. It is pure maths — no AI call, no API key, no network. It
holds two things:
- Demand gaps — topics people keep asking about that the corpus is thin on. (These build up from real usage, so a brand-new model has none yet.)
- Contradiction candidates — pairs of passages in different documents that are about the same thing and might disagree. The maths can only prove "same topic"; whether they truly conflict is the judge's job (next stage).
Look at the report — and re-compute it live at a chosen sensitivity:
# the stored report: demand gaps + contradiction candidates
rlat audit km.rlat --shape
# recompute candidates live, with the passage text, ready for an AI to judge
# (--min-cosine is the sensitivity dial; lower finds more, looser pairs)
rlat audit km.rlat --shape --min-cosine 0.85 --with-text --format json
# list the external (web-fetched) facts in the model + their source URLs
rlat audit km.rlat --external --format jsonCandidates come back demand-ranked — conflicts that sit in the path of real questions are listed first, so you spend attention where it matters. Full flag reference on the CLI page.
Which candidates are real?
The maths hands over a short list; an AI decides which items are genuine. The same judgement runs two ways, and you choose:
- Free, in-session — the skills (below) ask the AI assistant you are already talking to to judge the candidates. No API key, no separate bill. This is the recommended way.
- Metered, for automation — the library functions
(
curator.reconcile.judge_contradictions,store.external_freshness.recheck_external_freshness) accept an Anthropic client so you can run the judgement unattended in a script. That path needs an API key.
Why two stages instead of just asking the AI everything? Cost. Judging every possible pair in a large corpus would be millions of AI calls; the geometry narrows that to a handful first, so the AI step stays cheap either way.
Grow from trusted outside facts
When a gap is real and the corpus genuinely lacks the fact, rlat can fetch it from the web and add it — under strict safety rules so an unverified claim can never slip in:
- Two sources must agree. A fact only lands if at least two independent sources state it and concur. One source, or disagreement, means nothing lands.
- It must trace to those sources. The claim is checked against the fetched text; if it isn't supported, it's dropped.
- It carries its receipts. A landed fact stores its source URLs, and is born low-trust — it earns standing only as it proves useful over time.
Trust tiers
Every fact in the model carries a trust level that starts from where it came from, not from how confident the AI sounded:
| Source | Starting trust |
|---|---|
| You (you hand-provided it with a source) | highest |
| Verified external (≥2 agreeing web sources) | high |
| Single external (one web source) | baseline |
| Corpus synthesis (distilled from your own docs) | baseline |
A higher tier is a starting prior, not a permanent verdict — any fact still earns or loses standing as outcomes come in. (The full trust model is on the Claims page.)
Keep web-sourced facts current
A fact pulled from the web was true when fetched, but the world moves on — a
version, a price, a "current" anything. rlat refresh can't catch
this, because refresh only re-reads your local files; a web fact has
no local copy to re-read. So the freshness re-check re-fetches the cited URLs
and asks whether they still support the fact:
- fresh — the sources still back it. Nothing to do.
- stale — the sources have moved past it. Surfaced for you to re-fetch or retire.
- unknown — a page wouldn't load. Reported as uncheckable, never wrongly marked stale.
Resolve a confirmed conflict — non-destructively
When you've confirmed two documents genuinely conflict and decided which side is authoritative, rlat records the resolution as a high-trust note that cites both passages. It does not edit your source files — the conflicting passages stay exactly as they are; the model simply ranks the resolution first. This is a deliberate, one-at-a-time step on your decision, never an automatic edit.
Four skills run the whole loop free
The simplest way to use any of this is the bundled skills. Each runs on the AI assistant you are already using — no API key, no per-use bill — and each surfaces findings for you rather than editing anything. See the Skills page for how skills are wired.
| Skill | What it does | Ask it |
|---|---|---|
rlat-gap-scan | Finds the questions your corpus can't actually answer. | "What is my corpus missing?", "where are the gaps?" |
rlat-contradictions | Finds documents that disagree with each other. | "Are there contradictions in my corpus?", "which docs conflict?" |
rlat-refresh-facts | Re-checks web-fetched facts against the live world. | "Are my fetched facts still current?", "did anything go stale?" |
rlat-curate | Human-in-the-loop: surfaces findings and lets you approve a fill, hand-provide a source, or skip. | "Curate my knowledge base", "let me review before adding" |
Mostly no
The honest answer, stage by stage:
| Stage | Needs an API key? |
|---|---|
Detect (gaps, contradiction candidates, rlat audit --shape/--external) | No — it's maths. |
| Judge via the skills | No — the assistant you're already in does it. |
| Fetch from the web (via the skills) | No — the assistant's own web tools. |
| Land a fact you/the assistant verified | No — the free landing path. |
| Judge or land unattended, in a script (the metered library path) | Yes — an Anthropic key. |
So you only need a key if you want to run the loop as automation, outside an interactive assistant. When you do, rlat finds the key the usual way — see API keys for the environment variables it reads.
Dials and defaults
- Sensitivity (
--min-cosine). The contradiction finder's floor is a recall/precision dial: lower surfaces more (looser) pairs for the judge to filter; higher surfaces only near-identical ones. The stored default is conservative;0.85is a good floor for prose. - How many to judge (
--max-pairs). Caps the candidate list so the judge cost stays bounded on a big corpus. - Surface, don't edit. Everything is review-first by
default. Use
rlat-curatewhen you want a human gate on every change — approve a draft, or hand-provide your own authoritative source (which lands at the highest trust tier). - Where things land. New facts and resolutions live in the model's earned layer, alongside — never overwriting — your original passages. Your source files are never modified.
What it does and doesn't do
- Detection finds candidates, not certainties. The geometry only proves two passages are about the same topic; the judge (you or an AI) decides if they truly conflict. Most high-similarity pairs are just restatements.
- Contradictions need genuine cross-source disagreement. A clean, consistent corpus correctly finds ~zero — that's the tool working, not failing. The value is on knowledge bases that accumulated conflicting copies over time.
- Number-heavy corpora can over-flag. On documents dense with similar-looking figures or tables, the judge sometimes mistakes two different measurements for a conflict — which is exactly why the loop surfaces for review and never auto-edits.
- "No gaps found" means "none among the questions asked." It can't see a need nobody has queried for. Don't read it as "complete".