KiroGraph

Semantic code knowledge graph for Kiro: fewer tool calls, instant symbol lookups, 100% local.

Inspired by CodeGraph by colbymchenry for Claude Code, rebuilt natively for Kiro's MCP and hooks system.

Full support is for Kiro only. Experimental integrations for 34 other MCP-capable tools (Cursor, Copilot, Claude Code, Windsurf, Cline, and more) are available with auto-detection. See Integrations for the full list.

Why KiroGraph?

When you ask Kiro to work on a complex task, it explores your codebase using file reads, grep, and glob searches. Every one of those is a tool call, and tool calls consume context and slow things down.

KiroGraph gives Kiro a semantic knowledge graph that's pre-indexed and always up to date. Instead of scanning files to understand your code, Kiro queries the graph instantly: symbol relationships, call graphs, type hierarchies, impact radius, all in a single MCP tool call.

The result is fewer tool calls, less context used, and faster responses on complex tasks.

Features

Feature	Description
Graph & Analysis (KiroGraph-Core)
🕸️ Semantic Graph	tree-sitter AST parsing across 33+ languages — functions, classes, call edges, type hierarchies, all in SQLite
🎯 Context Building	One tool call returns entry points, related symbols, and code snippets for any task description
💥 Impact Analysis	Blast-radius traversal before making changes — know what breaks at any depth
🧬 Type Hierarchy	Traverse inheritance chains — base types, derived types, implementations
🔄 Circular Dependency Detection	Find import cycles using Tarjan's SCC algorithm
💀 Dead Code Detection	Find unexported symbols with zero incoming references
🔥 Hotspots & Surprises	Identify most-connected symbols and unexpected cross-module coupling
🧪 Affected Tests	Find test files impacted by source changes — useful in CI and pre-commit hooks
🌐 Graph Export	Interactive browser dashboard with search, clustering, path finding, and analytics
Semantic Search
⚡ 9 Semantic Engines	Cosine, TurboQuant, TurboVec, sqlite-vec, Orama, PGlite, LanceDB, Qdrant, Typesense — pick the best fit for your project
🗜️ TurboQuant Embedding Compression	Compresses embeddings 20–30× at index time using Google's TurboQuant algorithm (Walsh-Hadamard rotation + Lloyd-Max quantization). A 768-dim Float32 vector (3,072 bytes) becomes ~120 bytes — 300 MB of raw embeddings shrinks to ~12 MB in RAM. ANN search with zero native dependencies, pure TypeScript. Configurable via turboquantBits. Powered by turboquant-js by Danilo Dev.
⚡ TurboVec (Rust/SIMD)	Same TurboQuant algorithm in Rust via napi-rs — NEON on ARM64, AVX-512BW on x86. Faster search at the cost of a one-time Rust build. Configurable via turbovecBits (2–4). Powered by turbovec by Ryan Codrai. The native addon (native/turbovec-node/) is a Rust crate with its own Cargo build — it lives outside src/ because it is not TypeScript. kirograph install builds it automatically.
🤖 Custom Embedding Models	Use any HuggingFace feature-extraction model — nomic, Gemma, MiniLM, BGE, or bring your own
Architecture (KiroGraph-Arch opt-in module)
🏛️ Architecture Analysis	Package graph, layer detection, coupling metrics (Ca/Ce/instability)
📸 Snapshots & Diff	Save graph state before refactors, diff after to verify structural changes
Security
🔒 Security (KiroGraph-Sec opt-in module)	Goes beyond "this dependency has a CVE" — uses the call graph to determine if vulnerable code is actually reachable from your entry points. Maps your attack surface (which HTTP routes reach vulnerable deps). Detects hardcoded secrets and shows how many entry points expose them. SAST-lite finds SQL injection, path traversal, and dangerous eval in your code. AST-based SAST (opt-in via enablePatterns) runs 10 bundled structural pattern rules via @ast-grep/napi — matches actual code structure, not just symbol names. Supply chain health checks OpenSSF Scorecard scores and detects dependency confusion attacks. Covers 14 ecosystems, outputs CycloneDX SBOM/VEX and CI-ready SARIF reports.
Knowledge & Data
🧠 Persistent Memory (KiroGraph-Mem opt-in module)	Cross-session observations — decisions, errors, patterns — auto-linked to code symbols. Conflict detection: typed relations between observations (supersedes, conflicts_with, compatible) with agent judgment workflow (kirograph_mem_compare, kirograph_mem_judge). Stale review: schedule observations for re-evaluation (review_after + kirograph_mem_review). Passive capture: extract learnings from structured text. Prompt saving: session context reconstruction. Topic key: stable semantic addressing. Inspired by Engram.
👁️ Watchmen (KiroGraph-Watchmen opt-in module) ⚠️ experimental	Auto-synthesizes accumulated memory observations into workspace briefs and inclusion: manual skill files. Fires via the watchmenReady signal in kirograph_mem_store when threshold is reached. Local model (default, watchmenSynthesisMode: 'local'): runs gemma-4-E4B-it-ONNX on-device via @huggingface/transformers — ~3–4 GB one-time download, ~3–5 GB RAM, 8–15 s on Apple Silicon M1+. No API key, no background daemon, no external calls. Agent mode also available for Kiro (watchmenSynthesisMode: 'agent', uses active session). ⚠️ Experimental: output quality in local mode depends heavily on the model chosen and your hardware. Smaller models or slower machines may produce incomplete briefs and lower-quality skill files. Use agent mode for best results.
📚 Wiki (KiroGraph-Wiki opt-in module)	Karpathy-style LLM wiki — a set of markdown pages that compound knowledge across sessions. Three ops: ingest (build structured prompt from source text), apply-diff (write LLM-generated WIKI_DIFF to SQLite + disk), lint (broken links, orphan pages, contradictions). Context enrichment: kirograph_context auto-includes relevant wiki pages above score threshold. Two synthesis modes: agent (IDE LLM) or local (HuggingFace, same infra as Watchmen). Conflict resolution: deterministic by source date when wikiAutoResolveConflicts: true. Inspired by Karpathy's LLM Wiki pattern.
📖 Documentation Indexing (KiroGraph-Doc opt-in module)	Section-level retrieval from Markdown, MDX, RST, AsciiDoc, OpenAPI — 92-97% token savings
📊 Data Navigation (KiroGraph-Data opt-in module)	Query CSV/JSON/Excel/Parquet/PDF with filters, aggregations, joins — all server-side in SQLite
Token Optimization
🗜️ Shell Compression (KiroGraph-RTK opt-in module)	Token-optimized command output (git, tests, linters, docker, AWS) — 60-90% savings
🪨 Caveman Mode (KiroGraph-Caveman opt-in module) 🪨	Agent prose compression (lite → ultra) — fewer tokens on explanations without touching code
📦 General-purpose Compression (kirograph_compress, opt-in)	On-demand compression tool for arbitrary text. Two engines: rtk-style structural filters for shell output (command-hinted), caveman grammar for prose. Five levels (lite → ultra). Reports inline savings. Inspired by headroom.
📥 File Read Cache + CCR (kirograph_read / kirograph_retrieve, opt-in)	kirograph_read caches files on first read — unchanged files return a ~13-token marker on subsequent reads. kirograph_retrieve (CCR) recovers the cached full content without a filesystem re-read. Prefix-stable markers enable KV cache hits on conversation context. Inspired by lean-ctx and headroom.
📈 Token Analytics (KiroGraph-Gain core module)	Track cumulative savings from graph tools and shell compression over time
Integration (KiroGraph-Integration core module)
🔌 Multi-tool Support	Native Kiro + 32 experimental targets (Cursor, Copilot, Claude Code, Codex, Windsurf, Cline, and more)

