# What Is the Team-Shared Graph Artifact in Codebase-Memory-MCP? A Complete Usage Guide

> Learn about the team-shared graph artifact in Codebase-Memory-MCP. This guide shows how to use this persisted SQLite DB to share pre-built code intelligence and avoid re-indexing across your team.

- Repository: [Martin Vogel/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp)
- Tags: how-to-guide
- Published: 2026-07-30

---

**The team-shared graph artifact is a persisted SQLite database stored in your repository that contains the complete symbol graph of your codebase, allowing team members to share pre-built code intelligence without re-indexing.**

The team-shared graph artifact eliminates redundant indexing across development teams by persisting the complete symbol graph directly inside your Git repository. This portable database stores symbols, definitions, and cross-references in a standardized format that every team member can query instantly. In the codebase-memory-mcp project, this artifact serves as the single source of truth for code navigation and analysis.

## What Is the Team-Shared Graph Artifact?

The artifact is a portable, read-only SQLite database that acts as a serialized snapshot of your entire codebase’s symbol graph. It captures relationships between functions, classes, variables, and their definitions across multiple programming languages.

### Core Architecture and Files

When generated, the artifact creates two files under the hidden `.codebase-memory/` directory:

- **`graph.db`** – The SQLite database containing the full symbol graph, including nodes (symbols) and edges (references/relationships).
- **[`artifact.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/artifact.json)** – A JSON manifest tracking metadata such as schema version, Git commit hash, and build options.

This separation allows the system to validate compatibility before loading the database, ensuring that the graph structure matches the expectations of the current `cbm` binary.

### Storage Location and Portability

Because the artifact lives inside the repository as ordinary files, it integrates seamlessly with existing version control workflows. Team members pull the pre-built graph alongside source code, eliminating the expensive step of re-parsing the entire codebase.

## How the Artifact Is Generated

The generation process involves two main phases: indexing and export.

### The Indexing Phase

When you run `cbm index`, the tool walks your source tree and extracts symbols using language-specific grammar modules located in `internal/cbm/grammar_*.c` files. The core graph construction engine in [`internal/cbm/cbm.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c) assembles these symbols into an in-memory graph structure, mapping definitions to their references across the codebase.

### The Export Phase

After indexing completes, the **`cbm_artifact_export`** function (implemented in [`internal/cbm/artifact.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/artifact.c)) serializes the in-memory graph into the SQLite format. This function creates the `.codebase-memory/` directory if missing, writes the `graph.db` file, and generates the accompanying [`artifact.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/artifact.json) manifest.

For faster iteration during development, use the `--fast` flag:

```bash
cbm artifact export --fast

```

## Sharing and Distributing the Artifact

The artifact is designed to be **read-only** for consumers, ensuring consistency across team environments.

### Commit and Push Workflow

Once exported, commit the artifact to share it:

```bash
git add .codebase-memory/*
git commit -m "Update graph artifact to HEAD"
git push

```

Teammates simply run `git pull` to receive the updated `graph.db` without performing local indexing.

### Safety Validation

Before importing a shared artifact, the **`cbm_artifact_import`** function performs strict validation:

1. **Schema version check** – Compares the artifact's schema against `cbm_artifact_schema_version` to prevent loading incompatible database formats.
2. **Commit hash verification** – Ensures the manifest matches the repository’s current HEAD, guaranteeing the graph corresponds to the exact source snapshot.
3. **Path safety validation** – Runs `cbm_artifact_repo_path_is_shell_safe` to prevent command-injection attacks when accessing the artifact from shell environments.

If any check fails, the import aborts with a descriptive error, protecting your team from stale or corrupted graph data.

## How to Use the Team-Shared Graph Artifact

Once pulled, the artifact enables instant code intelligence through both CLI commands and the web interface.

### Command-Line Queries

Query the shared graph directly using the CLI commands exposed 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):

**Symbol Lookup:**

```bash
cbm search_graph MyClass

```

**Complex Traversals:**

```bash
cbm query_graph "SELECT * FROM symbols WHERE type='function'"

```

These commands read directly from the SQLite database, providing millisecond-level response times even on large codebases.

### Interactive Visualization

When built with UI support (`CBM_VARIANT=ui`), the binary can launch an embedded **graph-UI**—a Vite-based web application located in the `graph-ui/` directory.

To start the interactive browser:

```bash
cbm --ui

```

The web interface reads the same `graph.db` file, rendering the symbol graph as an explorable dependency map without requiring any re-indexing.

## Step-by-Step Workflow

Follow this workflow to maintain an up-to-date team-shared graph artifact:

1. **Index your codebase** to build the in-memory graph:
   ```bash
   cbm index .
   ```

2. **Export the artifact** to serialize the graph to disk:
   ```bash
   cbm artifact export --fast
   ```

3. **Commit and push** the artifact so teammates receive it:
   ```bash
   git add .codebase-memory/* && git commit -m "Update graph artifact"
   git push
   ```

4. **Pull updates** on teammate machines to get the latest graph without indexing:
   ```bash
   git pull
   ```

5. **Query instantly** using the shared database:
   ```bash
   cbm search_graph MyFunction
   ```

6. **Launch the UI** for visual exploration:
   ```bash
   cbm --ui
   ```

## Summary

- The team-shared graph artifact is a **SQLite database** stored in `.codebase-memory/` that eliminates redundant indexing.
- Generation occurs via [`internal/cbm/artifact.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/artifact.c) functions that export the graph built by [`internal/cbm/cbm.c`](https://github.com/DeusData/codebase-memory-mcp/blob/main/internal/cbm/cbm.c).
- Committed artifacts are validated on import using schema version checks and commit hash verification.
- Use **`cbm search_graph`** and **`cbm query_graph`** to query the shared graph instantly.
- Launch **`cbm --ui`** to visualize the artifact in the browser using the `graph-ui/` application.

## Frequently Asked Questions

### How do I generate the team-shared graph artifact for the first time?

Run `cbm index .` to build the in-memory representation of your codebase, then execute `cbm artifact export` to serialize it to `.codebase-memory/graph.db`. The export process automatically creates the JSON manifest required for version validation.

### Can I use an artifact from a different branch or older commit?

No. The `cbm_artifact_import` function validates the commit hash in [`artifact.json`](https://github.com/DeusData/codebase-memory-mcp/blob/main/artifact.json) against your current HEAD. If they mismatch, the import aborts to prevent navigating stale symbols that no longer align with your working directory.

### Why is the artifact stored as SQLite rather than JSON or XML?

SQLite provides **ACID compliance**, fast indexed lookups, and compact storage for complex graph relationships. The database format supports the `cbm query_graph` SQL-like interface while remaining portable enough to commit to Git.

### How do I update the artifact when dependencies change?

After modifying source code or dependencies, re-run `cbm index .` followed by `cbm artifact export` to regenerate the graph. Commit the updated `.codebase-memory/` files and push them. Teammates will receive the updated graph on their next `git pull` and can immediately query the new symbol relationships without local re-indexing.