loci

Scoped memory for coding agents. A router in front of two stores.

question ──▶ router ──▶ ┌── structure store   what calls what
             (no LLM)   └── episode store     what happened and why
                        └─▶ merged, cited answer   │
                            or ABSTAIN ────────────┘

Knowledge graphs hold structure but no prose, so they cannot answer why did the cookie get dropped. Verbatim-recall systems hold prose but no call graphs, so they cannot answer what calls run_agent_turn. Both make you name the namespace when you write.

loci decides the scope when you read. One question path serves "how does auth work here" and "have I solved this in any project" — only the size of the scope set changes.

The shape, in one picture

A street of independent shops. Each shop is one project — its own stock, its own books, nothing pooled in a shared warehouse. Each keeps two ledgers: what calls what, and what happened and why. They are read together or not at all.

Shops wear overlapping badges — yours, this client's, that vendor's, this monorepo's. A badge can cover shops at opposite ends of the street, which is why they are labels rather than a hierarchy.

You never walk the street yourself. You ask the dispatcher, who knows only which uncommon words are stocked where. They send you into at most three shops, or say nobody here carries that and name who might.

Each shop also hangs a signboard naming what it is — repository, package, command — and keeps a list of what it reaches for. Reading one against the other is how the street answers which of my shops buys from another, which no amount of asking the dispatcher ever could: that question is about the road between two shops, and the dispatcher only knows what is stocked inside them.

One thing the street still lacks: aisles inside a shop, so a word found in a test fixture does not count like the same word in shipped code.

The problem it solves

Put every project in one index and the largest one wins regardless of the question. Measured against a merged graph of ten real repositories:

That third row is the trap. Merged retrieval looks excellent whenever the answer happens to live in the largest corpus and collapses when it does not. It is the same failure in both directions, visible in only one.

Install

The distribution is loci-mem; the command, the import and the project are all loci. PyPI's loci is an unrelated outlier-detection package abandoned in 2018 — the same split as python-dateutil installing as dateutil.

pipx install loci-mem                 # routing + lexical search, one dependency
pipx install 'loci-mem[all]'          # + graphify, local embeddings, MCP server

The base install pulls numpy, and nothing else. Routing, BM25 and the char-gram matrix are a compiled Rust extension as of 0.6.0, so scikit-learn (and scipy behind it), rank-bm25 and joblib are gone. No torch, no vector database, no model download unless you ask for one.

Wheels are published for macOS, Linux and Windows; installing from the sdist builds from source and needs a Rust toolchain (1.75+).

Quickstart

pipx install 'loci-mem[all]'
loci setup             # scan, graph, index, embed, calibrate -- one pass
loci ask "why was the session cookie dropped on localhost?"

setup asks only what it cannot decide for you: which directories hold your projects, whether to register the repositories it found that are not yours, and whether to spend a one-time model download on semantic search. It ends by running doctor, so whatever it could not cover is the last thing you read rather than something you discover from a bad answer a week later.

Every prompt takes its default when stdin is not a terminal, so it is safe to run unattended in a container or under an agent. -y does the same from a terminal, and --no-graphs / --no-embed / --no-calibrate decide individual steps up front.

The same thing by hand. The order is a dependency chain, not a preference: graphs are what the index is built from, the index writes the chunks embed encodes, and calibrate fits its semantic floor from those vectors.

loci scan ~/code       # register every git repo it finds, one scope each
loci graphs            # optional: add code symbols (free, no model calls)
loci index             # build the routing index + episode store
loci embed             # optional: local vectors for semantic recall
loci calibrate         # optional: fit routing thresholds to your corpus
loci doctor            # what is missing, and the command that fixes it

loci ask "which projects use wrangler and D1?"
loci eval              # measure routing accuracy on YOUR corpus

Each step writes what the next one reads, which is what makes the order fixed rather than preferred:

flowchart TD
    scan["loci scan ~/code<br/>writes ~/.loci/scopes.json"]
    graphs["loci graphs<br/>writes graphify-out/graph.json, one per scope"]
    index["loci index<br/>writes ~/.loci/episodes.json, scope_index.json, rankers/"]
    embed["loci embed<br/>writes ~/.loci/embeddings.npz"]
    calibrate["loci calibrate<br/>writes ~/.loci/calibration.json"]
    doctor["loci doctor<br/>writes nothing at all"]

    scan -->|"there is nothing to graph or index until a scope exists"| graphs
    graphs -->|"the index is built FROM graph.json; index first<br/>and every project routes on prose alone"| index
    index -->|"embed encodes episode chunks, and they do not<br/>exist until index has written the store"| embed
    embed -->|"calibrate fits a per-scope semantic floor from<br/>those vectors; with none it keeps a default"| calibrate
    calibrate -->|"and then reports whatever is still missing"| doctor

