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

accel

Every device sharing every index run.

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.

cache

A machine-wide cache of vectors, so the same chunk is embedded once.

chunk

Turning a file on disk into embeddable chunks of text.

clientfile

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

clientid

Which app is on the other end of an MCP connection.

clients

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

clock

Local time, with the offset that says which local.

cloud

Semlith Cloud, from this side of the wire.

compact

Giving a store’s dead bytes back without re-embedding anything.

coreml

granite on the Neural Engine, and on the GPU through Core ML, macOS only.

cpucap

The CPU cap: the most of this machine’s CPU semlith’s own process may use while it indexes, from 0 to 100 % of every logical core.

cuda

The CUDA lane’s half of crate::accel: whether this machine has an NVIDIA card CUDA can use, the pack of libraries the lane runs on, and the session its worker embeds with.

daemon

semlith start — one process that owns every store.

doctor

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

drop

/api/drop/resolve: the real path of something dropped on the portal.

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.

gpu

The GPU’s half of crate::accel: whether this machine has one, the pinned components a lane needs, and the session a worker runs.

graph

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

helpers

“Index with semlith” in the file manager: opt-in, and removable.

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 look something up the slow way in a folder semlith already indexes.

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.

keyscan

The content scan’s second half: every secret-shaped match in a text, whether each one is a live-looking value or a provable test dummy, how likely it is to be real, what it looks like masked, and what redacting it leaves behind.

ledger

Writing the retrieval ledger, from wherever a retrieval happened.

leftovers

A one-time removal of what earlier releases wrote into clients semlith no longer supports.

llama

The llama.cpp lane: ggml-org’s llama-server, pinned by build, serving granite as GGUF f16 on Metal (macOS) or Vulkan (Windows and Linux).

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.

openvino

The OpenVINO lane: Intel’s plugin execution provider, from its PyPI wheel, running the fp16 model on an Intel GPU or NPU.

packs

The components the 0.32.0 lanes run on, each pinned by URL and SHA-256.

pattern

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

pipeline

The daemon as a login service, so a client never finds nothing. An index pass as three stages running at once.

portal

The portal, compiled into the binary.

prices

What a model’s tokens cost, for the ledger’s usage columns.

priority

Priority that follows the work.

progress

How far an index run is, and how long it has left: one account, used by the CLI, the daemon and the library’s embedders alike.

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.

schedule

Schedules: a report the daemon generates on its own, on a cadence, to a directory somebody named.

service

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

session

Embedding from token ids, which the index pass produces once per chunk.

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.

tree

semlith files --tree / semlith_files {tree: true}: a directory view that answers more than ls, find or tree can without opening a file (1.10).

trt

The TensorRT for RTX lane: NVIDIA’s plugin execution provider, from its PyPI wheel, running the fp16 model on a GeForce/RTX-class card.

upgrade

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

usage

The model, tokens and cost behind each ledger row, from the AI client’s own session log.

watch

Keep a store current while its corpus is being edited.

worker

The parse worker: every reader of a file’s own bytes, in a process of its own.

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

NotFound

An error that means “no such thing”: a store, a file, a run. A route answers it 404 rather than 500 (audit S23).

Pixels

An image’s pixel size.

Plan

What a run would do, before it embeds anything (2.7).

Refusal

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

ResolvedBoundary

A Boundary with its roots and the home directory resolved, so asking about a path costs that path’s resolution and nothing more.

Review

One file or folder the scan phase says a person could accept.

ScanProgress

How far a scan has got: walk, then read (each file read, hashed and checked for credentials), then rules once every file is decided.

Semlith

Shortener

Paths written relative to the store root that holds them, with the roots named once.

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

FAULT_PANIC_ENV

Record one file that failed on its own content.

HIDDEN_RULE

The rule a dotfile the walk skipped is listed under.

IGNORE_FILE

The file of gitignore patterns a store honours on top of .gitignore.

IMAGE_FLOOR_ENV

Overrides [IMAGE_FLOOR].

MODEL_CACHE_ENV

Overrides model_cache_dir.

Functions

canonical

canonical_calls

check_roots

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

code_shaped

Whether a question is about code, which is what brief spends its one text span and its graph lines on.

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.

git

git -C dir with everything a repository’s own config could make it run switched off.

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.

is_test_path

Whether a path sits under a test or fixture directory.

model_cache_dir

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

open_regular

Open a file that should be a regular file at exactly this path, refusing anything that is not one by the time it is open.

pictured

Whether a query describes something seen, which is what the image list is for (0.42.0, G13).

plain

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

push_files

The files semlith cloud push may send from root, and every one it may not, with the reason.

read_regular

open_regular, then at most cap of its bytes; more than that is a FileTooLarge error rather than a truncated file.

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.

serialize_plain_list

serialize_plain for a list of paths.

serialize_plain_lists

serialize_plain_list for lists grouped by a key.

shape_of

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

writer_sessions

How many writer embedding sessions are loaded in this process.