📃kami

Knowledge Agent Markdown Interface — AI-friendly personal knowledge base

日本語

kami is a local-first personal knowledge base CLI that manages Markdown + YAML frontmatter articles on the filesystem. Designed to be naturally usable by both AI coding agents (via CLI/JSON) and humans (via Web UI).

Features

• Markdown + YAML frontmatter — Standard format, works with any editor
• Multi-scope architecture — Global (~/.kami/) and local (./.kami/) scopes, with named vaults for global-scope context switching
• Full-text search — MiniSearch with BudouX Japanese tokenization, plus --where filters on arbitrary frontmatter fields
• Discovery — recent (sliding time window) and similar (related-article surfacing by title/tags/top terms)
• Wiki links — [[slug]] cross-references with backlink tracking; read --expand-links appends excerpts of linked articles
• Bulk operations — move, tag rename, and a batch command that executes many operations from JSON Lines input
• Section editing — Scope edits to a heading section with edit --section (replace or insert-before)
• Web UI — Browse, search, create, and edit articles in a browser (React SSR + Hono)
• Static site generation — Build a static HTML site from your knowledge base
• Hook system — Run custom scripts on article lifecycle events (pre/post create, update, delete, build)
• Template system — Customizable article templates with variable expansion
• AI tool integration — kami install sets up skills for Claude Code, Codex, and Gemini; agents are stamped via the KAMI_AGENT env var
• JSON output — --json flag on all commands for machine-readable output

Requirements

• Bun >= 1.0.0

Installation

bun install -g @kami-pkm/kami

Quick Start

# Initialize a knowledge base in the current project
kami init

# Create an article
kami create "My First Article" --folder notes --tag getting-started

# List articles
kami list

# Search
kami search "keyword"

# Articles updated in the last 2 hours
kami recent --since 2h

# Read an article
kami read my-first-article

# Start the Web UI
kami serve

Scopes

kami uses a multi-scope architecture to separate project-specific and shared knowledge:

| Scope | Path | Purpose | | ------ | ---------- | --------------------------------------- | | global | ~/.kami/ | Knowledge shared across all projects | | local | ./.kami/ | Project-specific knowledge (ADRs, etc.) |

• Read: Local scope first, falls back to global
• Write: Local scope if present, otherwise global
• --scope flag: Explicitly specify local, global, or all

The global scope can point at any number of named vaults; switch between them with kami vault use <name>.

CLI Commands

| Command | Description | | ------------- | ------------------------------------------------------ | | init | Initialize a new local scope | | create | Create a new article | | read | Read article content (--expand-links for linked excerpts) | | edit | Edit metadata, body, or a specific heading section | | delete | Delete an article | | list | List articles with filters, sort, and --where | | search | Full-text search | | recent | Articles updated within a sliding time window | | similar | Find articles related to a given slug | | links | Show forward links from an article | | backlinks | Show backlinks to an article | | move | Move an article to a different folder | | tag rename | Rename a tag across all matching articles | | batch | Execute many operations from JSON Lines input | | template | Manage templates (list, show, create) | | vault | Manage named global-scope vaults (list/add/use/remove) | | export | Export articles as Markdown or HTML | | reindex | Rebuild search index and link graph | | build | Build static HTML site | | serve | Start the web server | | install | Install kami skill for AI coding tools | | help | Show command catalog (use --json for machine output) |

Use kami <command> --help for detailed usage of each command.

JSON Mode

All commands support --json for machine-readable output, making kami ideal for integration with AI coding agents:

kami list --json
kami search "query" --json
kami read my-article --json --expand-links

For higher throughput, kami batch reads NDJSON from stdin and emits one JSON envelope per input line.

Wiki Links

Use [[slug]] syntax in article bodies to create cross-references between articles. kami automatically tracks forward links and backlinks:

kami links my-article             # Show outgoing links
kami backlinks my-article         # Show incoming links
kami read my-article --expand-links   # Inline linked-article excerpts

Templates

kami ships with built-in templates (note, daily) and supports custom templates:

kami template list             # List available templates
kami template show note        # Show template content
kami create "Title" -T daily   # Create article from template

Templates support variable expansion: {{title}}, {{date}}, {{datetime}}, {{folder}}.

Hooks

Run custom scripts on article lifecycle events. Configure hooks in hooks.json within a scope directory:

Supported events: article:pre-create, article:post-create, article:pre-update, article:post-update, article:pre-delete, article:post-delete, build:pre, build:post

Pre-event hooks can block operations; post-event hooks run as notifications.

Web UI

Start a web server to browse, search, and edit articles in the browser:

kami serve              # Start on default port 3000
kami serve --port 8080  # Custom port

Static Site Generation

Build a static HTML site from your knowledge base:

kami build              # Full build
kami build --clean      # Clean and rebuild

AI Tool Integration

Install kami as a skill for AI coding tools:

kami install                                       # Interactive setup
kami install --target claude-code --level project  # Non-interactive

Supported targets: claude-code, codex, gemini

Set KAMI_AGENT=<id> (e.g. claude-code) so created/updated articles are stamped with created_by / updated_by provenance fields.

Development

bun install
bun test           # Run tests
bun run typecheck  # Type check

License

MIT