Running it out of order does not fail loudly. It produces an install that works and quietly retrieves worse, which is the failure doctor exists to name.

scan registers one scope per git repository. It also reads who owns each repository out of git, prints who owns what, and asks before registering the ones that are not yours; that prompt takes its default like every other, which is to register everything.

A monorepo can become one scope per package instead. --split on loci scan or loci setup takes anything carrying package.json, pyproject.toml, Cargo.toml or go.mod one level down; a repo-local .loci.json names the rest and is honoured with or without the flag. --split is off by default, and the reason is measured rather than cautious: a new scope's aliases include its bare directory name, and an alias outranks your working directory (6.0 to 4.0). On the development corpus, splitting a repository holding glasses/ sent eight hand-written questions about a different project to Delroy/glasses — seven of them had routed correctly before the split, and six of the eight reverted when the alias boost was zeroed. A Jekyll _site/ build directory became a scope of its own on the same run. A .loci.json you wrote does not have that problem: you named those sub-projects deliberately, so you can see what they are called.

ask uses your working directory by default, and should. Questions that name no project — "how is this deployed?", "how do I run the tests?" — route correctly 100% of the time with cwd. Without it they are unanswerable, and loci abstains on all of them rather than guessing. cwd is not a tiebreaker signal here, it is the primary one.

Concepts

Scope. One project, one namespace. A registered git repository, one package of a monorepo (under --split, or named in .loci.json), or anything you add explicitly. Scopes are never merged.

Group. An overlapping label on a scope: me and vendor:<org>, read from git provenance; client:acme and anything else you assert by hand; and a monorepo's own id, carried by every package inside it and by the monorepo itself, so --group <monorepo> reaches the code no package claimed. A scope can be in several, and the scope set stays flat: grouping never merges scopes or nests one inside another.

What a group does to a question is its mode, and the mode answers two different questions. Reached through your working directory, explicit does nothing, soft (the default) multiplies every outside scope's evidence base by 0.5, and hard confines routing to members and abstains when the best answer is outside. Named on the command line with --group X, all three modes confine to X's members — the mode decides only what happens when the best answer is outside them: hard abstains and says so, soft and explicit answer with the best member anyway. Membership lives in the scope registry, mode in groups.json, so a re-scan — which rewrites the registry wholesale — cannot discard policy. Measured: hard anchored on cwd fires on questions that name an outside project (12 of 12) and not on questions carrying only its vocabulary (0 of 24), so in practice --group and project names drive it rather than where you are standing.

Structure store. What calls what — symbols, files, references, traversals with file:line citations. Supplied by graphify through an adapter.

Episode store. What happened and why — README and docs, git commit bodies, docstrings and comment blocks, and any notes you point it at. Stored verbatim, chunked on heading boundaries, redacted before it is written.

Router. Decides which scopes a question belongs to, deterministically, with no model call. Signals in order of weight: an explicit project name (6.0), the working directory (4.0), vocabulary evidence (measured 0.1–1.5), recency (0.15). Weight is not usefulness — cwd is the signal that carries most real questions, because most real questions name no project at all.

Abstention. A first-class outcome. ABSTAIN means ask the user, not pick the biggest. Both layers can refuse.

An abstention that only says no leaves the asking to you, so it carries the shortlist it refused to choose between — each project, and the terms that put it there:

loci ask "how is caching handled?"

ABSTAINED - not enough of the question exists in any project.
  candidates: Delroy (handled, caching), odysseus (handled, caching), tensor-serve (caching)
  re-run with --scope <name>, or from inside the project directory.

A scope earns its place by holding a term at most half the corpus holds. Holding one is not enough: change, handled and work sit in nearly every project, so matching them is a coincidence rather than a claim. Measured on the development corpus, that is the difference between naming three projects and listing all fourteen in score order, which is the registry rather than a shortlist.

When nothing clears that bar there is no shortlist to print, and saying so is the answer — the question's subject is not indexed anywhere, and choosing a scope would only relocate the guess:

loci ask "xyzzy plugh frotz quuz"

ABSTAINED - not enough of the question exists in any project.
  no project holds a distinctive term from this question -- `loci doctor` shows what is not indexed.

Architecture

The query path

The diagram at the top of this file is the elevator version. In full:

loci ask "why was the session cookie dropped on localhost?"
  │
  │   --scope NAME jumps straight past routing to the fan-out, and drops the
  │   episode gate with it: that gate exists to stop an answer arriving from
  │   the wrong scope, and you have just named the right one.
  ▼
