# HSUM

> hSUM: Stateful Understanding & Memory — local evidence for agents. Keep the source. Return the passage.

- **Type:** MCP server
- **Install:** `agentstack add mcp-burkan2-hsum`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [burkan2](https://agentstack.voostack.com/s/burkan2)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [burkan2](https://github.com/burkan2)
- **Source:** https://github.com/burkan2/hSUM
- **Website:** https://hsum.burkankale.com

## Install

```sh
agentstack add mcp-burkan2-hsum
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
# 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:

```text
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](https://github.com/burkan2/hSUM/releases/tag/v0.1.0-alpha.3)
> provides checksummed artifacts for macOS arm64 and Linux x86_64. 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:

```bash
"$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.

```bash
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:

```text
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:

```bash
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.

```bash
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:

```bash
"$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:

```bash
"$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:

```bash
"$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.

```bash
"$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:

```text
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:

```bash
"$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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-burkan2-hsum
- Seller: https://agentstack.voostack.com/s/burkan2
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.