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.

Beta — This project is under active development (0.1.x). Core functionality works but APIs may change. Bug reports and feedback are welcome.

Still in beta while we:

• [ ] Get more real-world usage across supported MCP clients
• [ ] Smooth out setup and instruction injection edge cases
• [ ] Lock down the MCP tool/API surface for a 1.0 release

Demo

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. Injects knowledge base instructions into your client's instruction file (AGENTS.md, CLAUDE.md, or rules file)
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:

| Tool | What it does | |------|-------------| | knowledge-search | Search the knowledge base before starting work | | knowledge-store | Save decisions, preferences, procedures, and insights | | knowledge-maintain | Review, promote, archive, and rebuild notes |

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

| Kind | Default Status | Use Case | |------|----------------|----------| | personalization | permanent | User preferences, habits, and personal style | | reference | fleeting | Technical facts, API details, and documentation snippets | | decision | permanent | Architectural choices, project commitments, and trade-offs | | procedure | fleeting | Step-by-step workflows and recurring tasks | | resource | permanent | Links, tools, libraries, and external documentation | | observation | fleeting | Insights, patterns, and temporary findings |

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

If you prefer manual configuration, add open-zk-kb to your client's MCP config file. No cloning required — the npm package includes everything.

Note: Manual install only adds the MCP server. To also inject the agent instructions, run bunx open-zk-kb@latest install --client <name> or add the contents of agent-instructions-full.md (or agent-instructions-compact.md for token-constrained clients) to your client's instruction file.

OpenCode

~/.config/opencode/opencode.json

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

Claude Code

~/.claude/settings.json

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

Cursor

~/.cursor/mcp.json

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

Windsurf

~/.codeium/windsurf/mcp_config.json

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

Zed

~/.config/zed/settings.json

{
  "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