DEV Community: Hadeel Sharaf

Semantic Code Intelligence: Helping AI Agents Navigate Codebases

Hadeel Sharaf — Sat, 24 Oct 2026 20:44:18 +0000

Finding code is easy. Finding the right code—and understanding what a change might affect—is harder.

Imagine asking an AI coding agent to modify a payment retry policy.

It finds the function responsible for retries, changes it, and reports success. But another module calls that function, a configuration controls its behavior, and existing tests depend on its current contract.

The problem is not necessarily that the agent cannot write code. It may not have retrieved enough context to understand the change.

This is where semantic code intelligence becomes useful: a collection of techniques that help developers and AI agents navigate code using its structure, symbols, relationships, and sometimes semantic similarity.

It is a broad industry term rather than a single standardized technology. Different implementations provide different capabilities.

1. Text Search vs. Code Intelligence

Suppose you want to find where getUser is defined.

grep -rn "getUser" src/

This returns textual matches, potentially including definitions, calls, comments, and tests.

A language-aware tool can resolve the symbol and locate its definition, provided the language server supports that operation and has sufficient project information.

The distinction is simple: text search finds matching text; symbol-aware navigation can identify code entities and their relationships.

Both are useful. The challenge is choosing the right method for the question.

2. The Main Building Blocks

Semantic code intelligence combines several complementary techniques.

Syntax parsing

Tree-sitter parses source code into syntax trees. It can identify functions, classes, expressions, and other structures, making it useful for structural queries and symbol-aware code chunking.

Parsing alone does not resolve every symbol or establish the complete meaning of a program.

Symbol navigation and indexing

Two important technologies are the Language Server Protocol (LSP) and SCIP.

LSP defines communication between development tools and language servers. Depending on the implementation, it supports go-to-definition, find-references, and rename.
SCIP is a language-agnostic protocol for indexing source code to support code navigation.

See the LSP specification and the SCIP project.

These technologies serve different purposes: LSP defines a communication protocol, while SCIP defines an indexing format.

Neither guarantees complete results across every language feature or repository. Accuracy depends on language support, index coverage, project configuration, and freshness.

Embeddings and vector search

Sometimes you know the behavior you are looking for but not which function implements it.

For example:

Where do we retry failed payments?

Embedding-based retrieval represents code snippets and queries as vectors, then retrieves candidates based on similarity.

This helps discover implementations when the query and source code use different terminology. However, similarity does not prove functional equivalence.

Use embeddings to discover candidates, not to guarantee exhaustive references or prove behavior.

Code graphs

Code graphs represent relationships such as function calls, imports, dependencies, and inheritance.

They help investigate questions such as:

Which functions call this method?
Which modules depend on this interface?
What might be affected by changing this component?

Static graphs may miss relationships involving dynamic dispatch, reflection, generated code, or runtime configuration. Dependency information also does not guarantee that a change is safe.

Hybrid retrieval

A retrieval pipeline can combine lexical search, semantic similarity, and structural information.

A typical workflow is:

Split source code into symbol-aware chunks.
Index chunks using BM25 or another lexical retrieval method.
Generate embeddings for semantic retrieval.
Merge and rerank the retrieved candidates.
Use symbol and dependency information to refine the results where available.

Lexical retrieval finds relevant terms, embeddings surface conceptually related code, and reranking helps prioritize candidates.

Hybrid retrieval is not automatically more accurate. Its effectiveness depends on indexing, chunking, ranking, and the quality of the underlying data.

3. A Practical Example: Changing a Payment Retry Policy

Consider an agent asked to increase the maximum number of payment retries.

A text search might find several occurrences of retry, but the relevant behavior could be distributed across a service, configuration file, and test suite.

Here is how different retrieval methods can help:

Step	Method	Purpose
1	Lexical search	Find retry-related identifiers and configuration keys
2	Semantic retrieval	Discover implementations described using unfamiliar terminology
3	Symbol indexing	Locate definitions and references for the relevant functions
4	Dependency analysis	Identify potentially affected callers and components
5	Test discovery and execution	Check expected behavior and detect regressions

For example, a search for retry might reveal retry_payment(), max_attempts, and recover_transaction(). Symbol resolution can then distinguish the definition of retry_payment() from its callers, while dependency analysis helps trace how the function is used.

These are illustrative names, not measured search results.

The key is that each step answers a different question. Semantic retrieval helps discover candidates; symbol indexing helps establish code relationships; tests provide evidence about behavior.

None of these steps alone proves that every relevant component has been found or that the resulting change is correct.

4. Why This Matters for AI Coding Agents

AI coding agents need relevant context before modifying a codebase. Without effective retrieval, they may repeatedly search files, read unrelated sections, and manually reconstruct dependencies.

This can lead to unnecessary token consumption, missed dependencies, incomplete changes, and repeated discovery work.

Persistent indexes can make symbol and relationship information available across tasks, reducing repeated exploration. Their value depends on the repository, language support, indexing overhead, and how frequently the code changes.

Better retrieval can improve the context available to an agent, but it does not guarantee correct reasoning or safe modifications. The agent must still inspect the source, validate assumptions, and test its changes.

5. Choosing the Right Tool

Engineering question	Suitable approach
Where does this exact string appear?	`grep` or lexical search
Where is this function defined?	LSP or a suitable symbol index
Which references resolve to this symbol?	LSP or SCIP-based indexing
Where is this behavior implemented?	Lexical and semantic retrieval, followed by source inspection
Which components may be affected by a change?	Dependency analysis and code graphs
Which tests should be examined?	Test discovery, dependency analysis, and coverage data

