HSUM

hSUM: Stateful Understanding & Memory

Local evidence for agents.

Keep the source. Return the passage.

Install

 

Colored badges are clickable and go to the relevant section or page. Source build works today (see Quickstart). GitHub prereleases provide prebuilt macOS arm64 and Linux x86_64 archives. Published cargo install and cargo binstall remain deferred while the crate has publish = false. Alpha binaries are checksummed and carry GitHub build attestations, but the macOS archive is not Apple-signed or notarized — see Verifying a release.

Connect an agent  ·  Contributing  ·  Roadmap  ·  Status

hsum is a local-first evidence engine for coding agents. It indexes one local source tree into immutable SQLite generations, then returns exact and BM25-ranked passages with canonical citations through a CLI or a read-only MCP stdio server. No account, model, daemon, telemetry, or network access is involved after the build.

When something leaves your agent's context window, you lose it. hsum keeps the source below the session, maps deterministic routes back to it, and returns the passage with its citation intact.

Quickstart

# 1. Build (pinned Rust 1.91; macOS arm64 or Linux x86_64)
cargo build --locked --release
export HSUM=/absolute/path/to/checkout/target/release/hsum

# 2. Index a repository
cd /absolute/path/to/a/repository
"$HSUM" init            # prints the exact data path and a verified first query

# 3. Search, then resolve immutable evidence
"$HSUM" search 'your identifier or "exact phrase"'
"$HSUM" get ''

# 4. Connect an agent (privacy note prints first)
"$HSUM" client config codex      # or claude-code | claude-desktop | generic
"$HSUM" client doctor codex      # real end-to-end probe of that config

Ask your agent

Copy this prompt into your coding agent to run the quickstart from an existing checkout:

