kenso 2.0.0

Minimal MCP server for searchable Markdown knowledge bases (SQLite FTS5)

Talk to your docs

kenso turns a folder of Markdown docs into a knowledge base you can talk to from your LLM. Ask questions, define tasks, brainstorm ideas — from your own docs. Zero config. No infrastructure. Always deterministic.

Docs · Getting Started · Writing Guide

Why kenso

Your documentation already has the answers. But finding them means remembering which file, scanning entire documents, or piecing together information scattered across multiple places. kenso lets you ask one question and get the right answer.

• Direct answers — finds the right paragraph without reading the whole doc.
• Cross-document reasoning — one question, ten docs, one synthesized answer.
• Natural queries — search how you think, not how the author wrote.
• Cross-domain — bridge code and business rules in one question.
• Define tasks, brainstorm, refine, explain — think with your docs, not from guesses.
• Generate docs from code — create documentation from your codebase.

Installation

With uv (recommended)

uv tool install kenso          # → .agents/skills/ (standard — Codex, Cursor, Gemini CLI, ...)
uv tool install kenso --claude # → .claude/commands/ + .claude/skills/
uv tool install kenso --codex  # → .codex/skills/ (legacy Codex projects)

With pip

pip install kenso[yaml]       # install with YAML frontmatter support

kenso install                 # → .agents/skills/ (standard — Codex, Cursor, Gemini CLI, ...)
kenso install --claude        # → .claude/commands/ + .claude/skills/
kenso install --codex         # → .codex/skills/ (legacy Codex projects)

Claude Code

Add permissions so kenso CLI runs without confirmation prompts:

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(kenso search:*)",
      "Bash(kenso stats:*)",
      "Bash(kenso lint:*)",
      "Bash(kenso ingest:*)"
    ]
  }
}

Quick Start

Now open your LLM and initialize kenso:

# Claude Code
/kenso:init docs/           # initialize kenso with your docs
/kenso:ask How is code deployed to production?

# Codex CLI
$kenso:init docs/           # initialize kenso with your docs
$kenso:ask How is code deployed to production?

kenso works with any Markdown file.
To improve retrieval quality, see Writing Effective Documents.

Commands

Lifecycle

Command	What it does
kenso:init	Analyzes your project, generates documentation, optimizes for retrieval, and indexes. Takes you from zero to a queryable knowledge base.
kenso:update	Detects code and doc changes, updates affected documentation, re-optimizes cross-links, re-indexes. Shows before/after metrics.
kenso update --ci	Headless version for CI/CD pipelines. Updates docs and opens a PR with a quality report.

Consultation

Command	What it does
kenso:ask	Ask a question, get a sourced answer from your docs.
kenso:define	Define a task with full project context — affected entities, rules, files, integration points, and acceptance criteria.
kenso:brainstorm	Explore ideas and trade-offs grounded in your real architecture and constraints.
kenso:explain	Understand why code exists — business rules, design decisions, domain context behind the implementation.

How it compares

	Plain LLM	Embedding RAG	kenso
Infrastructure	—	Model + vector DB + pipeline	pip install
Knows your project	✗	Partial	✓
Generates docs from code	✗	✗	✓
Keeps docs in sync	✗	✗	✓
Source citations	✗	Partial	✓
Deterministic	—	✗	✓
Semantic understanding	✓	✓	Relies on LLM
Vocabulary-independent	✓	✓	✗
Works with any content	✓	✓	Markdown only
Inspectable ranking	—	✗	✓
CI/CD automation	—	✗	✓
Free	✗	✗	✓

kenso uses BM25 keyword search over SQLite — no embeddings, no vector database, no API costs for search. The LLM already understands meaning; kenso gives it the right source text

Writing Effective Documents

kenso works with any Markdown. Adding frontmatter improves retrieval:

---
title: CI/CD Deployment Pipeline
category: infrastructure
tags: deployment, CI/CD, rollback, blue-green
aliases:
  - deploy pipeline
  - continuous deployment
answers:
  - How is code deployed to production?
relates_to:
  - path: infrastructure/monitoring.md
    relation: receives_from
---

Specific titles are indexed at 10× weight. Tags with synonyms your team uses help with vocabulary mismatch. A summary paragraph before the first H2 ensures the overview is always searchable.

See the full Writing Guide for field reference, structure tips, relation types, and a pre-commit checklist.

Performance

100% hit rate and 97.2% MRR across a 36-query eval harness covering 10 retrieval categories. Zero regressions across development. Run it yourself with python tests/eval/eval_harness.py.

Roadmap

kenso is under active development. Current focus areas:

• Search quality — Tokenization for compound terms (camelCase, snake_case), synonym expansion via .kenso/synonyms.yml, fuzzy matching for typos, smart snippets showing why a result matched.

• Near term — /kenso:refine (expert panel review of task definitions), deprecated document support, BM25 score simulation during authoring, search log analysis.

• Long term — Multi-repo knowledge bases, real-time API data sources, Jira integration, controlled vocabulary as formal taxonomy.

See the full roadmap for details.

Troubleshooting

kenso search returns no results — Run kenso stats to check if docs are indexed. If zero docs, run kenso ingest <path>.

"No such table: chunks" — The database schema changed. Delete the database file (.kenso/docs.db or ~/.local/share/kenso/docs.db) and re-ingest.

MCP server not connecting — Verify the command path is correct. If installed in a venv, use the full path (e.g. /path/to/.venv/bin/kenso). Restart your editor after changing MCP config.

License

MIT

---

kenso — inspired by Japanese 検索 (kensaku): to search.