MCP Tool List Token Budget

Each enabled flag adds tools to the model context on every MCP call. Total with all flags: 92 tools · ~4,367 tok.

Flag	Tools	~Tokens
core (always-on)	8	~472
enableMemory	16	~746
enableSecurity	15	~675
enableData	10	~519
enableWiki	10	~319
enableCodeHealth	7	~309
enableAgentUtils	4	~278
enableAdvancedAnalysis	4	~210
enableArchitecture	3	~142
enableWatchmen	3	~140
enablePatterns	3	~93
trackCallSites	2	~84
enableShellExec	1	~71
enableGeneralCompression	1	~68
Total	92	~4,367

Quick Start

kirograph install        # auto-detects your AI tools and configures them all

Or target a specific platform:

kirograph install --target kiro       # Kiro only
kirograph install --target cursor     # Cursor only
kirograph install --target claude     # Claude Code only
kirograph install --all               # all detected platforms (no prompt)

Or using the short alias:

kg install

All Kiro integration files are written to .kiro/. Restart Kiro IDE, or switch to the kirograph agent in Kiro CLI.

Documentation

📖 Full documentation on GitHub Pages

Page	Description
Installation	Install from npm or source, uninstall, verify
How It Works	Indexing layers (structural, semantic, architecture, memory, docs, data)
Integrations	Kiro setup, 34 other tools, auto-detection
Comparison	Feature comparison vs CodeGraph, code-review-graph, and others
MCP Tools	Full reference for all MCP tools
CLI Reference	All CLI commands with examples
Configuration	Config fields, semantic engines, architecture analysis
Security	Full SCA+: 14 ecosystems, EPSS, reachability, attack surface, secrets, SAST-lite, AST pattern matching (opt-in), supply chain, SBOM/VEX/SARIF
Languages & Frameworks	Supported languages, frameworks, and detection
Changelog	Release history
Contributing	How to contribute
Code of Conduct	Community guidelines
Security	Security policy

How It Works

┌─────────────────────────────────────────┐
│                  Kiro                   │
│                                         │
│  "Fix the auth bug"                     │
│           │                             │
│           ▼                             │
│  kirograph_context("auth bug")          │
│           │                             │
└───────────┼─────────────────────────────┘
            ▼
┌───────────────────────────────────────────┐
│         KiroGraph MCP Server              │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐   │
│  │  search  │ │ callers  │ │ context  │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘   │
│       └────────────┼────────────┘         │
│         SQLite Graph DB (.kirograph/)     │
└───────────────────────────────────────────┘

