# lore
### An independent code reviewer that **remembers your codebase between sessions**
*Reviews are the mechanism. The memory is the product.*
[](https://github.com/Vany/lore/actions/workflows/ci.yml)
[](src)
[](#what-it-has-actually-done)
[](package.json)
[](tsconfig.json)
[](spec/mcp-api.md)
[](LICENSE)
---
Every AI coding session starts amnesiac. It rediscovers the same conventions, re-raises
the same settled questions, and repeats the same mistake you corrected last week.
**`lore` is the memory.** It reviews a branch before it merges โ with models that did not
write the code โ and everything it learns doing so becomes a fact the next session already
knows.
| | |
|:--|:--|
| ๐ง | **It remembers.** 544 live facts about six codebases, each with provenance and an expiry |
| ๐ | **It disagrees with you.** 3,890 findings raised; 215 of your justifications rejected |
| ๐ซ | **It never bluffs.** A review that did not run is never reported as one that found nothing |
| ๐ | **It is not your author.** Every tier is a non-Anthropic model, enforced by absence |
---
## What a finding actually looks like
Not a nit about naming. This one is from lore reviewing **its own** commit, this morning:
> **`e8d3f8a3` ยท medium ยท `src/core/memory.ts:61`**
>
> **Claim.** SPEC D-151 says an unparseable `LORE_MIN_AVAILABLE_MB` *"refuses to start rather
> than falling back to the default"*, but nothing validates it at boot: `floorBytes()` throws
> lazily inside `review_start` and inside `checkHealth`. The startup-validation idiom for
> exactly this knob class exists 60 lines away and was not used.
>
> **Failure scenario.** Operator sets `LORE_MIN_AVAILABLE_MB=2g` โ the SPEC's own example โ and
> runs `make up`: the container starts green and answers `/healthz` 200, so the operator
> believes the value was accepted. In fact every `review_start` fails with an error shown only
> to client agents, `/status` answers 500, and the beat's only signal is deadman silence. **The
> monitor dies on the misconfiguration instead of reporting it.**
>
> **Asks.** *Fix this, or tell me why it is not a problem. Both are real answers, and I may be wrong.*
It read a sentence in a spec, checked it against the code, found the code narrower than the
claim, and traced what an operator would believe as a result. That is the class of defect
this is built to catch โ **a false statement about a failure**, which is what nearly every
real bug in this repository has turned out to be.
---
## The idea that makes it work
When a reviewer raises something you believe is wrong, you do not argue in a comment
thread. You write the reason **in the code**:
```ts
// lore-ok[a1b2c3d4]: bounded by the caller's schema check at api/route.ts:31,
// so a negative amount cannot reach here.
export function capture(amount: number) { โฆ }
```
That is *proposing a piece of lore*. The reviewer ratifies it โ and your reason becomes
something the codebase knows about itself โ or rejects it, and the finding returns at
**higher severity**, because a wrong justification is worse than a bug.
```mermaid
flowchart LR
F["finding raised"] --> J["you answer:
fix it, or justify it"]
J -->|"fix"| V["reviewer re-reads
the corrected tree"]
J -->|"lore-ok"| R{"reviewer
rules on it"}
R -->|"ratified"| K["it becomes
shared memory"]
R -->|"rejected"| H["returns,
higher severity"]
K --> E["the code moves,
the reason expires,
the finding comes back"]
```
**The author never closes its own finding.** That single rule is what keeps the loop
honest: it terminates when the code is correct, not when the author gets persuasive.
And a justification **expires**. It was a claim about specific code; when that code changes
the reason may no longer hold. Live proof: **8,088 of this deployment's knowledge rows have
been retired** as their sources moved, against 544 still standing. Without that, a design
like this rots into rubber-stamping within months.
---
## The ladder
Deterministic tooling first โ *a model should never be paid to decide what a typechecker
decides for free.* Then progressively dearer models, each seeing only code the previous
tier already passed.
| tier | engine | vendor | paid by |
|:--|:--|:--|:--|
| **T0** | the repo's own `tsc` ยท `eslint` ยท `cargo check`/`clippy` ยท `ast-grep` ยท `semgrep` | โ | free |
| **T1** | GLM-5.3 | Z.ai | subscription |
| **T2** | Kimi K3 | Moonshot | subscription |
| **T3** | GPT-5.6 Sol | OpenAI | subscription |
Three tiers, **three vendors** โ two tiers from one model family share blind spots and are
not two independent opinions.
```mermaid
flowchart TD
T0["T0 โ tsc, eslint, semgrep, ast-grep
free, deterministic"] --> T1["T1 โ GLM-5.3"]
T1 -->|"findings"| FIX["you fix, or justify"]
FIX -->|"a fix is unreviewed code"| T0
T1 -->|"clean"| DEEP["T2 โ Kimi K3 + T3 โ GPT-5.6 Sol
run together, different vendors"]
DEEP -->|"findings"| FIX
DEEP -->|"all agree"| P["passed
one signed line saying what was checked"]
```
**Every reviewer is a model that did not write the code.** That rules out the strongest
model on the board on purpose: a model reviewing its own output confirms the design it
already had in mind. It is enforced by *absence* โ no Anthropic credential is ever deployed
to the reviewer.
**One paid route exists and it is off by default.** When a subscription hits its
billing-cycle limit the chain can reach the same model through OpenRouter, which bills per
call. The measured difference on this deployment is stark:
| route | calls | cost |
|:--|--:|--:|
| subscriptions | 4,458 | **$0** |
| metered fallback | 93 | **$230.53** |
`LORE_ALLOW_METERED` (default `0`) decides whether lore may walk onto one. At `0` the tier
is skipped and named in `checks_skipped` โ a weaker review said out loud, rather than a bill
nobody chose.
---
## What it has actually done
Measured on the live deployment, **2026-09-17**, from the database rather than from memory:
| | | | |
|--:|:--|--:|:--|
| **609** | reviews, over 5 weeks | **341** | reached a clean verdict |
| **3,890** | findings raised | **786** | of them high severity |
| **2,394** | findings fixed | **215** | justifications **rejected** |
| **544** | live facts remembered | **8,088** | retired as the code moved |
| **4,551** | model calls | **14.1B** | tokens |
| **6** | codebases | **4.1** | rounds per review |
**54 of those reviews were lore reviewing lore.** Most of what it has found, it found in
itself โ and the shape of those findings is the reason the project has the shape it does:
> Nearly every real defect was a **false statement about a failure**, not a wrong algorithm
> โ a review that timed out and reported clean, a cap that discarded a round someone paid
> for, a status command that guessed at why it had no status, a paste-able config that could
> never have been pasted. The ladder logic, the fingerprinting and the VEX mapping all worked
> first time. [`MEMO.md`](MEMO.md) has every one of them, including the retractions.
---
## What you get, concretely
| you do | lore does | you get |
|:--|:--|:--|
| push a branch and ask for a review | runs your own `tsc`, ESLint, `semgrep`, `ast-grep`, then up to three models from three vendors | findings with a **failure scenario**, not style notes |
| fix, or write a `lore-ok[โฆ]` reason | re-reads the corrected tree; rules on your reason | the reason becomes **shared memory**, or comes back at higher severity |
| merge | signs one line naming the tree, the tiers, the vendors and the verdict | an **attestation**: what was checked, never "the code is correct" |
| start tomorrow's session, amnesiac | hands the reviewers what this repository already taught it | a review that does not re-raise what you settled last week |
---
## Use it
### 1. Try it on a laptop, with no service at all
```bash
npm ci
node ./src/index.ts review \
--branch feat/holds --into main \
--ticket "Release the hold when a capture declines"
```
Exit codes are the API, because the caller is usually a program:
| code | meaning |
|:--|:--|
| `0` | **passed** โ cleared by the full ladder: every tier ran, each a distinct vendor |
| `3` | **passed_thin_ladder** โ cleared, on a thinner ladder: a tier above the highest that ran never looked, or fewer vendors read the code than tiers ran |
| `1` | findings โ fix or justify, then run again |
| `70` | **did not run** โ never confuse with "found nothing" |
| `75` | quota exhausted โ also not a pass |
`0` and `3` are **both** successes, and `3` is the *ordinary* one here โ 287 of 341 clean
verdicts. A script treating `3` as failure blocks on nearly every clean review; one
treating it as `0` loses the distinction the ladder exists to make. Choose deliberately.
### 2. Run it for your whole team
**One deployment on one box serves every engineer.** That is the intended shape rather than
a scaling story bolted on afterwards: knowledge is per *repository* and shared by everybody
who works on it (D-18, D-19), so what your colleague's review established on Monday is what
your agent is handed on Thursday.
```bash
# on the company server, once
cd deploy
cp .env.example .env # three subscriptions by default, or one metered key
brew install opencode # opencode 2.x; the container runs this same version
opencode auth login # once per provider; the logins are pushed in by `make up`
make up # stages config, builds, starts, syncs credentials
# after re-logging a provider on the host
make sync-creds
# optional: a second ChatGPT subscription as `openai2` (D-157), renewed daily.
# The login is all it takes: it stages the provider and syncs the credential.
make login-openai2
make renew-daemon
# one line per engineer, per repository
make new NAME=alice GIT=git@github.com:acme/payments.git
make new NAME=bob GIT=git@github.com:acme/payments.git
make new NAME=carol GIT=git@github.com:acme/console.git
# keep the mirrors fresh, so nobody has to remember
make mirror REPO=payments
make mirror-daemon
```
Each `make new` prints **a revocable bearer token and the exact `.mcp.json` block to
paste** into that person's Claude Code, Cursor, or any other MCP client. Nothing else is
installed on their machine, and nothing is installed per project.
| property | how it works |
|:--|:--|
| **isolation** | a token reaches exactly one repository; one engineer cannot poll, submit to or attest another's review (D-78) |
| **sharing** | knowledge is per repository and shared by every session and teammate working on it |
| **capacity** | a claimed round starts immediately โ no worker queue โ and the service refuses politely at 128 open reviews |
| **revocation** | `make tokens` lists them by hash; `make revoke TOKEN=` turns one off. The secret is shown once, and revoking never needs it back |
| **perimeter** | `LORE_BIND` defaults to loopback. Put it on your tailnet, or bind it to the LAN deliberately โ on a LAN, **the tokens are the perimeter** |
| **cost** | flat subscriptions, one set for the whole team: 4,458 of this deployment's 4,551 calls billed nothing beyond them |
**lore never talks to a remote and holds no git credentials.** The mirror is fetched on the
host under your own agent, and the container only reads the directory it lands in. Keeping
it current is the *service's* job, not a person's (D-65): the client is an agent on another
machine with no shell here, and a stale mirror was once the single largest cause of failed
reviews.
### 3. The loop, exactly
Your agent drives this. lore ships its own instructions โ tool descriptions,
`lore://docs/*` resources and a `/lore:review` prompt โ because **the client is an agent,
so the docs are the interface**. What follows is what actually happens.
```
1. the engineer finishes a branch and pushes it
2. the agent calls review_start(branch, into, ticket) โ review_id, in under a second
3. T0 runs in a throwaway container: your own tsc / eslint / semgrep / ast-grep ~10s
4. T1 reads the diff one model, one vendor ~5-15 min
5. the agent calls review_poll(review_id) โ findings, each with a
claim, its evidence, and
the failure it predicts
6. the engineer or the agent fixes them โ or writes lore-ok[]: at the line
7. the agent hands the fixes back, either way round:
review_submit(review_id, diff, tree_hash) the usual path โ the work never
leaves the client's own history,
and lore applies it to a private
worktree without committing
review_start(..., pull_fresh: true) push first, no diff on the wire:
same review, re-pinned to the new tip
8. the ladder re-reads the CORRECTED tree, and rules on every justification
a rejected one comes back at higher severity
an accepted one becomes a fact this repository now knows
9. clean at T1 โ T2 and T3 run together, two more vendors, on the tree T1 cleared
10. all agree โ passed (exit 0) or passed_thin_ladder (exit 3)
11. the agent calls review_attest(review_id) โ one signed line
12. merge
```
**Step 7 is the one worth reading twice.** `review_submit` is the ordinary path and two
thirds of this deployment's rounds arrive through it: the fix stays in the client's own
history, lore applies it to a private worktree and never commits, and the reviewer keeps
one conversation per tier across the whole review rather than re-reading from cold.
`pull_fresh` is for when the branch is already pushed and composing a diff into a tool call
is the awkward part โ a whitespace-significant diff does not survive every client, which is
exactly why both exist.
Median: **4.1 rounds**, a round is minutes not seconds, and nothing blocks โ `review_start`
returns immediately and the agent goes back to work. What it must not do is walk away: a
review that nobody answers holds its findings and expires having concluded nothing, which
is why step 5 is a loop and why the channel below exists.
### 4. Watch it: the web board
`http://:7777/` is a live operator view โ server-sent events, no build step, no
JavaScript framework.
| surface | what it answers |
|:--|:--|
| **`/`** | every review in flight with its tier, round and age; which provider routes are in cool-off and until when; host load; model calls in flight; the running build's own commit |
| **`/status`** | the health report the heartbeat sends โ `ok`, and *why not* when it is false: stale mirrors, replica lag, uncollected high findings, host memory under the floor |
| **`/config.json`** | every setting with its value, its default, what it does and how to change it โ so "is metered spending on?" has an answer that is not a guess |
| **`/board.json`** | the same board as JSON, for your own dashboard |
| **`/healthz`** | unauthenticated liveness, for a probe |
A knowledge conflict โ two rules about the same thing that cannot both hold โ stops the
review and asks a person. **That decision is a button on this board**, and what it records
is deliberately modest: *"a person on the operator board (no credential, so no name
recorded)"*, plus whatever reason they typed. The page holds no credential, so which person
is not recoverable, and lore will not write down an attribution it cannot support. When you
need the decision attributed, `knowledge_resolve` over MCP does the same thing under a
token and records who. It is the one place lore deliberately refuses to guess.
### 5. Stop your agent sleeping: run the channel
A review takes tens of minutes and a client has no way to know when it finished, so agents
bridge the gap with a fixed `sleep`. Measured here: a median of three minutes of dead
waiting per finding, **339 hours in total** โ and no constant can be right, because a round
runs anywhere from twenty seconds to twenty-three minutes.
[`channel/lore-channel.ts`](channel/lore-channel.ts) is a
[Claude Code channel](https://code.claude.com/docs/en/channels): a small local process that
watches your reviews and pushes an event into your session the moment one needs you. The
polling still happens โ it just happens somewhere that costs no model turns.
```json
{
"mcpServers": {
"lore-channel": {
"command": "node",
"args": ["--experimental-strip-types", "/path/to/rev/channel/lore-channel.ts"]
}
}
}
```
**No url and no token**: it reads them from the `lore` entry already in that same file,
because that is how Claude Code reaches lore at all and a second copy is one more thing to
drift. Then start Claude Code with it enabled โ custom channels are not on the
research-preview allowlist, so during the preview this is the flag that loads it:
```bash
alias claude-lore='claude --dangerously-load-development-channels server:lore-channel'
```
There is no `settings.json` key for this, by design: a channel injects text into your
session, so Claude Code requires a per-session opt-in.
---
## Architecture
```mermaid
flowchart LR
C["MCP client
(an agent)"] -->|"review_start, poll,
submit, attest"| L["lore"]
L --> OC["opencode"] --> M["GLM-5.3 โ Kimi K3 โ GPT-5.6 Sol
three vendors, none of them the author"]
L --> S["scheduler
admission, quota-aware fallback"]
L --> W["repo cache
a worktree per review"]
L --> T0["T0 sandbox
no secrets ever;
network only for the install"]
L --> DB[("SQLite + Litestream")]
DB --> RP["local replica, then off-box"]
YOU["you: make mirror"] -->|"git"| W
```
`tsc` and `eslint` run in a throwaway container, copied from a read-only mount of the
reviewed tree โ they resolve their binaries out of the target's `node_modules`, so the
install runs, and an install runs lifecycle scripts. That container holds **no** credential,
no database and no signing key, and the *check* phases run with `--network none`. The
install phase does not: a registry needs the network, so a dependency's `postinstall` can
reach the internet from inside a review. That is the real boundary, and it is drawn where it
is deliberately โ the containment this buys is *nothing worth stealing is in there*, not
*nothing can get out*. lore does not execute a test suite at all (D-71): it reads
your tests and leaves running them to your CI.
---
## The rules it is built on
> ### A review that did not run is not a review that found nothing.
Every ambiguity resolves toward saying so loudly. Four reviews failing silently in a single
day is why this project has the shape it has.
- `failed`, `expired` and `fast_clean` are distinct states. **None of them is a pass.**
- An unparseable reply is a *failed* review โ one retry, then loud failure.
- Quota exhaustion never falls through to another tier.
- The attestation says **what was checked**, never that the code is correct.
- A knowledge conflict stops the review and asks a person โ and that block has an exit,
because a stop with no way to clear it is a trap, not a safeguard.
---
## What is **not** proven
Stated plainly, because a checklist that hides its gaps is the failure this tool exists to
catch.
- **Real quota exhaustion has never executed.** `passed_thin_ladder` has, 287 times โ this
section claimed the opposite for weeks, which is exactly why the state kept being reasoned
about as an exception.
- **`needs_human` has fired once, and it was wrong** โ two ADR sentences restating one
constraint, read as a contradiction. The lesson is the one worth repeating: a heuristic
that escalates to a person must fail quiet, not loud.
- **A fresh session has never driven a review to `passed` from the tool descriptions
alone.** Every review so far was driven by a primed session, so what is proven is the
service โ not the documentation, which [`spec/agent-docs.md`](spec/agent-docs.md) ยง1
insists *is* the interface.
- **Nothing bounds how many T0 sandboxes run at once.** Peak measured: 19 containers,
6 GiB each, on a 7.75 GiB Docker VM โ which is why 22% of one repository's T0 rounds were
OOM-killed before D-151/D-152. Honestly reported every time, and still lost coverage.
---
## Documents
| file | what it holds |
|:--|:--|
| [`SPEC.md`](SPEC.md) | purpose, workflow, and every decision `D-1`โฆ`D-161` |
| [`PLAN.md`](PLAN.md) | build order, and what each phase de-risked |
| [`spec/knowledge.md`](spec/knowledge.md) | the knowledge layer โ the product |
| [`spec/review-ladder.md`](spec/review-ladder.md) | tiers, findings, verdicts, invariants |
| [`spec/mcp-api.md`](spec/mcp-api.md) | MCP surface, provisioning, state machine |
| [`spec/agent-docs.md`](spec/agent-docs.md) | docs written for an agent, not a human |
| [`spec/deployment.md`](spec/deployment.md) | host constraints, throughput budget |
| [`spec/operations.md`](spec/operations.md) | alerting, the heartbeat deadman, spend |
| [`MEMO.md`](MEMO.md) | development diary โ the mistakes included |
| [`BUGS.md`](BUGS.md) | friction hit while *driving* it, not while reading it |
| [`research/`](research) | verified external facts, each dated |
**MIT** ยฉ Vany Serezhkin
*Built by an AI and a human who review each other's work.*