KiroGraph Configuration Reference: config.json Fields

KiroGraph stores its configuration in .kirograph/config.json at the root of your project. You can edit it directly with any text editor, or run kirograph install in an existing project to launch the interactive setup wizard that reads and updates the same file.

Where the Config Lives

The file is created the first time you run kirograph install or kirograph index. To open it in your editor:

# From your project root
code .kirograph/config.json

Complete Example

The following snippet enables the most commonly used modules:

{
  "languages": [],
  "include": [],
  "exclude": ["node_modules/**", "dist/**", "build/**", ".git/**", "*.min.js", ".kirograph/**"],
  "maxFileSize": 1048576,
  "extractDocstrings": false,
  "trackCallSites": false,
  "frameworkHints": [],
  "fuzzyResolutionThreshold": 0.5,
  "enableEmbeddings": true,
  "embeddingModel": "nomic-ai/nomic-embed-text-v1.5",
  "embeddingDim": 768,
  "semanticEngine": "turboquant",
  "turboquantBits": 3,
  "enableArchitecture": true,
  "architectureLayers": {
    "api":     ["src/routes/**", "src/controllers/**"],
    "service": ["src/domain/**", "src/application/**"],
    "data":    ["src/infrastructure/**"]
  },
  "enableSecurity": true,
  "securityDatabases": ["OSV"],
  "securityAutoEnrich": true,
  "enableMemory": true,
  "memoryContextLimit": 3,
  "enableDocs": true,
  "docsLinkCode": true,
  "cavemanMode": "off",
  "shellCompressionLevel": "off",
  "minLogLevel": "warn"
}

Default exclude patterns are: node_modules/**, dist/**, build/**, .git/**, *.min.js, .kirograph/**. These apply even when exclude is an empty array.

Config Field Reference

Indexing

languages

string[]

default:"[]"

Limit indexing to specific language names (e.g. ["typescript", "python"]). An empty array indexes all supported languages.

include

string[]

default:"[]"

Glob patterns that must match for a file to be indexed. An empty array includes everything not covered by exclude.

exclude

string[]

default:"see note"

Glob patterns for files and directories to skip during indexing. Merged with the default exclusion list.

maxFileSize

number

default:"1048576"

Skip any file larger than this byte count (default: 1 MB). Useful to skip generated or minified assets.

extractDocstrings

boolean

default:"false"

Extract JSDoc comments, Python docstrings, and inline documentation comments for each symbol.

trackCallSites

boolean

default:"false"

Record line and column numbers for call edges in the graph. Disable to reduce DB size on very large codebases.

frameworkHints

string[]

default:"auto"

Override auto-detected frameworks (e.g. ["react", "express"]). See Languages & Frameworks for the full list.

fuzzyResolutionThreshold

number

default:"0.5"

Name-matching threshold for cross-file symbol resolution (range 0.0–1.0). Lower values produce more aggressive fuzzy matches.

syncWarningThreshold

number

default:"10"

Emit a warning in kirograph_status when the number of pending (unsynced) files exceeds this value.

Semantic Search

enableEmbeddings

boolean

default:"false"

Generate vector embeddings for functions, methods, classes, interfaces, type aliases, components, and modules. Required for natural-language search. The embedding model is downloaded to ~/.kirograph/models/ on first use.

embeddingModel

string

default:"nomic-ai/nomic-embed-text-v1.5"

HuggingFace feature-extraction model ID. Changing this requires a full re-index (kirograph index --force).

embeddingDim

number

default:"768"

Output dimension of the chosen embedding model. Must match the actual model output or KiroGraph will warn and use the real value.

semanticEngine

string

default:"cosine"

Vector search backend. One of: cosine, turboquant, turbovec, sqlite-vec, orama, pglite, lancedb, qdrant, typesense. See Semantic Search for details on each engine.

turboquantBits

number

default:"3"

TurboQuant bits per coordinate (range 1–8). Controls the compression/quality tradeoff. Requires npm install turboquant-js. Changing this value requires kirograph index --force.

turbovecBits

number

default:"4"

TurboVec bits per coordinate (2, 3, or 4). Requires the built native addon. Changing this value requires kirograph index --force.

turboquantMemDocs

boolean

default:"false"

Use TurboQuant ANN index for memory observation and doc section search in addition to code nodes.

turbovecMemDocs

boolean

default:"false"

Use TurboVec ANN index for memory observation and doc section search in addition to code nodes.

qdrantDashboard

boolean

default:"false"

Open the Qdrant web dashboard after indexing completes.

typesenseDashboard

boolean

default:"false"

Open the Typesense web dashboard after indexing completes.

Architecture

enableArchitecture

boolean

default:"false"

Enable architecture analysis: package graph construction, layer detection, and coupling metric computation. Required by enableSecurity (auto-enabled if missing).

architectureLayers

object

default:"auto"

Custom layer definitions as a map of layer name → glob patterns. Overrides or extends auto-detected layers.

{
  "api":     ["src/routes/**", "src/controllers/**"],
  "service": ["src/domain/**", "src/application/**"],
  "data":    ["src/infrastructure/**", "src/persistence/**"]
}

Security

enableSecurity

boolean

default:"false"

Enable dependency vulnerability detection and reachability analysis. Automatically enables enableArchitecture if it is not already set.

securityDatabases

string[]

default:"[\"OSV\"]"

Vulnerability databases to query. Currently supported: OSV.

securityAutoEnrich

boolean

default:"true"

Auto-run vulnerability enrichment after manifest parsing during indexing. Set to false to run enrichment on-demand only via kirograph vulns --refresh.

enablePatterns

boolean

default:"false"

Enable AST pattern-matching SAST via @ast-grep/napi. Requires npm install @ast-grep/napi. See Security for bundled rules.

patternLibraryPath

string

default:"—"

Path to a directory of custom YAML pattern rules. Rules are merged with the bundled set.

patternSeverityThreshold

string

default:"low"

Minimum severity to store pattern findings. One of: critical, high, medium, low.

Memory

enableMemory

boolean

default:"false"

Enable persistent cross-session memory. Observations are stored in .kirograph/memory.db and surfaced in kirograph_context.

memorySearchAlpha

number

default:"0.5"

Blend weight for hybrid memory search (0 = full-text only, 1 = vector only).

memoryKeepRaw

boolean

default:"false"

Store the original observation text alongside the compressed version.

memoryMaxObservations

number

default:"10000"

Maximum stored observations before the oldest are auto-pruned.

memorySessionTimeout

number

default:"7200"

Session inactivity timeout in seconds (default: 2 hours). Observations after this window start a new session.

memoryContextLimit

number

default:"3"

Maximum number of memory observations surfaced per kirograph_context call.

memoryContextThreshold

number

default:"0.3"

Minimum relevance score required for a memory observation to appear in context results.

memoryExcludePatterns

string[]

default:"[]"

Glob patterns for files to exclude from symbol linking in memory observations.

Watchmen

enableWatchmen

boolean

default:"false"

Enable Watchmen, which auto-synthesizes workspace briefs from accumulated memory observations. Requires enableMemory: true.

watchmenThreshold

number

default:"5"

Minimum number of new observations since last synthesis before a watchmenReady event fires.

watchmenSynthesisMode

string

default:"local"

How briefs are synthesized. local runs a local HuggingFace model on-device (no API key, no external calls). agent delegates to the active AI agent via an askAgent hook (Kiro only, consumes tokens).

watchmenLocalModel

string

default:"onnx-community/gemma-4-E4B-it-ONNX"

HuggingFace model used for local synthesis. Downloaded once to ~/.kirograph/models/ (~3–4 GB). Only used when watchmenSynthesisMode: "local".

Documentation

enableDocs

boolean

default:"false"

Enable documentation indexing for section-level retrieval via kirograph_docs_* tools.

docsInclude

string[]

default:"[\"**/*.md\", ...]"

