Crate semlith 

semlith — a local semantic cache for AI agents.

Point it at files, get back a store that answers “what part of my corpus is relevant to this question?” in milliseconds, without shipping anything off the machine and without an agent burning tokens reading whole files.

Two pieces of state live side by side in the store directory:

• the vectors — a turbovec TurboQuant index holding only quantized vectors keyed by chunk id. A store created by 0.7.0 keeps them as a directory of shards under index/; every store written before it keeps the single index.tv it already has. See index.
• store.db — SQLite holding the chunk text, its file, and its line span.

A search quantizes the query, gets ids back from the index, then resolves them to text with one SQLite lookup each.

Modules

add

Fetching one URL into a store.

agentfiles

The three things semlith setup writes for an agent beyond its MCP registration: the Agent Skill, the steering hook, and the rule block.

brief

One call instead of four.

chunk

Turning a file on disk into embeddable chunks of text.

clientfile

Reading — and, when asked, writing — the configuration files agent clients own.

clients

The client setup stanzas, read out of docs/clients.md at compile time.

clock

Local time, with the offset that says which local.

daemon

semlith start — one process that owns every store.

doctor

What this machine’s semlith install looks like, and what can be repaired.

embed

Which embedding model a store uses, and how to load it.

filter

Narrowing a search to part of the corpus.

fleet

Several stores, one query.

graph

Structure half of the store: symbols, and the edges between them.

home

The store home, and how a command decides which store it means.

hook

The steering hook: one line, at the moment an agent is about to read a file semlith already holds.

http

A synchronous HTTP/1.1 server, just large enough to serve the portal.

image

Image support: what counts as an image, and the two CLIP models that make one comparable with a sentence.

index

The vector side of a store: read from disk only when something needs it, and in pieces small enough to put down again.

ledger

Writing the retrieval ledger, from wherever a retrieval happened.

lock

One writer at a time per store.

mcp

A stdio MCP server, so an agent can query and maintain the store as tool calls.

pattern

semlith pattern: a tree-sitter structural query over the indexed files of one language.

portal

The portal, compiled into the binary.

proxy

semlith mcp forwarding to a running semlith start.

replay

What an agent did after semlith answered.

report

Five reports, generated from this machine’s ledger, index and graph.

rerank

The rescoring stage: a cross-encoder over the head of the fused list.

routes

The daemon’s routes: thin adapters over what the CLI and the MCP tools already do.

service

The daemon as a login service, so a client never finds nothing. The daemon as a login service, so semlith is answering before a client asks.

setup

semlith setup: the far half of the install one-liner.

store

SQLite side of the store: file bookkeeping and chunk payloads.

system

One reading of the machine, and the defaults derived from it.

upgrade

semlith upgrade: fetch the newest release for this machine and swap the binary in place.

watch

Keep a store current while its corpus is being edited.

Structs

Boundary

What this caller is allowed to index.

Finding

One file a store holds that today’s rules would refuse.

Hit

IndexProgress

Where an index run has got to, handed to the callback once per file.

IndexReport

Pixels

An image’s pixel size.

Refusal

Why a path was refused, and whether the refusal is about what it holds.

Semlith

Span

One span of one file, and nothing around it.

Enums

FileOutcome

What the run decided about one file.

Flow

What a controlled run should do at the next file boundary.

Prefer

Which side of the corpus a caller would rather be given.

Read

What a read produced: the span, or the definitions to choose between.

Shape

What a query looks like, which decides which half of the fusion is trusted.

SkipReason

Why a file was skipped, as a closed set.

Target

What read was asked for: a span of a file, or a symbol by name.

Constants

IMAGE_FLOOR_ENV

Overrides [IMAGE_FLOOR].

MODEL_CACHE_ENV

Overrides model_cache_dir.

Functions

canonical

canonical_calls

The reading for [CANONICAL_CALLS], for the test that pins the cost.

check_roots

Which of roots can be read, and why the others cannot.

default_ignores_on

Whether the table applies, given whatever SEMLITH_DEFAULT_IGNORES says.

default_model

Default model: 384-dim, ~52 MB on disk. Measured against the previous default (BGE-small) on a 6260-chunk corpus it scored 16.00 code MRR@10 against 14.84, at a third of the download.

human_bytes

Byte counts sized to the unit that actually shows a digit — a small corpus reported as “0.0 MB” reads like a bug rather than a small corpus.

is_generated_dir

Whether this directory is generated output rather than somebody’s code.

model_cache_dir

Where ONNX model weights are cached. Shared across stores — the weights are large and identical for a given model.

plain

A path as a person or an agent should read it.

serialize_plain

Serialize a stored path in the form a person reads, leaving the value in memory as the store’s own key. One attribute per field beats a call at every place a struct reaches JSON, and the CLI’s --json, the portal and the MCP results all serialise these same structs.

shape_of

Whether a query is shaped like an identifier or like a question.