{
  "markdown": "# open-zk-kb\n\n[![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)\n[![npm version](https://img.shields.io/npm/v/open-zk-kb)](https://www.npmjs.com/package/open-zk-kb)\n[![npm downloads](https://img.shields.io/npm/dm/open-zk-kb)](https://www.npmjs.com/package/open-zk-kb)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nYou 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.\n\nopen-zk-kb gives your agent a memory — so corrections stick, context compounds, and every session starts smarter than the last.\n\n<p align=\"center\">\n  <a href=\"docs/pi.md\">\n    <img src=\"assets/pi-demo.gif\" alt=\"Store, apply, inspect, and remove an automatic preference in Pi\" width=\"760\">\n  </a>\n  <br>\n  <sub>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.</sub>\n</p>\n\n## Quick start\n\n> **Requires [Bun](https://bun.sh)** — install with `curl -fsSL https://bun.sh/install | bash`\n\n```bash\nbunx open-zk-kb@latest\n```\n\nThe installer configures your selected clients, installs agent instructions, and creates a local vault. Supported clients: **OpenCode**, **Claude Code**, **Cursor**, **Windsurf**, **Zed**, **Pi**, and **OMP**.\n\nSee the [Setup Guide](docs/setup-guide.md) for manual installation and troubleshooting.\n\n## Why open-zk-kb?\n\nYour 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.\n\nopen-zk-kb fixes that.\n\n- **Correct it once, it sticks** — your agent stores corrections, preferences, and decisions. Next session, it already knows.\n- **Works across every tool** — one knowledge base shared by [Claude Code, Cursor, Windsurf, OpenCode, Zed, Pi, and OMP](docs/setup-guide.md)\n- **Finds what's relevant** — hybrid search matches meaning, not just keywords, so only useful context surfaces\n- **Runs locally** — no API keys, no cloud, works offline. Your data stays on your machine.\n- **Human-readable** — plain Markdown files [you can browse, edit, and version control](docs/architecture.md#dual-storage-model)\n- **Open source** — MIT licensed\n\n## Pi: native knowledge tools\n\nInstall the Pi package, then restart Pi:\n\n```bash\npi install npm:open-zk-kb\n```\n\nThe 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.\n\nPi 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.\n\nSee the [Pi experience guide](docs/pi.md) for the complete preference workflow and renderer examples. For installer-managed instructions, verification, and troubleshooting, see [Pi installation](docs/setup-guide.md#pi-installation).\n\n## Configuration\n\nZero configuration required. Local embeddings work out of the box with no API key.\n\nSee the [Configuration Guide](docs/configuration.md) for embeddings, vault path, lifecycle tuning, and server settings.\n\n## Under the hood\n\nBuilt 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.\n\nSearch 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.\n\n## Telemetry\n\nWhen enabled (`telemetry.enabled: true` and `telemetry.share: true`), open-zk-kb sends one anonymous event for each completed session to [PostHog](https://posthog.com) (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](docs/telemetry.md) for the full event schema and details.\n\n## Documentation\n\n- [Setup Guide](docs/setup-guide.md) — installation, client-specific setup, troubleshooting\n- [Pi Experience](docs/pi.md) — native tools, automatic preferences, and renderer gallery\n- [Tools Reference](docs/tools-reference.md) — all 10 MCP tools with parameters and examples\n- [Note Lifecycle](docs/note-lifecycle.md) — note kinds, statuses, review system\n- [Configuration](docs/configuration.md) — embeddings, vault, lifecycle, and server settings\n- [Architecture](docs/architecture.md) — dual storage, ownership model, design decisions\n- [Development](docs/development.md) — local dev, testing, debugging\n- [Contributing](.github/CONTRIBUTING.md) — guidelines for contributors\n\n## License\n\n[MIT License](LICENSE)\n",
  "bytes": 5664,
  "sha": "5c2a1c05601fab60b0856d37343b71e225ec5b3e4d4b141efb038e42e307e8fa",
  "repo_slug": "mrosnerr/open-zk-kb",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mrosnerr_open_zk_kb_d5f888cd/readme"
}