KiroGraph: Local code knowledge graph for AI, optimized for token efficiency

Notifications You must be signed in to change notification settings

Fork 11

Star 75

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

120 Commits

120 Commits

assets

assets

docs

docs

scripts

scripts

src

src

.gitignore

.gitignore

CHANGELOG.md

CHANGELOG.md

README.md

README.md

package.json

package.json

tsconfig.json

tsconfig.json

Repository files navigation

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 other MCP-capable tools (Claude Code, Codex) are available but not fully tested. See Other Tools (Experimental) for details.

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.

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, and more (24 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.

The index is kept fresh automatically via Kiro hooks when using the Kiro integration; no background watcher process needed.

How Indexing Works

Indexing has three layers: structural (always on), semantic (opt-in), and architecture (opt-in).

Structural indexing

tree-sitter parses every source file into an AST. Nodes and edges are extracted and written to kirograph.db. This is what powers all graph traversal tools (kirograph_callers, kirograph_impact, kirograph_path, etc.) and exact/FTS symbol search.

This layer has no extra dependencies and runs on every kirograph index or kirograph sync.

Semantic indexing (opt-in)

When enableEmbeddings: true is set, KiroGraph additionally generates 768-dimensional vector embeddings for every embeddable symbol (function, method, class, interface, type_alias, component, module) using the nomic-ai/nomic-embed-text-v1.5 model (~130MB, downloaded once to ~/.kirograph/models/).

These embeddings power natural-language search in kirograph_context and act as a fallback in kirograph_search. The embeddings are stored in the semantic engine of your choice:

Engine Store Search type Extra deps

cosine (default) kirograph.db (vectors table) Exact cosine, linear scan none

sqlite-vec .kirograph/vec.db ANN (approximate), sub-linear better-sqlite3, sqlite-vec (native)

orama .kirograph/orama.json Hybrid (full-text + vector) @orama/orama, @orama/plugin-data-persistence

pglite .kirograph/pglite/ Hybrid (full-text + vector), exact @electric-sql/pglite (WASM)

lancedb .kirograph/lancedb/ ANN (approximate), sub-linear @lancedb/lancedb (pure JS)

qdrant .kirograph/qdrant/ ANN (HNSW), sub-linear qdrant-local (embedded binary)

typesense .kirograph/typesense/ ANN (HNSW), sub-linear typesense (auto-downloaded binary)

Each engine owns its embedding store exclusively; nothing is written to the SQLite vectors table when a non-cosine engine is active. If an engine's optional dependency is not installed, KiroGraph silently falls back to cosine.

Enable and configure via kirograph install (interactive arrow-key menu) or directly in .kirograph/config.json:

{ "enableEmbeddings": true, "semanticEngine": "pglite" }

Architecture analysis (opt-in)

When enableArchitecture: true is set, KiroGraph detects the high-level structure of your project (packages and architectural layers) and computes coupling metrics between them. Results are stored in arch_* tables inside kirograph.db and exposed via dedicated MCP tools and CLI commands.

Enable via kirograph install or directly in .kirograph/config.json:

{ "enableArchitecture": true }

See the Architecture Analysis section below for full details.

Installation

From npm (not yet available on npm registry)

npm install -g kirograph

From source

git clone https://github.com/davide-desio-eleva/kirograph.git cd kirograph npm install npm run build sudo npm install -g .

After building, the kirograph and kg commands are available globally.

Verify

kirograph --version

Uninstallation

Remove from a project

kirograph uninit [path] # Prompts to remove Kiro integration files and .kirograph/ data separately kirograph uninit --force # Remove Kiro integration files + .kirograph/ data without confirmation kirograph uninit --target all --force # Remove all integration files (Kiro + Claude + Codex) + .kirograph/ data

kirograph uninstall is an alias for kirograph uninit.

Without --force, KiroGraph asks separately whether to remove the selected tool integration files and whether to remove the shared .kirograph/ data. With --force, both are removed unconditionally.

This can remove:

.kirograph/: index database, snapshots, and export directory

Kiro target: .kiro/hooks/kirograph-*.json, .kiro/steering/kirograph.md, .kiro/agents/kirograph.json

Claude target (experimental): kirograph from .mcp.json, plus the KiroGraph import from CLAUDE.md

Codex target (experimental): the generated KiroGraph block from AGENTS.md

Remove the CLI globally

If installed from npm:

npm uninstall -g kirograph

If installed from source:

cd kirograph npm uninstall -g .

Quick Start

In your project:

kirograph install # wire up Kiro MCP + hooks + steering + CLI agent

All Kiro integration files are written to .kiro/. Restart Kiro IDE, or switch to the kirograph agent in Kiro CLI. It will now use KiroGraph tools automatically.

Or using the short alias:

kg install

How It Works

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

Kiro hooks mark the index dirty on every file save or create, then flush on agent idle, batching changes efficiently with no overhead during active editing.

Using with Kiro

kirograph install or kirograph install --target kiro sets up four things in your Kiro workspace (all coexist, so you can switch between IDE and CLI freely):

MCP Server (.kiro/settings/mcp.json)

Registers the KiroGraph MCP server. Used by both the IDE and the CLI agent:

{ "mcpServers": { "kirograph": { "command": "kirograph", "args": ["serve", "--mcp"], "autoApprove": [ "kirograph_search", "kirograph_context", "kirograph_callers", "kirograph_callees", "kirograph_impact", "kirograph_node", "kirograph_status", "kirograph_files", "kirograph_dead_code", "kirograph_circular_deps", "kirograph_path", "kirograph_type_hierarchy", "kirograph_architecture", "kirograph_coupling", "kirograph_package", "kirograph_hotspots", "kirograph_surprising", "kirograph_diff" ] } } }

IDE Auto-Sync Hooks (.kiro/hooks/)

Four hooks keep the index fresh automatically in the Kiro IDE:

Hook Event Action

kirograph-mark-dirty-on-save.json fileEdited kirograph mark-dirty

kirograph-mark-dirty-on-create.json fileCreated kirograph mark-dirty

kirograph-sync-on-delete.json fileDeleted kirograph sync-if-dirty

kirograph-sync-if-dirty.json agentStop kirograph sync-if-dirty --quiet

File changes are batched: saves and creates write a dirty marker; the actual sync runs when the agent stops. Deletes sync immediately. This means no overhead during active editing.

Hooks fire for: .ts, .tsx, .js, .jsx, .py, .go, .rs, .java, .cs, .rb, .php, .swift, .kt, .dart, .ex, .exs

CLI Agent Config (.kiro/agents/kirograph.json)

A custom agent for Kiro CLI that wires up the MCP server, inlines the steering instructions as a prompt, and handles sync in the CLI's own hook format. The CLI has no file-watch events, so syncing is handled at session boundaries instead:

Hook Event Action

agentSpawn Agent starts kirograph sync-if-dirty --quiet (catches edits made between sessions)

userPromptSubmit Each prompt kirograph sync-if-dirty --quiet (keeps graph fresh within a session)

stop End of each turn kirograph sync-if-dirty --quiet (deferred flush, mirrors IDE agentStop)

Use it with:

kiro-cli --agent kirograph

Or swap to it inside an active session:

/agent swap kirograph

Note: restart kiro-cli after running kirograph install for the agent to be picked up.

Steering File (.kiro/steering/kirograph.md)

Teaches the Kiro IDE to prefer graph tools over file scanning when .kirograph/ exists. The CLI agent has the same instructions inlined directly in its prompt field.

Other Tools (Experimental)

⚠️ Not fully tested, community-contributed. The integrations below are outside the original scope of KiroGraph. They are provided as-is. Issues and PRs related to these targets are welcome, but there is no guarantee they will be supported or merged without active help from the contributor.

KiroGraph can also be installed for other MCP-capable coding agents. All targets share the same .kirograph/ data; if the project is already initialized, installing another target only writes that tool's integration files and reuses the existing graph.

kirograph install --target claude # wire up Claude Code MCP + project memory kirograph install --target codex # write Codex instructions and print MCP config

Using with Claude Code

kirograph install --target claude

This writes:

.mcp.json: project-scoped MCP server config for Claude Code

.kirograph/claude.md: KiroGraph tool guidance

CLAUDE.md: an import of .kirograph/claude.md

Claude Code prompts for project MCP approval the first time it sees .mcp.json.

Using with Codex

kirograph install --target codex

This writes:

.kirograph/codex.md: KiroGraph tool guidance

AGENTS.md: a generated KiroGraph instruction block

Codex MCP configuration is user-scoped, so the installer prints the exact codex mcp add ... command and equivalent ~/.codex/config.toml snippet instead of editing files outside the project.

MCP Tools

All tools are auto-approved in Kiro once installed. Other MCP clients can use the same tools after configuring their respective targets.

kirograph_context

Comprehensive context for a task or feature, often sufficient alone without additional tool calls.

Parameter Type Default Description

task string required Task, bug, or feature description

maxNodes number 20 Max symbols to include

includeCode boolean true Include code snippets

projectPath string cwd Project root path

How it works: Extracts symbol tokens from the task description (CamelCase, snake_case, SCREAMING_SNAKE, dot.notation) → runs exact name lookup + FTS + vector search against the active semantic engine → resolves imports to their definitions → expands through the graph to related symbols → returns entry points, related nodes, edges, and code snippets. This is the only tool that uses the vector engine on every call.

kirograph_search

Quick symbol search by name. Returns locations only, no code.

Parameter Type Default Description

query string required Symbol name or partial name

kind

[truncated for AI cost control]