README
¶
mdkb
Local-first knowledge base over plain Markdown files. One Go binary: CLI plus MCP server, FTS5 keyword search, opt-in local embeddings, Obsidian-style wikilinks and backlinks, git-committed agent writes. Your files stay the source of truth.
Status: v0.1.0 released 2026-11-01 after a two-platform skeptic round (#15–#23 fixed). Semantic search is opt-in; its real-model evaluation on the Mac Studio is still pending. See the plan and the changelog.
Install
After v0.1.0 and its tap formula are published:
brew install contractorkeith/tap/mdkb
From source (Go 1.27 required):
go install github.com/ContractorKeith/mdkb/cmd/mdkb@latest
export PATH="$(go env GOPATH)/bin:$PATH"
Source installs report mdkb dev; release binaries report the release tag.
Or download the matching macOS/Linux amd64/arm64 tarball from
GitHub Releases, verify it
against checksums.txt (sha256sum on Linux, shasum -a 256 on macOS), extract
it, and place mdkb on your PATH. Git on PATH enables commits for writes.
macOS tarball binaries are unsigned, so Gatekeeper may block them. Prefer
Homebrew or go install. After verifying the checksum, you can remove the
download quarantine with xattr -d com.apple.quarantine mdkb.
Quick start (60 seconds)
# A new, separate scratch KB; explicit roots keep existing folders untouched.
example_root="$(mktemp -d)/mdkb-example"
mdkb init "$example_root"
mdkb --root "$example_root" new "Welcome" --body 'A local Markdown knowledge base.'
mdkb --root "$example_root" new "Ideas" --body 'Start with [[welcome]].'
mdkb --root "$example_root" search 'Markdown'
mdkb --root "$example_root" backlinks welcome
# Register the read-only stdio MCP server in Claude Code:
claude mcp add --scope local mdkb -- "$(command -v mdkb)" --root "$example_root" mcp
claude mcp list
Ask Claude Code to list or search your notes. Add --allow-write after mcp
to enable its two write tools. Every read supports --json; CLI writes support
--dry-run. Optional semantic search uses local Ollama; see
semantic settings and evaluation.
Obsidian relationship
mdkb complements Obsidian: use Obsidian as the editor and mdkb for CLI/agent access.
It owns a separate Markdown folder (default ~/kb). Your existing vault stays
untouched. An import obsidian command is planned after v1; there is no vault
import in this release.
Root precedence: --root > MDKB_ROOT > ~/.config/mdkb/config.toml
(root = "...") > ~/kb. An explicit init [path] wins over configuration.
See MCP setup and tools, CLI output contracts,
fixture notes and Homebrew publishing.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
mdkb
command
|
|
|
internal
|
|
|
app
Package app shares synchronized operations between the CLI and MCP front ends.
|
Package app shares synchronized operations between the CLI and MCP front ends. |
|
embed
Package embed chunks notes and obtains local embedding vectors.
|
Package embed chunks notes and obtains local embedding vectors. |
|
embed/embedtest
Package embedtest provides a deterministic local Ollama double.
|
Package embedtest provides a deterministic local Ollama double. |
|
eval
Package eval measures fixture retrieval against explicit relevance judgments.
|
Package eval measures fixture retrieval against explicit relevance judgments. |
|
index
Package index owns the rebuildable SQLite cache and all SQL access.
|
Package index owns the rebuildable SQLite cache and all SQL access. |
|
kb
Package kb owns all access to knowledge-base files.
|
Package kb owns all access to knowledge-base files. |
|
mcpserver
Package mcpserver exposes the knowledge base over MCP stdio.
|
Package mcpserver exposes the knowledge base over MCP stdio. |
|
search
Package search provides ranked search results over the index.
|
Package search provides ranked search results over the index. |