open-zk-kb

You open a new session and your agent has no idea who you are. Again. You re-explain your stack, your conventions, that one edge case you've corrected five times.

open-zk-kb gives your agent a memory — so corrections stick, context compounds, and every session starts smarter than the last.

<p align="center"> <img src="assets/demo.gif" alt="open-zk-kb demo" width="640"> <br> _{Your agent stores what it learns and searches it next session — automatically.} </p>

Why open-zk-kb?

Your agent starts from zero every session. No memory, no learning curve. You correct the same mistakes, re-explain the same conventions, re-teach the same context. Switch tools and it's even worse — your Cursor agent doesn't know what your Claude agent learned.

open-zk-kb fixes that.

• Correct it once, it sticks — your agent stores corrections, preferences, and decisions. Next session, it already knows.
• Works across every tool — one knowledge base shared by Claude Code, Cursor, Windsurf, OpenCode, Zed, Pi, and OMP
• Finds what's relevant — hybrid search matches meaning, not just keywords, so only useful context surfaces
• Runs locally — no API keys, no cloud, works offline. Your data stays on your machine.
• Human-readable — plain Markdown files you can browse, edit, and version control
• Open source — MIT licensed

How it works

1. You install it — one command, picks up your client automatically
2. Your agent stores what it learns — corrections, preferences, decisions, gotchas, workflows
3. Next session, it searches first — relevant context surfaces before your agent writes a single line

Your agent gets sharper the longer you use it — for your specific workflow.

Browse your notes in Obsidian

Your knowledge base is a fully themed Obsidian vault — homepage dashboard, kind-based folders with icons, breadcrumb navigation, and quick-add buttons. No manual setup.

<p align="center"> <img src="assets/obsidian-home.png" alt="Knowledge base in Obsidian" width="640"> <br> _{Homepage with project stats, navigation, and your full knowledge graph.} </p>

See the Obsidian Guide for the full walkthrough.

Quick start

Requires [Bun](https://bun.sh) — 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 so your agent knows when and how to use it
3. Creates a local vault at ~/.local/share/open-zk-kb

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

See the Setup Guide for manual installation and troubleshooting.

Configuration

Zero configuration required. Local embeddings work out of the box with no API key.

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

Under the hood

Built on the Zettelkasten method — atomic, linked notes with structured kinds. Each note captures one concept (a decision, a preference, a gotcha) and links to related notes, building an interconnected knowledge graph.

Search combines SQLite FTS5 full-text indexing with local vector embeddings (MiniLM-L6-v2) for semantic matching. Markdown files are the source of truth; the database is a rebuildable index.

Documentation

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

License

MIT License