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

The graph module integrates with Hivemind through three primary entry points: a CLI dispatcher in src/commands/graph.ts, Virtual File System (VFS) interceptors in src/graph/vfs-handler.ts, and agent pre-tool hooks that rewrite filesystem commands into graph queries.

The graph module in the 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, 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. The resulting snapshot is persisted to ~/.hivemind/graphs/<repo-key>/snapshots/ and referenced by 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 and 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
• src/hooks/cursor/pre-tool-use.ts
• src/hooks/hermes/pre-tool-use.ts

Each hook imports tryGraphRead from 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.

The VFS handler implements endpoints for 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.

// 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 and src/graph/deeplake-pull.ts. These workers are invoked both from the CLI and from post-commit hooks (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 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
2. discoverSourceFiles locates source code, cached extractions are managed by src/graph/cache.ts
3. buildSnapshot in src/graph/snapshot.ts assembles the graph structure
4. writeSnapshot persists data and updates last-build.json
5. Optional pushSnapshot uploads to cloud via 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
3. handleGraphVfs in 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 reads/writes history.jsonl for the hivemind graph history command
• src/graph/diff.ts computes deltas between snapshots for the diff sub-command

Summary

• The CLI dispatcher (src/commands/graph.ts) provides the hivemind graph interface, orchestrating builds, syncs, and history queries.
• VFS interception (src/graph/vfs-handler.ts, 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, 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. 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 invokes pullSnapshot from 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. 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 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 (and similar files for Cursor and Hermes) intercept commands targeting ~/.deeplake/memory/graph/. These hooks call tryGraphRead from src/graph/graph-command.ts, which parses the VFS path and delegates to handleGraphVfs in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}