Untitled

We’ve all been there. You open up a new session with your AI agent whether it’s Claude, Cursor, or an MCP-powered tool and you spend the first ten minutes doing the inevitable ritual dance: context setting.

Learn more at- https://spiderbrain.ai/

“Remember, we are using JWT with RS256, not SHA256.” “Don’t forget all database writes must go through the repository layer.” “Wait, scratch that last part, we actually shifted to a JWKS endpoint yesterday.”

It works, but it’s exhausting. The moment a project decision changes, you’re stuck re-explaining the new constraints every single time you start a new thread. It feels less like working with a brilliant engineering partner and more like onboarding a new junior developer every single morning.

There is a better way. Instead of rewriting your prompts from scratch, what if you could just edit the AI’s memory directly?

Enter Spiderbrain’s comment-to-change mechanism.

The Problem: The Empty Context Trap

The fundamental issue with traditional re-prompting is that every new AI session starts with an empty slate. You have to rebuild the context from scratch: which decisions were made, which constraints apply, and which architectural patterns the team follows.

As a project grows, this manual reconstruction becomes error-prone and time-consuming. You forget to mention a minor constraint, the AI hallucinates an old pattern, and suddenly you’re debugging code that shouldn’t have been written in the first place.

Trying to solve this by dumping everything into a massive, global system prompt doesn’t work either. It clogs the AI’s context window with irrelevant details and dilutes its focus.

Enter the Memory Tree

Instead of floating around in ephemeral chat histories or bloated system prompts, authoritative project data belongs in a Memory Tree.

The Memory Tree is a hierarchical, persistent record of your project’s decisions, constraints, patterns, and preferences. Each node in the tree is a structured fact that your AI recalls over the Model Context Protocol (MCP) in every single session.

These aren’t passing instructions; they are foundational truths about your codebase. For example:

“The auth module uses JWT with RS256. Never SHA256.”

“The API response envelope uses data and error fields. No other top-level keys.”

“All database writes must go through the repository layer. Direct ORM calls from controllers are not allowed.”

How “Comment-to-Change” Actually Works

When engineering decisions inevitably shift, you shouldn’t have to rewrite a master prompt document. With a Memory Tree, you just leave a comment on the specific memory node that needs updating.

Let’s say your team decides to migrate to a JWKS endpoint. Instead of worrying about how to phrase this to the AI next time, you simply annotate the existing memory node:

Comment: “Update this: we’re migrating to a JWKS endpoint, not a static public key.”

On your very next AI session, the magic happens behind the scenes:

The Client Reads the Tree: Your connected client (Claude, Cursor, Claude Code, etc.) scans the Memory Tree.

It Finds the Flag: It spots the node with the unresolved comment.

It Rewrites the History: The AI reads the original memory, processes your comment, applies the update to the node content, and marks the comment as resolved.

The next time the AI references that architectural rule, the memory automatically reads: “The auth module uses JWT verified against the JWKS endpoint at /auth/.well-known/jwks.”

You didn’t have to explain how to change it. You just ratified the change by leaving a quick note.

Why This Changes the Game

Shifting from prompt engineering to memory annotation provides three massive advantages for developers:

1. Scoped Steering (No More Global Noise)

The comment-to-change mechanism isn’t global. Memory nodes are anchored to specific files or modules. If you leave a comment on a memory node anchored to auth/, only AI sessions working within the auth/ directory will see and resolve that comment. The AI working on your frontend UI won't be bogged down by data-layer architecture changes. Your steering is precise and targeted.

2. Radical Efficiency & Auditability

Updating the Memory Tree is significantly cheaper than updating a prompt because you change exactly one node, not every future chat thread. Furthermore, because the tree maintains a history, your AI’s “brain” becomes entirely auditable. You can see exactly when a constraint changed and why.

3. Absolute User Control

A common fear with AI memory is “auto-extraction” — the idea that an AI might misunderstand a hypothetical conversation and permanently save a wrong fact.

Spiderbrain relies on a strict design principle: You ratify memory. Nothing is stored without your intent. The AI doesn’t automatically pull facts from your chats. If it discovers something worth remembering, it proposes a memory, and you confirm it. The same goes for comment-to-change: you write the comment, the AI interprets it, and you review the resolution before it’s locked in.

The Takeaway

We need to stop treating AI context as something we build up and tear down with every single task. By moving our architectural constraints into a persistent, scoped Memory Tree and using a simple comment-to-change workflow to keep it updated we can finally stop onboarding our AI tools, and just start coding.

Spiderbrain’s auto-blueprint replaces that hour with five minutes.

