They stack: with both enabled, shell commands return 60-90% fewer tokens and the agent's explanations around those results are also shorter. Pick both independently during kirograph install. The "ultra + ultra" combo gives maximum token savings on both fronts.

General-purpose Compression (opt-in)

When enableGeneralCompression: true is set, the kirograph_compress MCP tool is available for on-demand compression of arbitrary text before it reaches the model. Inspired by headroom by Tejas Chopra.

Unlike kirograph_exec (which compresses automatically in the background when a shell command runs) or caveman mode (which compresses the agent's own prose via steering), kirograph_compress is an explicit, agent-initiated action — the agent decides when to compress, what to compress, and at what intensity.

Two engines, one interface

Pass command to activate the rtk-style structural engine. Omit it to use the caveman grammar engine:

Compression levels

Every call returns inline savings: [42% tokens saved | 1800→1044 | rtk:git:aggressive].

When to use

• The agent received a long shell output outside of kirograph_exec (e.g. via a tool that runs a command directly)
• A block of text needs to be summarised before being stored as a memory observation
• You want to compare compressed vs original before deciding what to pass to a follow-up tool call

When not to use

• Commands run via kirograph_exec — already compressed automatically
• Agent prose — enable caveman mode instead (automatic, zero tool-call overhead)
• Source code — compression may break identifiers or whitespace-sensitive content

Memory (opt-in)

When enableMemory: true is set in .kirograph/config.json, KiroGraph stores persistent observations across sessions. Decisions, errors, patterns, and architecture notes are captured with zero LLM tokens on write (compression is deterministic, symbol linking is programmatic, embedding uses the local model) and minimal tokens on read. Inspired by cavemem by Julius Brussee and Engram by Gentleman-Programming.

How it works

The write path runs entirely without LLM involvement:

1. An observation is received (via hook or manual kirograph_mem_store call)
2. If caveman mode is enabled, the text is compressed deterministically using the configured level
3. A content hash deduplicates against existing observations
4. Symbol names in the text are detected and linked to graph nodes via qualified_name
5. The observation is embedded using the same local model and semantic engine as code symbols

On read, kirograph_mem_search performs hybrid FTS + vector search. Linked observations also surface automatically in kirograph_context and kirograph_impact results. Search results include inline relation annotations (⚡ conflict, ✓ compatible) so the agent sees contradictions without a separate query.

Conflict detection and knowledge hygiene

As the memory base grows, observations can contradict each other across sessions. KiroGraph provides a typed relation system to keep knowledge consistent:

• Scan: kirograph_mem_conflicts_scan uses FTS similarity to find candidate contradiction pairs, skipping already-reviewed ones.
• Compare: kirograph_mem_compare places two observations side by side and creates a typed relation (supersedes, conflicts_with, compatible, scoped, related, not_conflict).
• Judge: kirograph_mem_judge finalizes a pending relation with a confidence score and reason — resolving the conflict or confirming compatibility.

Stable addressing and stale scheduling

topicKey is a stable semantic identifier (e.g. "architecture/auth-model") that lets multiple sessions address the same concept without knowing its UUID. Pass it to kirograph_mem_store for any decision that may be revisited or superseded.

reviewAfter is an epoch-ms timestamp that schedules an observation for re-evaluation — useful after a planned migration, a library upgrade, or a time-boxed experiment. kirograph_mem_review lists all overdue observations; kirograph_mem_mark_reviewed clears them once validated.

Passive capture

kirograph_mem_capture extracts and stores observations from structured markdown text without LLM involvement. Bullets under headings like ## Key Learnings, ## Decisions, and ## Observations are parsed and stored as individual observations. This lets agents dump their reasoning in a structured block at session end and have KiroGraph index it automatically.

MCP Tools

CLI Commands

# Search (mirrors kirograph_mem_search)
kirograph mem search <query>
kirograph mem search <query> --kind error --limit 5

# Store (mirrors kirograph_mem_store)
kirograph mem store "decided to use idempotency keys for payments"
kirograph mem store "auth bug: token refresh missing" --kind error

# Timeline & status
kirograph mem timeline
kirograph mem status

# Maintenance (CLI-only)
kirograph mem prune --older-than 90d
kirograph mem reembed
kirograph mem lint
kirograph mem export --format jsonl

Session management

Sessions are managed automatically. On the first kirograph_mem_store call, KiroGraph checks for an active session (same IDE, started within the configured timeout). If none exists, a new session is created. The agentStop hook closes the session automatically.

The inactivity timeout defaults to 2 hours and is configurable via memorySessionTimeout (in seconds).

Configuration

Privacy

Wrap sensitive content in <private>...</private> blocks — they are stripped before storage. All data stays in the local .kirograph/kirograph.db file, same as the rest of the graph.

Watchmen (opt-in) experimental

When enableWatchmen: true is set (requires enableMemory: true), KiroGraph automatically synthesizes accumulated memory observations into workspace brief files. When the observation count since the last synthesis reaches watchmenThreshold (default: 5), kirograph_mem_store returns a watchmenReady signal. Inspired by watchmen by firstbatch.

Synthesis is performed by a local HuggingFace model (watchmenSynthesisMode: 'local', default) or delegated to the active AI agent ('agent', Kiro only, consumes tokens).

Local model

The default mode uses onnx-community/gemma-4-E4B-it-ONNX via @huggingface/transformers (ONNX Runtime). The model is downloaded once to ~/.kirograph/models/ alongside the embedding model — the same cache directory, no extra setup.

Output per tool

Configuration

Wiki (opt-in)

When enableWiki: true is set in .kirograph/config.json, KiroGraph maintains a project-level knowledge wiki — a set of structured markdown pages that compound knowledge across sessions. Unlike memory observations (ephemeral, session-scoped), wiki pages are curated, durable facts: architecture decisions, API contracts, domain concepts, and process steps. The LLM reads, writes, and searches pages via MCP tools; a two-step ingest flow (ingest → apply-diff) gives the agent explicit control over what enters the wiki. Inspired by Andrej Karpathy's LLM Wiki gist: the three-op pattern (ingest → apply → lint), the WIKI_DIFF block format, the two-tool ingest flow, and the principle of knowledge compounding rather than accumulating.

How it works

1. Agent calls kirograph_wiki_ingest with a source text (meeting notes, code review, design doc).
2. The tool returns a structured prompt containing the wiki schema, the current manifest, and the source text.
3. In agent mode (default): the agent generates a WIKI_DIFF block and calls kirograph_wiki_apply_diff to commit it. The agentStop hook prompts this automatically.
4. In local model mode: the source is queued in wiki_queue. At agentStop, a runCommand hook invokes kirograph wiki synthesize which runs a local HuggingFace model to generate and apply diffs — zero API cost, no data leaves your machine.
5. Pages are written to .kirograph/wiki/ as markdown files and indexed in SQLite with FTS5 full-text search.

kirograph_wiki_context surfaces relevant pages automatically inside kirograph_context results when the query matches wiki content above the configured threshold.

MCP Tools

WIKI_DIFF format

The LLM produces structured diff blocks that the tool applies atomically:

WIKI_DIFF_START
{"page": "auth-service", "title": "Auth Service", "action": "create"}

# Auth Service

Handles JWT token generation and validation with RS256 signing.
Tokens expire after 15 minutes.

## Related
- [[payment-flow]]
WIKI_DIFF_END

Supported actions: create (new page), upsert (overwrite), append (add section). Conflicts (incoming content contradicts an existing page) are surfaced as WIKI_DIFF_CONFLICTS blocks for the agent to resolve, or auto-resolved when wikiAutoResolveConflicts: true.

CLI Commands

# Initialise the wiki (creates SCHEMA.md and MANIFEST.md)
kirograph wiki init

# List all pages
kirograph wiki list
kirograph wiki list --format json

# Full-text search
kirograph wiki search "JWT authentication"

# Read a page
kirograph wiki page auth-service

# Ingest a source (agent mode: returns prompt; local mode: queues source)
kirograph wiki ingest --source "design docs" --file ./docs/auth-design.md

# Run local-model synthesis over the queue (local mode only)
kirograph wiki synthesize
kirograph wiki synthesize --quiet

# Rebuild the DB index from wiki markdown files on disk
kirograph wiki reindex

# Lint the wiki: detect broken links, orphan pages
kirograph wiki lint

# Wiki status
kirograph wiki status

Local model synthesis

When wikiSynthesisMode: 'local', KiroGraph queues source texts and runs a local HuggingFace model (wikiLocalModel) at agentStop via a runCommand hook. Same infrastructure as Watchmen — model downloaded once to ~/.kirograph/models/, runs on-device, no API key required.

Configuration

Documentation (opt-in)

When enableDocs: true is set in .kirograph/config.json, KiroGraph indexes project documentation by heading hierarchy and section structure. Instead of reading entire doc files, agents retrieve exactly the section they need via stable section IDs — saving 92–97% of tokens compared to reading full files. Inspired by jDocMunch-MCP by J. Gravelle.

How it works

The indexing pipeline:

1. Scans the project for documentation files matching docsInclude / docsExclude patterns
2. Detects the format (Markdown, RST, AsciiDoc, etc.) and parses headings into a section hierarchy
3. Generates stable section IDs: {file_path}::{ancestor-chain/slug}#{level}
4. Computes SHA-256 content hashes for incremental re-indexing (skips unchanged files)
5. If docsLinkCode: true, detects code symbol references (backtick patterns, CamelCase, snake_case) and stores cross-references via qualified_name
6. Stores everything in doc_sections and doc_code_refs tables in the same SQLite DB

On read, agents use kirograph_docs_search (FTS5) to find sections, kirograph_docs_section to retrieve content, and kirograph_docs_refs to navigate code ↔ docs cross-references.

Supported formats

MCP Tools

CLI Commands

# Table of contents
kirograph docs toc                          # whole project
kirograph docs toc README.md                # single file
kirograph docs toc README.md --tree         # nested tree

# Search
kirograph docs search "authentication"
kirograph docs search "config" --file docs/guide.md --limit 5

# Retrieve a section
kirograph docs section "README.md::installation#1"
kirograph docs section "README.md::installation#1" --context

# Outline
kirograph docs outline docs/api.md

# Cross-references
kirograph docs refs "docs/auth.md::oauth/token-refresh#2"

# Maintenance
kirograph docs reindex                      # force full re-index
kirograph docs lint                         # health checks
kirograph docs reembed                      # re-embed with current model

Context integration (opt-in)

By default, kirograph_context does not include doc sections — the agent uses kirograph_docs_* tools explicitly. If you want docs to surface automatically in context results, set docsContextLimit to a value greater than 0 during install (or in config).

When enabled, kirograph_context queries doc_code_refs for the symbols it found and includes up to N relevant doc sections (above docsContextThreshold score).

Configuration

Token savings

Documentation tools are tracked in kirograph_gain as a separate "Docs tools" source category. Typical savings per call:

Data (opt-in)

When enableData: true is set in .kirograph/config.json, KiroGraph indexes tabular data files and documents (CSV, TSV, JSONL, JSON, Excel, Parquet, PDF) that live alongside your code — test fixtures, seed data, configuration tables, sample datasets, reports. Instead of reading raw data files into context, agents query structured schemas and filtered rows — saving 95–99% of tokens. Inspired by jDataMunch-MCP by J. Gravelle.

Key features

• Streaming parser: never loads full files into memory. Processes line-by-line (CSV/JSONL) or in chunks (Excel/Parquet).
• Column profiling: type inference (string, integer, float, boolean, date), cardinality, null percentages, min/max, mean, sample values.
• Server-side computation: filters, aggregations, joins, and correlations run in SQLite. Only results enter the context window.
• Incremental indexing: content hash (SHA-256) per file. Only re-indexes files that changed.
• Optional format deps: CSV/TSV/JSONL/JSON are built-in (zero deps). Excel requires xlsx, Parquet requires parquetjs-lite, PDF requires @firecrawl/pdf-inspector (prebuilt Rust binary, linux-x64 and macOS ARM64).
• Code ↔ data linking: detects file path references in source code and populates data_code_refs. Enables test fixture awareness in kirograph affected.
• Schema drift detection: tracks profile history across re-indexes. kirograph data drift shows added/removed/changed columns.
• NL summaries: auto-generated natural-language descriptions for each column based on profile patterns.
• Validation rules: infers rules from profiles (required, type, range, enum, uniqueness).
• Anti-loop detection: warns when agent paginates row-by-row instead of using aggregations.
• Token budget enforcement: responses exceeding dataMaxResponseTokens are truncated.

Supported formats

MCP tools

Configuration

Token savings

Security

When enableSecurity: true, KiroGraph scans dependency manifests for known vulnerabilities and performs reachability analysis to determine if vulnerable code is actually reachable from entry points.

Configuration

Pipeline

The security pipeline runs after architecture analysis during indexing:

code extraction → reference resolution → architecture analysis → security analysis

Phases: manifest discovery → dependency parsing → dependency graph integration → vulnerability enrichment (OSV) → reachability analysis → impact analysis.

Supported ecosystems

Reachability verdicts

CLI commands

CycloneDX output

KiroGraph-Sec exports industry-standard CycloneDX 1.5 documents:

• SBOM — Full software bill of materials with all dependencies as components, package URLs, and dependency relationships
• VEX — Vulnerability Exploitability eXchange with reachability-derived analysis states and justifications

Feature comparison →

TurboQuant

TurboQuant is an optional upgrade that compresses your vector embeddings at storage time and replaces the default linear scan with an approximate nearest-neighbour (ANN) index — with zero native dependencies.

Built on turboquant-js by Danilo Dev, a TypeScript implementation of Google's TurboQuant algorithm. Embeddings are compressed immediately on kirograph index:

1. Walsh-Hadamard rotation with random sign flips in O(d log d). Distributes energy uniformly across all coordinates before quantization.
2. Lloyd-Max scalar quantization per rotated coordinate. Each value is encoded in turboquantBits bits (default: 3) using optimal codebooks.

Compression at a glance

When to use TurboQuant

Setup

npm install turboquant-js

{
  "enableEmbeddings": true,
  "semanticEngine": "turboquant",
  "turboquantBits": 4
}

Or select it interactively during kirograph install — the installer auto-runs npm install turboquant-js for you. Falls back silently to cosine if turboquant-js is not installed.

Configuration

The compressed index is serialized to .kirograph/turboquant.bin at the end of indexing and reloaded in milliseconds on startup. Run kirograph status to see live compression stats.

TurboVec

TurboVec is the Rust/SIMD counterpart of TurboQuant. It runs the same Walsh-Hadamard + Lloyd-Max quantization algorithm in Rust and exposes it to Node.js as a napi-rs native addon (native/turbovec-node/). SIMD-accelerated: NEON on ARM64 (Apple Silicon, AWS Graviton), AVX-512BW on x86-64. On macOS it links Apple's Accelerate framework; on Linux it links OpenBLAS; on Windows it uses pure-Rust matrixmultiply.

Built on turbovec by Ryan Codrai.

Compression at a glance

When to use TurboVec vs TurboQuant

Setup

The simplest path is kirograph install — it auto-installs Rust (via rustup) if missing on macOS/Linux, then builds the addon. Or manually:

cd native/turbovec-node
npm install
npm run build   # requires Rust toolchain — https://rustup.rs

{
  "enableEmbeddings": true,
  "semanticEngine": "turbovec",
  "turbovecBits": 4
}

Falls back silently to cosine if the addon is not built.

Configuration

The index is stored as two files: .kirograph/turbovec.tvim (binary) and .kirograph/turbovec.tvim.ids (JSON sidecar mapping internal u64 hashes back to string symbol IDs). Both are written atomically at the end of indexing.

Savings Heuristics

kirograph gain tracks two types of savings: compression (measured exactly) and graph tools (estimated via heuristics). For graph tools, the system estimates what the agent would have spent doing the same work without KiroGraph:

Constants: 1,500 tokens per average source file (~200 lines), 800 tokens per grep result set, 2,000 tokens per directory listing. These are conservative estimates; in practice agents often read more files, retry failed searches, and explore dead ends.

Credits

Original idea

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.
• code-review-graph by Tirth Kanani: community detection, execution flow tracing, refactoring tools, and multi-platform auto-detection patterns.
• rtk by rtk-ai: the shell compression module's command-family approach and token-optimized output 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 behind kirograph_retrieve, the dual-engine on-demand compression behind kirograph_compress, and the KV cache prefix stability approach (deterministic cache markers).
• 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. Exposes per-page markdown extraction with OCR and layout flags via a napi-rs native addon.
• 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.

Stargazers & Community

Thank you to everyone who contributed and starred the project on GitHub.