open-zk-kb

name	open-zk-kb
version	1.4.4
description	This skill should be used when the user asks to "store a note", "save this to the knowledge base", "remember this", "search my notes", "what do I know about X", "review stale notes", "how many notes", "KB stats", "mine sessions", "ingest a URL", "open Obsidian", "what template for a decision", or mentions knowledge base operations. Provides detailed reference for the 10 open-zk-kb MCP tools: knowledge-search, knowledge-store, knowledge-get, knowledge-maintain, knowledge-context, knowledge-template, knowledge-mine, knowledge-health, knowledge-ingest, knowledge-open.
allowed-tools	["mcp__open-zk-kb__knowledge-search","mcp__open-zk-kb__knowledge-store","mcp__open-zk-kb__knowledge-get","mcp__open-zk-kb__knowledge-template","mcp__open-zk-kb__knowledge-maintain","mcp__open-zk-kb__knowledge-ingest","mcp__open-zk-kb__knowledge-context","mcp__open-zk-kb__knowledge-mine","mcp__open-zk-kb__knowledge-open","mcp__open-zk-kb__knowledge-health"]

Ownership and retrieval boundary

Keep project management separate from the knowledge base. Code and tests own executable behavior; Git and issues own change and collaboration history; OpenSpec owns requirements and plans; docs own user-facing explanation; the knowledge base owns durable, reusable guidance not authoritative elsewhere. Do not inject tasks, plans, progress, commits, issue updates, or docs into notes by default.

Use a three-tier context model: compact project context for orientation, targeted search for the task's actual decision, and exact retrieval of one named note only when compact and targeted evidence leave a material gap. Search is task-relevance-gated: do not search or store merely because a session is active. Keep the compact result small, make at most one exact escalation, and prefer zero captures.

Rehoming and archival

For an existing note, choose explicitly:

• Keep it when its concept and destination are correct.
• Distill it when it contains durable guidance mixed with noise.
• Rehome it when the authoritative destination is project-specific: preserve the source, copy or distill into the destination-specific code, test, Git, issue, OpenSpec, or docs record, then verify that record before archiving the note.
• Archive after verification only when the destination is confirmed; otherwise defer.

Use normal destination tools (editor, test runner, Git, issue tracker, or docs workflow), not knowledge tools, for rehoming. For mixed notes, extract only the qualifying concept; do not silently move unrelated material. Preserve → copy/distill → verify → archive. Deletion is separate and explicit; never treat rehoming or archive as delete.

Storing Knowledge

Use knowledge-store with one concept per note only after the precision gate passes. Pass the canonical current project on every call; routine capture is always project-local. Include summary (one-line takeaway) and guidance (imperative instruction for future agents). If multiple genuinely independent candidates each qualify, keep them atomic rather than bundling; do not store nonqualifying material merely to split it. Never use routine store or mine calls to create global knowledge. For structured kinds, knowledge-template --kind {kind} shows full templates with examples.

Kinds (with key sections):

• personalization (~50w) — Preference, Context, Examples, Source
• decision (~150w) — Context, Options Considered, Decision, Tradeoffs Accepted, Consequences, Reversibility
• observation (~100w) — What I Saw, Where, Why It Matters, Implications
• reference (~120w) — Key Excerpts, Original Content
• procedure (~150w) — Trigger, Prerequisites, Steps, Verification, Common Failure Modes, Changelog
• resource (~50w) — What It Is, Why It's Useful, Key References, Notes from Use
• domain (~500w) — Agent Role, Scope, Note Conventions, Operations Playbook, Boundaries, Glossary. One per project; always surfaced in project-scoped searches.

Note: index and log notes are auto-generated by the server for project-scoped events. Never create them manually via knowledge-store.

Notes exceeding the target trigger a soft warning — split if the note covers more than one concept. Client-specific paths (e.g., .cursor/, .claude/) are auto-tagged, so path-specific notes do not need client on store. For harness-specific personalization that does not contain such a path, pass client explicitly to record its applicability.

Precision-first capture

No new note is the default. Routine storage requires every gate:

• Novel: project-visible search found no adequate existing note.
• Durable: useful beyond the current task and transient state.
• Behavior-changing: materially changes a future decision or action.
• Canonical here: better housed in the knowledge base than in code, tests, Git, issues, OpenSpec, documentation, generated logs, or another note.

