How the .codebase-memory/graph.db.zst Artifact Facilitates Team Sharing

The .codebase-memory/graph.db.zst file is a Zstandard-compressed Neo4j-compatible graph database that serves as a portable, version-controlled snapshot of your entire codebase structure, enabling teams to share consistent, queryable views without requiring local analysis or source access.

The codebase-memory-mcp repository implements a graph-based memory system that transforms raw source code into a navigable knowledge graph. At the heart of this system lies the .codebase-memory/graph.db.zst artifact—a compressed database snapshot that acts as the single source of truth for repository structure. According to the project documentation in docs/CONFIGURATION.md, this artifact captures, stores, and serves the graph representation of the codebase from a hidden directory at the repository root.

What Is the graph.db.zst Artifact?

The .codebase-memory/graph.db.zst file is the core artifact of the codebase memory system. As documented in docs/CONFIGURATION.md lines 3–7, this file represents a complete compressed graph database that captures the repository's structural elements—including files, directories, symbols, and import relationships.

The artifact resides in the hidden .codebase-memory directory, which the system creates at the project root to store collaboration artifacts. The documentation explicitly identifies this file in lines 13–15 as the compressed graph database component that enables efficient storage and distribution of codebase knowledge.

How It Facilitates Team Sharing

Consistent Development Environments

By distributing the pre-built graph rather than requiring each developer to parse the source locally, teams ensure every member queries an identical structural representation. The artifact eliminates environment drift—whether a developer uses macOS, Linux, or Windows, the decompressed graph contains the same nodes and relationships. This consistency is critical for AI-assisted coding tools and automated refactoring scripts that rely on predictable graph schemas.

Fast Onboarding and CI Integration

New contributors can begin querying the codebase within seconds rather than waiting for lengthy analysis processes. The artifact integrates directly into CI pipelines, where the build system generates the compressed graph and caches it between runs. Subsequent pipeline stages—including the Graph UI preview and automated documentation generators—reuse this artifact without re-parsing source files.

Bandwidth-Efficient Distribution

Zstandard compression provides high compression ratios (often exceeding 90%) while maintaining fast decompression speeds. This makes the artifact ideal for sharing across network boundaries, whether through Git LFS, CI artifact storage, or direct downloads. Teams can version the compressed file alongside their source code, ensuring historical codebase states remain queryable without bloating the repository.

Technical Implementation

Artifact Structure and Storage

The system stores the artifact at .codebase-memory/graph.db.zst using Zstandard (zstd) compression. When decompressed, the file expands into a Neo4j-compatible graph database format that supports Cypher queries. The compression scheme balances storage efficiency with query performance, allowing the Graph UI to fetch and decompress the database client-side or server-side depending on deployment configuration.

Integration with the Graph UI

The repository includes a web-based Graph UI that consumes this artifact directly. As implemented in graph-ui/index.html, the interface loads the compressed database via standard HTTP requests and renders the codebase structure interactively. This architecture enables offline querying—developers can explore the codebase graph without maintaining local source checkouts or running database servers.

Working with the Artifact

Downloading and Decompressing

Teams can fetch and decompress the artifact using standard Unix tools:

# Fetch the artifact from the repo (or CI artifact URL)

curl -L -o graph.db.zst https://github.com/DeusData/codebase-memory-mcp/raw/main/.codebase-memory/graph.db.zst

# Decompress with Zstandard (install via `apt install zstd` if needed)

zstd -d graph.db.zst   # produces graph.db

Loading into Neo4j

Once decompressed, the graph integrates with Neo4j for complex querying:

from neo4j import GraphDatabase

# Connect to a local Neo4j instance

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))

with driver.session() as session:
    # Import the decompressed graph file (Neo4j 5+ supports importing from an .db folder)

    session.run("CALL apoc.import.graph('file:///path/to/graph.db') YIELD file, nodes, relationships")
    # Example query: list all Python modules

    result = session.run("MATCH (m:Module) RETURN m.name AS module")
    for record in result:
        print(record["module"])

Browser-Based Visualization

The Graph UI provides immediate visualization without local database setup:

<!-- index.html loads the UI; the UI script fetches the compressed graph -->
<script type="module">
  import { loadGraph } from '/src/graphViewer.js';
  // The UI automatically decompresses and renders the graph
  loadGraph('/.codebase-memory/graph.db.zst');
</script>

Integrity Verification

To ensure the shared artifact hasn't been corrupted during transfer:

sha256sum graph.db.zst   # compare with the checksum stored in CI metadata

Summary

• The .codebase-memory/graph.db.zst artifact is a Zstandard-compressed Neo4j graph database that captures complete codebase structure according to docs/CONFIGURATION.md.
• It enables consistent team environments by providing a single, version-controlled representation of the repository.
• CI integration allows automated generation and caching, while bandwidth efficiency makes it practical for distributed teams.
• The artifact supports offline querying through the built-in Graph UI (graph-ui/index.html) and standard Neo4j tooling.
• Teams can verify integrity using SHA-256 checksums to ensure reliable sharing across network boundaries.

Frequently Asked Questions

How large is the graph.db.zst artifact compared to the source code?

Zstandard compression typically achieves ratios exceeding 90%, meaning a multi-megabyte codebase often compresses to a few hundred kilobytes. The exact size depends on the complexity and redundancy of the graph structure, but the format is optimized for efficient network transfer and storage as implemented in the DeusData codebase-memory-mcp system.

Can multiple team members write to the graph simultaneously?

The .codebase-memory/graph.db.zst artifact is designed as a read-only snapshot for distribution. While individual developers can load and query local copies, writes should occur through the centralized generation process—typically CI pipelines that rebuild the graph after merges. This ensures the shared artifact remains consistent and immutable across the team.

What happens if the artifact becomes corrupted?

The repository recommends verifying integrity using SHA-256 checksums stored in CI metadata. If corruption occurs, teams can regenerate the artifact by triggering the analysis pipeline or downloading a fresh copy from the latest successful build. The source documentation indicates the system treats this file as a disposable cache that can be rebuilt from source when necessary.

Does the Graph UI require an internet connection to work?

No. Once the graph.db.zst artifact is downloaded, the Graph UI can operate entirely offline. As implemented in graph-ui/index.html, the interface fetches the compressed file locally and performs client-side decompression and rendering, making it suitable for air-gapped environments or travel scenarios without source access.

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