confinement                                                       groups.py
  │   reads the registry and groups.json. Never the index, never a model.
  │     --group X  ─▶  eligible = members of X, in ALL THREE modes
  │     else cwd   ─▶  the strictest group of the scope you are standing in
  ▼
route                                                             router.py
  │   reads scope_index.json: token ─▶ {scope: node_df}. One dict lookup per
  │   query token. Deterministic, sub-millisecond, no model call.
  │
  ├──▶ ABSTAIN — deictic, no_evidence or out_of_group. Names the cause, lists
  │             the scopes with a claim on the question and what each one
  │             holds, names the flag that fixes it, and queries nothing.
  │             An outcome, not an error.
  ▼
selected scopes, at most 3        one thread each; neither store is ever
  │                               queried across a scope boundary
  ├─── scope ─── scope ─── scope
  │      │
  │      │  expand the question against THIS scope's postings — a dict
  │      │  lookup, so a token the scope does not have cannot be invented —
  │      │  then append the tokens of its nearest embedded symbol labels
  │      │
  │      ├─ structure store   graphify query --graph <this scope's graph>
  │      │                    what calls what, with file:line citations
  │      │
  │      └─ episode store     BM25 + char 3–5 gram + embeddings, fused
  │                           gated: lexically grounded OR semantically
  │                           confident, so it can return nothing, and does
  ▼
merged, cited answer — one block per scope, and `no evidence in this scope`
wherever both of a scope's stores came back empty

Both stages refuse independently: the router can decline to pick a scope at all, and a scope it did pick can still hand back nothing.

The routing decision

Everything above the fan-out is one function. It scores every scope in the corpus, then asks three refusal questions in a fixed order. An alias or cwd signal skips the last two, but not the first.

flowchart TD
    Q["question, plus cwd and --group when given"]
    CONF{"which group confines this question?"}
    E1["eligible = members of X<br/>strict only when that group's mode is hard"]
    E2["eligible = members<br/>strict"]
    E3["demoted = every scope outside the group"]
    E4["nothing confined, nothing demoted"]
    BASE["evidence base, for EVERY scope in the corpus<br/>sum(scope-idf x prominence) / query tokens / size^0.15"]
    PEN["demoted? base x 0.5<br/>here, before the boosts, so it cannot invert one"]
    BOOST["+ ALIAS 6.0, the question names the project<br/>+ CWD 4.0, DEEPEST containing scope only<br/>+ RECENCY 0.15, a tiebreak and no more"]
    TOPS["top = best ELIGIBLE scope<br/>top_all = best scope in the whole corpus"]
    OOG{"strict, and top_all is outside the group,<br/>and top_all would itself have been routable?"}
    A1(["ABSTAIN out_of_group<br/>the best answer is outside the group"])
    FORCED{"forced?<br/>top carries an alias hit or the cwd signal"}
    ENUM{"enumerative?<br/>which projects / what repos / any of my / where else / have I ever"}
    DEIX{"deictic?<br/>this / these / it / its / here / the project / the app / ..."}
    A2(["ABSTAIN deictic<br/>the question points at a subject it never names"])
    EV{"enough evidence?<br/>ANY ONE of the three is enough"}
    A3(["ABSTAIN no_evidence<br/>too little of the question exists in any project"])
    SEL{"did the question ask for a SET?"}
    SELECT["keep every eligible scope scoring at or above 0.85 x top,<br/>cap at 3, then force in every concentrated-token holder"]
    SETSEL["keep every eligible scope clearing 0.8 x the floor ON ITS OWN,<br/>in rank order, cap at 8 -- no ratio cutoff at all"]
    OUT(["selected scopes"])

    Q --> CONF
    CONF -->|"--group X, any mode"| E1
    CONF -->|"cwd scope's strictest group is hard"| E2
    CONF -->|"cwd scope's strictest group is soft"| E3
    CONF -->|"explicit, or no group at all"| E4
    E1 --> BASE
    E2 --> BASE
    E3 --> BASE
    E4 --> BASE
    BASE --> PEN
    PEN --> BOOST
    BOOST --> TOPS
    TOPS --> OOG
    OOG -->|yes| A1
    OOG -->|no| FORCED
    FORCED -->|yes| SEL
    FORCED -->|no| ENUM
    ENUM -->|"yes, and it is not picking ONE scope"| EV
    ENUM -->|no| DEIX
    DEIX -->|yes| A2
    DEIX -->|no| EV
    EV -->|"summed token evidence at or above the floor<br/>(7.6 shipped, refitted by loci calibrate)"| SEL
    EV -->|"at least 4 matched tokens"| SEL
    EV -->|"an eligible scope holds a CONCENTRATED token:<br/>held by at most 2 scopes, prominent inside them"| SEL
    EV -->|"none of the three"| A3
    SEL -->|no| SELECT
    SEL -->|yes| SETSEL
    SELECT --> OUT
    SETSEL --> OUT

