# Core Functionalities of the Graph Module in Hivemind: A Virtual Filesystem for Code Dependencies > Explore Hivemind's graph module core functionalities. This virtual filesystem exposes code dependency graphs as file paths, allowing AI agents to query repo structure with shell commands, bypassing actual I/O. - Repository: [Activeloop/hivemind](https://github.com/activeloopai/hivemind) - Tags: api-reference - Published: 2026-06-11 --- **The graph module implements a virtual filesystem (VFS) layer that exposes code dependency graphs as readable file paths, enabling AI agents to query repository structure using standard shell commands like `cat`, `ls`, and `head` without performing I/O on the actual codebase.** The `graph` package in the [activeloopai/hivemind](https://github.com/activeloopai/hivemind) repository provides a read-only interface for exploring complex code dependencies through a virtual filesystem abstraction. This architectural component allows AI coding assistants to introspect repository structures using familiar Unix-style commands while maintaining strict isolation from the underlying filesystem. Understanding the core functionalities of the graph module in hivemind reveals how the system transforms static dependency snapshots into interactive, queryable resources. ## Architecture Overview The graph module organizes its functionality into three distinct layers that work together to provide seamless access to dependency data. This separation of concerns ensures that command parsing, snapshot management, and content rendering remain decoupled while delivering a unified interface. The **command parsing layer** intercepts shell invocations and validates virtual paths. The **VFS dispatch layer** handles routing and snapshot acquisition. The **renderer layer** synthesizes human-readable output from graph data structures. ## Command Parsing and Path Validation The entry point for all graph interactions resides in [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts), which implements the `parseReadTargetPath` function to detect and process shell commands targeting the `/graph/*` virtual namespace. This module specifically handles read-only operations such as `cat`, `head`, `tail`, and `ls` while rejecting dangerous patterns. It prevents path traversal attacks by blocking `..` sequences and refuses complex pipelines that could bypass the virtual filesystem constraints. When a valid command is detected, the parser dispatches the request to `handleGraphVfs`; otherwise, it falls back to standard shell semantics. ## VFS Dispatch and Snapshot Management At [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts), the system implements endpoint routing and snapshot loading logic that bridges raw commands to graph data. The dispatcher maps URL-style sub-paths to specific renderers based on the pattern following `/graph/`. The handler supports nine distinct endpoints: [`index.md`](https://github.com/activeloopai/hivemind/blob/main/index.md), `find/`, `show/`, `query/`, `impact/`, `neighborhood/`, `layers`, `tour`, and `path//`. Each endpoint corresponds to a specific analysis operation on the dependency graph. Snapshot acquisition derives a project key from the current working directory and locates the local graph snapshot, validating its schema against `GraphSnapshot` type definitions from [`src/graph/types.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/types.ts). If no snapshot exists or validation fails, the system returns a graceful `no-graph` result with a helpful message rather than throwing an exception. ## Graph Query Renderers The renderers in `src/graph/render/` transform binary graph data into plain-text output suitable for terminal consumption. Each endpoint has a dedicated implementation that shares common utilities for ranking, fuzzy matching via `fuzzyMatches`, and handle persistence using `saveHandles` and `loadHandles`. ### Index and Discovery The [`index.md`](https://github.com/activeloopai/hivemind/blob/main/index.md) renderer provides a high-level summary including commit hash, node and edge counts, top files by centrality, and breakdowns of node and edge kinds. This serves as the entry point for understanding graph coverage and freshness. ### Symbol Search and Resolution **`find/`** performs case-insensitive substring searches across node IDs and labels, persisting results to a handle table for subsequent reference. **`show/`** resolves numeric handles or string patterns to individual nodes, displaying detailed attributes and one-hop neighbors grouped by relation type. **`query/`** combines these operations, returning the top five matches with their immediate neighborhoods in a single request. ### Dependency Analysis **`impact/`** calculates the transitive closure of dependents (blast radius) for a given symbol, showing all downstream code that could be affected by modifications. **`neighborhood/`** aggregates all symbols defined within a specific file alongside their cross-file dependencies. ### Structural Exploration **`layers`** groups symbols by architectural subsystem using path-based heuristics to identify logical tiers. **`tour`** generates a deterministic, dependency-ordered walkthrough of the entire graph, ensuring agents encounter base definitions before dependent code. **`path//`** executes shortest-path searches between two symbol patterns, revealing the dependency chain linking disparate components. ## Practical Usage Examples The virtual filesystem accepts standard shell commands against the `~/.deeplake/memory/graph/` path prefix. All commands are intercepted by the graph module and processed without touching the actual repository files. List available graph endpoints: ```bash ls ~/.deeplake/memory/graph ``` Search for symbols containing "auth": ```bash cat ~/.deeplake/memory/graph/find/auth ``` Display details for the first search result using the handle table: ```bash cat ~/.deeplake/memory/graph/show/1 ``` Perform a combined query with neighborhood context: ```bash cat ~/.deeplake/memory/graph/query/auth ``` Analyze the impact of modifying a specific function: ```bash cat ~/.deeplake/memory/graph/impact/authService.login ``` Find the shortest dependency path between components: ```bash cat ~/.deeplake/memory/graph/path/Controller/Service ``` ## Supporting Infrastructure Several utility modules complete the graph functionality. [`src/graph/types.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/types.ts) defines TypeScript interfaces for `GraphNode` and `GraphEdge` structures. [`src/graph/last-build.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/last-build.ts) tracks the most recent successful graph build for the current work-tree, while [`src/graph/deeplake-pull.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-pull.ts) manages asynchronous retrieval of remote snapshots when local data is unavailable. ## Summary - **Virtual Filesystem Interface**: The graph module exposes dependency data through standard shell commands (`cat`, `ls`, `head`) using virtual paths under `/graph/*`, eliminating direct filesystem I/O risks. - **Three-Layer Architecture**: Command parsing in [`graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/graph-command.ts), dispatch logic in [`vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/vfs-handler.ts), and rendering functions in `src/graph/render/` provide clear separation of concerns. - **Nine Query Endpoints**: Comprehensive access patterns including symbol search (`find`), dependency impact analysis (`impact`), architectural layering (`layers`), and shortest-path queries (`path`). - **Handle Persistence**: The `saveHandles` and `loadHandles` utilities enable result caching between commands, allowing numeric references like `show/1` to recall previous search results. - **Graceful Degradation**: Missing or malformed snapshots trigger informative `no-graph` responses rather than crashes, ensuring reliable operation in uninitialized workspaces. ## Frequently Asked Questions ### How does the graph module prevent unauthorized filesystem access? The `parseReadTargetPath` function in [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts) explicitly blocks path traversal sequences (`..`) and rejects complex shell pipelines. It only permits simple read-only commands (`cat`, `head`, `tail`, `ls`) targeting the virtual `/graph/*` namespace, ensuring agents cannot use the graph interface to escape the sandbox and read arbitrary repository files. ### What is the difference between the `find` and `query` endpoints in the Hivemind graph module? **`find/`** performs a case-insensitive substring search across node IDs and labels, returning a list of matches with numeric handles. **`query/`** combines this search with immediate neighborhood exploration, returning the top five symbols plus their one-hop dependencies in a single operation. Use `find` for discovery and `query` for rapid context gathering. ### How does the graph module handle missing or outdated snapshots? The [`vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/vfs-handler.ts) dispatcher attempts to locate a local snapshot using the project key derived from the current working directory. If no snapshot exists or schema validation fails against the `GraphSnapshot` type, the renderer returns a `no-graph` result containing a helpful message explaining how to generate the graph. This graceful degradation ensures AI agents receive actionable feedback rather than error stack traces. ### What are the shared utilities used across graph renderers? All renderers in `src/graph/render/` utilize common functions including `rank` for result ordering, `fuzzyMatches` for approximate string matching, and edit-distance calculations for typo tolerance. The `saveHandles` and `loadHandles` functions provide persistent mapping between search results and numeric references, enabling the `show/` endpoint to resolve previous `find` results efficiently.