A CLI that builds a knowledge graph from a directory of markdown files and exposes it via MCP.
- Extracts entities and relations using any LLM (via litellm)
- Resolves duplicate entities using local embeddings + LLM verification
- Induces a typed schema from the extracted data
- Stores everything in a single SQLite file (powered by sqlite-vec)
- Exposes the graph via CLI queries and an MCP server
pip install kgmdOr with uv:
uv tool install kgmd- Python 3.10+
- An API key for any LLM provider supported by litellm (OpenRouter, OpenAI, Anthropic, etc.)
- Embeddings run locally by default via fastembed (no API key needed)
- Your Python must be built with SQLite extension loading enabled — see
docs/install.md if
kgmd buildfails on extension loading
cd my-notes/
kgmd init # create .kgmd/ (config, prompts, graph.db)
export OPENROUTER_API_KEY="sk-..."
kgmd build # extract -> resolve -> induce
kgmd stats # what got built
kgmd find "machine learning" # semantic search
kgmd entity "Brian Anderson" # one entity, with mentions and relations
kgmd neighbors "Brian Anderson" --depth 2Full walkthrough: docs/quickstart.md.
kgmd build runs three stages:
- Extract — each markdown file is chunked and sent to an LLM, which returns structured JSON with entities (people, organizations, projects, etc.) and relations between them.
- Resolve — entity mentions are embedded locally, clustered by cosine similarity, and duplicate clusters are verified by the LLM before merging.
- Induce — aggregate statistics about entity types and relation predicates are sent to the LLM, which produces a typed YAML schema with hierarchies.
All state lives in .kgmd/graph.db, a single SQLite file. Re-running kgmd build is incremental —
unchanged files are skipped. See docs/concepts.md.
A .kgmdignore file at the corpus root keeps material out of the graph, and therefore out of the
paid extraction path; kgmd build --dry-run shows what would be indexed before you spend anything.
Syntax and precedence: docs/reference/configuration.md.
kgmd mcp launches an MCP server over stdio exposing seven read-only tools over the graph. Setup,
the exact registered tool names, and client configuration are in
docs/guides/mcp.md.
| Topic | Page |
|---|---|
| Install, prerequisites, credentials | docs/install.md |
| Zero to a queryable graph | docs/quickstart.md |
| Pipeline stages and vocabulary | docs/concepts.md |
| Every command and option | docs/reference/cli.md |
| Every configuration setting | docs/reference/configuration.md |
| Export formats | docs/reference/export.md |
| MCP integration | docs/guides/mcp.md |
| Re-runs, cost, reset, backup | docs/guides/maintenance.md |
| Troubleshooting | docs/guides/troubleshooting.md |
| Worked examples | docs/examples/personal-notes.md |
| Contributing | docs/contributing/development.md |
| Release history | CHANGELOG.md |
Index: docs/README.md.
git clone https://github.com/johncarpenter/kgmd.git
cd kgmd
make install # pip install -e ".[dev]"
make test # pytest
make lint # ruff check
make format # ruff formatSee docs/contributing/development.md and docs/contributing/architecture.md.