Stop reading stale READMEs. Generate a live blueprint of your current project at spiderbrain.ai.

How Auto-Blueprint Works

When you point Spiderbrain at a repository (local folder, GitHub, or GitLab), a high-performance Rust parser reads the actual import statements within the code itself — bypassing outdated documentation entirely.[ Raw Source Code ] │ (Rust Parser) ▼ [ Directed Import Graph ] │ (Leiden Community Detection) ▼ [ Structural Clusters & Spatial Layout Canvas ]

The parsed graph is then processed through a three-stage pipeline:

Leiden Community Detection: Finds the actual structural clusters.

Spikescore Ranking: Flags the critical “keystone” files in each cluster.

Graph Layout Optimization: Places clusters spatially based on their coupling.

The output is a live blueprint canvas where each cluster forms a distinct group, the most significant files are highlighted as named nodes, and inter-cluster edges represent real-time connections.

What the Auto-Blueprint Reveals

The Documented Architecture vs. The Real One: Most codebases suffer from a gap between the architecture diagram in the docs and the architecture living in production. This gap is almost always where maintenance pain is concentrated.

Unintended Community Formation: Community detection isolates structural clusters that were never explicitly designed — groups of files that became tightly coupled through organic growth. These are your prime targets for architectural refactoring.

The Actual Entry Points: High-centrality files with no significant incoming dependencies reveal themselves clearly as entry points (request handlers, CLI commands, or cron jobs) without manual tracing.

Boundary Violations: Files inside one module folder that import heavily from another module’s private internals are immediately exposed as cross-boundary violations.

The First 5 Minutes Workflow

Ingest: Open Spiderbrain, add a new project, and point it at your repository.

Auto-Draw: Wait 30 to 90 seconds (for a typical 50k LOC repo) while the engine generates the blueprint.

Analyze Clusters: Examine the communities. Do they align with the explicit folder hierarchy, or have boundaries blurred?

Target Keystones: Locate the highlighted high-Spikescore nodes. These are the files you need to read first to understand the system.

Contextualize Your AI: Share the blueprint layout with your AI client via Spiderbrain’s Model Context Protocol (MCP) tools. Ask: “What is the largest community and what does it own?” Your AI now has the spatial reality to provide grounded, hallucinations-free answers.

One Graph, Three Perspectives: Deepview

A map of your codebase is not a single thing; the right representation depends on the question you are asking. Deepview provides three distinct views of the same underlying graph to surface different operational realities.

1. Web View: What Depends on What?

Rendered as a force-directed network, the Web view focuses on immediate dependency relationships. Nodes represent files or modules, while edges show imports. The visual weight of a node reflects its structural significance.

Best Used For: Analyzing a specific change’s scope, identifying community boundaries, finding bridge nodes, and evaluating a single file’s immediate blast radius.

2. Map View: The Whole Project at a Glance

The Map view is a macro-level, deterministic spatial layout organized by community membership. Tightly coupled modules cluster closely together, while isolated elements appear at a distance.

Best Used For: Gaining an architectural overview of a brand-new repo, tracking structural drift between commits, and spotting architectural anomalies (e.g., a file located far from its companion folder nodes).

3. Flow View: Architecture as a Layered Diagram

Flow view organizes the codebase into a layered hierarchy — hierarchically rendering entry points and high-level abstractions at the top, down to low-level infrastructure at the bottom.

Best Used For: Onboarding conversations, checking if business logic is cleanly isolated from data access, and identifying structural violations (such as components importing up the stack instead of down).

Multi-View Diagnostic Routine

Experienced teams don’t stick to one view; they cycle through them contextually to build rapid structural intuition:[ Step 1: Map View ] ──────> [ Step 2: Flow View ] ──────> [ Step 3: Web View ] Get spatial overview & Verify module sits in the Zoom in on target files identify core cluster. correct architectural layer. and compute blast radius.

A map of your codebase is not a single, static artifact. The optimal representation depends entirely on the question you are asking. Just as a city looks fundamentally different from a street-level view, a transit map, or a satellite image, different architectural views surface distinct information for different purposes.

Take control of your codebase intelligence: Learn more and deploy the full stack at spiderbrain.ai.

Spiderbrain's Deepview provides three specialized representations of the exact same underlying codebase graph. Mastering when to leverage each view allows engineers and AI agents to navigate massive codebases with precision.

1. Web View: Micro-Topology and Dependency Analysis

The Web view renders your dependency graph as a dynamic, force-directed network where nodes represent files or modules and edges represent explicit import relationships.

When to Deploy Web View

Reach for the Web view when analyzing localized impact or tracing exact connectivity paths. It answers critical, micro-topological questions:

