#spiderbrain

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

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.

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.