loci

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 writes ~/.loci/scopes.json"] graphs["loci graphs writes graphify-out/graph.json, one per scope"] index["loci index writes ~/.loci/episodes.json, scope_index.json, rankers/"] embed["loci embed writes ~/.loci/embeddings.npz"] calibrate["loci calibrate writes ~/.loci/calibration.json"] doctor["loci doctor 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 and every project routes on prose alone"| index index -->|"embed encodes episode chunks, and they do not exist until index has written the store"| embed embed -->|"calibrate fits a per-scope semantic floor from 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: , 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 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 , 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