Four things in that shape are load-bearing and none of them are obvious.

forced is an escape, not a signal. An alias hit or a cwd hit contributes nothing to either evidence count, so a scope winning purely on 6.0 or 4.0 reads as zero evidence to the gates below. It skips both of them instead: deixis is only a problem when nothing else has identified the subject, so a question that says "it" and names a project is unaffected.

out_of_group is judged against the whole corpus, not the group. It fires only when the corpus-wide winner is outside the group and would itself have routed. Without that second test it swallowed the other two reasons entirely — on a question matching no vocabulary, every scope scores near zero and the winner is whoever took the 0.15 recency tiebreak.

The three evidence gates are OR'd because they fail on different question shapes. A short question about a rare symbol has high evidence and a low count; a long question about a familiar subsystem has the reverse. Requiring all three abstains on both.

Enumeration inverts every other gate, so it gets its own selection rule. Every gate above asks is there enough evidence for ONE scope, and a question about something several projects share splits its evidence across them by construction — so the more projects genuinely share a term, the less likely all of them come back. Measured, which of my projects use Cloudflare workers or D1? returned one owner of two: 2.098 against 1.0867, where the 0.85 ratio needed 1.783.

The ratio is the part that inverts. It measures distance from the top scope, and the top scope of an enumeration is merely whichever owner says the term most often. Set mode drops it and asks each scope the same routability question in turn, against a floor discounted to 0.8 — because a member of a set legitimately carries less evidence than a lone answer.

Enumeration is grammatical, like deixis, so it is detected the same way: a closed class of markers, no threshold. It also outranks deixis. "where else does this pattern appear?" points at its subject and asks across the corpus; the deixis rule exists because a pointing question gives no way to pick one scope, and an enumerative question is not picking one.

The frame nouns are stripped from the query, which is the deixis insight one level down — projects is scaffolding, not vocabulary. It is not a cosmetic step: in the development corpus projects is held by exactly two scopes, so it scored as discriminative evidence for those two and dragged both into every "which of my projects" answer. Stripping it moved negative-family abstention from 66.7% to 88.9%.

loci ask "which of my projects use Cloudflare workers or D1?"
# ENUMERATED -> 3M1RY33T.github.io, urthreads

Scopes and groups

Groups are overlapping labels over a flat scope set. There is no tree anywhere, and nothing is ever merged.

      scope                        the groups it carries
      ───────────────────────────  ──────────────────────────────────────
      delroy           monorepo    me    delroy
      delroy/glasses   sub-scope   me    delroy
      delroy/client    sub-scope   me    delroy   client:acme
      acme-api         repo        me             client:acme
      vendorlib        repo                                     vendor:someorg

      me, vendor:someorg   read from git provenance by `scan` or `groups infer`
      delroy               computed by `scan` from the filesystem: a repository
                           that splits gives its own id to every sub-project
                           inside it, and to itself
      client:acme          asserted by hand, with `loci group add`

Five scopes, four groups. delroy/glasses is not stored inside delroy; it carries the label delroy exactly as it carries me. client:acme spans a monorepo sub-project and an unrelated repository, which a hierarchy could not express at all. The two sub-scopes exist only because that repository declared them in .loci.json, or was scanned with --split; without either, delroy is one scope and the containment group does not exist. A parent excludes its sub-scopes' subtrees from its own collection, so no file is counted twice and neither vocabulary is inflated with the other's tokens.

What a group does to a question is its mode, and the mode answers two different questions depending on how the group was reached:

                    reached through your cwd        named with --group X
  ────────────────  ─────────────────────────────   ────────────────────────
  explicit          nothing                         confines to X's members
  soft (default)    every outside scope's           confines to X's members
                    evidence base × 0.5
  hard              confines to members, and        confines to X's members,
                    abstains when the best          and abstains when the
                    answer is outside               best answer is outside

The right-hand column is the counter-intuitive half, so it is measured rather than asserted. On a three-scope fixture — alpha and beta in group team, vend outside it — one question, four policies:

