DEV Community: NEHA JAKATE

Vectors vs. Graphs: Picking the Right Tool for Code Intelligence

NEHA JAKATE — Sun, 02 Aug 2026 11:44:26 +0000

The Problem

Ask five teams building AI coding tools how they represent a codebase for an LLM, and you'll get two answers: embeddings, or a dependency graph. Both camps are right — for different questions. Picking the wrong one for your use case is why some "semantic code search" tools return technically-similar-but-practically-useless results.

Architecture: What Each Model Actually Captures

Vectors: Semantic Similarity

embed("parse a JWT token") ≈ embed(function verifyToken(token) {...})

Embeddings place semantically similar functions close together in vector space. The query doesn't need exact keyword matches — "parse a JWT token" finds the right utility even if the function is named decodeAuthPayload.

Best for: finding unfamiliar code by intent, code completion across different styles, spotting duplicate logic, semantic clustering of docs.

Limitation: vectors capture meaning, not structure. Two semantically similar functions might be years apart in age, one deprecated and one live in production — the embedding doesn't know the difference.

Graphs: Structural Truth

callers(auth/middleware.js) → [23 modules]
communities() → [{name: "billing", files: [...]}, {name: "auth", files: [...]}]

Traversing imports, calls, and inheritance answers exact structural questions: reachability, transitive dependencies, ownership boundaries.

Best for: finding what breaks if you change a function, mapping module dependencies, identifying hot-path slices, detecting team boundaries via community detection.

Limitation: graphs find everything structurally reachable, but can't rank by relevance or catch intent-based similarity across unrelated components. A graph traversal will happily return 40 structurally-connected files with no sense of which 3 actually matter for your question.

Implementation: The Combined Pattern

Neither model wins outright — the canonical pattern chains them:

# Step 1: graph-first neighborhood
neighborhood = graph.get_neighborhood(
    target_file,
    include=["imports", "callers", "community"]
)

# Step 2: vector re-ranking inside that neighborhood
results = vector_search(
    query=user_query,
    candidates=neighborhood,   # constrained, not global
    top_k=10
)

This gives you results that are both connected (graph-verified as structurally relevant) and semantically relevant (vector-ranked within that constrained set) — instead of either a noisy global vector search or an unranked pile of everything structurally reachable.

Failure Modes to Watch For

Failure	Cause
Vector search returns deprecated/dead code	No graph-position awareness — embedding similarity ignores whether code is even reachable from production
Graph traversal returns too much	No relevance ranking — "structurally reachable" ≠ "relevant to this question"

Learnings

The decision framework that generalizes: ask what your engineers actually query for.

Mostly "find code that does X" → vectors alone are probably sufficient
Mostly "what breaks if I change X" or "where are the team boundaries" → you need a graph
Most mature codebases eventually need both, chained as above

Resources

Spiderbrain uses this exact pattern: a pre-built structural graph with semantic re-ranking applied at query time.
Related: Every AI Coding Assistant Sees Your Files, Not Your Architecture (the graph side of this argument in more depth)

🚀 Free on Local · ☁️ Hosted on Pro & Cortex

Link : https://spiderbrain.ai/

Linkedin : https://www.linkedin.com/company/spiderbrain

Discuss: if you're running vector search over a codebase today, are you constraining candidates by any structural signal first, or searching the whole embedding space every time?

Your Docs Are Already Lying to You — Here's How to Make Them Graph Nodes Instead

NEHA JAKATE — Sun, 02 Aug 2026 10:56:54 +0000

The Problem

Documentation diverges from code the moment it's written. Not eventually — immediately. There's no trigger anywhere in a typical stack that says "this code changed, go check if the doc describing it is still true."

Six months later, that doc isn't just outdated. It's actively misleading, and nobody's the wiser until someone follows it and gets burned.

Architecture: Docs as First-Class Graph Nodes

The fix isn't "write better docs" or "review docs more often" — that doesn't scale and everyone already knows it. The fix is architectural: treat documentation as nodes in the same graph as your code, connected by real edges.

Without graph edges:

docs/auth.md  ──(no connection)──  auth/middleware.js

Docs go stale silently. No trigger to update when code changes.

With graph edges:

docs/auth.md ──[describes]──> auth/middleware.js
                                     │
                              [commit fingerprint tracked]

Docs become connected nodes — flagged when stale, surfaced automatically when relevant.