Exclude progress, completed-work and release summaries, cleanup reports, milestones, immediately resolved findings, transient research, and authoritative records elsewhere. Zero captures is a successful result.

When a candidate qualifies, capture it before evidence is lost rather than harvesting indiscriminately at session end. Explicit requests to remember enduring knowledge receive prompt handling subject to safety, scope, novelty, and canonical-home checks. Search before creating; reuse an adequate note, or use a supported reviewed update for a canonical living note. If no safe update path exists, do not create a duplicate. Normally create zero or one routine note per task; separately justify genuinely independent durable concepts.

Title Convention

Titles are scannable labels (3–6 words), not summaries. Detail belongs in summary.

	Example
✅	"Bun SQLite WAL mode"
✅	"FTS5 over trigram search"
✅	"Release prep checklist"
🚫	"Bun SQLite requires explicit WAL mode for concurrent access" (too long)
🚫	"Database stuff" (too vague)

Limits: max 10 words / 80 chars (hard reject). Over 6 words triggers a soft warning.

Good vs Bad Examples

✅ Good — concise title, correct kind, actionable guidance:

title: "Bun SQLite WAL mode"
kind: "observation"
summary: "SQLite in Bun uses journal mode by default; WAL must be set explicitly."
guidance: "Run `db.exec('PRAGMA journal_mode=WAL')` after opening any Bun SQLite db."

🚫 Bad — vague title, wrong kind, useless guidance:

title: "Database stuff"
kind: "reference"
summary: "Some notes about the database."
guidance: "Check the database."

Kind Selection Guide

Scenario	Kind
User consistently prefers concise answers across work	personalization
User wants tabs in this project because its formatter requires them	decision or domain
Current harness routes requests to a named model	reference (or fleeting if temporary)
We chose PostgreSQL over MySQL after comparing replication	decision
Bun's SQLite requires explicit WAL mode for concurrent access	observation
API endpoint for user creation is POST /api/v2/users	reference
Deploy: run build, tag version, push to registry	procedure
Bun SQLite docs: https://bun.sh/docs/api/sqlite	resource
Project's agent role, scope, conventions, and boundaries	domain

Personalization Boundary

Use personalization only for an enduring user preference or behavioral expectation. Preference wording alone (such as “I prefer” or “use X”) is not sufficient.

Apply the durability test within the declared scope before storing: Would this still help a future agent working in that project or client after the current task and transient implementation, subscription, or configuration change? Universal preferences must also remain broadly useful across projects and clients. If not, use decision, reference, domain, or a fleeting note as appropriate.

Record applicability explicitly using existing scope parameters/tags:

• Project — always pass project on routine storage (stored as exactly one project:<name> tag).
• Client/harness — pass client when applicable (stored as client:<name>).
• Global — do not omit project or add scope:global during routine capture. Publish only a separately distilled, project-agnostic derivative through confirmed maintenance.

Do not store these as general personalization:

• Exact configuration state, such as #1E1E1E, /Users/me/.config/app, or model: claude-3-5-sonnet → reference, or fleeting if temporary.
• Temporary choices, such as “use the Pro subscription this month” or “route to model X for this task” → fleeting reference or decision.
• Project requirements, such as “this repository must use Bun” or “use tabs because the formatter requires them” → decision or domain.
• Feature or implementation requirements, such as “add OAuth to this app” → decision or project-scoped reference/domain guidance.

✅ Durable personalization: “Keep answers concise in every client.” ✅ Scoped personalization: “In Claude Code, ask before running long test suites” with client: "claude-code"; this remains useful across future Claude Code sessions.

Boundaries

✅ Always:

• One concept per note — split if in doubt
• Include both summary and guidance on every store call
• Search before storing to avoid duplicates, passing the current project explicitly

⚠️ Ask first:

• Before archiving or deleting notes you didn't create this session
• Before changing the kind or status of a permanent note

🚫 Never:

• Bundle multiple concepts into one note
• Use vague titles like "Notes" or "Stuff"
• Store sensitive data (API keys, credentials, tokens)
• Store progress, cleanup, completed-work summaries, transient research, or facts authoritative elsewhere
• Create duplicates when an adequate note exists or safe update is unavailable
• Store global or unscoped knowledge through routine tools

Lifecycle

Notes have a lifecycle field controlling mutability. The server enforces it.