loci route "how does the gizmo parser emitter handle sprocket calibration"

  unconfined                  -> vend, alpha
  --group team   explicit     -> alpha
  --group team   soft         -> alpha
  --group team   hard         -> ABSTAIN (out_of_group); candidates: alpha (sprocket), beta (calibration)

All three modes dropped vend, the scope that won unconfined. --group is you asserting the answer is in here; the mode decides only what happens when it is not. The shortlist under hard is wider than the selection above it on purpose: it is what the abstention refused to choose between, not what it would have answered from — beta is on it because calibration is a term only beta holds, and off the answer because that is all it has.

Reached through cwd instead, soft demotes and does not confine. The same question asked from inside alpha with no --group at all returns alpha, vend: vend scores 3.39 against alpha's 6.18 — far outside the 0.85 widening band — and comes back regardless, because it is the sole holder of gizmo, parser and emitter, and the concentrated tier forces every holder of a shared-or-rare term into the answer. Demoted is not excluded.

Commands

loci index reuses any scope whose files and git HEAD are unchanged, so reindexing is cheap enough to run from a commit hook.

Keeping it current

Nothing updates itself. There is no watcher, no daemon and no installed git hook: every refresh is a command you run.

loci update            # the whole chain, for everything registered

It is setup for an install that already exists, so it prompts for nothing and opts you into nothing new: embeddings are re-encoded because you already had embeddings, and the thresholds are refitted because they were already fitted. It also rescans wherever your last scan was pointed, so a repository created since then is registered rather than missed — that is what the roots key in scopes.json is for, and loci update ~/work adds another.

The one thing it rebuilds unconditionally is the structure graph, because that is the only staleness in loci that is otherwise silent. loci graphs builds a graph that is missing and skips every scope that already has one, so a project whose code moved keeps routing on the symbols it had the day it was registered. Everything else announces itself: index re-parses a scope whose fingerprint moved, and doctor names embeddings that no longer line up with the store. Rebuilding all of them is affordable because graphify does not rewrite a graph whose code did not change — measured, a second consecutive run left graph.json byte-identical with its mtime untouched, and loci's own fingerprint reads that mtime, so refreshing the graphs does not force a reindex of the scopes that stood still.

By hand, the same thing, and the order is the dependency chain again:

loci graphs --all      # `loci graphs` alone would skip every existing graph
loci index             # unchanged scopes are reused, not re-parsed
loci embed             # a full re-encode; skipping it silently disables
                       # semantic search for every scope whose chunk count moved
loci calibrate         # the floor measures shared vocabulary, which just changed

Two things update cannot do for you. A project deleted from disk stays in the registry — it is reported, not removed, because the entry carries groups and aliases you set by hand and the directory may only be unmounted. And a long-running loci mcp server holds its fitted rankers and vectors in memory from boot, so restart it after a rebuild.

From inside an AI client

loci skill install          # -> ~/.claude/skills/loci/SKILL.md

That installs one skill with subcommands, not eight commands cluttering the listing:

/loci "<question>"          ask memory; routes on your working directory
/loci update                refresh everything registered
/loci doctor                coverage gaps per project, and the fix for each
/loci scopes                what is registered, and the group each is in
/loci route "<question>"    where a question routes, and why it abstained
/loci add <path>            register one project
/loci setup [dirs…]         first run
/loci <anything else>       passed through to the `loci` CLI verbatim

The passthrough rule is what keeps it short: index, embed, graphs, calibrate, eval and groups all work from the client without being documented twice, so the skill cannot drift from flags it never mentions. What it does mention is checked — a test parses the Usage block and fails if any command in it stops existing.

The skill ships inside the package rather than in a dotfiles repo, because it documents flags and abstention reasons that the CLI can change; loci skill install after an upgrade is the whole update path. --print writes it to stdout for a client that does not read ~/.claude/skills.

Two things it teaches an agent that are not obvious from the CLI. Run it from the project root — cwd is the primary routing signal, so a question asked from the wrong directory routes worse than one asked from none. And ABSTAINED is an answer: the reason names what to do next, the shortlist under it names the projects that could plausibly own the question and the terms that put them there, and an agent that rephrases and retries instead is burning turns on a decision that was about vocabulary rather than wording. An abstention carrying no shortlist at all is the one case where rephrasing cannot help either — nothing in the corpus holds a distinctive term from the question.

MCP

loci mcp speaks stdio, so a client launches it — you do not run it yourself.

Claude Code:

claude mcp add loci --scope user -- loci mcp
claude mcp list                       # loci: ... - ✔ Connected

Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "loci": { "command": "loci", "args": ["mcp"] }
  }
}

Use an absolute path for command if loci lives in a version-managed environment — pyenv shims and pipx venvs resolve against a shell your client does not have. which loci from a working shell, then paste the target.