Which specific files are most central to this local subsystem?

What is the exact blast radius of a file before making a change? (Selecting a node highlights its entire reachable subgraph).

Where are the immediate community boundaries? (Delineated through automated community coloring clusters).

Which load-bearing files act as "bridges" between decoupled modules? (Identified via high betweenness centrality scores).

Operational Insight: Web view rewards zooming in. It is uniquely engineered for scoping a specific module or change—not for taking in the whole-project picture at once.

2. Map View: Macro-Architecture and Spatial Proximity

The Map view provides a macro-level spatial layout of your entire codebase, organized cleanly by community membership and structural proximity. Modules that are tightly coupled cluster closely together, while loosely coupled components appear far apart. This layout is completely deterministic—the exact same codebase state will always produce the identical spatial arrangement.

When to Deploy Map View

Map view serves as the perfect starting point for exploring an unfamiliar codebase, giving you an immediate architectural gestalt before reading a single file. Use it to answer:

Where are the primary structural clusters and domain boundaries in this codebase?

Which application areas are completely isolated (low in/out degrees) versus highly connected?

How has the high-level architecture drifted between commits? (Evaluated via side-by-side maps).

Where are the structural anomalies? (e.g., files that sit physically far away from where their folder path implies they should belong).

3. Flow View: Layered Hierarchy and Architectural Health

The Flow view reorganizes the codebase graph into a structured, layered architectural diagram. It aligns your system from top to bottom—positioning public entry points and high-level abstractions at the summit, and low-level infrastructure or utility layers at the base.

When to Deploy Flow View

Flow view reads like a classic systems blueprint, making it the natural choice for system architects and engineering onboarding conversations. Use it to diagnose structural health:

What are our main application entry points, and what is their downward dependency chain?

Are there circular dependencies looping between independent layers?

Is the data access layer correctly isolated beneath the business logic layer?

Which modules are actively violating architectural rules by importing upward instead of downward?

4. The Deepview Workflow: Switching Views Mid-Task

The true power of code intelligence is unlocked not by lingering in a single view, but by fluidly shifting between them as your engineering objectives evolve. This entire diagnostic routine takes under a minute, replacing the implicit architectural memory senior engineers carry in their heads with a programmatic control plane.

Step 1: Open Map View   ───► Get the global spatial layout; locate your target cluster.

                                    │

                                    ▼

Step 2: Switch to Flow View ───► Verify if that cluster sits in its proper architectural layer.

                                    │

                                    ▼

Step 3: Switch to Web View  ───► Zoom into the target file, compute its exact blast radius,

                                 and audit its callers before refactoring.

5. Structuring AI Context Windows via Architecture

When selecting files to supply to an AI coding assistant, picking files at random or relying purely on text-search results introduces immense noise and misses critical structural dependencies. Deploying Deepview's three lenses builds a highly optimized, coherent architectural slice for the AI:

Deepview Lens

Analytical Value Provided to AI Context

Map View

Pinpoints the macro-cluster and domain boundaries the task belongs to.

Web View

Isolates the precise local scope and recursive blast radius of the target change.

Flow View

We have spent decades optimizing how we look at code changes. We use linters to enforce style, unit tests to verify logic, and pull request reviews to share context. But even with 100% test coverage and a green CI build, we still ship production incidents. Why?

The blind spot isn’t in our testing tools — it is in how we perceive risk. We treat “diff size” as a proxy for safety, assuming that a small change is inherently low-risk. In complex systems, this is a dangerous fallacy. The real metric that defines risk is Blast Radius: the number of downstream modules that depend on the code you are touching.

Take control of your codebase intelligence: Learn more and deploy the full stack at spiderbrain.ai.

What Blast Radius Actually Measures

Blast radius is not “how many files you touched.” It is “how many files could be broken by what you touched.”

When you modify a utility function, you aren’t just changing those few lines of code; you are changing the behavior of every upstream module that calls it. If you modify a shared library used by 40 other services, your blast radius is 40 — regardless of whether your diff touches one line or a hundred.

The graph structure of your codebase determines the risk, not the volume of your edits.

Look closely at the graph above. If you modify one of the outer “leaf” nodes, the impact is contained. If you modify the central hub that everything else connects to, you are effectively touching the entire graph.

The Three Tiers of Risk

Once you view your codebase as a dependency graph rather than a collection of text files, you can categorize changes by their structural impact.

Foundational abstractions, core services, high-centrality nodes.

Mandatory staged rollouts, caller audits, deploy gates.

Computing Blast Radius: The Spiderbrain Approach

