<div align="center">

kb-mcp

An agent-native knowledge base.

pip install kb-mcp — give any LLM agent a structured, queryable, local-first second brain.

</div>

---

The problem

Knowledge bases for humans (Notion, Obsidian) and for search engines (Elasticsearch, vector DBs) leave a gap: LLM agents need a knowledge layer that speaks their protocol and assumes the reader is a model, not a person.

kb-mcp fills it.

	Obsidian / Notion	Vector DBs (Chroma / LanceDB)	kb-mcp
Reader-optimised for	Humans	Embeddings	LLM agents
Protocol	Web UI	SDK	MCP (stdio)
Schema	Free-form	Free-form	Typed (project / decision / lesson / ...)
Default storage	Cloud / proprietary	Local files	SQLite + FTS5
Setup	Sign up	pip install + configure	pip install and go

---

Features

• 🧠 Agent-native. Every document is reachable from any MCP client (Claude Desktop, Cursor, OpenCode, Codex, …) via kb_search / kb_get / kb_add / kb_link.
• 📐 Schema-first. Six built-in document types (project, decision, lesson, glossary, person, faq) — extensible via Python subclassing.
• 🔍 Full-text search. SQLite FTS5 with BM25 ranking. Snippet-aware results returned to the agent.
• 🔗 Typed links. Documents reference other documents; backlinks are automatic.
• 📝 Markdown friendly. Round-trip import/export with frontmatter. Humans can edit, agents can read.
• 🪶 Zero deps by default. SQLite ships with Python. pip install kb-mcp and you're done.
• 🔒 Local-first. Your data lives in ~/.local/share/kb-mcp/. No cloud, no telemetry, no phone-home.

---

Quickstart

pip install kb-mcp
kb init
kb add --type project --title "kb-mcp" --tags kb,mcp,open-source --body "Agent-native knowledge base."
kb search "mcp server"

# Expose to any MCP client
kb serve

That's it. Five commands, zero config files.

👉 Full walkthrough: docs/quickstart.md

---

Document types

Type	Purpose	Example
project	Repo / initiative background	kb-mcp, micro-app-fork
decision	Architecture Decision Record (ADR)	"Use SQLite FTS5 over Elasticsearch"
lesson	Post-mortem / lessons learned	"Don't last_insert_rowid() across multi-INSERT batches"
glossary	Term definitions	FTS5, MCP, ADR
person	People the agent should recognise	"Zhang Bei, owner, uses Hermes"
faq	Frequently asked questions	"Why SQLite?"

Subclass kb_mcp.schema.Document to add your own.

---

MCP integration

Add to ~/.config/claude_desktop_config.json (or any MCP client):

{
  "mcpServers": {
    "kb": {
      "command": "kb",
      "args": ["serve"]
    }
  }
}

The agent then sees four tools:

• kb_search(query, type?, tags?, limit?) — BM25-ranked results with snippets
• kb_get(id) — full document by id (or slug)
• kb_add(type, title, body, tags?, source?) — create document
• kb_link(from_id, to_id, rel?) — typed edge between documents

---

Development

git clone https://github.com/your-org/kb-mcp
cd kb-mcp
pip install -e ".[dev]"
pytest          # unit + E2E (real SQLite temp file, no mocks)
ruff check .
mypy src/

👉 Spec: docs/requirements.md · Architecture: docs/architecture.md · CLI reference: docs/cli-reference.md

---

Roadmap

Version	Scope	Status
v0.1.0	CLI + MCP server + SQLite/FTS5 + 6 doc types + Markdown I/O	🚧 in progress
v0.2.0	Vector search (sqlite-vss) as opt-in, hybrid BM25 + embedding ranking	planned
v0.3.0	Multi-vault (per-project isolated KBs) + shared-vault mode	planned
v0.4.0	Web UI (read-only) + collaborative editing hints	exploring
v1.0.0	Postgres backend, multi-user auth, hosted mode	exploring

See docs/requirements.md § 4 for v0.1 scope decisions and out-of-scope list.

---

Status

alpha. API and storage format may change before v0.2.0. Pin minor versions (kb-mcp>=0.1,<0.2) in production.

---

Contributing

Issues and PRs welcome. See CONTRIBUTING.md (TODO before v0.1.0 release).

By participating, you agree to abide by the Code of Conduct (TODO before v0.1.0 release).

---

License

MIT — do what you want, just keep the copyright notice.