Three tools — ask, scopes, doctor — not several dozen. Agents are the primary consumer, and a wide tool surface pushes orchestration onto the model and burns a turn per hop.

Without this the server is dead weight: it is installed by the mcp extra and reachable by nothing, and every question an agent asks goes through the CLI instead — paying full process and model startup per question, and never touching the boot-time warm-up the server exists to provide.

Pass cwd to ask whenever the client knows it, and group to narrow the same way --group does on the command line. The server loads the embedding model and the largest scopes' rankers at boot, so the first tool call an agent makes is fast rather than paying ~4.4s of startup while the user waits.

Measure it on your own corpus

Every accuracy figure below was fitted and measured against one person's repositories — ten when the constants were fitted, fourteen now. That is a claim you would otherwise have to take on trust, and the drift between those two numbers cost the behavior family 57 points.

loci eval            # a few seconds, no labelling, no setup
loci eval --misses   # and what it got wrong

It only asks questions whose correct answer is known by construction:

10 scopes | random guessing would score 10.0%

family                  n  correct  scopes  what it measures
deictic + cwd          80  100.0%       -   should route to the scope you are in
deictic, no cwd         8  100.0%       -   should abstain; nothing says which project
unanswerable            6  100.0%       -   should abstain; no corpus can answer these
signature              20  100.0%     1.0   are your scopes distinguishable from each other?

The signature family is an upper bound — it asks each scope about its own rarest words, so a real question phrased in shared vocabulary does worse. A low score there is a fact about your projects, not necessarily a bug to tune away.

Calibration

Routing gates on three independent signals, and any one passing is enough: one exceptionally discriminative token, enough summed token evidence, or enough matched tokens. They fail on different question shapes — a short question about a rare symbol has high evidence and a low count, a long question about a familiar subsystem has the reverse — so requiring all three abstains on both.

The evidence floor is the one that depends on your corpus, because it depends on how much vocabulary your projects share. loci calibrate fits it from the same auto-labelled questions, and reports whether the bands separate at all:

evidence floor      7.17
fitted from         149 routable + 14 unroutable questions, none hand-labelled
classifies          84.0% of its own samples correctly

! The bands OVERLAP -- some questions that should route score no higher than
  questions that should not, so no threshold separates them cleanly.

An overlap warning is information about your projects, not a defect: they share enough vocabulary that evidence alone cannot always tell them apart, and cwd or --scope should carry more of the weight.

What it reads, and what it writes

Everything stays on your machine. No LLM in the query path; routing is a dict lookup per token. Embeddings, when enabled, run locally.

Collected per scope: README*, docs/**/*.md, source files (for docstrings and comment blocks), and git log. Add anything else with loci add --glob, including absolute paths outside the repo.

The only configuration loci reads from inside a repository is .loci.json, and only if you write it. It names sub-projects at any depth, and unlike --split it is honoured on every scan:

{"scopes": [{"path": "client"}, {"path": "services/api"}]}

Paths are relative to the repository root and may not escape it. A malformed file is ignored — a scan that aborts on a stray comma is worse than one that misses a declaration. Nothing writes this file; you do.

The only thing loci ever puts inside a repository is graphify-out/graph.json. Two commands write it: loci graphs, which does nothing else, and loci setup, which offers it at step 2 of 5 and takes yes as the default — including with no terminal, where every prompt takes its default. loci setup --no-graphs skips it, and every other command reads.

So inside a repository exactly two files matter, and they point in opposite directions:

<repo>/graphify-out/graph.json    loci writes it, on request. You never do.
<repo>/.loci.json                 you write it. loci never does.

Everything else goes to ~/.loci (or $LOCI_HOME). One directory, not one per project: routing is a cross-scope decision, so answering which project is this about needs every scope's vocabulary in the same lookup, and N per-project indexes would turn the cheap question into the expensive one.

~/.loci/                    what it holds               written by

├── scopes.json             the scope registry, and     scan, add, group,
│                           the roots it was scanned    update
│                           from, for `loci update`
├── groups.json             group policy: default mode  group set
│                           and any mode set per group
├── scope_index.json        routing index, the token    index
│                           -> {scope: node_df} map
├── episodes.json           the episode store: chunks   index
│                           verbatim, already redacted
├── rankers/<scope>.lex     fitted BM25 + char-gram     index
├── embeddings.npz          chunk and symbol vectors    embed
├── .symbols-<scope>.json   symbol labels, in the       embed
│                           order embeddings.npz has
├── calibration.json        the fitted evidence floor   calibrate
│                           + a semantic floor / scope
└── .index.lock             advisory build locks, so    index, embed
    .embed.lock             two builds cannot inter-
                            leave their writes