These capabilities can be exposed to AI agents through APIs, tools, or integrations such as the Model Context Protocol (MCP). The agent should use only the capabilities actually supported by the integration.

6. Trade-offs to Consider

Before introducing code intelligence, consider the operational costs:

Index freshness: Outdated indexes can produce misleading results. Incremental updates or reindexing are essential.
Language support: Indexing capabilities and precision vary across languages and frameworks.
Infrastructure cost: Persistent indexes require storage, compute, and maintenance.
Retrieval quality: Embeddings and rerankers need evaluation; similarity scores alone do not establish correctness.
Analysis limitations: Static analysis may not capture all runtime behavior.
Security: Code indexes and embedding stores can contain proprietary source information and require appropriate access controls.

For a small repository, ordinary search and existing language-server features may be sufficient. For large monorepos or agent workflows involving frequent cross-file changes, additional indexing and dependency analysis may justify the complexity.

Start with existing search, add symbol-aware navigation where needed, and introduce semantic retrieval or graph analysis when specific problems justify them. Evaluate the result using representative tasks, retrieval precision and recall, index freshness, latency, token consumption, and end-to-end task success.

Conclusion

Semantic code intelligence is not a replacement for text search. It combines complementary techniques to retrieve code with different levels of structural and semantic information.

Use lexical search for exact matches, symbol indexing for definitions and references, embeddings for discovering implementations by intent, and code graphs for exploring dependencies and potential impact.

For AI coding agents, the objective is not to retrieve more code indiscriminately. It is to retrieve relevant evidence, understand its limitations, and validate the resulting changes.

The goal is not to make every search semantic. It is to retrieve the right evidence for the question being asked.

Ontology-Driven Observability for Agentic Monitoring

Hadeel Sharaf — Tue, 20 Oct 2026 22:01:56 +0000

Traditional observability tells us what is happening in our systems. Ontology-driven observability helps us understand how system components are connected — and gives AI agents better context to investigate incidents.

1. What Is Ontology-Driven Observability?

It starts with a shared model of the system: its services, databases, users, infrastructure, and their relationships.

Instead of treating metrics, logs, and traces as isolated signals, telemetry is connected to a knowledge graph.

For example:

checkout-service → depends_on → payments-db
checkout-service → runs_on → node-01

Each statement is a triple: Subject → Predicate → Object.

The result is a connected view of the system that supports dependency analysis, impact assessment, and root-cause investigation.

2. Use Case Without LLMs or AI Agents

Ontology-driven observability is useful even without AI.

Consider a payments database that becomes unavailable.

A graph-based monitoring system can:

Identify services that depend on the database.
Calculate the potential blast radius of the failure.
Apply predefined rules to correlate the incident with service health.
Alert the responsible teams with dependency context.

This is deterministic, rule-based monitoring. The knowledge graph provides context, while predefined queries and rules perform the analysis.

3. Use Case for Agentic Monitoring

Now introduce an LLM-powered agent.

When checkout latency increases, a monitoring agent can query the knowledge graph to identify affected services and their dependencies. It can then investigate relevant metrics, logs, traces, and deployment events.

A multi-agent workflow could delegate these investigations to specialized agents and combine their findings into an evidence-backed root-cause hypothesis.

The workflow becomes:

Detect → Explore dependencies → Investigate telemetry → Correlate evidence → Recommend action

This approach aligns with Netflix's E2EGraph initiative, presented at QCon London 2026, which explores knowledge-graph-backed observability and agent-assisted root-cause analysis at scale.

Importantly, the graph provides structured context; it does not automatically prove causation. Agents must still validate their hypotheses against actual telemetry.

4. Should We Prefer This Approach?

It depends on system complexity.

Ontology-driven observability is particularly valuable when:

Incidents cross multiple services, infrastructure layers, and teams.
Telemetry is scattered across different tools.
Root-cause analysis requires understanding complex dependencies.
AI agents need reliable, structured context rather than relying on raw logs alone.

For smaller systems, conventional observability with consistent instrumentation, useful tags, and distributed tracing may be sufficient. OpenTelemetry Semantic Conventions provide a practical starting point.

A complete knowledge graph introduces additional costs: ontology design, data integration, graph maintenance, and governance.

5. Should Agentic Monitoring Run in a Sandbox?

Develop and test it in a sandbox or staging environment first.

However, the knowledge graph and observability pipeline do not inherently need to run in a sandbox. The critical security concern is the agent's execution environment and permissions.

A practical rollout strategy is:

Sandbox: Test incident scenarios, graph queries, agent reasoning, and tool calls using synthetic or sanitized telemetry.
Production read-only mode: Allow agents to query approved production telemetry and propose explanations without changing the system.
Controlled remediation: Introduce actions such as restarting services or rolling back deployments only with strict permissions, independent validation, and human approval where appropriate.

Sandboxing and least-privilege access help limit the consequences of incorrect reasoning or unintended tool calls. For further guidance, see OpenAI's documentation on agent guardrails and human review.

Final Thoughts

Ontology-driven observability is not a replacement for traditional monitoring. It is a way to add shared context and connected system knowledge to it.

Rules can use the graph to perform deterministic analysis. LLM-powered agents can use the same graph to investigate incidents dynamically and coordinate more complex workflows.

The strongest starting point is simple: establish reliable telemetry and system relationships first, then introduce agentic analysis where it provides measurable value.