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

> Understand how the team-shared graph artifact in Codebase-Memory-MCP functions. This persisted SQLite database enables teams to share pre-built code graphs, eliminating redundant indexing and boosting efficiency.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: internals
- Published: 2026-07-12

---

**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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/.codebase-memory/artifact.json)
3. Records the schema version and current commit hash for validation

The CLI command to trigger this workflow is:

```bash
cbm index .
cbm artifact export --fast

```

The [`cbm.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash

# 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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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:

```bash
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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/artifact.json)) stored in `.codebase-memory/`
- Generated by **`cbm_artifact_export`** in [`internal/cbm/artifact.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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`](https://github.com/DeusData/codebase-memory-mcp/blob/main/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.