Implementation: What Gets Ingested

Three source types become graph nodes:

Markdown files — README, docs/, architecture notes. Each file becomes a node.
Docstrings — JSDoc and Python docstrings, linked directly to the function/class node they document.
OpenAPI specs — ingested as structured schema, woven into the graph rather than treated as a separate artifact.

Drift Detection

compare(doc_commit_fingerprint, code_commit_fingerprint)
→ if code changed since doc was last reviewed: flag as drift

This is systematic, not a manual "does this still look right?" pass — it's a commit-fingerprint diff.

Doc-Splitter Pattern

Instead of treating a README as one giant node, each ##/### section becomes its own node. A query like:

"how does auth session expire?"

returns the exact section describing session expiry — not the entire README dumped into context, which wastes tokens and buries the answer.

Learnings

The core insight that generalizes: a graph edge is the actual mechanism that turns docs from a static artifact into a living layer of your code intelligence system. Without the edge, "keep docs updated" is a policy nobody follows consistently. With the edge, staleness becomes a detectable, gateable property — same as a failing test.

Resources

Spiderbrain ingests markdown, docstrings, and OpenAPI specs into the graph automatically. Free on Local, hosted brain on Pro and Cortex.
Related: The One Metric Your AI Code Review Tool Ignores (same commit-fingerprint approach applied to blast radius instead of docs)

🚀 Free on Local · ☁️ Hosted on Pro & Cortex
Link : https://spiderbrain.ai/

Linkedin : https://www.linkedin.com/company/spiderbrain

Discuss: what's your team's current process for catching doc drift, if any? Curious how many people are doing this manually vs. not at all.

28 MCP Tools in One Connection: A Developer's Field Guide

NEHA JAKATE — Sun, 02 Aug 2026 10:55:16 +0000

The Problem

Model Context Protocol (MCP) lets an AI agent call structured tools instead of guessing from raw text dumped into a context window. Fine in theory — but most MCP integrations just expose "read file" and "search," which barely improves on copy-pasting code into a chat window.

The real question: what tools should an agent actually have access to, for codebase work specifically?

Architecture: Three Tool Categories

Spiderbrain's MCP server exposes 28 tools, split into three functional groups:

Codebase Tools (17)

Structural queries a flat context window literally cannot answer:

blast_radius(path)      // reach, callers, transitive impact
score_summary()          // keystones, blindspots, node scores
communities()            // clusters, boundary edges, paths
insights(area)           // summaries, diffs, navigation, search

Memory Tools (9)

Access to the Memory Tree — a project's accumulated decisions and constraints, persisted across sessions:

memory_recall(files)     // scoped brief for current context
memory_search(query)     // semantic search over the full tree
memory_add(node)         // write with explicit user ratification
memory_browse(scope)     // browse by scope or recency

Blueprint Tools (2)

spiderbrain_blueprint_read()   // current nodes, edges, annotations
spiderbrain_blueprint_draw()   // AI proposes canvas edits — requires human acceptance

Implementation: Which Tools to Call, and When

Don't call all 28 on every turn — that's noise, not context. Here's the practical dispatch table:

Situation	Call
New project	`score_summary()` + `top_spikescore(10)`
Before editing a file	`node(path)` + `blast_radius(path)`
Session start	`memory_recall(files)`
Planning a refactor	`communities()` + `boundary_edges()`
Onboarding to unfamiliar code	`blueprint_read()` + `insights(area)`

This mapping matters more than tool count. An agent with 28 tools and no dispatch logic will either call none of them or call all of them — both are worse than an agent with 5 tools it actually reaches for at the right moment.

Learnings

The pattern that generalizes beyond this specific server: structure your MCP tools around the moments in a workflow, not around your data model. "New project," "before editing," "session start," "refactor," and "onboarding" are moments a developer or agent actually hits. "Get node," "get edge," "get community" are just database operations wearing a tool-call costume.

Resources

Spiderbrain is free on Local, hosted brain available on Pro and Cortex.
Related: Every AI Coding Assistant Sees Your Files, Not Your Architecture (for the underlying graph model these tools query) 🚀 Free on Local · ☁️ Hosted on Pro & Cortex

Link : https://spiderbrain.ai/

Linkedin : https://www.linkedin.com/company/spiderbrain

Discuss: has anyone else settled on a "moment-based" tool dispatch pattern for their own MCP servers? Curious what situations you gate on.