# How the Hivemind Graph Module Integrates with CLI, VFS, and Agent Hooks

> Learn how the Hivemind graph module integrates with CLI, VFS, and agent hooks via dedicated entry points for seamless workflow automation and efficient data management.

- Repository: [Activeloop/hivemind](https://github.com/activeloopai/hivemind)
- Tags: deep-dive
- Published: 2026-06-11

---

**The graph module integrates with Hivemind through three primary entry points: a CLI dispatcher in [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts), Virtual File System (VFS) interceptors in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts), and agent pre-tool hooks that rewrite filesystem commands into graph queries.**

The `graph` module in the [activeloopai/hivemind](https://github.com/activeloopai/hivemind) repository provides a self-contained knowledge graph backend that powers both command-line interactions and AI agent workflows. Understanding how this module integrates with the rest of the system reveals a decoupled architecture where heavy extraction pipelines run independently from lightweight read operations. This article examines the specific integration points that connect the graph subsystem to CLI commands, virtual file system handlers, and background synchronization workers.

## CLI Integration: The Command Dispatcher

Located in [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts), the CLI dispatcher serves as the primary entry point for user-facing graph operations. It parses `hivemind graph` sub-commands—including `build`, `diff`, `history`, `pull`, and `push`—and delegates to the appropriate pipeline functions.

When a user executes `hivemind graph build`, the dispatcher invokes `runBuildCommand`, which orchestrates the symbol extraction process. This function discovers source files through `discoverSourceFiles`, extracts symbols using language-specific extractors in `src/graph/extract/*`, and assembles a `GraphSnapshot` via `buildSnapshot` in [`src/graph/snapshot.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/snapshot.ts). The resulting snapshot is persisted to `~/.hivemind/graphs/<repo-key>/snapshots/` and referenced by [`last-build.json`](https://github.com/activeloopai/hivemind/blob/main/last-build.json), making it immediately available for VFS reads without re-running extraction.

The `runPullCommand` and push operations integrate with cloud storage through [`src/graph/deeplake-push.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-push.ts) and [`src/graph/deeplake-pull.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-pull.ts), allowing snapshots to synchronize across environments.

## Virtual File System: Agent Interception

The most critical integration point for AI agents resides in the VFS interception layer. Rather than querying a live database, Hivemind intercepts filesystem commands targeting `~/.deeplake/memory/graph/` and serves synthesized content from the local snapshot.

This interception happens through **pre-tool hooks** located in:
- [`src/hooks/codex/pre-tool-use.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/codex/pre-tool-use.ts)
- [`src/hooks/cursor/pre-tool-use.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/cursor/pre-tool-use.ts)
- [`src/hooks/hermes/pre-tool-use.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/hermes/pre-tool-use.ts)

Each hook imports `tryGraphRead` from [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts). When an agent issues a command like `cat /graph/index.md`, the hook rewrites the path to a VFS endpoint and calls `tryGraphRead`, which validates the command and forwards the sub-path to `handleGraphVfs` in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts).

