From Observability to Understanding: Building an Agent‑Native Code Knowledge Graph with UModel

Background

AI agents such as Cursor, Copilot, Claude Code and Codex are now able to perform code completion, cross‑file refactoring, bug localization and architecture design. When a real enterprise‑level project is handed to an agent, the key question is whether the agent truly understands the project.

Two Existing Paradigms

No‑Index (Claude Code) : Uses Unix‑style tools ( grep, rg, glob) for real‑time file‑system search. Advantages are zero indexing cost, always‑fresh results, privacy‑friendly and simple reliability. Limitations are lack of structural awareness, no persistence across sessions and poor scalability for large monorepos.

CodeIndex / Vector‑Index (Cursor, Windsurf, Copilot) : Parses source with tree‑sitter, slices code into semantic units, embeds them and stores embeddings in a vector database (e.g., Turbopuffer). Incremental sync is done with a Merkle tree. Advantages are fast semantic search and cross‑file relevance. Limitations are that similarity search is purely textual, cannot guarantee structural relationships and struggles with very large codebases (e.g., 50 k files may require tens of thousands of tokens).

Why Both Paradigms Fail Core Needs

Typical developer questions such as “What is the impact of changing pkg/a2a Adapter interface?” or “Why is the vibeops‑xxx SLO broken?” require:

Deterministic structural relationships (import, call, inheritance) rather than probabilistic similarity.

Cross‑domain entity linking (code ↔ ops services, alerts, incidents).

A temporal dimension (commit, build, deploy, test, incident logs) to trace evolution.

UModel’s Solution: Deterministic Code Knowledge Graph

UModel extends the observability model (EntitySet, LogSet, MetricSet, Link) to the code domain and provides:

AST‑based extraction with 100 % confidence for definitions, references, calls, imports and inheritance across 40+ languages via tree‑sitter rules.

Cross‑repo composite primary keys (e.g., md5(repo_id:pk_value)) to avoid collisions when multiple repositories share module names.

EntitySetLink types (contains, imports, calls, extends, describes, belongs_to) annotated with __confidence__ and __extraction_method__ (EXTRACTED / INFERRED / AMBIGUOUS).

LogSets for code history (commit_log, build_log, deploy_log, incident_log) linked to entities, enabling queries such as “Which modules were modified in the last week?” or “Did any incident occur after the last deployment of this module?”.

Five Paradigms of Code Understanding

Agentic Search (Claude Code): real‑time file search, no structural reasoning.

CodeIndex / Vector Index: semantic search with embeddings, limited structural insight.

Code Graph + RAG (Qodo, Augment Code): adds a code graph on top of vector search, still limited by graph query capabilities and code‑only scope.

CodeWiki / LLM‑generated documentation (DeepWiki): converts code to human‑readable wiki, excellent for reading but lacks reliable graph traversal and verification.

UModel Code Knowledge Graph : deterministic AST extraction + cross‑domain links + full temporal logs, forming a live GIS‑like system for code.

Technical Pipeline

DETECT: Incremental change detection (SHA256 per file, Merkle‑tree diff)</code>
<code>EXTRACT: Dual‑track extraction</code>
<code>  • AST track (tree‑sitter) → 100% certain structural edges</code>
<code>  • LLM track → module summaries, doc‑code links, component ownership (confidence 0.6‑0.9, method INFERRED)</code>
<code>RESOLVE: Cross‑file symbol resolution (e.g., Go import → module_path, method receiver → type)</code>
<code>BUILD: Graph assembly + architecture discovery (directed edge weighting, hierarchical analysis, Leiden community detection, LLM‑assisted naming)</code>
<code>SYNC: Push entities, topology and schema to UModel backend (SLS storage)</code>
<code>SERVE: Query layer</code>
<code>  • Two‑step query: graph‑match to get entity IDs, then batch fetch business fields</code>
<code>  • Aggregations via direct SQL on __topo logstore

CLI Design (code‑wiki)

code-wiki query <subcommand>    # graph queries</code>
<code>  ├─ search <keyword></code>
<code>  ├─ context <entity></code>
<code>  ├─ impact <entity></code>
<code>  ├─ callers / callees <symbol></code>
<code>  ├─ deps / rdeps <entity></code>
<code>code-wiki check <subcommand>    # governance checks</code>
<code>  ├─ arch        # architecture violations</code>
<code>  └─ hotspots    # coupling hotspots</code>
<code>code-wiki ingest               # build / update graph</code>
<code>code-wiki status               # health check</code>
<code>--format brief   # output < 500 tokens, optimized for LLM token budget</code>
<code>--format json    # full JSON for downstream processing

Case Study 1: Autonomous Impact Assessment

$ code-wiki query search a2a</code>
<code>$ code-wiki query context pkg/a2a</code>
<code>$ code-wiki query impact pkg/a2a</code>
<code>$ code-wiki check hotspots

The combined run (~15 seconds) lists direct dependents, entry points, cross‑component edges and high‑coupling warnings, then formats a concise impact report for the main agent.

Case Study 2: RCA from Alert to Code Root Cause

# 1. Locate the service module</code>
<code>$ code-wiki query context pkg/server</code>
<code># 2. Trace callers of the failing handler</code>
<code>$ code-wiki query callees pkg/server.handleRequest</code>
<code># 3. Correlate recent commits (commit_log shows a refactor in pkg/a2a 2 h ago)</code>
<code># 4. Assess impact of the changed module</code>
<code>$ code-wiki query impact pkg/a2a

The agent concludes that a recent a2a interface refactor broke the call chain in pkg/server, pinpointing the root cause without opening any source file.

Case Study 3: Architecture Governance

$ code-wiki check arch</code>
<code># Reports utility layer calling API layer, infra calling service layer, etc.</code>
<code>$ code-wiki check hotspots</code>
<code># Highlights pkg/a2a/adapter (48 imports) as a high‑coupling hotspot</code>
<code>$ code-wiki query rdeps pkg/a2a/adapter</code>
<code># Shows reverse dependencies across many modules, prompting a split recommendation.

Future Directions

Standardized benchmark (SWE‑bench style) to compare Model + Bash, Model + CodeWiki and Model + UModel on impact analysis, call‑chain tracing, architecture violation detection and RCA. Metrics include accuracy, recall, reasoning steps and token consumption.

Agent‑driven self‑maintenance : automatically flag LLM‑inferred edges for re‑evaluation after code changes, run periodic health checks for orphaned entities and execute quality‑verification pipelines.

CI integration : on each PR run code-wiki ingest --incremental, code-wiki check arch and code-wiki query impact to enforce architectural guardrails.

By unifying code structure, history and operational context into a deterministic graph, UModel transforms agents from “search‑only” tools into true code‑understanding assistants, enabling reliable root‑cause analysis, impact assessment and continuous architectural governance.