Code Knowledge Graph
A queryable graph of your codebase built from AST analysis — imports, calls, inheritance, and cross-file relationships resolved in milliseconds.
What is the Code Knowledge Graph?
The Code Knowledge Graph is Krnl's semantic understanding layer for your codebase. It parses every Python file in your project using Tree-sitter (with a built-in ast fallback), builds a graph of modules, classes, functions, imports, calls, and inheritance relationships, and stores it in an indexed SQLite database. The agent queries this graph to understand code context without reading entire files.
With vs. Without the Graph
Here's the same task — “add input validation to the login handler” — executed with and without the Code Knowledge Graph:
Without Graph — The agent reads files blindly
With Graph — The agent knows the codebase structure
Architecture
The graph is built from three layers working together:
Tree-sitter parses Python files into concrete syntax trees. Falls back to Python's built-in ast module when Tree-sitter is not installed. Extracts: modules, classes, functions, imports, function calls, and inheritance.
A NetworkX MultiDiGraph holds nodes (Module, Class, Function) and edges (imports, calls, inherits, defines) in memory for fast traversal. Cross-file references are resolved via a ModulePathIndex.
SQLite database stores the full graph with WAL mode for concurrent access. The graph is rebuilt per-file on invalidation (triggered by file writes) — no full rebuilds needed.
Graph Model
| Node Type | Description | Attributes |
|---|---|---|
| Module | A Python file | file_path, language |
| Class | A class definition | qualified_name, parent_class, line_start, line_end |
| Function | A function or method | qualified_name, parent_class, line_start, line_end |
| Edge Type | Meaning |
|---|---|
| imports | A file imports a symbol from another module |
| calls | A function calls another function or method |
| inherits | A class inherits from another class |
| defines | A module defines a class or function |
Graph-Aware Context
When you give the agent a task, it analyzes the task text for mentioned symbols, looks them up in the graph, and automatically pulls in neighbor nodes up to a configurable hop limit. This means:
- Mention a function name → the agent also reads its callers and callees
- Mention a class → the agent also reads its parent class and subclasses
- Edit a file → the graph invalidates only that file (incremental update)
- No full rebuilds — changes are propagated per-file with zero downtime
Real-World Example
When you ask the agent to “refactor the User class to use a factory pattern”, the graph automatically:
Graph locates User class at src/models/user.py and identifies all subclasses (AdminUser, GuestUser)
Graph finds all files that import or instantiate User (auth.py, routes.py, tests/)
Agent reads only the relevant files (5 files) instead of scanning the entire codebase (47 files)
After edit, only src/models/user.py is re-parsed — no full graph rebuild needed
Configuration
All three features are opt-in. Enable them in your project's config.yaml or via the VS Code extension settings panel:
Option 1: config.yaml
graph:
enabled: true # Enable the code knowledge graph
backend: networkx # Graph backend (networkx)
db_path: .krnl/graph.db # SQLite database path
languages: # File types to parse
- python
context:
graph_aware: true # Enrich prompts with graph context
graph_hop_limit: 1 # How many hops to traverse (1-5)
differential_updates: true # Only send changed nodes
memory:
per_session: true # Persist structured memory per sessionOption 2: VS Code Extension
Open the Krnl Code settings panel in VS Code and toggle the checkboxes under Advanced Features:
- Enable Code Knowledge Graph — builds the graph at startup
- Graph Hop Limit — sets how many levels of neighbors to traverse (1–5). Higher = more context, more tokens.
- Enable Graph-Aware Context — uses graph for smarter context selection
- Enable Per-Session Memory — persists structured memory across sessions
tree_sitter and tree_sitter_python packages. Without them, the system falls back to Python's built-in ast module (less precise but always available).Visual Indicators
When the Code Knowledge Graph is enabled, you'll see visual indicators across all interfaces:
CLI Startup
VS Code Extension
The view tab shows which features are active: ⬡ ◎ ◆ symbols appear in the panel header when Graph, Context-Aware, and Per-Session Memory are enabled respectively.