How to Migrate from Other Code Intelligence Tools to Codebase-Memory-MCP

Migrating to Codebase-Memory-MCP requires exporting your existing tool's data into a canonical dump, converting it to CB-MCP's protobuf format using cbm-import, and loading it into the Zstandard-compressed graph store via cbm-store import to create a persistent, queryable code intelligence layer.

Codebase-Memory-MCP (CB-MCP) is a modern, language-agnostic code intelligence platform that replaces traditional Language Server Protocol servers and LSIF-based pipelines with a persistent graph database. Moving from tools like Sourcegraph, custom LSP implementations, or LSIF indexes involves transforming your existing symbol data into CB-MCP's internal format and initializing the storage engine found in internal/cbm/zstd_store.c/h. This guide walks through the complete migration workflow using the actual commands and configuration files from the DeusData/codebase-memory-mcp repository.

Export Your Existing Code Intelligence Data

The first phase involves extracting a complete snapshot from your current tool to ensure deterministic indexing. CB-MCP ingests a single, canonical dump (.cbm archive), so capturing the full state upfront prevents data inconsistencies during the transition.

Identify your source tool's export format. Most tools support LSIF (Language Server Index Format), JSON-LSP, or SQLite dumps. Use the tool's CLI or API to generate a dump containing symbols, definitions, references, and file-level metadata. If your tool only offers a live LSP connection, record a session using a codelldb-style trace or write a script that walks the codebase and invokes the LSP to produce an LSIF file.

For LSIF-compatible tools like Sourcegraph, run:

lsif-export --output repo.lsif.json

Convert to CB-MCP Format

Once you have the export, transform it into CB-MCP's internal protobuf schema. The storage engine in internal/cbm/zstd_store.c/h expects a flat, versioned protobuf stream, so correct conversion ensures the graph engine can resolve edges without post-processing.

Using cbm-import

Run the provided conversion utility with a configuration file to map source fields to CB-MCP types:

cbm-import --config cbm-import.yaml repo.lsif.json > repo.cbm

Adjust cbm-import.yaml to map source fields like symbol.kind and file.path to CB-MCP's SymbolKind and FilePath enums. This configuration ensures that symbols from your existing tool correctly populate the graph nodes.

Custom Converter Scripts

For tools lacking direct converters, write a Python or Go script that reads the exported JSON and emits cbm_store.proto messages. The script should output a stream of protobuf messages that match the schema expected by zstd_store.c, preserving symbol IDs where possible to maintain cross-reference continuity across imports.

Load and Index the Graph Store

With the converted archive ready, initialize the CB-MCP store and import the data. This creates the persistent graph that powers all downstream queries.

Initialize a fresh store and import the archive:

cbm-store init --path /var/lib/cbm
cbm-store import --path /var/lib/cbm repo.cbm

After importing, run cbm-store vacuum to compress and deduplicate edges, optimizing the storage layout. Verify the import using the built-in test suite or by executing Cypher queries against the graph:

cbm-store vacuum --path /var/lib/cbm
cbm-exec 'MATCH (n) RETURN count(n)'
cbm-exec 'MATCH (s:Symbol) WHERE s.kind = "function" RETURN count(s)'

Integrate Into Your Development Workflow

Replace your existing LSP server with the CB-MCP daemon to serve queries to IDEs and CI pipelines. CB-MCP is process-agnostic; any client that speaks the CB-MCP API (GraphQL, Cypher, or custom RPC) can replace the previous tool without code changes.

Start the LSP daemon:

cbm-lsp start --store /var/lib/cbm --port 8080

Point IDE extensions or CI pipelines to the CB-MCP endpoint at http://localhost:8080. Update build scripts to invoke cbm-store import as part of CI/CD when new commits land. Adjust authentication and role configuration in cbm-config.yaml if you need ACLs for multi-user environments.

For incremental updates during development, enable watch mode to avoid full re-imports:

cbm-store watch --store /var/lib/cbm --path . --debounce 5s

Optional Optimizations and Tuning

Fine-tune the migration for performance and storage efficiency as your codebase grows.

• Compression Tuning: Adjust the zstd compression level in zstd_store.c to balance between faster reads and smaller storage footprint.
• Incremental Indexing: Use cbm-store watch for CI/CD pipelines to process only changed files.
• Visual Debugging: Deploy the optional graph UI by running npm run dev in the graph-ui/ directory to explore the graph visually at http://localhost:5173.

Register custom extractors in cbm-config.yaml for niche languages not supported out-of-the-box (C, C++, Go, Python, and TypeScript are supported natively). Place custom extractors under internal/extractors/ and reference them in the configuration.

Summary

• Export your existing tool's data to LSIF, JSON, or SQLite format to create a canonical dump before conversion.
• Convert exports using cbm-import with cbm-import.yaml mapping, or write custom scripts to emit cbm_store.proto messages for the zstd_store.c engine.
• Load data via cbm-store init and cbm-store import, then verify with cbm-exec Cypher queries or the tests/ harness.
• Integrate by starting cbm-lsp on port 8080 and updating IDE extensions to point to the CB-MCP endpoint.
• Optimize using zstd tuning, cbm-store watch for incremental updates, and the graph-ui/ visual explorer.

Frequently Asked Questions

Can I run CB-MCP alongside my existing tool during migration?

Yes, CB-MCP supports incremental migration by design. You can run both the old tool and CB-MCP side-by-side during the transition period. Use the legacy tool for features not yet covered by CB-MCP, and gradually port those features to CB-MCP queries. Once validation is complete, simply switch the IDE extension endpoint from the old LSP server to cbm-lsp running on port 8080.

How do I handle programming languages not supported by default?

CB-MCP supports C, C++, Go, Python, and TypeScript out-of-the-box. For niche languages, create a custom extractor under internal/extractors/ and register it in cbm-config.yaml. The extractor should output symbols and relationships in the format expected by cbm-import, allowing the zstd_store.c engine to index the new language alongside existing code.

How do I verify that the migration preserved all symbols correctly?

After running cbm-store import, execute the comprehensive test suite included in the tests/ directory by running make test (defined in Makefile.cbm). This harness validates edge-type probes, inheritance extraction, and Cypher query functionality. Additionally, run specific Cypher queries using cbm-exec to spot-check critical symbols and ensure cross-reference continuity has been maintained from your previous tool.

What is the performance impact of using Zstandard compression?

The zstd_store.c storage engine uses Zstandard compression to reduce disk usage while maintaining query performance. You can tune the compression level in the source to prioritize faster reads (lower compression) versus smaller storage (higher compression). For most codebases, the default settings provide sub-second query latency while reducing storage by 60-70% compared to uncompressed JSON indexes, as documented in docs/BENCHMARK.md.

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