scopes.json is machine-managed and rewritten wholesale by every scan; groups.json is yours and must survive one. That is why membership lives in the registry and mode lives in the policy, and why they are two files.

Redaction

Everything collected passes through loci.redact before it is written, so a credential committed by accident never reaches the episode store, the vectors or the rankers.

Files that exist to hold secrets are never opened — .env*, .dev.vars, *.pem, *.key, id_rsa, secrets.*, credentials.json. Then every chunk is scanned for AWS keys, GitHub/Slack/Google/Stripe/OpenAI/Anthropic tokens, private-key blocks, JWTs, user:password@host connection strings, bearer tokens, and long opaque values assigned to a secret-shaped name.

Chunks are built through a single constructor, so a new collection path cannot forget to redact. A secret assignment keeps its key name and loses only its value, so the chunk still reads sensibly and still routes:

client_secret = "aVeryLong..."   ->   client_secret = "[REDACTED:secret-assignment]"

loci index reports what it removed, per scope and by kind — silent redaction is indistinguishable from none. Deliberately biased toward over-redaction: a false positive costs one chunk a little retrieval quality, a false negative copies a live credential into a plaintext file and a vector index.

Design rules, and the measurements behind them

Each of these is something a reasonable implementation gets wrong.

1. Never merge scopes into one index. See the table at the top: 2% and 18% on-topic against a merged graph.

2. Abstention is a feature at both layers. Measured 10/10 on probes including deliberate nonsense. Every RAG tool confidently answers "what is the airspeed velocity of an unladen swallow"; this one says it does not know.

3. Margin and ratio tests do not measure confidence. Both were tried and both invert on real data. "How do I fix this bug?" produces routing margin 0.94 while a correctly-routed question produces 0.18. Nonsense scored 0.608 against a large scope with a higher top-to-p90 ratio than a genuine question against a small one. What separates them is whether the question's words exist in the corpus at all.

4. A matched-token count is not evidence. Compared against auto-labelled questions, count does not separate routable from unroutable at all — it inverts. Summed token evidence does. Count is kept only as one of three OR'd gates.

5. Deixis is grammatical, so detect it grammatically. A question that points at its subject ("this project", "the app", "it") cannot be routed by vocabulary, because the words that would identify the subject are exactly the ones it declines to say. No lexical statistic rescues this: per-token evidence for start (2.51) and services (2.56) is indistinguishable from real evidence like session (2.53). A closed class of markers took abstention from 37.5% to 100%.

6. Normalize for scope size, twice. With one scope 67× larger, ordinary English words appear in exactly one scope and score as maximally discriminative for it.

7. Docstrings are excellent retrieval material and poor routing material. They are high-volume generic English — "returns", "the value", "default", "configuration" — and folding them into routing halved accuracy on both a symbol-indexed and a prose-only corpus.

8. Coverage is the binding constraint, not ranking. This surfaced in every experiment. Running a free AST-only index over three un-indexed repos moved routing 69.6% → 82.6% while adding two more scopes to compete against. Hence doctor as a first-class command: an empty answer with a reason beats a confident answer from the wrong project.

Ranking

Episode search fuses three signals, renormalizing over whichever produced one:

The lexical pair recovers questions the structure graph cannot see at all. The embedding ranker covers what neither lexical ranker can: a question and its answer that share no vocabulary.

Adding embeddings destroyed abstention — every chunk gets a nonzero score, so an absolute floor stops firing. The fix is a two-tier gate: a hit must be lexically grounded or semantically confident, because a lexical gate alone rejects exactly what embeddings were added for.

Cross-encoder reranking is available via --rerank and off by default: it measured 2/6 → 3/6 precision@1 at ~96ms/query with two small regressions, on six cases whose labels are themselves arguable.

Performance

loci index          15s full · 3.9s when nothing changed
loci ask            1.0s one-shot with --fast · ~5s with semantic ranking
MCP server          6s at boot, then 0.2-0.3s per tool call
routing             sub-millisecond, and flat from 25 to 100 scopes

Three things make that work, each a measured bottleneck first:

Traversal prunes, it does not filter. Path.glob("**/*.py") descends into node_modules, .venv and Pods in full — 32.9s to enumerate one repo. It improves the index as well as the clock: one project was 66% vendored third-party source before pruning.

Lexical rankers are fitted at index time. Char 3–5 gram TF-IDF over a large scope costs ~1.5s, and an in-process cache never survives a CLI or MCP invocation.

