open-zk-kb

open-zk-kb

Shared, persistent memory for AI assistants, built on the Zettelkasten method. One knowledge base for all your tools — so context persists across sessions and clients.

Demo

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

Why open-zk-kb?

AI 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:

• Adds the MCP server to your client config
• Installs knowledge base instructions (skill for Claude Code, managed block for OpenCode/Windsurf)
• 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.

Manual Install

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