lean-kg
Lightweight Knowledge Graph for AI-Assisted Development LeanKG is a local-first knowledge graph that gives AI coding tools accurate codebase
Open source Repository Open in the app JSON README (API)
About
Lightweight Knowledge Graph for AI-Assisted Development LeanKG is a local-first knowledge graph that gives AI coding tools accurate codebase context. It indexes your code, builds dependency graphs, and exposes an MCP server so tools like Cursor, OpenCode, and Claude Code can query the knowledge graph directly. No cloud services, no external databases. Visualize your knowledge graph with force-directed layout, WebGL rendering, and community clustering.
Details
- Kind
- Plugins
- Topic
- AI, RAG & memory
- Publisher
- freepeak
- Origin
- marketplace
- Category
- ferramentas
- Stars
- 217
- Forks
- 26
- Open pull requests
- 9
- Last push
- 2026-09-10T00:26:32Z
- Repository state
- ativo
- Language
- Rust
- License
- Apache-2.0
- Added
- 2026-08-30 01:48:58
- Updated
- 2026-08-30 01:48:58
- Origin id
freepeak/leankg/lean-kg
README
<p align="center"> <img src="assets/icon.svg" alt="LeanKG" width="128" height="128"> </p> <h1 align="center">LeanKG</h1> <p align="center"> <strong>Enterprise-ready code knowledge graph for AI coding agents</strong><br> Multi-repo · env governance · incidents & services · req↔code · −65% tokens / −85% tool calls </p> <p align="center"> <a href="https://leankg.onrender.com"><strong>Live Demo</strong></a> · <a href="docs/prd.md">Docs</a> · <a href="https://hub.docker.com/r/freepeak/leankg">Docker Hub</a> </p> <p align="center"> <a href="https://github.com/FreePeak/LeanKG/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"></a> <a href="https://crates.io/crates/leankg"><img src="https://img.shields.io/crates/v/leankg.svg" alt="crates.io"></a> <a href="https://hub.docker.com/r/freepeak/leankg"><img src="https://img.shields.io/docker/v/freepeak/leankg?label=docker&logo=docker" alt="Docker Hub"></a> <a href="https://github.com/FreePeak/LeanKG/actions"><img src="https://img.shields.io/github/actions/workflow/status/FreePeak/LeanKG/ci.yml?branch=main&label=CI" alt="CI"></a> </p> <p align="center"> <img src="assets/banner.svg" alt="LeanKG" width="100%"> </p> --- ## Installation ### Prerequisites Postgres + pgvector is required (only storage engine). From a LeanKG checkout: ```bash docker compose up -d postgres # host :5433 ``` Default URL: `postgresql://postgres:postgres@localhost:5433/leankg` (override with `LEANKG_PG_URL`). One-liners below do **not** start Postgres — they fail if `:5433` is down. ### One-liners ```bash # Docker — index + embed + MCP HTTP (Postgres must already be up) curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/docker-up.sh | bash # Agent — binary + MCP wiring (cursor | claude | opencode | gemini | kilo | antigravity | docker | update) curl -fsSL https://raw.githubusercontent.com/FreePeak/LeanKG/main/scripts/install.sh | bash -s -- cursor ``` Skip cold embed: `LEANKG_SKIP_EMBED=1 curl -fsSL …/docker-up.sh | bash` ### Docker (manual) ```bash docker compose up -d # Postgres :5433 + MCP :9699 # or MCP only (bring your own PG via LEANKG_PG_URL): docker run -d --name leankg -p 9699:9699 \ -e LEANKG_PG_URL=postgresql://postgres:postgres@host.docker.internal:5433/leankg \ -v "$(pwd):/workspace" freepeak/leankg:latest curl http://localhost:9699/health ``` MCP URL: `http://localhost:9699/mcp` ### From source ```bash cargo install leankg # or: git clone https://github.com/FreePeak/LeanKG.git && cd LeanKG && cargo build --release ``` --- ## Get Started ```bash # 0. Postgres once — point at your instance (or: docker compose up -d postgres) export LEANKG_PG_URL="postgres://user:pass@host:5432/db" # 1. Per project: init -> migrate -> index cd your-project leankg init && leankg migrate && leankg index ./src # 2a. Wire up an AI client — one command (also: cursor | codex | gemini) leankg connect claude-code # add --remote http://host:9699 to reuse a shared server # 2b. ...or serve MCP over HTTP yourself leankg mcp-http --port 9699 # GET /health returns 200 when ready ``` Self-check any deployment: `leankg doctor --deep` — PG latency, migrations, index freshness, embedding coverage, pool env, orphan edges, duplicate names (exit 0 pass / 1 warn / 2 fail). Measured timings (`scripts/quickstart_smoke.sh`, run weekly in CI): full e2e smoke **88 s** vs a 300 s budget; indexing a small repo takes well under 2 minutes. Docker MCP users: pass **container** paths as `project=` (e.g. `/workspace`), never host paths. ### Server-side setup pipeline (clone -> index -> embed) `leankg setup` with no flags keeps the legacy client-side behavior (register MCP + hooks). Pass pipeline flags to instead clone a list of repos and index each one server-side: ```bash # Status: print the resolved repo list without running anything LEANKG_REPOS="github.com/org/repo-a,github.com/org/repo-b" leankg setup --status # Clone + index + embed each repo under LEANKG_CLONE_ROOT (default: cwd) LEANKG_REPOS="github.com/org/repo-a,github.com/org/repo-b" \ LEANKG_GIT_REF=main \ LEANKG_CLONE_ROOT=/srv/repos \ leankg setup --clone --index --embed ``` Repo sources: - `LEANKG_REPOS` — comma-separated `host/namespace` paths to clone. - `LEANKG_PROJECT_DIRS` — comma-separated dirs already mounted on disk (skips clone; falls back to indexing what exists when no git token is set). Env knobs: `LEANKG_GIT_HOST` (default `github.com`), `LEANKG_GIT_REF` (default `main`), `LEANKG_CLONE_ROOT` / `CLONE_ROOT`, `LEANKG_ENV` (default `local`), git token via `GITLAB_TOKEN` / `GIT_TOKEN` / `GITHUB_TOKEN`. Each cloned repo gets a minimal `.leankg/leankg.yaml`, then `leankg index` and `leankg embed --wait` run inside it. A `setup.done` marker prevents re-runs. Set `LEANKG_SETUP=1` on `leankg mcp-http` to run the same pipeline once after the server binds (spawned as a background task; the server stays healthy). ### Web UI UI talks REST (`:8080`), not MCP (`:9699`). Start the API, then the Vite app in `ui-v2/`: ```bash # Terminal A — REST API (+ embedded UI if assets are in src/embed/) leankg serve --port 8080 # open http://127.0.0.1:8080/ # Terminal B — hot-reload explorer (recommended for local UI work) cd ui-v2 npm install npm run dev # open http://127.0.0.1:5173/?path=src ``` Vite proxies `/api` → `127.0.0.1:8080`. Status should show **connected**. Details: [ui-v2/README.md](ui-v2/README.md) · [docs/archive/web-ui.md](docs/archive/web-ui.md) --- ## Enterprise Ready Peers in this space are mostly personal / single-repo. LeanKG is the **company platform**: shared index, ops graph, and measured agent economics. | Pillar | Ships as | | ------ | -------- | | Multi-repo server | Docker MCP `:9699` + Postgres/pgvector; `LEANKG_PROJECT_DIRS` | | Env governance | `env=`, `promote_environment`, `find_env_conflicts` | | Ops & ownership | `get_service_graph`, `query_incidents`, `get_team_map` | | Req ↔ code | `index_prd`, `get_traceability`, `get_traceability_matrix` | | Mega-graph | Frontier-local queries; 100k–700k+ elements | | Agent surface | **1** MCP tool (`leankg_context`) serving ~76 capabilities as verbs; peers typically ~1–17 raw tools | | Cost | A/B **−65% tokens**, **−85% tool calls**, **2.5×** vs grep/cat | | Capability | LeanKG | GitNexus | Graphify | Codanna | Context7 | | ---------- | ------ | -------- | -------- | ------- | -------- | | Multi-repo team deploy | Yes | Partial | Limited | Limited | n/a | | Env / incidents / team map | Yes | No | No | No | No | | PRD traceability | Yes | No | Partial | No | No | | Mega-graph (100k+) | Yes | Partial | Viz capped | Varies | n/a | | MCP depth | 77 | ~17 | ~10 | ~5 | docs only | Deep dives (archived): [ROI vs Graphify](docs/archive/reports/leankg-vs-graphify-company-roi-2026-07-21.md) · [Competitive one-pager](docs/archive/competitive-analysis.md) · [Research matrix](docs/archive/analysis/leankg-competitive-research-and-improvement-strategy-2026-08-02.md) --- ## Why LeanKG? Agents normally rebuild structure with grep → open files → huge context. LeanKG returns a **targeted subgraph** (callers, dependents, blast radius, tests, docs) plus the **team layer** (env, services, incidents, requirements) over MCP. | Without | With LeanKG | | ------- | ----------- | | Many tool calls, large context | Surgical subgraph + TOON (~40% smaller payloads) | | No blast radius | Severity-graded impact | | Keyword only | Keyword + HNSW semantic + ontology | | Single-repo guesswork | Multi-repo index + ops tools | --- ## Key Features - **MCP-native** — search, impact, call graphs, ontology, architecture, team knowledge - **Postgres + pgvector** — only storage engine; HNSW semantic search (`--features embeddings` / Docker) - **Procedural ontology** — hot-reload `ontology/workflows.yaml` → `kg_trace_workflow` - **Impact & deps** — `imports`, `calls`, `tested_by`, `http_calls`, `service_calls` - **Web UI v2** — Force / Tree / Circles explorer (`leankg serve` + `cd ui-v2 && npm run dev`) - **Languages** — Rust, Go, C/C++, Java, Kotlin, TS/JS, Python, Ruby*, PHP*, Dart, Swift*, ObjC*, Terraform, CI YAML (*depth varies) --- ## MCP prefer-order Discover first — do **not** open with `query_graph`: `leankg_context` → `get_overview_context` → `mcp_status` → `concept_search` / `semantic_search` / `search_code` → impact / deps / `get_context` | Question | First tools | | -------- | ----------- | | Any question (default) | `leankg_context` (intent is auto-classified; degrades L3→L0 instead of erroring) | | Fuzzy / domain NL | `concept_search` → `semantic_search` → `search_code` | | Exact symbol / file | `search_code` | | How A↔B? | `shortest_path` | | Expand after seeds | `query_graph` | Catalog: [docs/archive/mcp-tools.md](docs/archive/mcp-tools.md) · Setup: [docs/archive/agentic-instructions.md](docs/archive/agentic-instructions.md) --- ## CLI ```bash leankg init | index ./src | status | update leankg impact <file> --depth 3 leankg path <from> <to> | explain <symbol> | graph-query "<q>" leankg embed --init && leankg embed # --features embeddings leankg mcp-stdio --watch | mcp-http --port 9699 | serve --port 8080 leankg ontology sync | ontology trace <workflow> ``` UI hot-reload: `cd ui-v2 && npm install && npm run dev` → http://127.0.0.1:5173 Full reference: [docs/archive/cli-reference.md](docs/archive/cli-reference.md) --- ## Docs The documentation set lives in [`docs/`](docs/) — a single unified PRD (`docs/prd.md`) + task tracker (`docs/prd-task-tracker.md`). All historical design docs, analyses, reports, and plans are preserved under [`docs/archive/`](docs/archive/). | Doc | | | --- | --- | | [PRD](docs/prd.md) | Unified product requirements + HLD (single SoT) | | [Task tracker](docs/prd-task-tracker.md) | Done / in-progress / todo | | [Architecture (archived)](docs/archive/architecture.md) | Design & data model (historical) | | [MCP tools (archived)](docs/archive/mcp-tools.md) | Tool catalog (historical) | | [CLI (archived)](docs/archive/cli-reference.md) | All commands (historical) | | [Benchmarks (archived)](docs/archive/benchmark.md) | Methodology (historical) | | [Embeddings](src/embeddings/EMBEDDINGS.md) | HNSW / ops | | [Postgres migration (archived)](docs/archive/analysis/pg-migration-report.md) | Engine notes (historical) | | [AGENTS.md](AGENTS.md) | Agent / Docker notes | --- ## Troubleshooting | Issue | Fix | | ----- | --- | | High RAM (macOS) | `LEANKG_MMAP_SIZE=134217728` — see [INSTRUCTION.md](INSTRUCTION.md) | | MCP “not initialized” in Docker | Use container `project=/workspace`, not the host path | | Embeddings / cold embed | [src/embeddings/EMBEDDINGS.md](src/embeddings/EMBEDDINGS.md) | **Requirements:** macOS or Linux · Docker recommended for teams · Rust 1.75+ only when building from source. --- ## Contributing 1. Fork + feature branch (prefer a worktree) 2. Update docs when behavior changes 3. `cargo build --release && cargo test` 4. Open a PR with summary + test plan ## License [Apache License 2.0](LICENSE)