To make blast radius a useful metric, it must be objective, automated, and deterministic. Human intuition is notoriously bad at estimating reachability in massive codebases.

Tools like Spiderbrain approach this by constructing a directed import graph directly from the source code. By analyzing this graph at commit time, we can compute the impact using standard graph traversal algorithms.

For any given changed node, the blast radius is computed via a traversal (BFS or DFS) with a complexity of $O(V + E)$, where $V$ is the number of vertices (modules) and $E$ is the number of edges (imports).

Because this graph is built from static source code, the result is:

Stable: It doesn’t change based on who runs the test.

Auditable: You can trace exactly why a module is considered “affected.”

Language-Agnostic: It relies on the structure of the dependency graph, not the semantics of the language.

Putting Blast Radius to Work

Once you have visibility into blast radius, you can change your engineering workflow from reactive to proactive:

CI Gates: Don’t just check if tests pass; check if the blast radius exceeds a safety threshold. Flag Tier-3 changes for mandatory senior-engineer review or automated integration testing in a staging environment.

Refactoring Strategy: Sort your refactoring plan by blast radius, ascending. Always start with leaf nodes (low BR) and move inward. If you start by refactoring a high-BR foundation, you introduce instability into the entire system before you’ve even addressed the simple parts.

Incident Postmortems: When an incident occurs, calculate the blast radius of the commit that caused it. You will almost always find that high-BR changes lacking corresponding caller-test coverage are the root cause.

The Shift in Engineering Vocabulary

When your team begins to see blast radius, the conversation changes. “This is a small change” is no longer a valid argument for merging a PR.

The question becomes: “What is the structural position of this change? How many modules depend on it? Have we verified the callers?”

That shift in framing is what true code intelligence is for. It turns the “gut feeling” of experienced engineers into a measurable, data-driven guardrail for every developer on the team.

Every AI coding assistant suffers the same fundamental limitation: it sees your files, not your architecture. When you paste a function into an LLM context window, you get an answer back — but the answer is grounded strictly in flat text, not in the structural reality of your codebase. The difference between textual understanding and architectural awareness matters more than most engineering teams realize.

Learn more: https://spiderbrain.ai

1. What “Seeing Your Codebase” Actually Means

When an AI assistant reads a file like auth/middleware.js, it simply processes a sequence of characters and syntax blocks. It operates blindly, completely unaware of the broader ecosystem:

It does not know that this single file is imported by 23 other modules.

It cannot tell that four of those modules belong to a service your team deprecated last quarter.

It fails to recognize that one critical caller lives directly inside a payment path with 99.9% uptime requirements.

This missing context cannot be solved by prompt engineering. It is a fundamental data model problem. Text-in-context is a flat, linear representation of a reality that is fundamentally shaped like a network graph.

2. Structural Reality vs. Context Windows

Every codebase is natively a directed graph where functions call functions, modules import modules, and classes extend classes. This network graph encodes more systemic intelligence about your software than any single file ever could. It maps which changes are safe to make in isolation, highlights load-bearing files with high structural dependencies, and calculates the exact architectural blast radius of an edit before you touch a line of code.

Simply stuffing more files into a massive context window does not fix the problem. While larger windows allow more text, raw context scales linearly with cost, whereas the graph structure of a codebase scales exponentially with size. A 100-file context window is still just a flat list; the intricate relationships between those files remain completely invisible unless you reconstruct them manually inside your prompt. A deterministic code intelligence graph pre-computes all of that structure once, making it queryable in milliseconds.

3. Visualizing Code Intelligence Architecture

The following flowcharts demonstrate how a flat text model contrasts with a deterministic graph model when analyzing code relationships and calculating systemic impact.

Diagram 1: The Context Window Blind Spot (Flat Text Model)

This diagram illustrates how standard AI assistants view a file as a standalone text block, completely isolated from its real-world upstream dependencies and operational constraints.

[ Input User Query: “Modify auth/middleware.js” ]

│

▼

┌───────────────────────────┐

│ AI Assistant Reads │

│ ~300 Lines of Raw Text │

└─────────────┬─────────────┘

│

┌────────────────┴────────────────┐

▼ ▼

┌───────────────────────┐ ┌───────────────────────┐

│ BLIND SPOT #1 │ │ BLIND SPOT #2 │

│ Fails to see upstream │ │ Completely unaware of │

│ callers & dependencies│ │ high-uptime production│

│ (e.g., 23 importers) │ │ impact (99.9% path) │

└───────────────────────┘ └───────────────────────┘

│ │

└────────────────┬────────────────┘

│

▼

┌───────────────────────────────────────┐

│ Probabilistic Guess/Output Generated │

