kkernel

The khive kernel — a single Rust binary that serves the MCP request surface and provides the admin CLI for database, pack, and versioning operations.

kkernel is the only binary khive ships. kkernel mcp serves the khive-mcp request tool over stdio (or a persistent Unix-socket daemon); the rest of the subcommand tree covers everything an operator needs outside of agent dispatch — schema migrations, KG sync/validate/fetch, pack introspection, embedding-model lifecycle, and reindexing.

Install

cargo install kkernel

or build from source:

git clone https://github.com/ohdearquant/khive.git && cd khive
cd crates && cargo build --release -p kkernel

The npm package khive installs a thin khive / khive-mcp shim that forwards to kkernel mcp for users who prefer npm install -g khive over Rust tooling; the two install paths produce the same binary underneath.

Usage

Point an MCP client at the binary's mcp subcommand:

{ "mcpServers": { "khive": { "command": "kkernel", "args": ["mcp"] } } }

kkernel mcp                            # stdio, default ~/.khive/khive.db
kkernel mcp --daemon                   # persistent warm daemon over a Unix socket
kkernel mcp --db :memory:              # ephemeral in-memory database
kkernel mcp --pack kg --pack gtd       # explicit pack list (default: full production set)
kkernel mcp --actor my-project         # default namespace for unscoped ops

Run a verb DSL expression directly — the same syntax the request tool accepts — without going through an MCP client:

kkernel exec 'knowledge.stats()'
kkernel exec 'knowledge.index(rebuild_ann=true)'
kkernel exec '[knowledge.list(limit=5), knowledge.stats()]'
kkernel exec --pending-events          # cron-friendly: fire due scheduled_event notes

Subcommands

Subcommand	Purpose
`mcp`	Serve the MCP `request` surface — stdio, `--daemon`, or a registered transport
`exec`	Run a verb DSL expression (or `--ops-file batch.jsonl`) through the pack registry
`sync`	Build a working SQLite database from `.khive/kg/*.ndjson` sources
`kg`	`validate` / `init` / `fetch` / `export` / `import` / `status` / `hook` — KG versioning ops
`db`	`migrate` / `check` — apply or report pending schema migrations
`pack`	`list` / `handler <name>` — introspect registered packs and their verb surface
`engine`	Embedding-model lifecycle: list, status, migrate, drift-check
`vector`	Vector store capabilities and orphan sweep
`reindex`	Rebuild embedding vectors and FTS documents for entities, notes, and knowledge atoms
`backend`	`list` / `info <name>` — inspect registered storage backends

All subcommands emit JSON on stdout by default (for piping/parsing); pass --human where supported for a readable table. kkernel kg, kkernel sync, and the NDJSON-to-SQLite rebuild logic they wrap live in khive-vcs and khive-vcs-adapters; kkernel's own kg/ module is a thin CLI wrapper over those libraries.

Configuration

Resolution precedence for the default namespace: --actor > --namespace (legacy alias) > [actor] id in a khive.toml config file > "local". Config file search order when --config is not given: ./khive.toml, ./.khive/config.toml, ~/.khive/config.toml. ~/.khive/.env is loaded into the process environment at startup if present (real env vars take precedence).

Environment variable	Effect
`KHIVE_DB`	Database path (also `kkernel mcp --db`)
`KHIVE_ACTOR` / `KHIVE_NAMESPACE`	Default namespace (also `--actor` / `--namespace`)
`KHIVE_NO_EMBED`	Disable local embedding model
`KHIVE_PACKS`	Comma/whitespace-separated pack list (also repeated `--pack`)
`KHIVE_CONFIG`	Path to the TOML config file (also `--config`)
`KHIVE_LOG`	Log level for stderr (JSON results on stdout are unaffected)
`KHIVE_BRAIN_PROFILE`	Brain profile for feedback routing and recall boosting

Two feature flags gate optional functionality, both pass-through to khive-mcp: bench-embedder (deterministic hash embedder for benchmarking, never enabled in release builds) and channel-email (SMTP/IMAP polling loop, inert without KHIVE_EMAIL_* env vars).

Where this sits

kkernel sits at the top of the storage dependency chain — it depends on every pack crate (khive-pack-kg, -gtd, -memory, -brain, -comm, -schedule, -formal, -knowledge, -session), khive-mcp (the server library it serves), khive-vcs / khive-vcs-adapters (KG versioning and import/export), and the core storage stack (khive-runtime, khive-db, khive-storage, khive-types, khive-score). Its _pack_links module force- references each pack crate so the linker keeps their inventory::submit! verb registrations in the final binary — dependency alone is not enough for that to happen.

Governed by ADR-016 (request DSL), ADR-049 (the --daemon warm runtime), and ADR-027 (pack self-registration via inventory).

License

Apache-2.0.