kmd — knowledge-markdown

CLI + MCP server for structured markdown knowledge vaults. Validate, index (SQLite FTS5), and serve content to AI agents — one npx away.

Same primitives as Open Knowledge Format (markdown + YAML frontmatter + directory tree), but opinionated where OKF is minimal:

	OKF	kmd
Vocabulary	open — producer picks type values	controlled — vault.yaml defines kinds, scopes, statuses, tags; kmd validate enforces
Structure	flat — organize however	three domains: projects/ · research/ · notes/
Validation	none — format spec only	deterministic, LLM-free; gates sync + pre-commit hook
Cross-refs	bundle-relative /path.md	[[wikilinks]] (Obsidian-native, rename-safe, no-dangling guarantee)
Agent surface	none — bring your own	two MCP tools (prime, search) + template resources
Infrastructure	n/a	node:sqlite FTS5; zero external deps

Install

npx @bartolli/kmd --help

Commands

kmd validate [<path>]     deterministic vault checker (default: $WIKI_VAULT)
kmd sync                  vault → SQLite index (runs validate first)
kmd mcp [<vault-root>]    stdio MCP server
kmd db reset              delete and recreate the index

MCP registration

{
  "mcpServers": {
    "wiki": {
      "command": "npx",
      "args": ["-y", "@bartolli/kmd", "mcp", "/absolute/path/to/vault"]
    }
  }
}

Two tools:

• prime(scope, task?) — orientation briefing: identity, primer, active ADRs, plan, vocabulary, hubs, task-relevant pages.
• search(query, scope?, kind?, limit?) — FTS5 ranked candidates {path, title, kind, summary, score}. Never page bodies.

Templates served as MCP resources at wiki://template/{domain}/{kind}.

Vault structure

vault/
├── vault.yaml              # controlled vocabulary
├── templates/               # frontmatter templates → MCP resources
├── projects/{scope}/        # specs, ADRs, plans, stories
├── research/{topic}/        # articles, sources
└── notes/                   # low-ceremony capture

Development

Requires Node.js 22+ (node:sqlite FTS5) and pnpm 11+.

pnpm install
pnpm -r run typecheck && pnpm -r run test && pnpm lint

License

MIT