│ (Risk: Dependency Hallucination) │

└───────────────────────────────────────┘

Diagram 2: The Deterministic Graph Advantage (Spiderbrain Model)

This diagram outlines how a code graph engine mapping files like Spiderbrain maps the absolute topological structure of your code, providing reliable, repeatable impact analysis.

[ Input User Query: “Modify auth/middleware.js” ]

│

▼

┌───────────────────────────┐

│ Deterministic Lookup │

│ Over Codebase Graph │

└─────────────┬─────────────┘

│

▼

┌───────────────────────────┐

│ Map Structural Nodes │

│ and Dependency Edges │

└─────────────┬─────────────┘

│

┌────────────────┴────────────────┐

▼ ▼

┌───────────────────────┐ ┌───────────────────────┐

│ Exact Blast Radius │ │ Contextual Filtering │

│ Calculated Instantly │ │ Flags deprecated paths│

│ (Identifies 23 nodes)│ │ and isolated systems │

└───────────────────────┘ └───────────────────────┘

│ │

└────────────────┬────────────────┘

│

▼

┌───────────────────────────────────────┐

│ Trustworthy Code Intelligence │

│ (Reproducible and Auditable Output) │

4. What Determinism Buys You

Probabilistic AI models guess. They are extraordinarily proficient at guessing, but they are still predicting the next token based on probability. A deterministic graph traversal is not a guess. When a tool like Spiderbrain evaluates a codebase, its architectural calculation is precise and absolute.

If the system indicates that auth/middleware.js has a blast radius affecting 23 modules, that answer will remain exactly the same tomorrow, next week, and after a subsequent refactor that touches an entirely unrelated directory. This absolute reproducibility forms the foundation of trustworthy code intelligence. It can be fully audited, tracked over time across commits, and integrated directly into deployment gates to protect your production pipeline.

5. Summary: Closing the Practical Gap

When engineering teams rely solely on text-grounded AI tools, they consistently hit three structural friction points:

Dependency Hallucination: The assistant confidently claims a function is safe to modify or prune because it cannot see the upstream components relying on it.

Missing Blast Radius: A developer renames a core utility or changes a payload format, inadvertently breaking multiple downstream microservices.

Context Rot: The fragments of code pasted into a chat interface last week fast become stale, failing to reflect the code that actually shipped to production today.

A code graph built natively at commit time eliminates all three vulnerabilities. By evaluating the actual relationships between files, it understands the exact structural state of your codebase at the moment that matters most — before you merge your code.

Further Reading

Blast Radius: The Change-Impact Metric Your AI Tool Ignores

From Comments to Graph: How Spiderbrain Reads Your Documentation

Documentation has an age problem. The moment it is written, the code starts diverging from it. After six months, the Markdown files in a docs/ folder describe a system that only half-exists, and after a year, they become actively misleading. The root cause is not engineering neglect; it is that documentation and code are stored separately with no structural connection. Updating code does not trigger an update to the documentation because no graph edge exists between them.

Spiderbrain's documentation layer transforms this paradigm by treating documentation as first-class nodes within the code graph.

Learn more: https://spiderbrain.ai

1. Documentation Nodes in the Graph

A Spiderbrain brain ingests various forms of documentation, transforming static text into active elements of the codebase architecture:

Markdown files: README files, dedicated docs/ directories, and high-level architecture notes.

Inline Documentation: JSDoc blocks, Python docstrings, and comments attached directly to functions and classes.

OpenAPI specifications: Structured schemas outlining API endpoints and data contracts.

┌───────────────────────┐ ┌───────────────────┐ │ Documentation Node ├───────────────────►│ Code Node │ │ (e.g., auth/README.md)│ [Graph Edge] │(e.g., session.js) │ └───────────────────────┘ └───────────────────┘

Each ingested artifact is assigned its own node in the graph. Explicit relationships (edges) are then mapped dynamically between documentation nodes and the corresponding code nodes using three primary alignment strategies:

Explicit References: Direct mentions of specific filenames, class structures, or function names within the text.

Import Path Matching: Spatial alignment, such as automatically associating a README.md inside an auth/ directory with the code modules living in that exact directory.

Keyword Overlap: Contextual indexing powered by the platform's semantic layer.

2. Why the Graph Edge Matters

Without a structural edge connecting code to its descriptions, documentation remains a isolated asset that must be searched independently, allowing it to go stale silently. Waving documentation into the codebase graph unlocks critical automated advantages:

Expanded Impact Analysis: A blast radius computation for a file like auth/session.js instantly identifies and includes the documentation nodes referencing it.