What Gets Indexed?

KiroGraph uses tree-sitter to parse your source files into an AST and extract:

• Nodes: functions, methods, classes, interfaces, types, enums, variables, constants, routes, components, dependencies, vulnerabilities, and more (26 node kinds total)
• Edges: calls, imports, exports, extends, implements, contains, references, instantiates, overrides, decorates, type_of, returns

Everything is stored in a local SQLite database (.kirograph/kirograph.db). Nothing leaves your machine. No API keys. No external services.

Requirements

• Node.js >= 18
• Kiro IDE (fully supported)
• Other MCP-capable tools (experimental — see Integrations)

Credits

KiroGraph is inspired by CodeGraph by Colby McHenry. The original concept of building a semantic code graph for AI coding agents comes from his work.

Inspirations

• cavemem by Julius Brussee: the memory module's hook-based observation capture, deterministic compression, and SQLite storage pattern.
• Engram by Gentleman-Programming: conflict detection (typed relations + judgment workflow), topic_key stable addressing, review_after stale observation scheduling, passive capture, and prompt saving patterns.
• caveman by Julius Brussee: the caveman mode's agent prose compression concept, multi-level steering injection.
• watchmen by firstbatch: the watchmen module's session-mining concept, workspace brief generation, and AGENTS.md mirroring pattern.
• LLM Wiki by Andrej Karpathy: the wiki module's three-op pattern (ingest → apply → lint), WIKI_DIFF block format, two-tool ingest flow, and the principle of knowledge compounding rather than accumulating.
• jDocMunch-MCP by J. Gravelle: the documentation module's section-first retrieval approach, stable section IDs, and byte-offset addressing.
• jDataMunch-MCP by J. Gravelle: the data module's column profiling, streaming parsers, and server-side aggregation approach.
• rtk by rtk-ai: the shell compression module's command-family approach and token-optimized output patterns.
• code-review-graph by Tirth Kanani: community detection, execution flow tracing, refactoring tools, and multi-platform auto-detection patterns.
• lean-ctx by Yves Gugger: file read caching, multiple read modes, and context budget governance concepts.
• headroom by Tejas Chopra: the CCR (Cached Content Retrieval) pattern (kirograph_retrieve), dual-engine on-demand compression (kirograph_compress), and KV cache prefix stability via deterministic marker strings.
• turboquant-js by Danilo Dev: the TurboQuant engine — TypeScript implementation of Google's Walsh-Hadamard + Lloyd-Max quantization algorithm used for embedding compression.
• turbovec by Ryan Codrai: the TurboVec engine — Rust implementation of TurboQuant with SIMD acceleration, exposed to Node.js via a napi-rs native addon.
• pdf-inspector by Firecrawl: the PDF parser used in the data module — pure Rust, no OCR, no network, prebuilt binaries for linux-x64 and macOS ARM64.

Contributors

• Alessandro Franceschi — Claude Code and Codex integration, Elixir/Phoenix language and framework support.
• Mauro Argo — original idea for the architecture layer analysis feature.

How It Compares

KiroGraph combines capabilities from 14 separate projects into one integrated MCP server:

Capability	Inspired by	What KiroGraph adds
Code graph	CodeGraph	Architecture metrics, execution flows, layered dependency view
Community detection	code-review-graph	Coupling metrics (Ca/Ce/instability), refactoring tools, multi-platform auto-detect
Memory	cavemem + Engram	Symbol-linked observations, 9 semantic engines, conflict detection, stale review
Watchmen synthesis	watchmen	Local-model synthesis on-device, auto threshold, steering + skill file generation
LLM Wiki	Karpathy's LLM Wiki gist	WIKI_DIFF format, FTS5 search, conflict resolution, local model mode
Docs	jDocMunch-MCP	Code ↔ docs cross-references
Data	jDataMunch-MCP	Unified with code graph in one server, PDF parsing
PDF parsing	pdf-inspector	Pure Rust, no OCR/network, prebuilt binaries, piped into data module
Shell compression	rtk	Integrated as MCP tool, no separate binary
Prose compression	caveman	Multi-level (lite/full/ultra) via steering
On-demand compression + CCR	headroom	Dual-engine (rtk shell + caveman prose) via kirograph_compress; CCR pattern via kirograph_retrieve; KV-cache prefix stability
Embedding compression	turboquant-js	9 engine options, SIMD Rust variant, 20–30× RAM savings
SIMD vector search	turbovec	NEON on ARM64, AVX-512BW on x86, auto-built by installer
Context layer	lean-ctx	File caching, read modes, budget governance

See the full comparison for a detailed feature matrix against CodeGraph, code-review-graph, jCodeMunch, and others.

Star History

License

MIT

Document	Description
License	MIT License — permissions, conditions, copyright
Disclaimer	Limitations of use, no professional advice, data handling
Warranty Disclaimer	Software provided "as is", no warranties of any kind
Limitation of Liability	Exclusion of liability for damages arising from use
Terms of Use	Permitted and prohibited use, user obligations, privacy