FreePeak/LeanKG

⚡ Implementation: 100% Go. The Rust engine was removed at the parity cutover; the whole engine is the root Go module github.com/FreePeak/LeanKG . See docs/prd.md for the parity ledger. Build: make go-build · Test: make go-test · Bench: make go-bench .
Enterprise-ready code knowledge graph for AI coding agents
Multi-repo · env governance · incidents & services · req↔code · −65% tokens / −85% tool calls
Live Demo
·
Docs
·
pkg.go.dev
·
Changelog
---
Installation
Prerequisites
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.
Install
**Published module** — the engine is a Go module, so the toolchain installs both
binaries from pkg.go.dev straight into $(go env GOPATH)/bin:
**Prebuilt archives** — releases
carry leankg- - .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):
Container
Dockerfile is a three-stage CGO-free build: engine binaries, then a
demo graph baked from a slice of this repo (the language examples/, the engine,
the dashboard source), then an unprivileged runtime that serves that store
read-only. The dashboard build is already embedded in the binary
(internal/web/embed), so there is no Node stage.
This is the image leankg.onrender.com runs: one
container, one port, leankg serve --read-only --ui :$PORT.
---
Get Started
Semantic (L3) search is the one optional layer: it needs embeddings. Set
LEANKG_EMBED_PROVIDER (see Embedding providers 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.
Embedding providers
LeanKG embeds through one provider, chosen by LEANKG_EMBED_PROVIDER: local (a
llama.cpp sidecar or an attached endpoint, the default), openai (any OpenAI-compatible
API) or deterministic (tests only). Every variable is listed with an example in
.env.example; the leankg-embed usage text names the same set.
The catalog rows (model id, pinned revision, dimensions, query and document prefixes)
live in internal/embed/catalog.go.
EmbeddingGemma 2 with a Hugging Face Storage Bucket
embeddinggemma-2 (Google, 768 dimensions, Matryoshka truncation to 512/256/128) is served
by llama.cpp. Bulk embedding is too slow on a laptop, so it is split:
- **Bulk (on a Hugging Face Job):** scripts/hf-embed.sh exports the pending texts with
leankg-embed export, uploads them to your private Storage Bucket, runs
scripts/hf_embed_job.py as an hf jobs uv run job that loads the sentence-transformers
model from the bucket, downloads the vectors and imports them with leankg-embed import.
The import stamps the collection exactly as the local provider would for the same
LEANKG_EMBED_* environment (catalog revision, width, prefixes), so the next
leankg-embed run needs no full rebuild. Each vector line may be the native 768-d width
(reduced to the configured width) or the configured width; the export's content_hash is
recorded, so an element edited after export is re-embedded by the next run.
- **Queries and hook backlogs (local):** the local llama.cpp sidecar serves query vectors and
the small backlogs that leankg index --hook embeds. The session hook never starts a job.
Prerequisites:
- llama.cpp llama-server release b11454 or newer.
- The BF16 GGUF from ggml-org/embeddinggemma-2-GGUF
for the local sidecar.
- The hf CLI, logged in (hf auth login), with HF Jobs credits (a job needs a positive balance).
- The sentence-transformers model files of
google/embeddinggemma-2 at revision
914f7f89142e33e77833254d9c9b90c3cef7303b, uploaded to your bucket