leankg 0.19.1

Lightweight Knowledge Graph for AI-Assisted Development
Documentation

Contents

Get Started

1. Install the CLI

One command — binary, MCP wiring, and agent docs for your tool of choice:

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- <target>
Target What you get
cursor Binary + MCP + skill + AGENTS.md + session hook
claude Binary + MCP + plugin + skill + CLAUDE.md + hooks
opencode Binary + MCP + plugin + skill + AGENTS.md
gemini / kilo / antigravity Binary + MCP + skill + agent docs
docker Hub image + index + embed + MCP HTTP (no Rust) 
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor

cargo install leankg
# or
git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG && cargo build --release

curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/docker-up.sh | bash
curl http://localhost:9699/health

Point your MCP client at http://localhost:9699/mcp. Multi-project RocksDB mounts: AGENTS.md.

Published Hub tags currently target linux/arm64. On linux/amd64, build with docker compose -f docker-compose.rocksdb.yml up --build.

2. Wire up your agent(s)

Installing the binary alone does not connect your agent. Run setup (or use an install target above) so MCP is registered:

leankg setup

This configures Cursor, Claude Code, OpenCode, Gemini, and other supported clients with LeanKG’s MCP server, skills, and hooks where available.

3. Index each project

cd your-project
leankg init
leankg index ./src
leankg status

Optional: enable watch mode so the graph stays fresh while you and your agent edit code:

leankg mcp-stdio --watch

4. Ask better questions

leankg impact src/main.rs --depth 3
leankg path "Handler" "Repository"
leankg explain "APIRouter"
leankg web    # UI at http://localhost:8080

Upgrade anytime:

leankg update

Why LeanKG?

When an AI agent needs to understand code, it usually discovers structure the slow way: grep, glob, and Read — one file at a time — rebuilding call paths and dependencies by hand. That is a pile of tool calls and round-trips before the real work starts.

LeanKG hands the agent the exact subgraph it needs. It indexes symbols, edges, tests, docs, and (optionally) embeddings into a local knowledge graph, then exposes them over MCP. Instead of crawling the tree, the agent asks one question and gets back callers, dependents, blast radius, and targeted source — surgical context, not a file-by-file search.

graph LR
    A[AI Agent] -->|intent| B[LeanKG MCP]
    B --> C[Graph + Embeddings]
    C -->|targeted context| A
Without LeanKG With LeanKG
Grep → open many files → large context Query the graph → minimal, relevant subgraph
No blast-radius awareness Impact radius with confidence + severity
Keyword-only search Keyword + semantic (HNSW) + ontology
Stale mental model of the repo Index + optional --watch incremental updates

On cost: LeanKG’s win on every codebase is precision and speed — fewer tool calls, faster answers. Token savings are real and scale-dependent: modest on small repos, material on large monorepos multiplied by team-wide agent usage.

Measured Results

Vector-engine A/B gate (100 tasks, synthetic agent workload vs grep/cat-style baseline) — see docs/benchmarks/vector_engine_gate_results.json:

Metric Result Floor
Token reduction −65.0% ≥ 60%
Tool-call reduction −84.6% ≥ 80%
Speedup 2.50× ≥ 2×
1M SQ8 ANN P95 ~0.055 ms < 50 ms

Unified agent A/B (19 cases vs grep baseline): ~30% input token savings, ~3× tokens/result efficiency.

Load test (~100K nodes):

Operation Throughput
Insert elements ~57k / sec
Insert relationships ~67k / sec
Retrieve elements ~419k / sec
Cache speedup (cold → warm) 345–461× 
cargo build --release
target/release/leankg benchmark-unified --project .
cargo bench --bench vector_engine_ab

Full methodology: docs/benchmark.md

Key Features

  • MCP-native — 85+ tools for search, impact, call graphs, ontology, architecture, and team knowledge
  • Impact radius — blast radius before you change code, with confidence and severity
  • Dependency graph — imports, calls, tested_by, http_calls, service_calls, tunnels, and more
  • Semantic search — CozoDB HNSW over dense embeddings (--features embeddings; included in Docker)
  • Community detection — Leiden clusters with per-cluster skill context
  • Local-first storage — SQLite by default; RocksDB for multi-project / team deploy
  • Token-aware payloads — targeted subgraphs + TOON responses (~40% smaller MCP payloads)
  • Team knowledge — incidents, env conflicts, service topology, Obsidian vault sync
  • Graph export — Mermaid, DOT, HTML, SVG, GraphML, Neo4j, portable snapshots
  • Web UI — force-directed graph, WebGL rendering, community clustering, linked source view

