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

<p align="center"> <img src="assets/demo.gif" alt="open-zk-kb demo" width="640"> <br> _{Real MCP calls — store, search, and stats run against a live knowledge base.} </p>

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:

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.

<details> <summary><h2>Manual Install</h2></summary>

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"]
    }
  }
}

</details>

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