# open-zk-kb

> Shared, persistent memory for agents, built on the Zettelkasten method

Shared, persistent memory for agents, built on the Zettelkasten method. One knowledge base for all your tools — so context persists across sessions and clients. Stores atomic notes (decisions, preferences, patterns, procedures, context) as linked Markdown files with wiki-links, full-text search (SQLite FTS5), and local semantic embeddings.

## Installation

Requires Bun runtime.

```bash
bunx open-zk-kb@latest
```

The interactive installer adds the MCP server to your client config and installs knowledge base instructions.

## MCP Tools (10 tools)

### knowledge-search
Search the knowledge base for relevant context. Uses full-text search (SQLite FTS5) and local semantic embeddings (MiniLM-L6-v2). No API key required.

Parameters:
- query (string, required): Natural language search query
- kind (string, optional): Filter by note kind
- tags (array, optional): Filter by tags
- limit (number, optional): Max results (default 10)

### knowledge-store
Store a note with one concept. Notes have YAML frontmatter and Markdown content. Returns related notes by similarity.

Parameters:
- title (string, required): Note title
- content (string, required): Note content
- kind (string, required): personalization, reference, decision, procedure, resource, observation, or domain. Note: index and log are auto-generated and cannot be set manually
- summary (string, required): One-line takeaway
- guidance (string, required): Imperative instruction for future agents
- tags (array, optional): Categorization tags
- related (array, optional): IDs of related notes for wikilinks

### knowledge-template
Get the canonical note template for a specific kind. Returns skeleton structure with positive and negative examples.

Parameters:
- kind (string, required): The note kind to get the template for

### knowledge-mine
Bulk-screen candidate notes for duplicates and optionally store. Accepts candidates extracted from session history or other sources.

Parameters:
- candidates (array, required): Array of candidate notes with title, content, kind, summary, guidance
- dry_run (boolean, optional): Preview only without storing (default: true)
- project (string, optional): Scope all mined notes to a project

### knowledge-health
Operational metrics and health dashboard for the knowledge base.

Parameters:
- project (string, optional): Scope stats to a project
- period (string, optional): "7d", "30d" (default), or "90d"
- telemetry (boolean, optional): Include local-only tool invocation aggregates

### knowledge-maintain
Maintenance actions for the knowledge base.

Parameters:
- action (string, required): review, promote, archive, delete, rebuild, embed, dedupe, unlinked, broken-links, link-health, full, migrate-layout, format

### knowledge-ingest
Extract article content from URLs or raw HTML into clean markdown. Returns title, content, word count, and metadata.

Parameters:
- url (string, optional): URL to fetch and extract
- html (string, optional): Raw HTML to extract (preferred — pass HTML from your web tools)

### knowledge-context
Get a knowledge base overview with computed inventory (note counts by kind, recent notes, resources) and recent log entries.

Parameters:
- project (string, optional): Project name to scope the overview
- logEntries (number, optional): Number of recent log entries to include (default 10)

### knowledge-open
Open the knowledge base vault in Obsidian. Detects Obsidian installation, registers the vault, and launches with a scaffolded theme, plugins, and homepage.

Parameters:
- project (string, optional): Project to focus on after opening

### knowledge-get
Retrieve a single note by its exact ID. Faster and more precise than knowledge-search. Use when you already know the note ID (e.g. from search results or context hints).

Parameters:
- noteId (string, required): Exact note ID to retrieve

## Zettelkasten Concepts

The Zettelkasten ("slip box") method stores one atomic concept per note, with explicit links between related ideas. This enables emergent knowledge discovery as the network grows.

### Note Kinds

- personalization: User preferences, habits, personal style (permanent by default)
- reference: Technical facts, API details, documentation snippets (fleeting by default)
- decision: Architectural choices, project commitments, trade-offs (permanent by default)
- procedure: Step-by-step workflows, recurring tasks (fleeting by default)
- resource: Links, tools, libraries, external documentation (permanent by default)
- observation: Insights, patterns, temporary findings (fleeting by default)
- domain: Project operating manuals — agent role, scope, conventions, boundaries (permanent by default)
- index: Auto-generated project catalog with wikilinks grouped by kind (permanent, auto-generated only)
- log: Auto-generated chronological operations log with bold date entries (permanent, append-only, auto-generated only)

### Note Lifecycle

Notes follow the Zettelkasten lifecycle: fleeting (temporary captures) → permanent (reviewed and linked) → archived (no longer active). Wiki-links (`[[note-slug]]`) connect related notes, building an interconnected knowledge graph.

## Supported Clients

OpenCode, Claude Code, Cursor, Windsurf, Zed, Pi, OMP

## Links

- Repository: https://github.com/mrosnerr/open-zk-kb
- npm: https://www.npmjs.com/package/open-zk-kb
- Documentation: https://github.com/mrosnerr/open-zk-kb/tree/main/docs