Set up and smoke-test hSUM (https://github.com/burkan2/hSUM) from the current
checkout without changing source or configuration files. First check that this
is macOS arm64 or Linux x86_64 and that `cargo` is available. If Rust/Cargo is
missing, offer me two choices and wait for my answer: I can install Rust from
https://www.rust-lang.org/tools/install, or you can install it with rustup
after I explicitly approve that system change. When Cargo is ready, run
`cargo build --locked --release`, verify `./target/release/hsum --version`, set
HSUM to the binary's absolute path, then initialize the repository I name and
run one search. Report each command and its result, including any failure,
before proceeding to the next step. Documentation is at
https://hsum.burkankale.com/docs/0.1.0-alpha.3/ and
https://hsum.burkankale.com/llms.txt.

init refuses dangerous roots, writes nothing into the repository, stores the index in your user directory, and prints a search command it ran itself to confirm the command returns evidence. Every result carries an immutable hsum://v1/... citation that get resolves against stored bytes, not against whatever the file looks like later.

> [!NOTE] > This is an alpha. The > v0.1.0-alpha.3 GitHub prerelease > provides checksummed artifacts for macOS arm64 and Linux x8664. The crate > remains publish = false, so cargo install is unavailable.

Connect your agent

hSUM speaks MCP over stdio only. client config prints a copyable snippet that pins the binary's absolute path and one project-scoped trust binding. It guesses no PATH, edits no config files for you, and cannot be steered into another project:

"$HSUM" client config codex --format toml     # Codex
"$HSUM" client config claude-code             # Claude Code
"$HSUM" client config claude-desktop          # Claude Desktop
"$HSUM" client config generic                 # anything MCP-capable

The server exposes exactly four read-only tools: evidence_search, evidence_get, evidence_project, and evidence_status. It marks every returned passage untrusted_content: true so agents treat it as evidence, never as instructions. Privacy boundary: hSUM uploads nothing anywhere; a cloud-backed client may forward returned passages to its own model provider under that client's policy, and the generated config prints that warning before the snippet.

Available in 0.1.0-alpha.3

| Capability | Status | Current boundary | |---|---|---| | Local filesystem ingest | Available | One canonical root, one project, and one filesystem source per managed index | | Markdown, text, and source code | Available | Lowercase .md, .markdown, .txt, .rs, .py, .ts, .tsx, .js, .jsx, .go, .java, .kt, .kts, .c, .h, .cpp, .hpp, .cc, .hh, .cxx, .rb, .cs, .swift, .php, .scala, .sh, .bash, and .sql | | Exact and BM25 search | Available | auto and lexical are equivalent; there are no embeddings or vectors | | Immutable citations and historical get | Available | Evidence remains resolvable while its immutable version remains in this alpha index | | Atomic generations | Available | Explicit ingest; no watcher or daemon | | Status and read-only doctor | Available | Diagnosis only; no repair, prune, backup, or migration command | | MCP stdio | Available | Four read-only tools bound to one trusted project | | JSONL and live connectors | Unsupported | Planned after the filesystem slice | | Semantic search, models, and reranking | Unsupported | No model install or download path exists | | HTTP server or web UI | Unsupported | MCP stdio is the only transport | | Prebuilt installation | Available | Checksummed GitHub prerelease archives for macOS arm64 and Linux x86_64; no installer or crates.io package |

Build from source

The repository pins Rust 1.91.0 with rustfmt and Clippy. Release CI runs on clean GitHub-hosted macOS arm64 and Linux x86_64 machines. The implementation uses Unix filesystem and locking primitives on local storage; Windows is unsupported.

git clone 
cd 
cargo build --locked --release
./target/release/hsum --version

Ask your agent

Copy this prompt into your coding agent to install hSUM from source:

Install hSUM (https://github.com/burkan2/hSUM) from this reviewed source
checkout without changing application source or configuration files. First
confirm that the host is macOS arm64 or Linux x86_64 and check
`rustc --version` and `cargo --version`. If Rust/Cargo is missing, offer me two
choices and wait for my answer: I can install Rust from
https://www.rust-lang.org/tools/install, or you can install it with rustup
after I explicitly approve that system change. Once Cargo is available, run
`cargo build --locked --release` and `./target/release/hsum --version`. Then
give me the exact `export HSUM=...` command using this checkout's absolute path
and report the commands and results without making any other changes.
Documentation is at https://hsum.burkankale.com/docs/0.1.0-alpha.3/ and
https://hsum.burkankale.com/llms.txt.

The first build may contact Rust and crate registries to obtain the pinned toolchain and dependencies. After a binary exists, hSUM has no network client, account, telemetry, model download, HTTP server, or other network runtime path. An already populated Cargo cache can build with Cargo's normal --offline option.

For the examples below, set HSUM to the absolute path of the binary before changing directories:

export HSUM=/absolute/path/to/checkout/target/release/hsum

First local evidence

Run the dry run first. It scans and estimates the source but writes no index, trust binding, or repository pointer.

cd /absolute/path/to/a/repository
"$HSUM" init --dry-run
"$HSUM" init
"$HSUM" search '"HTTPServer::handle_request"' --explain

init chooses the enclosing Git root, or the current directory when there is no enclosing Git worktree. It creates a private managed SQLite index and a user-side trust binding. It does not modify the repository unless --write-pointer is supplied. The optional .hsum.toml pointer is only a logical hint; it never grants authority without a matching user trust binding.

Useful initialization controls:

"$HSUM" init --no-ingest
"$HSUM" init --index my-index --project default
"$HSUM" init --write-pointer
"$HSUM" init --index-quota-bytes 1073741824

• --no-ingest creates and trusts the index while leaving the source in

never_succeeded state.

• --allow-broad-root is required for /, the account home, or a directory

above the enclosing Git worktree.

• --allow-large-source raises the persisted source ceiling from 10,000 files

or 2 GiB to the hard ceiling of 50,000 files or 8 GiB.

• --force-pointer is valid only with --write-pointer and replaces

conflicting pointer bytes after preflight.

• Re-running init for the same trusted root is idempotent only when the stored

index, project, source identity, and source root still match.

Command inventory

The current candidate exposes only the following command graph:

| Command | Output and effect | |---|---| | hsum init [PATH] | Dry-run or create one managed filesystem index, project, source, and user trust binding; --rebuild safely replaces the binding and index | | hsum trust PATH --confirm | Add or confirm a root-bound user trust binding for an existing matching index | | hsum ingest | Dry-run or commit one authoritative filesystem generation | | hsum search QUERY | Human evidence or one JSON document; exact plus BM25 | | hsum get CITATION_URI | Human evidence or one JSON document from an immutable citation | | hsum status | Human status/problems or one JSON document | | hsum doctor | Read-only human integrity diagnosis | | hsum context | Human selection details or one JSON document | | hsum client config CLIENT | Copyable JSON or TOML for codex, claude-code, claude-desktop, or generic | | hsum client doctor CLIENT | Validate the generated configuration with a real empty-directory MCP probe | | hsum help error SUBCODE | Offline explanation of one stable public error subcode | | hsum completions SHELL | Completion text on stdout for bash, zsh, fish, powershell, or elvish | | hsum man | A generated hsum(1) page on stdout | | hsum mcp | Project-bound MCP over stdin/stdout |

The only help subcommand is the offline error catalog, hsum help error ; for command help use hsum --help or hsum --help. The current candidate has no model, backup, prune, forget, restore, repair, watch, or daemon command.

Source discovery and ingest

The current candidate accepts valid UTF-8 text without NUL bytes. Lowercase filename extensions are matched exactly. The per-file default is 2 MiB and remains 2 MiB when --allow-large-source is used.

Source files chunk at declaration boundaries where the language has them — fn, class, def, func, and their equivalents. Shell and SQL have no unambiguous declaration keyword, so they chunk at paragraph and line boundaries instead. Configuration formats such as .yaml, .json, and .toml, markup such as .html and .css, and extensionless files such as Makefile are not indexed.

Discovery stays conservative by default:

• nested .gitignore rules are honored;
• hidden names and target, node_modules, build, dist, out, vendor,

__pycache__, and venv are excluded by default;

• .git, .ssh, .aws, .gnupg, .config, .cache, .idea, .vscode,

environment files, common credential names, and private-key extensions are treated as sensitive and are not admitted by the CLI;

• source roots, directories, and files are opened without following symlinks;
• hard links are ordinary regular files and cannot be distinguished from their

original paths, so secret-path rules are defense in depth rather than a content sandbox;

• file identity and metadata are checked around reads, and directory changes

during enumeration fail closed;

• traversal is capped at 100,000 visited entries, 10,000 directories, depth

128, and 50,000 entries in one directory.

Files that are unreadable, invalid UTF-8, contain NUL, exceed the file limit, or change during the read become source failures rather than partially indexed bodies. Inspect a refresh before committing it:

"$HSUM" ingest --dry-run
"$HSUM" ingest
"$HSUM" status --problems

When the indexing pipeline changes

The set of indexable extensions and the chunking rules are hashed into a pipeline fingerprint that is stored in the index. When a new hSUM build changes those rules, the stored fingerprint no longer matches and the index stops opening: every command, including search and ingest, fails with pipeline fingerprint does not match this binary.

ingest cannot recover such an index because it must open the index before it can rebuild it. Inspect the destructive replacement first, then run it:

"$HSUM" init --rebuild --dry-run
"$HSUM" init --rebuild

Rebuild validates that the old index is structurally coherent apart from its pipeline fingerprint, preserves other trusted roots, and creates a new index and binding from the current source. It refuses corruption rather than silently treating damage as compatibility. Evidence and citations from the replaced index do not survive.

A refresh runs as two bounded passes. The first pass only enumerates and estimates the eligible source without writing anything; a storage preflight then checks that estimate against free capacity. The second pass re-verifies each file's identity while spooling bodies into a bounded staging area before the commit transaction. Because the prior generation stays fully readable until the new one activates, managed storage transiently peaks above its steady state during a refresh; the preflight reserve accounts for that peak.

Each successful authoritative refresh activates one atomic generation. Unchanged bodies and immutable historical versions are reused. If every targeted file fails, no generation or index epoch advances and the command exits 1. A committed generation that also retains file failures exits 6 and reports a partial source. Prior evidence is carried forward where the failure contract permits it.

Deletion has two independent confirmations:

• replacing a previously nonempty source with an empty snapshot requires

--allow-empty-snapshot;

• deleting more than 25% of prior active documents, or more than 1,000

documents, requires --allow-mass-delete.

Exactly 25% is allowed without the mass-delete confirmation. Use --lock-timeout-ms 0..60000 to bound the wait for the single writer; the default is 5,000 ms.

Search and citations

The current candidate combines three local lexical signals:

1. case-sensitive identifier-like literals;
2. conservative exact quoted spans;
3. SQLite FTS5 BM25.

The candidate lists are fused deterministically. --explain includes the signal ranks and fixed-point fusion score. --mode auto and --mode lexical produce the same behavior.

"$HSUM" search 'generation recovery'
"$HSUM" search '"EVIDENCE_FORGOTTEN"' --limit 20 --timeout-ms 3000 --explain
"$HSUM" search 'source_state' --json

Search limits are 1–50 results, the deadline is 100–10,000 ms, and the defaults are 10 results and 3,000 ms. A query is at most 4,096 UTF-8 bytes. Double quotes delimit exact spans and have no escape syntax. The CLI exposes --cursor in the pre-stable grammar but rejects it; cursor pagination is MCP-only.

Every result includes a canonical citation:

hsum://v1///?rev=#bytes=-

The URI fixes the index, source, document, immutable revision, and exact byte span. get resolves stored evidence, not whatever happens to be in the source tree now:

"$HSUM" get ''
"$HSUM" get '' --max-bytes 65536 --verify-so

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [burkan2](https://github.com/burkan2)
- **Source:** [burkan2/hSUM](https://github.com/burkan2/hSUM)
- **License:** Apache-2.0
- **Homepage:** https://hsum.burkankale.com

Install and usage instructions live in the source repository linked above.