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: 126 tools · ~6,240 tok.

| Flag | Tools | ~Tokens | |------|------:|--------:| | core (always-on) | 3 | ~170 | | enableNavigation | 3 | ~120 | | enableMemory | 16 | ~746 | | enableSecurity | 15 | ~675 | | enableData | 10 | ~519 | | enableWiki | 10 | ~319 | | enableCodeHealth | 25 | ~935 | | enableDocs | 5 | ~241 | | enableAgentUtils | 4 | ~278 | | enableArchitecture | 5 | ~205 | | enableWatchmen | 3 | ~140 | | enablePatterns | 3 | ~93 | | trackCallSites | 2 | ~84 | | enableGitContext | 7 | ~410 | | enableComplexity | 5 | ~660 | | enableEditPrimitives | 5 | ~280 | | enableBranch | 3 | ~300 | | enableShellExec | 1 | ~71 | | enableGeneralCompression | 1 | ~68 | | Total | 126 | ~6,240 |

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.
• tokensave: gap-close roadmap inspiration — code quality tools (complexity, god class, recursion, doc coverage), git workflow context tools (diff_context, commit_context, test_map), atomic edit primitives, multi-branch indexing, per-call token metrics, and MCP protocol annotations (readOnlyHint, alwaysLoad).

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 | | Gap-close roadmap | tokensave | Code quality metrics, git context tools, atomic edit primitives, multi-branch indexing |

See the full comparison for a detailed feature matrix against CodeGraph, code-review-graph, jCodeMunch, tokensave, 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 |