open-zk-kb

Persistent knowledge base for AI coding assistants. Stores decisions, preferences, patterns, and context as searchable Markdown notes — so your assistant remembers across sessions.

Demo

_{Real MCP calls — store, search, and stats run against a live knowledge base.}

Why open-zk-kb?

AI coding assistants forget everything between sessions. open-zk-kb gives your assistant a persistent, structured memory it queries automatically.

• Hybrid search — full-text + local embeddings, so only relevant notes surface
• Atomic notes — one concept per note (6 kinds, lifecycle management) keeps results precise
• Local-first — no API keys, works offline, scales to thousands of notes
• Human-readable — Markdown + YAML frontmatter, rebuildable from files
• Shared memory across tools — one knowledge base for OpenCode, Claude Code, Cursor, Windsurf, and Zed
• MIT-licensed

Quick Start

Requires Bun — install with curl -fsSL https://bun.sh/install | bash

bunx open-zk-kb@latest

That's it. The interactive installer:

1. Adds the MCP server to your client config
2. Installs knowledge base instructions (skill for Claude Code, managed block for OpenCode/Windsurf)
3. Creates a local vault at ~/.local/share/open-zk-kb

Supported clients: OpenCode, Claude Code, Cursor, Windsurf, Zed

How It Works

Your AI assistant gets three MCP tools:

The installer injects instructions that guide the AI to proactively search for relevant context before starting work and store valuable knowledge as it discovers it. No plugin required — the AI drives everything through tool calls.

Notes are stored as Markdown files with YAML frontmatter. A SQLite index provides fast full-text search, with local vector embeddings for semantic matching. No API key needed.

Configuration

Zero configuration required for basic usage. The installer creates ~/.config/open-zk-kb/config.yaml automatically.

To use an API provider for embeddings instead of local models:

embeddings:
  provider: "api"
  base_url: "https://openrouter.ai/api/v1"
  api_key: "your-api-key-here"
  model: "openai/text-embedding-3-small"
  dimensions: 1536

Any OpenAI-compatible API works (OpenRouter, Together, Groq, local vLLM, etc.). See docs/configuration.md for the full reference.

Note Kinds

Notes follow a lifecycle: fleeting → permanent → archived. See Note Lifecycle for details.

{
  "mcp": {
    "open-zk-kb": {
      "type": "local",
      "command": ["bunx", "open-zk-kb@latest", "server"],
      "enabled": true
    }
  }
}

{
  "mcpServers": {
    "open-zk-kb": {
      "command": "bunx",
      "args": ["open-zk-kb@latest", "server"]
    }
  }
}

{
  "mcpServers": {
    "open-zk-kb": {
      "command": "bunx",
      "args": ["open-zk-kb@latest", "server"]
    }
  }
}

{
  "mcpServers": {
    "open-zk-kb": {
      "command": "bunx",
      "args": ["open-zk-kb@latest", "server"]
    }
  }
}

{
  "context_servers": {
    "open-zk-kb": {
      "command": "bunx",
      "args": ["open-zk-kb@latest", "server"]
    }
  }
}

Development

git clone https://github.com/mrosnerr/open-zk-kb
cd open-zk-kb
bun install && bun run build
bun run setup            # interactive installer

Links

• Setup Guide — installation, instruction injection, verification
• Tools Reference — all 3 MCP tools, parameters, examples
• Configuration Reference — embeddings, vault, logging
• Note Lifecycle — statuses, review, promotion
• Architecture Design — system design, dual storage, instruction injection
• Development & Contributing — local dev, testing, debugging
• Contributing Guidelines

License

MIT License