Lean KG

LeanKG: Deja de quemar tokens. Empieza a programar de forma eficiente.

Documentación

LeanKG

⚡ Implementación: 100% Go. El motor Rust fue eliminado en el corte de paridad; todo el motor es el módulo Go raíz github.com/FreePeak/LeanKG. Consulta docs/prd.md para el registro de paridad. Compilación: make go-build · Pruebas: make go-test · Benchmarks: make go-bench.

Grafo de conocimiento de código listo para empresas para agentes de codificación de IA
Multi-repositorio · gobernanza de entornos · incidentes y servicios · req↔código · −65% tokens / −85% llamadas a herramientas

Demo en vivo · Documentación · pkg.go.dev · Registro de cambios

Instalación

Requisitos previos

Ninguno — sqlite es el motor de almacenamiento predeterminado. Sin Postgres, sin Docker.

Postgres sigue disponible como una opción explícita (LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL) para despliegues a escala de servidor, pero nada en el flujo predeterminado lo utiliza.

Instalar

Módulo publicado — el motor es un módulo Go, por lo que la cadena de herramientas instala ambos binarios desde pkg.go.dev directamente en $(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

Archivos precompilados — releases incluyen leankg-<os>-<arch>.tgz para linux/darwin × amd64/arm64, ambos binarios en la raíz del archivo más un .sha256. leankg update sigue el mismo canal.

Desde un checkout — requiere Go 1.25+ y git; instala en ~/.local/bin (pasa un PREFIX para cambiarlo):

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

Contenedor

Dockerfile es una compilación de tres etapas sin CGO: binarios del motor, luego un grafo de demostración horneado a partir de una porción de este repositorio (el lenguaje examples/, el motor, el código fuente del panel), luego un runtime sin privilegios que sirve ese almacén de solo lectura. La compilación del panel ya está incrustada en el binario (internal/web/embed), por lo que no hay etapa de Node.

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

Esta es la imagen que ejecuta leankg.onrender.com: un contenedor, un puerto, leankg serve --read-only --ui :$PORT.

Comenzar

# 1. Per project: one-shot index (sqlite default — zero config, store at .leankg/leankg.db)
cd your-project
leankg index .

# 2. Wire up an AI client — one command (claude-code | cursor | codex | gemini | opencode | omp)
leankg connect claude-code           # stdio entry; --http --url http://host:9699/mcp to reuse a shared server

# 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

Autoverificación de cualquier despliegue: leankg doctor — imprime la ruta del almacén, los recuentos de elementos y archivos, y la marca de agua de escritura (salida 0 pasa / 2 falla).

MCP sobre HTTP: el servidor resuelve el proyecto desde su cwd de proceso — ejecútalo desde el checkout o pasa --project DIR para fijar uno.

Tiempos medidos

Tiempo frío de Go hasta el primer valor (compilación → indexación → enlace de servicio → primera consulta REST + MCP): presupuesto de CI 300s, puerta Cold TTFV, números por ejecución en el artefacto ttfv-go-cold — medición local de caché fría 17.8s (macOS arm64); reemplaza el quickstart_smoke.sh de la era Rust.

Interfaz web

El panel integrado es servido por leankg serve --ui ADDR (una compilación de ui-v2 compilada en el binario). Los endpoints de datos /api/* del panel se sirven en la misma dirección; serve --rest expone los endpoints de herramientas /api/v1/* por separado.

Para el desarrollo de la interfaz, ejecuta el servidor de desarrollo de Vite contra una dirección REST (hace proxy de /api a BACKEND_TARGET, predeterminado http://127.0.0.1:8080):

# Terminal A — REST API
leankg serve --rest 127.0.0.1:8080

# Terminal B — hot-reload dev server
cd ui-v2
npm install
npm run dev
# open http://127.0.0.1:5173

Detalles: ui-v2/README.md · docs/archive/web-ui.md

Listo para empresas

Los pares en este espacio son en su mayoría personales / de un solo repositorio. LeanKG es la plataforma de empresa: índice compartido, grafo de operaciones y economía de agentes medida.

Pilar	Se entrega como
Servidor multi-repositorio	MCP HTTP `:9699`; `LEANKG_PROJECT_DIRS` sirve muchos proyectos con `?project=` por solicitud (REST) / argumento `project` (MCP); sqlite predeterminado, PG opcional
Gobernanza de entornos	`query --action env_conflicts`, instantáneas por entorno, `leankg obsidian`
Operaciones y propiedad	`query --action service_context` / `incidents`, `leankg incident` / `note` / `team-map`
Req ↔ código	`leankg prd` / `prd-trace`, `query --action prd`, matriz de trazabilidad de ontología
Mega-grafo	Consultas locales de frontera; 100k–700k+ elementos
Superficie de agente	3 herramientas MCP (`import` / `query` / `status`) que sirven 30 acciones (22 de consulta + 8 de importación); los pares suelen tener ~1–17 herramientas crudas
Costo	A/B −65% tokens, −85% llamadas a herramientas, 2.5× vs grep/cat

Capacidad	LeanKG	GitNexus	Graphify	Codanna	Context7
Despliegue de equipo multi-repositorio	Sí	Parcial	Limitado	Limitado	n/a
Mapa de entornos / incidentes / equipo	Sí	No	No	No	No
Trazabilidad de PRD	Sí	No	Parcial	No	No
Mega-grafo (100k+)	Sí	Parcial	Viz limitado	Varía	n/a
Superficie MCP	3 herramientas / 30 acciones	~17	~10	~5	solo docs

Inmersiones profundas (archivadas): ROI vs Graphify · Resumen competitivo de una página · Matriz de investigación

¿Por qué LeanKG?

Los agentes normalmente reconstruyen la estructura con grep → abrir archivos → contexto enorme. LeanKG devuelve un subgrafo dirigido (llamadores, dependientes, radio de explosión, pruebas, docs) más la capa de equipo (entornos, servicios, incidentes, requisitos) a través de MCP.

Sin	Con LeanKG
Muchas llamadas a herramientas, contexto grande	Subgrafo quirúrgico + TOON (~40% cargas más pequeñas)
Sin radio de explosión	Impacto clasificado por gravedad
Solo palabras clave	Palabras clave + semántica HNSW + ontología
Suposiciones de un solo repositorio	Índice multi-repositorio + herramientas de operaciones

Características clave

Nativo MCP — búsqueda, impacto, grafos de llamadas, ontología, arquitectura, conocimiento del equipo
SQLite predeterminado (configuración cero — sin Postgres, sin Docker requerido) con backend Postgres/pgvector opcional (LEANKG_DB_ENGINE=postgres + LEANKG_PG_URL)
Ontología — catálogo de conceptos + capa procedimental (flujos de trabajo, pasos, puntos de decisión, modos de fallo), query --action ontology, POST /api/v1/ontology/match, y trazabilidad req↔código a través de leankg prd / prd-trace
Impacto y dependencias — bordes contains, calls, imports; radio de explosión BFS (leankg impact)
Interfaz web v2 — explorador Force / Tree / Circles (cd ui-v2 && npm run dev; la compilación integrada es servida por leankg serve --ui)
Despliegue — binario único sin CGO, sin dependencias de runtime: Dockerfile compila una imagen de demostración de solo lectura para Render, /health responde a los sondeos del contenedor, y --ui / --http / --rest / --rpc cada uno enlaza su propia dirección
Lenguajes — 40 perfiles: 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

Orden de preferencia MCP

Descubre con query — enruta por la escalera por defecto (L1 exacto → L2 difuso → L3 semántico), degrada en lugar de fallar, y cada respuesta lleva retrieval{rung,reason} + freshness.

Pregunta	Cómo
Cualquier identificador (predeterminado)	`query "Alpha"` (exacto, luego respaldo difuso)
Radio de explosión	`leankg impact <file>` o `query --action impact --to <qn>`
¿Quién llama a X?	`query --action callers --to <qn>`
¿Cómo A↔B?	`query --action path --to <qn>`
Detalles del elemento	`query --action explain --to <qn>`
Búsqueda de patrones	`query --action pattern --pattern "func $_(...)"`
Trazabilidad de PRD	`leankg prd-trace FR-3T-01`
Archivo (comprimido)	`query --action read --path src/main.go`

3 herramientas: import (índice/PRD/memoria/sesión/ontología/lectura) · query (escalera + verbos de grafo + acciones) · status (inventario/frescura/configuración).

CLI

leankg index .                          # one-shot index -> .leankg/leankg.db
leankg writer                           # index once, then watch + re-index
leankg query "parseConfig"              # name lookup (exact, then fuzzy) — JSON out
leankg query "parseConfig" --compress   # one line per result
leankg impact src/main.go --depth 3     # blast radius of a file or element
leankg status                           # health, inventory, freshness, embed state
leankg doctor                           # store path, element/file counts, watermark
leankg connect claude-code              # MCP entry: claude-code|cursor|codex|gemini|opencode|omp
leankg install --target cursor          # same wiring, flag form (--register-cwd: claude-code hook)
leankg serve --stdio                    # MCP over stdio (what harnesses spawn)
leankg serve --http 127.0.0.1:9699      # MCP over streamable HTTP (/mcp, /health)
leankg serve --rest 127.0.0.1:8080      # REST API (/health, /api/v1/*)
leankg serve --ui 127.0.0.1:8081        # embedded dashboard (/api/* data API served here)
leankg serve --rpc 127.0.0.1:9090       # ConnectRPC (gRPC + gRPC-Web + JSON)
leankg version

Recarga en caliente de la interfaz: cd ui-v2 && npm install && npm run dev → http://127.0.0.1:5173

Uso completo: leankg help y leankg <command> --help. La referencia CLI archivada de la era Rust: docs/archive/cli-reference.md

Módulo Go

El motor es el módulo raíz github.com/FreePeak/LeanKG, versionado por las etiquetas de release vX.Y.Z de la raíz — por lo que el proxy y pkg.go.dev resuelven versiones reales y go install github.com/FreePeak/LeanKG/cmd/leankg@latest compila el servidor + CLI directamente desde el código fuente.


Superficie	exactamente 3 herramientas MCP — `import` / `query` / `status` (fijadas por `internal/mcp/server_test.go`). `query` enruta la escalera (L1 exacto → L2 palabra clave/FTS → L3 semántico) y degrada en lugar de fallar, por lo que cada respuesta lleva `retrieval{rung,reason}` + `freshness`
Almacenamiento	SQLite (WAL, FTS5, vectores float32-BLOB, marca de agua residente en DB) por defecto; PostgreSQL + pgvector opcional (`LEANKG_DB_ENGINE=postgres` + `LEANKG_PG_URL`) con esquema por proyecto y HNSW por modelo — ambos detrás de `store.Backend`
Transportes	MCP stdio · MCP HTTP transmisible (`--http`, `/mcp` + `/health`) · REST (`--rest`, `/health` + `/api/v1/*`) · ConnectRPC (`--rpc`) · panel integrado (`--ui`)
Indexación	40 perfiles de lenguaje (`internal/langs.Default`), niveles AST regex → ast-grep → tree-sitter (detrás de la etiqueta `tstree`), detección de cambios de 3 señales, rol `writer` con reconciliación fsnotify
Embeddings	binario `leankg-embed` + puerto de proveedor (compatible OpenAI / sidecar llama.cpp / determinista). Cada escritor de vectores está protegido por `ModelStamp`, por lo que un cambio de modelo falla de manera ruidosa en lugar de mezclar espacios vectoriales

Diseño

cmd/leankg/         serve (stdio | MCP HTTP | REST | RPC | dashboard) · index · writer
                    query · impact · status · doctor · report · connect · install
                    prd · prd-trace · incident · note · obsidian · push · pull · update
cmd/leankg-embed/   run · full · export · import · status
internal/store/     Backend interface + SQLite (WAL/FTS5/watermark) + PGStore (pgvector)
internal/core/      3-tool envelope + L0–L3 ladder + memory/graph routing
internal/index/     extractors, 3-signal detection, call-edge resolution
internal/langs/     the 40 profiles, AST tiers, per-language LSP specs
internal/graph/     impact · path · callers/callees · context · explain · clusters
internal/ontology/  concept catalog + procedural workflows/traceability
internal/mcp/       modelcontextprotocol/go-sdk adapters (stdio + streamable HTTP)
internal/rest/      stdlib net/http REST surface
internal/web/       ui-v2 dashboard via //go:embed (checked-in build) + its /api/*
internal/embed/     provider port, ModelStamp guards, NDJSON export/import
internal/memory/    full-markdown memory + mnemopi bank adapter
internal/watch/     fsnotify reconcile (writer role)
internal/golden/    Rust-vs-Go parity fixtures

Compilación

go build ./... && go vet ./... && go test ./... -count=1   # CGO-free shape
go build -tags tstree ./...                                # tree-sitter tier (CGO)

La compilación del panel bajo internal/web/embed está verificada y se resincroniza con make go-ui-assets; su marcador de procedencia es embed/ui-build.json. scripts/test-dual-engine.sh es la puerta de SQLite + Postgres en vivo (LEANKG_TEST_PG_URL controla la mitad de PG).

Limitaciones conocidas

Los bordes de llamadas están limitados al paquete. Sin resolución de importaciones/tipos, por lo que una llamada con el mismo nombre en el mismo paquete se resuelve y el despacho entre paquetes es de mejor esfuerzo; el camino de actualización son las tablas de símbolos de tree-sitter.
Guardas heurísticas, documentadas en internal/index/relations.go: los archivos ≥ 1 MiB se omiten como paquetes vendored/minificados, los objetivos de llamadas de menos de 4 caracteres se descartan como ruido, y las llamadas salientes están limitadas por elemento y por archivo.
La unidad de alcance es un repositorio. Una raíz de portafolio (decenas de miles de archivos anidados) no es un proyecto; registra sus hijos uno a la vez.
--ui enlaza una API de datos no autenticada (rutas query/read/importación). Enlázala a loopback o colócale un proxy al frente — el contenedor de demostración público la sirve --read-only contra un grafo horneado desechable.

Documentación

El conjunto de documentación vive en docs/ — un PRD unificado único (docs/prd.md) + rastreador de tareas (docs/prd-task-tracker.md). Todos los documentos de diseño históricos, análisis, informes y planes se conservan bajo docs/archive/.

Doc
PRD	Requisitos de producto unificados + HLD (única fuente de verdad)
Seguimiento de tareas	Hecho / en curso / pendiente
Arquitectura (archivado)	Diseño y modelo de datos (histórico)
Herramientas MCP (archivado)	Catálogo de herramientas (histórico)
CLI (archivado)	Todos los comandos (histórico)
Benchmarks (archivado)	Metodología (histórico)
Migración a Postgres (archivado)	Notas del motor (histórico)
AGENTS.md	Notas para agentes

Solución de problemas

Problema	Solución
Proyecto incorrecto servido	Inicie el servidor con `--project DIR` (`query`/`impact` también respetan `LEANKG_PROJECT`)
Embeddings / cold embed	`leankg-embed status`, luego `leankg-embed full` (env del proveedor: `LEANKG_EMBED_*`)

Requisitos: macOS o Linux · Go 1.25+ solo al compilar desde el código fuente. Sin Docker, sin Postgres — sqlite es el almacén predeterminado.

Contribuciones

Haga un fork + rama de características (prefiera un worktree)
Actualice la documentación cuando cambie el comportamiento
go build ./... && go vet ./... && go test ./...
Abra un PR con resumen + plan de pruebas

Licencia

Licencia Apache 2.0