Open Zk Kb README
The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Open Zk Kb listing page.
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.
The full loop in Pi: store a preference, carry it into a fresh session, inspect the vault, and remove it when it stops being useful.
Quick start
Requires Bun — install with
curl -fsSL https://bun.sh/install | bash
The installer configures your selected clients, installs agent instructions, and creates a local vault. Supported clients: OpenCode, Claude Code, Cursor, Windsurf, Zed, Pi, and OMP.
See the Setup Guide for manual installation and troubleshooting.
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
Pi: native knowledge tools
Install the Pi package, then restart Pi:
The extension exposes all ten knowledge-* tools directly in Pi. Results use Pi-native compact rendering: search, store, context, and health have focused summaries and expandable detail, while the other tools show concise status output. The MCP server and local SQLite/embedding work still run with Bun >= 1.0; Pi itself runs under its supported Node.js runtime. Installing Bun is therefore required even when using the Pi package.
Pi also loads active project preferences automatically when a session starts and injects them into model context without requiring a model-initiated search. The visible knowledge-context entry reports what happened without fabricating a tool call.
See the Pi experience guide for the complete preference workflow and renderer examples. For installer-managed instructions, verification, and troubleshooting, see Pi installation.
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 server settings.
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.
Telemetry
When enabled (telemetry.enabled: true and telemetry.share: true), open-zk-kb sends one anonymous event for each completed session to PostHog (EU Cloud) on a later startup. It includes a canonical client, bounded model IDs, vault size, and counts for all ten tools—not note content, queries, paths, names, or email addresses. Runtime defaults are disabled; the interactive installer enables sharing only after affirmative consent, while unattended and direct package installs remain disabled unless configured separately. Set DO_NOT_TRACK=1 to unconditionally block sharing (local SQLite counters are unaffected), or keep both flags false. See Telemetry for the full event schema and details.
Documentation
- Setup Guide — installation, client-specific setup, troubleshooting
- Pi Experience — native tools, automatic preferences, and renderer gallery
- Tools Reference — all 10 MCP tools with parameters and examples
- Note Lifecycle — note kinds, statuses, review system
- Configuration — embeddings, vault, lifecycle, and server settings
- Architecture — dual storage, ownership model, design decisions
- Development — local dev, testing, debugging
- Contributing — guidelines for contributors