hSUM documentation
hSUM indexes a local filesystem into an immutable, citable evidence store, then serves it to coding agents over a read-only MCP server. No account, no model download, no network.
Alpha
This documents 0.1.0-alpha.4. Supported release archives are macOS
arm64 and Linux x86_64 on local filesystems. The crate is not published to crates.io.
See boundaries for what is deliberately absent.
Compatible update
Alpha.2 and alpha.3 indexes and citations remain compatible. Restart any in-flight MCP pagination after upgrading because cursors are release-bound.
Quickstart
Install, index a repo, and run your first search in about five minutes.
Concepts
Generations, citations, trust bindings, and why evidence is immutable.
Connect an agent
Install Codex once for repository-aware tools, or configure another MCP client.
CLI reference
Every command and flag in the alpha.4 surface.
MCP reference
The four evidence tools, their inputs, and their JSON output.
Error codes
Every stable subcode with cause and fix.
What hSUM does
An agent asking "how does auth work here?" usually gets an answer assembled from whatever happened to fit in context. hSUM answers with passages, each one addressed by an immutable citation that resolves to exact bytes at an exact revision.
- Ingest walks a filesystem root and writes one atomic generation into a private SQLite index.
- Search combines exact identifier matching, conservative quoted-phrase matching, and lexical BM25.
- Get resolves an
hsum://v1citation back to the exact bytes that were indexed.
Retrieval is deterministic. The same query against the same generation returns the same passages in the same order.
Boundaries
Absent in alpha.4, deliberately — so you can rely on what is present:
| Area | Status |
|---|---|
| Local filesystem ingest, lexical + exact retrieval | included |
| Read-only MCP stdio server | included |
| Immutable citations with revision pinning | included |
| Vector or semantic search, embeddings | not in alpha.4 |
| Account, telemetry, HTTP server, remote connectors | not in alpha.4 |
| File watcher, backup, restore, prune, migration | not in alpha.4 |
Agent-readable docs
A machine-readable summary of this site lives at
/llms.txt, following the
llms.txt convention. Every documentation page is
static HTML with no client-side rendering, so agents can fetch any URL directly.