How the Team-Shared Graph Artifact Works in Codebase-Memory-MCP

The team-shared graph artifact is a persisted SQLite database stored in the repository that allows teams to share pre-built code graphs without re-indexing.

The team-shared graph artifact is the central mechanism in codebase-memory-mcp that eliminates redundant indexing work across development teams. By serializing the complete symbol graph into a portable SQLite database, the system enables instant graph sharing through standard version control workflows.

What Is the Team-Shared Graph Artifact?

The artifact is a portable SQLite database that stores the full code-base graph including symbols, definitions, cross-references, and their relationships. According to the codebase-memory-mcp source code, the artifact consists of two files written to the hidden .codebase-memory/ directory:

• graph.db – The actual SQLite database containing the serialized graph
• artifact.json – A metadata manifest describing the schema version, commit hash, and build options

When a developer runs the export routine, the system creates these files via the cbm_artifact_export function implemented in internal/cbm/artifact.c. This persistence layer transforms an ephemeral, in-memory graph into a shareable, read-only database that teammates can query immediately after cloning or pulling the repository.

How the Artifact Is Generated

Generation occurs in two phases: indexing and export.

First, the indexer walks the source tree and extracts symbols using language-specific grammar modules (internal/cbm/grammar_*.c). This process builds an in-memory graph representation of the entire codebase.

Second, the export routine serializes this graph into the SQLite format. The core logic resides in internal/cbm/artifact.c, where the exporter performs the following:

1. Writes the graph structure to .codebase-memory/graph.db
2. Generates the JSON manifest at .codebase-memory/artifact.json
3. Records the schema version and current commit hash for validation

The CLI command to trigger this workflow is:

cbm index .
cbm artifact export --fast

The cbm.c file orchestrates this process, calling the artifact exporter automatically after indexing completes.

Sharing and Distributing the Artifact

Because the artifact lives inside the repository, teams share it through standard Git workflows. The files are committed and pushed like source code, allowing teammates to obtain the pre-built graph instantly without expensive re-indexing.

A typical sharing workflow looks like this:

# After indexing and exporting

git add .codebase-memory/*
git commit -m "Update graph artifact"
git push origin main

# Teammates simply pull to receive the graph

git pull

The artifact is read-only for consumers. When loaded via cbm_artifact_import, the system validates the manifest against the current binary capabilities. If the schema version in artifact.json does not match the expected cbm_artifact_schema_version, the import aborts to prevent compatibility issues.

Querying the Shared Graph

Once imported, the artifact serves as the backend for multiple query interfaces. The CLI provides direct commands that operate on the shared SQLite database:

• cbm search_graph <symbol> – Fast symbol lookup across the entire graph
• cbm query_graph – Programmable query language for complex traversals

These commands are exposed through the Python entry point in pkg/pypi/src/codebase_memory_mcp/_cli.py, which reads the .codebase-memory/graph.db file directly.

For interactive visualization, the UI variant supports browser-based graph exploration:

CBM_VARIANT=ui cbm --ui

This launches a Vite-based web application located in graph-ui/ that connects to the same SQLite database, rendering the symbol graph interactively without requiring a separate backend process.

Safety Validation and Integrity Checks

Before loading a shared graph, the system performs mandatory validation checks in internal/cbm/artifact.c to ensure safety and consistency:

• Schema version compatibility – The cbm_artifact_schema_version must match between the artifact and the consuming binary
• Commit hash verification – The manifest must align with the repository's current HEAD, guaranteeing the graph corresponds to the exact source snapshot
• Path safety validation – The cbm_artifact_repo_path_is_shell_safe function validates repository paths to prevent command-injection attacks when artifacts are accessed from shell environments

These checks ensure that teams cannot accidentally load stale or incompatible graph data, protecting against navigation errors and security vulnerabilities.

Summary

• The team-shared graph artifact is a SQLite database (graph.db) plus metadata (artifact.json) stored in .codebase-memory/
• Generated by cbm_artifact_export in internal/cbm/artifact.c after the indexing phase completes
• Shared via Git commits, eliminating the need for every team member to re-index the codebase
• Read-only consumption via cbm_artifact_import with automatic schema and commit hash validation
• Queryable through cbm search_graph and cbm query_graph commands, or visualized via the --ui flag using the Vite-based interface in graph-ui/

Frequently Asked Questions

How do I update the team-shared graph artifact after modifying source code?

Run cbm index . followed by cbm artifact export --fast to regenerate the SQLite database and manifest. Commit the changes in .codebase-memory/ and push to your remote repository. Teammates will receive the updated graph on their next git pull.

What happens if my teammate uses a different version of the codebase-memory-mcp tool?

The cbm_artifact_import function checks the schema version stored in artifact.json against the binary's expected version. If they differ, the import aborts with a compatibility error. Both team members must use binaries that support the same cbm_artifact_schema_version to share artifacts.

Can I use the graph artifact without installing the full indexing toolchain?

Yes. If you only need to query an existing graph, you can clone the repository containing the .codebase-memory/ directory and run cbm search_graph or cbm --ui directly. The SQLite database is self-contained, so read-only operations work without the language-specific grammar parsers required for indexing.

Is the graph artifact safe to commit to version control?

Yes. The artifact is designed as a portable, read-only SQLite file. It excludes absolute paths and validates repository paths via cbm_artifact_repo_path_is_shell_safe to prevent shell injection. However, because it is a binary file that changes frequently, some teams prefer to use Git LFS (Large File Storage) for the graph.db file to keep repository operations fast.

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