kb

KB

A persistent memory plugin for Claude Code. Markdown vault maintained by your agent across sessions. Based on Karpathy's LLM Wiki pattern.

What it does

• SessionStart hook injects vault context — a compact pointer by default (lazy mode), or the working set, index, and recent session summaries in eager mode
• Stop hook writes a small session manifest when you finish working
• PostCompact hook re-injects vault context after compaction (solves compaction amnesia)
• Trust boundary separates curated knowledge (wiki/) from untrusted content (raw/, sessions/), with sanctioned CLI commands for each tier
• KB.md template teaches Claude to ingest sources, answer queries, and lint your vault

Install

Requires Bun — the CLI and hooks run TypeScript directly.

bunx @beaudry/kb init

Scaffolds ~/kb with the vault structure. init does not touch Claude Code configuration — hooks ship with the KB plugin:

claude plugin marketplace add JustinBeaudry/kb
claude plugin install kb@kb

Safe to run init again — idempotent.

Custom vault path

bunx @beaudry/kb init --vault-path /path/to/vault

Per-project vault

Create a .kb file in your project root containing the vault path:

/path/to/project/vault

Usage

Ingest

Give Claude any source — file path, URL, pasted text, or conversation context:

"Ingest this article on dependency injection"

Claude reads source, copies files to raw/ for provenance, presents takeaways for confirmation, writes wiki pages, cascades updates to related pages, updates index and log. Single ingest typically touches 5-15 pages.

Query

Ask Claude anything your vault might know:

"What decisions did we make about the auth system?"

Claude checks index, follows wikilinks, answers with citations. Novel insights get filed as new wiki pages automatically.

Lint

Ask Claude to check vault health:

"Lint the vault"

Reports orphan pages, dead links, missing frontmatter, stale content, missing types, and contradictions.

Refine

Ask Claude to improve vault structure:

"Refine the vault"

Finds stale pages, under-connected pages, merge/split candidates, and backlink gaps. Presents findings for approval, then applies changes. Shows vault health before and after.

Extract

Extract knowledge from session manifests into wiki pages:

"Extract from sessions"

Sessions are sources. Claude enumerates unprocessed manifests with kb sessions --unprocessed, generates cached summaries with kb summarize, retrieves them through the ask-gated kb read-session, runs the standard ingest workflow on confirmed items, and marks finished manifests with kb mark-extracted. Summaries require the claude CLI (or a KB_SUMMARIZE_COMMAND equivalent) — without one, kb summarize exits nonzero and extraction cannot proceed.

Toggle session-start nudge: /kb:extract on or /kb:extract off.

CLI reference

Command	What it does
kb init	Scaffold the vault (does not register hooks)
kb doctor	Check vault health, hook wiring, and inject-budget pressure
kb uninstall	Print plugin-removal instructions; vault is preserved
kb map [query]	Budget-bounded structural map of the wiki — node summaries for navigation
kb get-node <id>	Fetch a page or section by node ID (--neighbors, --follow-wikilinks <n>)
kb recall <query>	Search curated pages, return evidence envelope
kb get <page>	Fetch a curated page by name
kb list-topics	List index topics
kb read-raw <file>	Ask-gated bounded read from raw/
kb read-session <file>	Ask-gated bounded read from sessions/ (incl. summaries/)
kb sessions [--unprocessed]	List session manifest names — never content
kb mark-extracted <file>	Mark a manifest as extracted
kb capture-session	Write a session manifest (used by the Stop hook)
kb summarize <manifest>	Generate or reuse a cached session summary
kb summaries pin|unpin	Pin or unpin a cached summary

All commands accept --vault-path <dir> (alias -p <dir>) to target a vault explicitly, overriding KB_VAULT and per-project .kb files.

Trust boundary

Vault content is two-tier:

• Curated (wiki/, index.md, context.md) — trusted, retrieved via kb recall, kb get, kb list-topics.
• Untrusted (raw/, sessions/) — provenance and machine-generated content, readable only through the ask-gated kb read-raw / kb read-session (bounded excerpts, explicit --approve or KB_APPROVE=1 in non-interactive use).