Agent Knowledge Base

A CLI tool and MCP server for managing markdown knowledge bases across projects. Externalizes project context (CLAUDE.md/AGENT.md) and shared documentation (API docs, specs, workflows) into a central versioned directory, then exposes it to AI coding agents via MCP.

Supports Claude Code, OpenAI Codex, and OpenCode.

Why

• Context files are scattered across repos with no way to share docs between projects
• API documentation gets duplicated - the same API docs copied into 3+ repos
• No version history - when you update project context, the old version is gone
• Large reference docs waste context - 9000-line API docs shouldn't load into every session

kb solves this by centralizing knowledge into ~/knowledge-base/ with:

• Per-project context that replaces in-repo CLAUDE.md files
• Shared docs that multiple projects reference without duplication
• Global shared docs that are available to all projects automatically
• Inline mode to embed shared doc content directly into context.md (loaded at session start without MCP calls)
• Git versioning on every change (auto-committed)
• An MCP server so agents can search, read, and write docs on-demand
• A TUI browser for navigating and assigning refs to the knowledge base interactively

Setup

1. Install

go install github.com/leona/kb@latest

Or download a prebuilt binary from the latest release:

curl -Lo kb https://github.com/leona/kb/releases/latest/download/kb-linux-amd64
chmod +x kb
sudo mv kb /usr/local/bin/kb

Replace kb-linux-amd64 with your platform: kb-darwin-arm64 (macOS Apple Silicon), kb-darwin-amd64 (macOS Intel), kb-windows-amd64.exe.

2. Initialize the knowledge base

kb init

This creates ~/knowledge-base/ with:

• kb.yml — configuration file
• shared/ — directory for shared documents
• projects/ — directory for per-project knowledge
• .git/ — version history (auto-managed)

To use a different directory:

kb init --dir ~/my-knowledge-base

Then set KB_ROOT in your shell config:

export KB_ROOT="$HOME/my-knowledge-base"

3. Configure MCP for a project

From inside a project directory:

kb setup

Or specify the project name:

kb setup my-project

This auto-detects installed agents and:

1. Creates MCP config in the project directory (.mcp.json for Claude Code, .codex/config.toml for Codex, opencode.json for OpenCode)
2. Writes @import pointers in CLAUDE.md (and AGENTS.md/AGENT.md if they exist) pointing to the KB context

Shows what will be written and asks for confirmation (-y to skip).

Restart your agent after setup to connect to the MCP server.

Claude Code expands this @import automatically — the full context loads as before. When Claude modifies the context, it edits the KB file (because of the directive header), not the repo's CLAUDE.md.

Browsing

Interactive TUI for navigating the knowledge base:

kb

• Launched outside a project → shows all projects and shared docs in dual-pane view
• Launched inside a registered project → jumps to that project's detail view
• Navigate with arrow keys or h/l, tab to switch panes, / to filter, Enter to open, Esc to go back
• Space to toggle ref/inline mode (project detail) or cycle global status (main view)
• q or Ctrl+C to quit

Agent Usage

Agents use KB tools via MCP to search, read, and create docs on-demand.

Searching the knowledge base:

Reading shared API docs:

Creating a new shared doc:

Versioning

Every CLI write operation auto-commits to the KB's git repo with a descriptive mes

... View full README on GitHub