Concepts

Five ideas explain most of hSUM's behavior.

Index and project

An index is one SQLite database bound to one filesystem root. A project is a named scope inside it; alpha.4 creates default automatically. Both get a stable UUID that appears in every citation.

hsum context

Index: repo
Index ID: 30bf24f0-457f-4bf2-b56d-cb33ba0eb547
Project: default
Project ID: d385f3cf-c799-45fb-9851-18071cc86059
Source root: /path/to/repo
Binding: 495d788b-897c-46b6-86c2-5d28d80b3d42
Selection: trusted_root

Generations

Every ingest commits one generation — an atomic snapshot of the source. Either the whole generation lands or none of it does; there is no half-updated index. hsum status reports the current generation number.

A single-writer advisory lock serializes ingests. Concurrent readers are never blocked, so an agent can search while an ingest runs.

Citations

A citation names exact bytes at an exact revision:

hsum://v1/<index_id>/<source_id>/<document_id>?rev=<sha256>#bytes=<start>-<end>

Part	Meaning
`index_id`	UUID of the index that produced the passage
`source_id`	UUID of the source file
`document_id`	UUID of the indexed document
`rev`	SHA-256 of the file revision at index time
`bytes`	Half-open byte span within that revision

Because rev pins content, a citation cannot silently drift. Edit the file and the old citation still resolves to what was actually indexed. Pass --verify-source-hash to get to check the current file against the pinned revision.

Why this matters for agents

An agent that answers with a citation is making a checkable claim. You can resolve it yourself and see the exact bytes, rather than trusting a paraphrase.

Trust bindings

The MCP server refuses to serve a project unless the caller presents a binding UUID created by hsum init or hsum trust. The binding is user-side state, not a secret embedded in the repo, so cloning a repository grants no access to anyone's index.

hsum trust /path/to/repo --confirm

--confirm is required; hSUM never creates a trust binding implicitly.

Untrusted content

Every search and get result carries "untrusted_content": true. Indexed files are data, not instructions — if a repository contains text telling an agent to take an action, that text is content to be reported, never a command to follow.

Prompt injection

Treat retrieved passages as untrusted input. hSUM marks them, but the agent runtime must honor the marking.

Retrieval

alpha.4 runs three retrievers and merges them: exact identifier matching, conservative quoted-phrase matching, and lexical BM25. --mode auto and --mode lexical are equivalent in this release. There is no vector search and no embedding model, which is why first-run needs no download.

Retrieval is bounded. --timeout-ms (default 3000) caps work, and the response reports a stop_reason such as limit_reached or unique_exhausted so you can tell a complete result from a truncated one.