The embedding model is loaded at MCP boot. ~2.3s of imports plus model construction is process startup, not work. --fast skips it for one-shot CLI questions.

Scale

Scope count is not the limit; vocabulary overlap is. The failure gets safer as scope count rises — more scopes sharing a term means less evidence for any one, and the gate fires. A small corpus of highly similar projects is the dangerous configuration.

Durability

Writes go through a temp file and os.replace, so a reader never sees a half-written index. Path.write_text truncates before it fills: measured on an 8MB store, 11 torn reads in a few seconds of concurrent access, and 0 after the change. An MCP server reading while loci index runs sat squarely in that window.

loci index and loci embed hold an advisory lock, so two builds refuse to interleave rather than producing an index and a store that disagree. Locks left by a dead process are detected and broken.

The store is written before the index, because the index is what readers gate on: a crash between the two leaves a stale index pointing into a store that is a superset of it, never an index promising chunks that do not exist.

Extending

Two contracts in backends/base.py:

class StructureBackend(Protocol):
    def sources(self, scope) -> list[dict]: ...
    def vocabulary(self, scope) -> Counter: ...      # feeds the router
    def query(self, scope, query, *, budget, dfs) -> list[StructureHit]: ...

class EpisodeBackend(Protocol):
    def collect(self, scope) -> list[Chunk]: ...      # verbatim, redacted
    def search(self, question, chunks, scope_id, *, k, rerank) -> list[EpisodeHit]: ...

Nothing above backends/ knows which implementation is in use. Swapping graphify for tree-sitter, SCIP or an LSP index means writing one adapter, not editing the router. search must be able to return an empty list — a store that always finds something cannot be trusted when it does.

Why it is not a graphify fork

loci depends on graphify through one adapter that reads its graph.json data contract and shells out to graphify query --graph. Forking would mean inheriting a 767KB extractor and ~18 tree-sitter grammars to change code that never needed changing. The scoping gap that motivated loci — graphify tags merged-graph nodes with a repo attribute and exposes no way to filter on it — is solved above graphify by keeping one graph per scope. Both projects are MIT, so forking stays available; it just is not necessary.

Status

Alpha, and the numbers deserve their caveats.

Measured on a 173-item set over 14 scopes. 112 of those items are generated from a fixed taxonomy applied to every scope, so that portion is unbiased by construction. The remaining 61 were hand-authored by the same person who built the router; each carries a contamination field recording what the author had seen, and uncontaminated results are always reported separately.

The eval corpus is not in this repository. The harness reads fourteen real projects, six of them private or never pushed anywhere, and its records name them at file:line — so evals/ and the evals/RESULTS.md cited throughout these sources are kept locally and are not published here or in the sdist. What ships instead is loci eval, which generates its own questions from whatever corpus you have registered; that is the number worth trusting about your own setup, and it is the one this README asks you to run.

Known limits:

• The behavior family fell from 85.7% to 28.6% when the corpus grew from 10 scopes to 14, and the cause is not a threshold — sweeping SIZE_PRIOR across 0.0–0.5 on the new corpus never beats the shipped 0.15. Two scopes now hold 5,995 and 4,680 distinct tokens against urthreads' 427, and a scope whose vocabulary approaches the corpus's own matches every question on ordinary English. Five alternative scoring families were swept against it and none beat the plain sum; the one strict improvement ships inert as CORROBORATION_WEIGHT, because a single item on a single corpus is not evidence. This is the largest open problem in the router.
• The synthetic test bed cannot reproduce that failure: CorpusSpec.size_skew varies file volume, not vocabulary breadth, so all thirteen shapes read 100% at every value of the constant that would fix it. Closing that is a test-bed change and it blocks the router change.
• Two eval golds were found stale during this release, one of which was marking a correct three-scope answer down as a precision failure. Corpus drift turns right answers into recorded misses and nothing in the harness notices.
• The structure store surfaces the answering symbol in 4 of 7 probes.
• Large prose-only scopes over-attract; a scope with thousands of chunks and no code graph absorbs questions belonging elsewhere.
• CI now runs the suite on Linux, Windows and macOS across Python 3.10–3.13. Standing it up found a third platform bug that reading had missed: Windows refuses os.replace against a destination another handle holds open, so every durable write failed there while both other platforms stayed green. Reading finds bugs — it did not find that one. No user has run loci on Windows yet.
• loci eval and loci calibrate share question families, so a perfect eval score immediately after calibrating is partly circular.

The most useful thing anyone can do is run loci eval on a corpus that is not mine and say what it reports.

License

MIT.