Change Flagging: When a code node undergoes significant modifications, its connected documentation edges are flagged automatically for review.

Proactive AI Context Selection: When executing a development task, an AI agent receives relevant documentation automatically. The data is surfaced because the graph connects the elements natively, eliminating the need for a developer to manually gather background files.

3. Advanced Synchronization: Drift Detection and Section Splitting

To maintain absolute alignment between documentation and rapidly evolving codebases, Spiderbrain deploys two core algorithmic patterns:

Documentation Drift Detection

The platform continuously tracks architectural divergence by comparing the commit fingerprint of a code node against the timestamp of the last commit that altered its associated documentation edges.Code Node: Commit #104 [Current] ──┐ ├─► (Divergence Detected: Surface for Review) Documentation: Commit #82 [Stale] ──┘

Nodes where the underlying source code has advanced many versions past the documentation are flagged as drift candidates. While this does not serve as a flawless measure of literal semantic staleness, it provides a systematic, highly effective audit trail that exposes unreviewed documentation without requiring manual repository reviews.

The Doc-Splitter Pattern

For extensive files like sprawling READMEs or architecture overviews, Spiderbrain applies a section-aware splitter. Instead of mapping a massive file to a single node, the tool parses the document by its H2 and H3 heading structures, spinning each subsection off into an isolated documentation node with localized edges.

As a result, extensive documents become navigable by exact section. A query regarding "how does the auth session expire?" isolates and retrieves the specific text block addressing session expiry, bypassing the noise of the surrounding document.

4. Making Documentation Useful Again

The primary goal of the documentation graph is not to automate the writing of documentation. Instead, it aims to weave existing knowledge directly into the structural fabric of the codebase. By doing so, documentation is surfaced when relevant, flagged when stale, and instantly fed into AI context windows exactly when it is needed.

MCP tools are the interface between your AI and everything Spiderbrain knows about your project. When you connect any MCP client, 28 tools become available. Knowing which ones to use — and when — is the practical skill that turns "MCP is connected" into "my AI is genuinely more capable."

The codebase tools (17)

These tools give your AI access to the structural graph: the computed relationships between files, the scoring of nodes by importance, and the structural insights derived from the graph.

Blast radius and reach

spiderbrain_blast_radius(node) — computes the transitive reachable set from a node. Returns the count and the top downstream files by spikescore.

spiderbrain_callers(node) — returns the files that directly import a given node.

spiderbrain_transitive_callers(node, depth) — returns callers up to a specified graph depth.

Scoring and ranking

spiderbrain_top_spikescore(n) — returns the top-N nodes by spikescore. The keystone list.

spiderbrain_node_score(node) — returns all three scores (webscore, spikescore, blindspot) for a given node.

spiderbrain_top_blindspot(n) — the top-N nodes by blindspot score. The invisible high-reach files.

Community and structure

spiderbrain_community_of(node) — returns the community ID and all members for a given node.

spiderbrain_communities() — lists all communities with their anchor nodes and member counts.

spiderbrain_boundary_edges() — returns all edges that cross community boundaries. These are the cross-team dependencies.

spiderbrain_path(source, target) — the shortest structural path between two nodes.

Insights and summaries

spiderbrain_insights(area) — returns the scored insights for a module or directory in plain English, each with evidence and a concrete next step.

spiderbrain_score_summary() — a top-level structural summary: community count, keystone list, highest-blindspot files, drift flags.

spiderbrain_compare(commit_a, commit_b) — structural diff between two brains (commits). Returns the drift vector.

Node navigation

The memory tools (9)

These tools give your AI access to the Memory Tree: the project's accumulated decisions, constraints, and patterns.

Recall and scoping

spiderbrain_memory_recall(files) — returns the scoped memory brief for a list of files. The primary tool for session start.

spiderbrain_memory_all() — returns the full Memory Tree. Use sparingly — prefer scoped recall.

spiderbrain_memory_search(query) — semantic search over memory content.

Writing and steering

spiderbrain_memory_add(content, scope) — adds a new memory node. Your AI can propose memories; you ratify them.

spiderbrain_memory_comment(id, comment) — leaves a comment on a memory node (the comment-to-change trigger).

spiderbrain_memory_resolve(id) — marks a comment as resolved after applying the update.

spiderbrain_memory_forget(id) — permanently deletes a memory. Irreversible.

Browsing

spiderbrain_memory_by_scope(scope) — returns all memories anchored to a specific scope.

spiderbrain_memory_recent(n) — returns the N most recently modified memory nodes.

The blueprint tools (2)

spiderbrain_blueprint_read() — returns the current blueprint state as structured data: nodes with types and labels, edges with directionality and types, annotations.

