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

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 (9 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
• Obsidian-native — browse your knowledge graph, navigate by kind, and explore connections visually
• 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

See the Setup Guide for manual installation, client-specific configs, and troubleshooting.

Configuration

Zero configuration required. The installer creates ~/.config/open-zk-kb/config.yaml with sensible defaults — local embeddings work out of the box with no API key.

See the Configuration Reference for embeddings, vault path, lifecycle tuning, and Obsidian scaffold options.

Development

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

Documentation

• Setup Guide — installation, manual config, client-specific setup, troubleshooting
• Tools Reference — all 8 MCP tools with parameters and examples
• Note Lifecycle — 9 note kinds, statuses, review system, promotion
• Configuration — embeddings, vault, logging, Obsidian scaffold
• Obsidian Guide — managed scaffold, 14 plugins, navigation, screenshots
• Architecture — dual storage, ownership model, design decisions
• Development — local dev, testing, debugging, adding tools
• Contributing — guidelines for contributors

License

MIT License