Architecture: docs/architecture.md · MCP catalog: docs/mcp-tools.md

Screenshots

UI guide: docs/web-ui.md · Live demo: https://leankg.onrender.com

How It Works

  1. Extract — tree-sitter (and language-specific extractors) turn source into CodeElement nodes and typed relationships.
  2. Store — CozoDB over SQLite (local) or RocksDB (multi-project / Docker) holds the graph + optional HNSW vectors.
  3. Serve — MCP stdio (editor agents) or HTTP/SSE (Docker / remote) answers tools like get_impact_radius, search_code, semantic_search, get_architecture.
  4. Refresh — --watch and incremental index keep the graph aligned with the working tree.
Repo ──► Indexer ──► Knowledge Graph ──► MCP Tools ──► AI Agent
              │              │
              └─ embeddings ─┘ (optional)

MCP & Agents

Agent Auto-setup Notes
Cursor Yes Per-project install; session hook
Claude Code Yes Plugin + full lifecycle hooks
OpenCode Yes Plugin + skill
Gemini CLI Yes MCP + skill / agent docs
Codex / Antigravity / Kilo Yes MCP + skill / agent docs
Docker MCP HTTP Yes Shared RocksDB; multi-repo mounts 
leankg setup                 # configure MCP + hooks
leankg mcp-stdio --watch     # local AI tools
leankg mcp-http --port 9699  # HTTP/SSE for Docker / remote

Setup details: docs/agentic-instructions.md

Language Support

Structural extraction and cross-file edges into one graph (no per-language product setup):

Family Languages / formats
Systems Rust, Go, C / C++*
JVM Java, Kotlin
Web TypeScript, JavaScript
Scripting Python, Ruby*, PHP*
Mobile Dart, Android XML
Infra Terraform, CI YAML

*Depth varies by extractor maturity — see the PRD / roadmap for parity status.

CLI Quick Reference

leankg init
leankg index ./src
leankg status
leankg impact <file> --depth 3
leankg path <from> <to>
leankg explain <symbol>
leankg detect-clusters
leankg embed --init && leankg embed   # needs --features embeddings
leankg web
leankg mcp-stdio --watch
leankg mcp-http --port 9699
leankg update

Full CLI: docs/cli-reference.md

Documentation

Doc Description
docs/cli-reference.md All CLI commands
docs/mcp-tools.md MCP tool reference
docs/agentic-instructions.md AI tool setup & auto-trigger
docs/architecture.md System design & data model
docs/web-ui.md Web UI
docs/benchmark.md Benchmark methodology
src/embeddings/EMBEDDINGS.md Embeddings / HNSW internals
INSTRUCTION.md Memory tuning & ops playbook
docs/roadmap.md Roadmap
AGENTS.md Agent / Docker deployment notes

Troubleshooting

Issue Fix
High RAM on macOS export LEANKG_MMAP_SIZE=134217728 and LEANKG_CACHE_MAX_TOKENS=100000 — see INSTRUCTION.md
database is locked leankg proc kill (stop web/MCP before re-index)
Embeddings / cold embed src/embeddings/EMBEDDINGS.md
MCP “not initialized” in Docker Pass container project= paths (e.g. /workspace), not the host Mac path — see AGENTS.md

Requirements

  • Rust 1.75+ (only when building from source)
  • macOS or Linux
  • Docker optional (recommended for teams / multi-repo)

Contributing

Issues and PRs are welcome. For larger changes, open an issue first so we can align on design.

  1. Fork and create a feature branch (prefer a git worktree for isolation)
  2. Update docs when behavior changes (docs/prd.md / task tracker as needed)
  3. cargo build --release && cargo test
  4. Open a PR with a clear summary and test plan

License

Apache License 2.0

Star History