The VFS handler implements endpoints for [`index.md`](https://github.com/activeloopai/hivemind/blob/main/index.md), `find/…`, `show/…`, `impact/…`, `neighborhood/…`, `layers`, `tour`, and `path/…`. It loads the JSON snapshot through `loadSnapshotOrError` and renders the requested view, returning the synthesized body to the agent without touching the real filesystem.

```typescript
// Agent hook integration (simplified)
import { tryGraphRead } from "../../graph/graph-command.js";

export async function preToolUse(input: { command: string; cwd?: string }) {
  const cwd = input.cwd ?? process.cwd();
  const rewritten = rewritePaths(input.command);        // host → VFS path
  const graphBody = tryGraphRead(rewritten, cwd);
  if (graphBody !== null) {
    // Agent sees this output instead of executing real cat/ls
    return { stdout: graphBody };
  }
  // Fall back to normal shell execution
}

```

## Background Synchronization: Push and Pull Workers

The graph module maintains consistency with cloud storage through background workers defined in [`src/graph/deeplake-push.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-push.ts) and [`src/graph/deeplake-pull.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-pull.ts). These workers are invoked both from the CLI and from post-commit hooks ([`graph/git-hook-install.ts`](https://github.com/activeloopai/hivemind/blob/main/graph/git-hook-install.ts)).

**`runPullCommand`** fetches the newest cloud snapshot for the current HEAD and writes it to the local snapshot directory, making updated graph data instantly available for subsequent VFS reads. **`pushSnapshot`** (called optionally during `hivemind graph build`) uploads the locally built snapshot to DeepLake, enabling team-wide sharing of extracted knowledge graphs.

Because VFS reads depend solely on the [`last-build.json`](https://github.com/activeloopai/hivemind/blob/main/last-build.json) metadata, agents can query graph data during sync operations without blocking on network requests.

## Data Flow: From Build to Query

The integration architecture separates write-heavy extraction from read-heavy queries:

**Build Path:**
1. `hivemind graph build` triggers `runBuildCommand` in [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts)
2. `discoverSourceFiles` locates source code, cached extractions are managed by [`src/graph/cache.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/cache.ts)
3. `buildSnapshot` in [`src/graph/snapshot.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/snapshot.ts) assembles the graph structure
4. `writeSnapshot` persists data and updates [`last-build.json`](https://github.com/activeloopai/hivemind/blob/main/last-build.json)
5. Optional `pushSnapshot` uploads to cloud via [`src/graph/deeplake-push.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-push.ts)

**Query Path:**
1. Agent issues `cat ~/.deeplake/memory/graph/query/auth`
2. Pre-tool hook calls `tryGraphRead` from [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts)
3. `handleGraphVfs` in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts) parses the sub-path
4. `loadSnapshotOrError` retrieves the local JSON snapshot
5. Renderer generates the response (e.g., `renderIndex`, `renderFind`)
6. Synthesized content returns to the agent's STDOUT stream

**History and Diff Utilities:**
- [`src/graph/history.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/history.ts) reads/writes `history.jsonl` for the `hivemind graph history` command
- [`src/graph/diff.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/diff.ts) computes deltas between snapshots for the `diff` sub-command

## Summary

- **The CLI dispatcher** ([`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts)) provides the `hivemind graph` interface, orchestrating builds, syncs, and history queries.
- **VFS interception** ([`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts), [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts)) allows agents to query graph data through standard filesystem commands without accessing the real filesystem.
- **Agent hooks** (`src/hooks/*/pre-tool-use.ts`) integrate `tryGraphRead` into Claude, Cursor, and Hermes workflows by rewriting shell commands to graph queries.
- **Background workers** ([`src/graph/deeplake-push.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-push.ts), [`src/graph/deeplake-pull.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-pull.ts)) keep local snapshots synchronized with cloud storage independently of read operations.
- **Complete decoupling** between extraction (build) and query (VFS) enables lightweight agent interactions while maintaining heavy analysis pipelines.

## Frequently Asked Questions

### How does the graph module handle agent requests without blocking on extraction?

The module separates concerns through snapshot-based architecture. When agents query graph data via `tryGraphRead`, they read from pre-built JSON snapshots loaded by `loadSnapshotOrError` in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts). The heavy extraction work only runs during `hivemind graph build`, which updates the snapshot independently. This design ensures that VFS reads complete in milliseconds regardless of repository size.

### What happens when a user runs `hivemind graph pull`?

The `runPullCommand` function in [`src/commands/graph.ts`](https://github.com/activeloopai/hivemind/blob/main/src/commands/graph.ts) invokes `pullSnapshot` from [`src/graph/deeplake-pull.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/deeplake-pull.ts), which fetches the latest cloud snapshot for the current Git HEAD. After writing the snapshot to `~/.hivemind/graphs/<repo-key>/snapshots/`, the function updates [`last-build.json`](https://github.com/activeloopai/hivemind/blob/main/last-build.json). Subsequent agent queries through `tryGraphRead` immediately see the updated data without requiring a rebuild.

### Which files are responsible for language-specific symbol extraction?

The `src/graph/extract/*` directory contains language-specific AST extractors for TypeScript, JavaScript, Python, Go, and other supported languages. During the build process, `runBuildCommand` calls `extractFile` for each discovered source file, with results cached via [`src/graph/cache.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/cache.ts) to avoid re-extracting unchanged files.

### How do agents access graph data through standard shell commands?

Agent hooks in [`src/hooks/codex/pre-tool-use.ts`](https://github.com/activeloopai/hivemind/blob/main/src/hooks/codex/pre-tool-use.ts) (and similar files for Cursor and Hermes) intercept commands targeting `~/.deeplake/memory/graph/`. These hooks call `tryGraphRead` from [`src/graph/graph-command.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/graph-command.ts), which parses the VFS path and delegates to `handleGraphVfs` in [`src/graph/vfs-handler.ts`](https://github.com/activeloopai/hivemind/blob/main/src/graph/vfs-handler.ts). The handler renders the appropriate view (index, find, show, etc.) and returns synthesized content that the agent receives as STDOUT, completely transparent to the agent's normal filesystem operations.