hebb
hebb turns a folder of markdown notes into a fast, connected knowledge base — and gives your AI tools a memory they can search and recall.
Point hebb at a vault of .md files. It builds a full-text index, follows your [[wiki-links]] and tags to assemble related context, and serves both over the Model Context Protocol (MCP) — so Claude and Codex can search your notes and pull in connected material while they work. Your notes stay plain markdown on your disk; hebb indexes and serves them, it never takes ownership.
Multi-vault, like git is multi-repo: run hebb inside a vault directory, or pass --vault.
Why hebb
- Agent-native. One MCP server gives Claude Code, Claude Desktop, and Codex the same tools:
search_vault, get_context_for_topic, expand_context, vault_stats, reindex_vault.
- Connected recall, not just keywords. hebb walks
[[wiki-links]] and shared tags to gather a topic's context, so an agent gets the related notes, not just the literal hits.
- Local and fast. Pure-Go SQLite FTS5 — no service, no cloud, no cgo. A single static binary; your vault never leaves your machine.
- Composable. A CLI, a local web UI, an MCP server, a Claude Code plugin, and a file watcher over one engine. Use the parts you want.
Install
hebb is a single static binary for macOS or Linux (arm64 or amd64). Pick one method:
Install script. Downloads the matching release binary to ~/.local/bin:
# public repo:
curl -fsSL https://raw.githubusercontent.com/cizer/hebb/main/install.sh | sh
# private repo (uses your GitHub CLI auth for both the script and the binary):
gh api repos/cizer/hebb/contents/install.sh -H "Accept: application/vnd.github.raw" | sh
Override the target dir with HEBB_INSTALL_DIR, or pin a version with HEBB_VERSION=vX.Y.Z.
Go: go install github.com/cizer/hebb/cmd/hebb@latest (set GOPRIVATE=github.com/cizer/* while the repo is private).
Homebrew: planned, not yet enabled.
Then make sure the install dir is on your PATH, and check the binary:
export PATH="$HOME/.local/bin:$PATH" # add to your shell profile if it isn't already
hebb --version
Later, upgrade in place with hebb update.
Set up a vault
A vault is just a folder of markdown notes. hebb adds a .hebb/ directory to it (like .git adds .git/) and wires it into your machine and agents. Start one of two ways.
A new vault
hebb new ~/notes
Scaffolds a PARA skeleton (1-Projects/, 2-Areas/, 3-Resources/, 4-Archives/), a baseline CLAUDE.md and AGENTS.md, a note template, and an empty memory seed, then installs it. Refuses to scaffold into a non-empty directory, so it never overwrites existing files.
An existing folder of notes
hebb install --vault ~/existing-notes
Indexes the folder in place and wires it. Pass --vault the first time because the folder has no .hebb/ yet for hebb to find. After that the vault self-identifies, so you can just cd ~/existing-notes && hebb <command>.
What hebb install does
Both paths run hebb install. It is idempotent and never modifies your notes:
- writes
.hebb/config.toml (the committed, per-vault config) and builds the search index at .hebb/index.db;
- symlinks the vault's agent memory (
.hebb/memory/) into Claude's project directory;
- installs hebb's skills into
~/.claude/skills (--no-skills to skip);
- offers an interactive picker to connect your agents (or pass
--codex / --claude-desktop / --mcp-json explicitly, or --no-interaction to skip);
- with
--launchd, renders background jobs (--load also starts them).
Check the result any time with hebb doctor, and browse the vault with hebb serve (local web UI on 127.0.0.1).
Connect your agents
The picker can do this for you, or wire each explicitly:
See Agents for how each adapter works.
What to commit
Commit .hebb/config.toml and your notes, so a cloned or synced vault self-identifies. The index (.hebb/index.db) is derived and rebuilt on demand, so gitignore it. Memory under .hebb/memory/ travels with the vault. To keep the markdown synced automatically, enable [git] in config.toml (see hebb sync below).
Multiple vaults
