Your first knowledge base

Install HyperKB, connect one MCP client, and save a decision you want to remember in the next session.

Requirements

• Python 3.10 or newer.
• ripgrep (rg) on your PATH for literal search. BM25 remains available when ripgrep is absent.
• An MCP client that can launch a local stdio server.
• Git and the optional sync dependencies if you want synchronization between machines.

The shell commands below use Linux/macOS paths. Local search does not require a model download, an embedding service, or a model API key. Install ripgrep using your system package manager, for example brew install ripgrep on macOS or sudo apt install ripgrep on Debian/Ubuntu.

Install from source

git clone https://github.com/calvincs/hyperkb
cd hyperkb
python3 -m venv .venv
.venv/bin/pip install -e ".[mcp]"
.venv/bin/hkb init

This creates your knowledge base at ~/.hkb/. The virtual environment belongs to this source checkout; keep the checkout at a stable location. To install the synchronization and encrypted-credential extras as well, use .[all] instead of .[mcp].

Connect your client

Find the absolute executable path:

pwd

Append /.venv/bin/hkb-mcp to that directory. Put the resulting absolute path in your MCP client's server configuration. For clients using the mcpServers format:

{
  "mcpServers": {
    "hyperkb": {
      "command": "/absolute/path/to/hyperkb/.venv/bin/hkb-mcp",
      "env": {"HKB_SOURCE": "my-client"}
    }
  }
}

Replace the path and client label. Do not use ~ inside the executable path: a client may launch the command without shell expansion. The client starts HyperKB as a subprocess. A fresh server can initialize the default knowledge base automatically if you skipped hkb init.

For the full connection details and multiple clients, read MCP & clients.

Save one useful decision

These examples are MCP tool calls, not shell commands. Ask your agent to create a topic file:

hkb_add(
    create_file=True,
    to="infra.postgres",
    description="Postgres connection settings and the reasons behind them.",
    keywords=["postgres", "connection", "pool"]
)

Then save a decision with its rationale:

hkb_add(
    to="infra.postgres",
    content="@type: decision\nUse a connection pool limit of 20. Higher limits exhaust our worker budget under load."
)

The response includes the file and an entry epoch. Keep that pair when you need to update or link to this entry.

Retrieve it in another session

hkb_search(query="connection pool", domain="infra")
hkb_context(topic="postgres connection limits", max_tokens=2000)
hkb_show(name="infra.postgres")

The Markdown file lives at ~/.hkb/storage/infra.postgres.md. You can read it in an ordinary text editor. Search uses a rebuildable SQLite index alongside ripgrep.

Choose another location

.venv/bin/hkb init --path /absolute/path/to/my-knowledge

Use the same root in your MCP configuration:

{
  "command": "/absolute/path/to/hyperkb/.venv/bin/hkb-mcp",
  "args": ["--path", "/absolute/path/to/my-knowledge"],
  "env": {"HKB_SOURCE": "my-client"}
}

The root is the directory containing .hkb, not .hkb/storage itself.

If something goes wrong

Run hkb doctor from your virtual environment for a read-only health report. Use hkb reindex to rebuild the index from Markdown, even if MCP cannot start. Both accept --path ROOT. See maintenance & recovery before moving or restoring data.