spiderbrain_blueprint_draw(contribution) — proposes an AI drawing contribution to the canvas. Lands beside existing work, never over it. Requires user acceptance.

Which tools to reach for first

For a new project: start with spiderbrain_score_summary() to get the structural overview, then spiderbrain_top_spikescore(10) to identify the keystones.

Before modifying a file: spiderbrain_node(path) + spiderbrain_blast_radius(path) — know the structural position and reach before touching it.

At session start: spiderbrain_memory_recall(files) — get the scoped brief for the files you're about to work on.

Before a refactor: spiderbrain_communities() + spiderbrain_boundary_edges() — understand the community landscape and where the cross-team dependencies live.

 The best AI coding tools are impressive. They complete your code, explain your tests, and suggest refactors that often look exactly right. But impressive is not the same as trustworthy — and in engineering infrastructure, trustworthy is the harder bar.

Spiderbrain is the coding intelligence layer for AI agents: a deterministic, source-free file graph that scores blast radius and severity, Spiderbrain

The reproducibility test

Here is a simple test: ask your code intelligence tool the same question twice. Does it give you the same answer?

For probabilistic models, the answer is usually: mostly. The answers will be semantically similar but not byte-identical. Temperature, sampling, and model state all introduce variance. This is fine for suggestions. It is not fine for infrastructure — for

  +deploy gates, for security audits, for compliance checks.

Determinism means: same input, always same output. No exceptions, no drift.

Why it matters for real use cases

Blame and audit: if your tool told you a change was safe and it wasn't, you need to know what analysis it performed. A deterministic graph traversal produces an auditable trace. A probabilistic inference does not.

CI gating: deploy gates that rely on non-deterministic analysis will be gamed or ignored. Teams quickly learn to retry until they get the answer they want. A deterministic threshold — blast radius > 30 triggers mandatory review — is unambiguous.

Security analysis: source-free code analysis (where the graph is shared without source code) requires that the shared artifact is stable across runs. If the representation drifts, the privacy guarantee breaks down.

Incremental analysis: deterministic builds can be cached. Only changed nodes need recomputation. Non-deterministic analysis cannot safely be cached — you cannot know if the cached result is still valid.

What determinism costs

Determinism trades flexibility for reliability. A deterministic parser cannot reason about what code means — it can only compute what the code is. It will miss the clever architectural pattern that a language model would catch in a comment.

This is the right trade for infrastructure. You want your deploy gate to say "this function has 34 callers and 8 of them lack test coverage" — not "this function seems to be widely used, based on the surrounding context."

The two-layer model

The right architecture uses both: a deterministic graph layer for structure, and a probabilistic layer for semantics. Spiderbrain follows this model: the base graph (import edges, call edges, community membership) is fully deterministic. Semantic enrichment (clustering by topic, extracting intent) is an optional AI layer on top.

The deterministic layer is the foundation you build on. The semantic layer is the intelligence you add. Mixing them — letting probabilistic inference contaminate the structural layer — is where code intelligence tools lose the trust of the teams using

them.

The receipt model

Spiderbrain's graph is built from a hash-chained commit fingerprint. Every brain corresponds to exactly one commit. If the commit changes, the brain changes. If neither changes, the brain is identical across every machine, every run, every engineer.

In architecture, a keystone is the central stone of an arch. Remove any other stone and the arch is weakened. Remove the keystone and the arch collapses. Every codebase has an equivalent: a small set of files whose modification is disproportionately risky compared to any other change.

Experienced engineers know instinctively which files these are. In a codebase they built, the knowledge is reliable. In a codebase they inherited, it is not. In a codebase an AI agent is building, nobody knows.

Spike score finds the keystones.

Learn more: https://spiderbrain.ai

What makes a file a keystone?

A keystone is not simply the most-imported file. High in-degree is a necessary but not sufficient condition. The properties that distinguish a true keystone from a merely popular file:

Bridge centrality: the keystone sits between clusters. A high percentage of all graph paths pass through it. If it fails, communication between components fails.

Cross-community reach: the keystone's blast radius crosses community boundaries. Modifying it requires coordination across team boundaries, not just within a team.

Depth of reach: the keystone's callers include other high-degree nodes. Its blast radius is not just wide but deep — problems propagate recursively through the graph.

Spikescore combines these properties into a single graph-wide ranking. The top-10 spikescore nodes in any codebase are your keystones.

The keystone inventory!

The first practical output of running Spiderbrain against a new codebase: the keystone inventory. The top-10 spikescore nodes, listed with their blast radius, community membership, and test coverage.

