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.

• 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

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.

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"

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.

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

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:

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

$ kb log
a1b2c3d 2026-03-04 02:26 ref: link my-project → rest-api-docs
e4f5a6b 2026-03-04 02:26 shared: add rest-api-docs (1 file(s), 500 lines)
c7d8e9f 2026-03-04 02:18 import: my-project from ~/repos/my-project/CLAUDE.md
0a6b0f2 2026-03-04 02:07 init: knowledge base

kb init offers to set up a git remote and enable auto-push. When enabled (auto_push: true in kb.yml), every commit is automatically pushed to the remote in the background.

When configured, agents get 16 tools:

The kb_draft → kb_write workflow ensures agents preview changes before persisting them.

Agents can create shared docs, link them, and manage globals entirely through MCP — no CLI needed.

~/knowledge-base/
  .git/                              # Auto-managed version history
  kb.yml                             # Config + project path mappings + globals
  shared/                            # Cross-project shared docs
    rest-api-docs/
      api-reference.md               # The actual documentation
      meta.yml                       # Optional: title, description, source, tags
    design-patterns/
      reactivity.md
  projects/                          # Per-project knowledge
    my-project/
      context.md                     # Project context (the "real" CLAUDE.md)
      refs.yml                       # Links to shared docs: [rest-api-docs]
      notes/                         # Additional project-specific docs
        architecture.md

kb.yml — Global config with project path mappings and globals:

version: 1
editor: hx                                    # Fallback: $EDITOR, then vi

globals:                                       # Shared docs available to all projects (referenced)
  - style-guide

inline_globals:                                # Shared docs embedded into all projects' context.md
  - coding-standards

projects:
  my-project: ~/repos/my-project
  other-project: ~/documents/other-project
  work-api: /opt/work/api-server

Projects can be anywhere on disk — they don't need to be under a common directory.

refs.yml — Per-project shared doc references:

refs:
  - rest-api-docs
  - design-patterns
inline:                    # Embedded directly into context.md
  - commit-conventions

meta.yml — Optional shared doc metadata:

title: REST API Reference
description: API endpoints, authentication, and usage examples
source: https://docs.example.com/api
tags: [api, rest, reference]

~/repos/my-project/CLAUDE.md     ← 300 lines of context, edited in-repo
~/repos/other-project/CLAUDE.md  ← Duplicate API docs, diverges over time

~/repos/my-project/CLAUDE.md     ← One line: @~/knowledge-base/projects/my-project/context.md
~/knowledge-base/
  projects/my-project/context.md ← The actual 300 lines, versioned, with edit directive
  shared/rest-api-docs/         ← API docs, shared by both projects

The repo's CLAUDE.md becomes a single @import pointer. Claude Code expands this at session start and sees the full content. The KB's context.md starts with:

<!-- KB managed: ~/knowledge-base/projects/my-project/context.md -->
<!-- Always edit THIS file for project context. Do NOT edit the repo's CLAUDE.md. -->

This directive ensures agents edit the KB file (versioned, centralized) rather than the repo's pointer file.

When context.md is updated, kb copies it to .kb-context.md in the project directory. This keeps a versioned copy of the project context alongside your code.

Shared docs can be linked in two modes:

• Ref (default) — listed in a <!-- KB:REFS --> comment as a summary with line counts. Agents fetch content on-demand via kb_read/kb_search. Best for large reference docs.
• Inline (--inline) — content embedded directly into context.md inside <!-- KB:INLINE --> blocks, loaded at session start. Best for small docs that should always be available (commit conventions, style guides).