Lifecycle	Behavior	Default for
living	Mutable, updated freely	personalization, reference, procedure, resource, domain
snapshot	Immutable after creation	decision, observation
append-only	Additive only, no rewrites	(explicit opt-in)

• Auto-detection: titles with a date (e.g., "Analysis 2026-04-26") auto-set to snapshot.
• Enforcement: snapshot updates and append-only rewrites are rejected by the server. Create a new note instead.

Staleness: Every note includes a staleness_days metric — days since last access (or creation if never accessed). If staleness > 90 days and the note's claim might be outdated, verify before relying on it.

Precision Audit

At review points, check that searches were made before creation, stored notes passed all four gates, and an authoritative home or adequate existing note was not duplicated. Check for rare missed durable, behavior-changing knowledge only after checking overcapture. Present any proposed mutation under existing approval boundaries. A session with zero qualifying candidates is complete.

Ingesting URLs

When a URL may supply durable reusable knowledge, use knowledge-ingest to extract it. Store a resource only if the extracted candidate passes the precision gate; ingestion alone is not a capture requirement.

• With a web tool (Playwright, Exa, web_fetch): fetch first, then knowledge-ingest(html: "...", url: "...") — handles JS rendering and bot protection.
• Without a web tool: knowledge-ingest(url: "...") directly — basic fetch, may fail on protected sites.

Project Overview

Use knowledge-context at the start of a session to orient yourself:

• knowledge-context(project: "example-project") — returns the current project's inventory plus explicitly global notes
• Never omit project on routine stored-knowledge calls; omission does not grant vault-wide access
• Optional: logEntries (number, default 10) to control how many log entries are shown

Maintenance

Maintenance is deliberately full-vault: review, dedupe, rebuild, formatting, embedding repair, audits, migration, and publication may inspect every project and must label ownership. The server computes validation and duplicate evidence; the agent judges what it means and what action to recommend.

Global publication uses publish-global. Author a complete project-agnostic derivative from a project-local source, run a dry-run preview, show the user the evidence, and apply only with explicit confirmation and the matching token. Publication preserves the local source and records only a local-to-global relationship; the global derivative contains no reverse project provenance. Legacy notes without exactly one project tag or scope:global are unclassified: inventory them in maintenance and explicitly assign them to a project or publish a distilled derivative. Never silently make them global.

Metrics: routine knowledge-health requires the current project for note metrics; infrastructure and telemetry may remain vault-level and are labeled separately.

One-command maintenance: knowledge-maintain(action: "full") — runs rebuild → migrate-layout → format → dedupe → embed → link-health in dependency order.

Individual actions (when you need targeted maintenance):

• knowledge-maintain review — surface stale/unreviewed notes with suggested actions
• knowledge-maintain dedupe — find and resolve duplicate notes
• knowledge-maintain embed — backfill missing semantic embeddings
• knowledge-maintain migrate-layout — move flat vault to kind-based directory structure

Review workflow: run review → decide per note (promote/archive/delete/skip) → act with the corresponding action and noteId. Suggested actions are hints, not commands — always apply your own judgment.

Mining Session History

Use knowledge-mine to bootstrap the KB from past sessions. It bulk-screens candidates and reports STORE/SKIP/REVIEW evidence, but classifications never authorize mutation by themselves.

Workflow:

1. Enumerate sessions: session_list (filter by date/project)
2. Read in batches of 5–10: session_read per session
3. Extract candidates that pass the precision gate — decisions, observations, procedures, resources, and personalizations
4. Call knowledge-mine(project: "<current-project>", candidates: [...], dry_run: true) with no dispositions; retain each deterministic candidate key
5. Judge each candidate and submit explicit candidate-keyed store, update, or skip dispositions. Leave uncertain or REVIEW candidates unspecified. Updates require the selected noteId and expectedUpdatedAt
6. Review the mutation-free normalized plan and batch token
7. Apply the unchanged ordered candidates and dispositions with dry_run: false, confirm: true, and that batch token

Never call dry_run: false without a reviewed plan; that legacy form now returns a zero-mutation migration response. If apply reports a partial failure, reconcile the completed prefix and ambiguous remainder before retrying—there is no automatic rollback or idempotency guarantee.

Tips: Batch sessions (5–10) to stay within context. Include source for provenance. Pass project to scope all candidates. Maximum 50 per call.

For detailed kind descriptions and examples, see kinds-reference.md.