This inventory answers the question every engineering lead asks when they inherit a codebase: "which files, if they break, take down everything?" The answer should be known explicitly, not guessed.

For most teams, the inventory reveals surprises. The files with the highest spikescore are often not the ones in the architecture diagram. They are utility functions from early in the codebase's history, configuration loaders, or shared data model files that evolved into cross-service contracts through organic growth.

What to do with the keystone inventory?

Document: keystones deserve more documentation than they typically have. Their importance is not obvious from their size or location. A comment explaining why a file is a keystone — what depends on it, what contract it enforces — is worth the maintenance cost.

Test coverage: if any keystone has low test coverage, fixing that coverage is the highest-ROI test investment in the codebase. A keystone with no tests is a ticking failure waiting for a merge.

Change gating: consider adding a manual review gate for keystone modifications in your CI pipeline. A blast-radius check that flags PRs touching a keystone file for senior review adds friction in exactly the place where friction is valuable.

Refactor planning: some keystones are keystones because they should be extracted — they have accumulated dependencies they shouldn't own. The inventory identifies these over-loaded nodes as the highest-priority refactor candidates.

Keystones in AI-agent workflows!

When an AI agent is autonomously building or refactoring code, it has no concept of keystone risk. It sees the diff, runs the tests, and proceeds. A test suite that covers the changed file but not its callers will pass while latent structural risks accumulate.

Serving the keystone inventory to the AI agent before it begins work changes this. The agent knows: "these files are keystones — changes to them require explicit justification and expanded test coverage." The constraint is structural, not stylistic.

This is the productive use of code intelligence in AI-agent workflows: not replacing the agent's judgment, but grounding it in structural reality before it starts.

The eight-file rule!

For most codebases in the 50k–300k LOC range, the meaningful keystone set is 6–12 files. Fewer than that and the codebase is either very small or very well-decomposed. More than that and some of those "keystones" are actually just popular utilities, not true bridge nodes.

This capability is part of Spiderbrain’s DeepView platform, which maps structural dependencies, blast radius, and codebase communities to help engineering teams understand complex systems in real time.

Most code tooling is reactive. You write code, you run tests, you find out what broke. The discovery of impact happens after the change — in CI, in a review, in production.

Spiderbrain’s live edit alert is predictive. Save a file and you immediately know which downstream files need re-checking, before you run tests, before you push, before you ask your AI to continue building.

What the alert actually shows?

When you save a file, Deepview’s live file-watch triggers a graph traversal from the changed node outward. The result is not a list of all files that transitively import the changed file — that list is often very long and mostly irrelevant.

The alert filters to the files that are structurally significant in the blast radius: the callers with high webscore (community anchors), the files with low test coverage that sit in the reachable set, and any files whose community membership means a change here propagates across a community boundary.

Why this is different from a linter or type-checker

A linter checks syntax and style. A type-checker verifies that the types are consistent. Neither of them tells you about the structural blast radius of your change.

A type error is a correctness error — the code won’t compile. The live edit alert surfaces a different class of problem: a structurally significant change that is technically correct but could have upstream effects that aren’t visible from the changed file.

This is the gap between “the tests pass” and “the system is safe to deploy.” Type-checkers close some of that gap. Structural blast-radius alerts close a different part of it — the part that shows up in post-mortems as “the change was correct but the caller had assumptions we didn’t check.”

The workflow change

The alert changes the question engineers ask at the moment of saving from “is this right?” to “who else does this affect?”

That second question sounds simple. In practice, it’s the question that most engineers don’t have a fast way to answer. They could trace the imports manually, or run a grep for callers, or ask the AI — but all of these take time and break the development flow. The alert makes the answer instantaneous.

The practical effect: engineers who work with live alerts stop writing code in isolation. They develop an awareness of the structural scope of every change — not as a conscious calculation but as a background signal, like knowing how close your car is to the lane boundary without actively measuring.

Why the alert is the flagship demo

The live edit alert is the moment the product earns its keep in real time. Every other feature — the graph, the scoring, the memory tree — requires explanation. The alert demonstrates itself: save a file, see the downstream scope, recheck the flagged files, push with confidence.

It is the one feature that makes a sceptical senior engineer say “okay, that is actually useful” — not because they didn’t know blast radius existed, but because they’ve never had a tool that surfaced it at the moment it was actionable.

Building a verification habit

Teams that adopt the alert as part of their save-push workflow develop a structural verification habit that significantly reduces the surprise-regression class of incident. The pattern:

Make the change

Save: read the alert

Open the top-flagged downstream file: verify its callers still hold

If any flagged file has no test coverage: add a test or add to the review checklist

Push