# kb0

> The knowledge base layer for AI agents. Markdown-first, MCP-native, git-backed, with per-agent permissions (ACL) and provenance built in. Every note is a markdown file; every write is a git commit signed by the agent identity.

kb0 runs as a local MCP server. An agent connects over MCP (stdio) and gets 10 typed tools to read, write, search, and link notes in a "vault" (a git repo of markdown). The npm package `kb0-mcp` provides the server (the `kb0` binary) plus a TypeScript client; the PyPI package `kb0-mcp` provides a Python client.

## Install & run

- Install: `npm install -g kb0-mcp` (Node >= 20) — provides the `kb0` command.
- Create a vault: `kb0 init my-vault` — git-inits a folder with an `_inbox/`.
- Serve over MCP: `kb0 serve --agent <name> --vault <path>` — add `--strict` to require an ACL policy file.
- Env vars: `KB0_VAULT_DIR`, `KB0_AGENT`, `KB0_STRICT=1`, `OPENAI_API_KEY` (enables semantic search; without it, search is keyword-only).

## Wire into an MCP host (Claude Desktop, Cursor, Claude Code, Windsurf)

Add to the host's MCP config (e.g. `claude_desktop_config.json`, or a project `.mcp.json`). Use an ABSOLUTE vault path:

    {
      "mcpServers": {
        "kb0": {
          "command": "kb0",
          "args": ["serve", "--agent", "claude", "--vault", "/absolute/path/to/vault"],
          "env": { "OPENAI_API_KEY": "sk-..." }
        }
      }
    }

## The 10 MCP tools

- `vault.search(query, { mode?: 'hybrid'|'semantic'|'keyword', ranking?: 'rrf'|'weighted', limit?, filters? })`
- `vault.read(path)` → `{ path, hash, content, frontmatter }`
- `vault.list({ prefix?, tag?, status?, limit? })`
- `vault.write(path, { title, content, status?, tags? })` → `{ path, hash, id }`
- `vault.update(path, { content, expectedHash, title?, status?, tags? })` → `{ path, hash }`
- `vault.delete(path)`
- `vault.backlinks(path)` / `vault.links(path)`
- `vault.recent(limit)`
- `vault.status()`

## Conventions an agent must follow

- **Provenance is server-owned.** `author`, `id`, `created`, `updated` are set from the agent identity. Do NOT pass them — you cannot forge who wrote a note. Pass only `title`, `content`, `status`, `tags`.
- **Optimistic locking.** `vault.update` requires an `expectedHash` from a prior `vault.read`. On a `CONFLICT` error, re-read to get the current hash, then retry.
- **Inbox pattern.** Agents write drafts to `_inbox/`; humans or a curator agent promote them to canonical paths (e.g. `notes/`). Don't write straight to canonical unless that is the workflow.
- **ACL.** `.vault-policy.yaml` grants globs per agent per operation (read/write/update/delete). Permissive by default. `ACL_DENIED` is intentional, not a bug.
- **Links.** `[[path/to/note.md]]` wikilinks are indexed — query relationships with `vault.backlinks` / `vault.links`.
- **Errors are typed:** `NOT_FOUND`, `CONFLICT`, `VALIDATION`, `ACL_DENIED` — all structured and recoverable.

## Native clients (instead of raw MCP)

- **TypeScript** — `npm i kb0-mcp`, then:

      import { VaultClient } from 'kb0-mcp/client';
      const kb = await VaultClient.connect({ vault: './my-vault', agent: 'bot' });
      await kb.write('notes/x.md', { title: 'X', content: '...' });
      await kb.close();

- **Python** — `pip install kb0-mcp`, then `from kb0 import VaultClient` (async context manager).

## Hosted vaults (kb0 cloud)

The vault address picks the backend: a filesystem path is local; `kb0://<name>` addresses one of your NAMED hosted vaults on the kb0 cloud (create/rename vaults in the dashboard; the default vault is used by clients that send no name). An unknown name fails with NOT_FOUND — do not invent vault names. Hosted needs an API key (created in the dashboard at https://cloud.kb0.dev) — pass `apiKey` (TS) / `api_key=` (Python) or set `KB0_API_KEY`. Same 10 tools; hosted search is keyword today. Setting `KB0_API_KEY` on a LOCAL vault forwards a content-free, hash-chained audit trail (every read/search/write — paths and queries, never note bodies) to the same dashboard.

      // TS:     VaultClient.connect({ vault: 'kb0://team-kb', agent: 'bot', apiKey: KB0_API_KEY })
      #  Python: async with VaultClient(vault="kb0://team-kb", agent="bot", api_key=KB0_API_KEY) as kb: ...

## Docs

- Repo: https://github.com/vitorchristoval/kb0
- Quickstart (Claude Desktop): https://github.com/vitorchristoval/kb0/blob/main/docs/quickstart-claude-desktop.md
- SDK (Anthropic / OpenAI / LangGraph): https://github.com/vitorchristoval/kb0/blob/main/docs/quickstart-sdk.md
- Architecture: https://github.com/vitorchristoval/kb0/blob/main/docs/architecture.md
- npm: https://www.npmjs.com/package/kb0-mcp · PyPI: https://pypi.org/project/kb0-mcp