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

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 – 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 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) 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 manifest.

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

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:

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:

Symbol Lookup:

cbm search_graph MyClass

Complex Traversals:

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:

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:

   cbm index .

2. Export the artifact to serialize the graph to disk:

   cbm artifact export --fast

3. Commit and push the artifact so teammates receive it:

   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:

   git pull

5. Query instantly using the shared database:

   cbm search_graph MyFunction

6. Launch the UI for visual exploration:

   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 functions that export the graph built by 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 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.

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