LeanKG

What is LeanKG?

LeanKG is a code knowledge graph for AI coding agents, shipped as a single CGO-free Go binary (github.com/FreePeak/LeanKG, root module — see pkg.go.dev). Where agents usually rebuild structure with grep → open files → huge context, LeanKG returns a targeted subgraph (callers, dependents, blast radius, tests, docs) plus a team layer (env, services, incidents, requirements) over MCP. The Rust engine was removed at the parity cutover; build with make go-build, test with make go-test. See docs/prd.md for the parity ledger.

Get Started

# 1. Per project: one-shot index, then an incremental embed (sqlite default — zero config,
#    store at .leankg/leankg.db). In a git repo root it reads the HEAD commit's objects, so
#    uncommitted, untracked and ignored files are not indexed. Add --no-embed to skip the embed.
cd your-project
leankg index .

# 2. Wire up an AI client — one command (claude-code | cursor | codex | gemini | opencode | omp).
#    The stdio entry is `serve --stdio --memory`: the agent gets the code graph AND the
#    markdown memory layer (per-project at <project>/.leankg/memory), no second server.
leankg install --target claude-code  # `connect claude-code` is the same writer
#    Restart the client afterwards so it picks the entry up.

# 3. ...or serve MCP over HTTP yourself (endpoint /mcp; GET /health returns 200 when ready)
leankg serve --http 127.0.0.1:9699 --rest 127.0.0.1:8080 --memory
leankg install --target claude-code --http --url http://127.0.0.1:9699/mcp

Semantic (L3) search is the one optional layer: it needs embeddings. Set LEANKG_EMBED_PROVIDER (see docs/embedding.md and .env.example); leankg index then embeds incrementally after indexing. Until an embed runs, queries answer from exact + fuzzy matches.

Self-check any deployment: leankg doctor — prints the store path, element and file counts and the write watermark (exit 0 pass / 2 fail).

MCP over HTTP: the server resolves the project from its process cwd — run it from the checkout or pass --project DIR to pin one.

Installation

None — sqlite is the default storage engine. No Postgres, no Docker.

Postgres remains available as an explicit opt-in (LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL) for server-scale deployments, but nothing in the default flow touches it.

Published module — the engine is a Go module, so the toolchain installs both binaries from pkg.go.dev straight into $(go env GOPATH)/bin:

go install github.com/FreePeak/LeanKG/cmd/leankg@latest         # server + CLI
go install github.com/FreePeak/LeanKG/cmd/leankg-embed@latest   # embedding pipeline

Prebuilt archives — releases carry leankg-<os>-<arch>.tgz for linux/darwin × amd64/arm64, both binaries at the archive root plus a .sha256. leankg update follows the same channel.

From a checkout — requires Go 1.25+ and git; installs to ~/.local/bin (pass a PREFIX to change it):

git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG
scripts/install-go.sh                # or: make install-go

# Or fetch and run the installer directly (clones over HTTPS, same behavior):
curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install-go.sh | bash

Container — Dockerfile is a three-stage CGO-free build: engine binaries, then a demo graph baked from a slice of this repo, then an unprivileged runtime that serves that store read-only.

docker build -t leankg .
docker run --rm -p 8080:10000 -e PORT=10000 leankg   # dashboard + its /api on :8080

MCP surface

Discover with query — it routes down the ladder by default (L1 exact → L2 keyword → L3 semantic; a natural-language question goes straight from an L1 miss to L3, which fuses keyword and vector ranks), degrades instead of erroring, and every answer carries retrieval{rung,reason} + freshness.

3 tools: import (index/PRD/memory/session/ontology/read) · query (ladder + graph verbs + actions) · status (inventory/freshness/config).

Features

• MCP-native — search, impact, call graphs, ontology, architecture, team knowledge
• SQLite default (zero-config — no Postgres, no Docker required) with an opt-in Postgres/pgvector backend (LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL)
• Ontology — concept catalog + procedural layer (workflows, steps, decision points, failure modes), query --action ontology, POST /api/v1/ontology/match, and req↔code traceability via leankg prd / prd-trace
• Impact & deps — contains, calls, imports edges; BFS blast radius (leankg impact)
• Multi-repo server — MCP HTTP :9699; LEANKG_PROJECT_DIRS serves many projects, selected per request by ?project=<dir|name> (REST and MCP) or the MCP project tool argument; with neither, a multi-project server refuses rather than answering from the wrong graph. sqlite default, PG opt-in
• Env governance — query --action env_conflicts, per-env snapshots, leankg obsidian
• Ops & ownership — query --action service_context / incidents, leankg incident / note / team-map
• Req ↔ code — leankg prd / prd-trace, query --action prd, ontology traceability matrix
• Web UI v2 — Force / Tree / Circles explorer (cd ui-v2 && npm run dev; the embedded build is served by leankg serve --ui)
• Deploy — single CGO-free binary, no runtime deps: Dockerfile builds a read-only demo image for Render, /health answers container probes, and --ui / --http / --rest / --rpc each bind their own address
• Languages — 40 profiles: Go, Rust, TypeScript/TSX, JavaScript/JSX, Python, Markdown, Java, Kotlin, Swift, Objective-C, Dart, C/C++, C#, PHP, Ruby, Scala, Perl, Lua, Haskell, Elixir, Crystal, CUDA, Cypher, Elm, Erlang, F#, GLSL, HLSL, Nim, OCaml, SQL, PowerShell, Q#, Solidity, SystemVerilog, Verilog, Zig
• Agent economics — A/B −65% tokens, −85% tool calls, 2.5× vs grep/cat; peers in this space are mostly personal / single-repo. Deep dives (archived): competitive analysis · ROI vs Graphify · research matrix

Embeddings

Semantic (L3) search needs embeddings; see docs/embedding.md for providers (local / openai / deterministic), the EmbeddingGemma 2 + Hugging Face Storage Bucket bulk path, and the .env.example variable list. The catalog rows (model id, pinned revision, dimensions, prefixes) live in internal/embed/catalog.go.

Performance

• Go cold time-to-first-value — 17.8s (macOS arm64); CI budget 300s, gate "Cold TTFV" in .github/workflows/ci.yml, per-run numbers in the ttfv-go-cold artifact.
• Quickstart happy path — 1.4s warm on a generated 10-file Go fixture (index 0.05s, server bind 1.08s, first query 0.05s, doctor 0.03s); scripts/quickstart_smoke.sh runs the same steps locally (QUICKSTART_DRY_RUN=1 prints the plan).