--- slug: "open-zk-kb" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/mrosnerr/open-zk-kb@main/README.md" repo: "https://github.com/mrosnerr/open-zk-kb" source_file: "README.md" branch: "main" --- # open-zk-kb [![CI](https://github.com/mrosnerr/open-zk-kb/actions/workflows/ci.yml/badge.svg)](https://github.com/mrosnerr/open-zk-kb/actions/workflows/ci.yml) [![npm version](https://img.shields.io/npm/v/open-zk-kb)](https://www.npmjs.com/package/open-zk-kb) [![npm downloads](https://img.shields.io/npm/dm/open-zk-kb)](https://www.npmjs.com/package/open-zk-kb) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 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.

Store, apply, inspect, and remove an automatic preference in Pi
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](https://bun.sh)** — install with `curl -fsSL https://bun.sh/install | bash` ```bash bunx open-zk-kb@latest ``` 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](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/setup-guide.md) 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](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/setup-guide.md) - **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](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/architecture.md#dual-storage-model) - **Open source** — MIT licensed ## Pi: native knowledge tools Install the Pi package, then restart Pi: ```bash pi install npm:open-zk-kb ``` 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](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/pi.md) for the complete preference workflow and renderer examples. For installer-managed instructions, verification, and troubleshooting, see [Pi installation](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/setup-guide.md#pi-installation). ## Configuration Zero configuration required. Local embeddings work out of the box with no API key. See the [Configuration Guide](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/configuration.md) 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 anonymous session analytics to [PostHog](https://posthog.com) (EU Cloud) — which client and models you use, vault size, and tool usage counts. No note content, search queries, file paths, names, or email addresses are collected. Runtime configuration defaults remain disabled; the interactive installer asks for consent with **Yes** preselected and enables sharing only after confirmation. Non-interactive and direct package installs remain disabled unless configured separately. Set `DO_NOT_TRACK=1` to unconditionally block sharing (local SQLite counters are unaffected), or set both flags to `false`. See [Telemetry](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/telemetry.md) for the full event schema and details. ## Documentation - [Setup Guide](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/setup-guide.md) — installation, client-specific setup, troubleshooting - [Pi Experience](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/pi.md) — native tools, automatic preferences, and renderer gallery - [Tools Reference](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/tools-reference.md) — all 10 MCP tools with parameters and examples - [Note Lifecycle](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/note-lifecycle.md) — note kinds, statuses, review system - [Configuration](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/configuration.md) — embeddings, vault, lifecycle, and server settings - [Architecture](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/architecture.md) — dual storage, ownership model, design decisions - [Development](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/docs/development.md) — local dev, testing, debugging - [Contributing](https://github.com/mrosnerr/open-zk-kb/blob/HEAD/.github/CONTRIBUTING.md) — guidelines for contributors ## License [MIT License](https://github.com/mrosnerr/open-zk-kb/tree/HEAD/LICENSE)