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.

chunk

Turning a file on disk into embeddable chunks of text.

clients

The client setup stanzas, read out of the README at compile time.

daemon

semlith start — one process that owns every store.

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.

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.

routes

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

setup

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

store

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

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.

Hit

IndexProgress

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

IndexReport

Pixels

An image’s pixel size.

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.

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

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.

model_cache_dir

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

shape_of

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