Glob patterns for documentation files to include.

docsExclude

string[]

default:"[\"node_modules/**\", ...]"

Glob patterns for documentation files to exclude.

docsLinkCode

boolean

default:"true"

Automatically link documentation sections to code symbols by name.

docsContextLimit

number

default:"0"

Maximum doc sections surfaced in kirograph_context (0 = disabled).

docsContextThreshold

number

default:"0.3"

Minimum confidence score for a doc reference to appear in context results.

docsMaxFileSize

number

default:"1048576"

Maximum documentation file size to index (bytes).

docsSummarization

string

default:"first-sentence"

Section summary strategy. One of: embedding, first-sentence, off.

Data

enableData

boolean

default:"false"

Enable tabular data indexing and querying for CSV, TSV, JSONL, XLSX, Parquet, and PDF files.

dataInclude

string[]

default:"[\"**/*.csv\", \"**/*.tsv\", ...]"

Glob patterns for data files to include. Defaults cover CSV, TSV, JSONL, NDJSON, XLSX, XLS, Parquet, data/**/*.json, and PDF.

dataExclude

string[]

default:"[\"node_modules/**\", ...]"

Glob patterns for data files to exclude.

dataLinkCode

boolean

default:"true"

Auto-link data files to code symbols via path detection.

dataContextLimit

number

default:"0"

Maximum datasets surfaced in kirograph_context (0 = disabled). Keep at 0–1 for PDF datasets as content columns are verbose.

dataMaxFileSize

number

default:"52428800"

Maximum data file size to index (default: 50 MB).

dataMaxRows

number

default:"1000000"

Maximum rows to index per data file.

dataQueryLimit

number

default:"500"

Hard cap on rows returned per query.

dataMaxResponseTokens

number

default:"8000"

Maximum token budget per data tool response.

Agent Behavior

cavemanMode

string

default:"off"

Communication style for agent responses. One of: off, lite, full, ultra. Higher levels compress agent output more aggressively.

shellCompressionLevel

string

default:"off"

Shell output compression level. One of: off, normal, aggressive, ultra. Controls how kirograph_exec compresses command output before returning it.

enableAgentUtils

boolean

default:"true"

Enable agent utility tools: kirograph_read (cached file reads with 7 modes), kirograph_retrieve (context-compressed retrieval), and kirograph_budget (session budget tracking).

enableGeneralCompression

boolean

default:"false"

Enable kirograph_compress for on-demand compression of arbitrary text. Uses RTK-style shell filters (with command hint) or caveman grammar (without). Independent of shellCompressionLevel and cavemanMode.

minLogLevel

string

default:"warn"

Minimum log level written to the KiroGraph log. One of: debug, info, warn, error.

Get Started

Guides

Modules

KiroGraph Configuration Reference: config.json Fields

Where the Config Lives

Complete Example

Config Field Reference

Indexing

Semantic Search

Architecture

Security

Memory

Watchmen

Documentation

Data

Agent Behavior

Build docs developers (and LLMs) love

Get Started

Guides

Modules

Documentation Index

​Where the Config Lives

​Complete Example

​Config Field Reference

​Indexing

​Semantic Search

​Architecture

​Security

​Memory

​Watchmen

​Documentation

​Data

​Agent Behavior

Build docs developers (and LLMs) love

Where the Config Lives

Complete Example

Config Field Reference

Indexing

Semantic Search

Architecture

Security

Memory

Watchmen

Documentation

Data

Agent Behavior