DeusData/codebase-memory-mcp

▲ 51 stars today★ 48,094⑂ 3,962

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

About DeusData/codebase-memory-mcp

DeusData/codebase-memory-mcp is an open-source project on GitHub, mainly written in C. Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools It currently holds 48,094 stars and 3,962 forks with 554 open issues, and was last pushed on 2026-11-03 (repository created 2026-02-24).

Project Overview

Git Homed tracks it on the AI Agent Skills Trending board and on the AI AI Agent Skills Trending list, currently at rank #85 with 51 new stars today.

GitHub Repository Details

Repository DeusData/codebase-memory-mcp · default branch main · size 365701 KB · watchers 164 · source: GitHub REST API and repository README

README

codebase-memory-mcp: local code intelligence for AI agents via MCP

GitHub Release License CI Native and frontend tests MCP tools Languages Hybrid LSP Agents Pure C Platform OpenSSF Scorecard SLSA 3 VirusTotal arXiv Join the community on Discord

Understand your repository, from source code to the systems around it. codebase-memory-mcp is an MCP server that connects code, documentation, configuration, and infrastructure in a persistent local knowledge graph. Use it to find an unfamiliar feature, follow a call across services, trace a deployment back to its source, or assess which parts of a project a change could affect.

Give your coding agent structural context through Model Context Protocol (MCP), or query the graph directly from the CLI. The MCP server is the core of the project. Its optional visual companion, CBM Lens, is in open beta (v0.0.1), with a source reader, architecture maps, the Galaxy graph, coverage diagnostics, architecture decisions, and local code chat.

The native C backend exposes 17 MCP tools, parses languages and file formats with vendored grammars, and adds Hybrid LSP type resolution for supported languages. The installer supports 46 automatic or conditional client integrations, including client configuration, skills, agent profiles, and applicable hooks. Indexing and graph queries need no hosted service or API key. Focused graph queries can reduce repeated file reads and token use; see the measured results.

Quick start · Capabilities · Documentation · Infrastructure · Smart CI · Explore CBM Lens · Agent setup · MCP tools

Local processing: Source analysis and graph storage run on your machine. CBM Lens can optionally download a model for browser AI after you enable it; inference stays on the device. The installer writes agent configuration for the clients you select. See Security for release verification and SECURITY.md for reporting issues.

See the graph with CBM Lens (open beta v0.0.1). Folders become nested platforms, files and symbols become selectable blocks, and arrows show indexed relationships. The recording opens src/foundation in the map of this repository, selects arena.c and opens its source. Height can show source size; hotspot gravity reflects static fan-in. Still image.

https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/CBM Lens Beta architecture walkthrough: open src/foundation, select arena.c and read its source beside the map

Galaxy. Explore the code knowledge graph in 3D. The recording follows the outgoing relationships of cbm_arena_alloc one layer further, switches to the hierarchy and shows the two-hop call path to cbm_alloc. Edge pulses show relationship direction; they do not represent live execution. Still: two dependency layers around cbm_max_file_bytes.

https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/Code knowledge graph in CBM Lens Beta Galaxy: expand cbm_arena_alloc, switch to the hierarchy and follow its call path through arena_grow to cbm_alloc

Explore. Browse files in an IDE-style workspace, read syntax-highlighted source in Monaco, and keep the code graph alongside it. File impact shows what depends on the open file, and Code details shows the callers and calls of the symbol under the caret. Select code to ask the local chat about it.

https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/CBM Lens Beta Explore: limits.c in the source reader beside its file impact summary and direct graph dependencies

More views: system structure and behavior

System structure groups symbols into components and lets you inspect their dependencies.

https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/CBM Lens Beta system structure: source groups of this repository with their dependencies, src selected

Behavior shows possible calls from a selected operation and the source evidence behind them.

https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/CBM Lens Beta Behavior view: the possible direct calls of compileCards and its declaration

The high-resolution GIFs show CBM Lens Beta on 20 October 2026; the still images were captured on 12–13 October. All show public source from this repository. See capture details for each capture's build, indexed scope and recording setup.

Why codebase-memory-mcp

Quick Start

Install the latest release (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash

The standard native release includes CBM Lens. Start it after installation with codebase-memory-mcp daemon start --open --port=9749. The Nix packages and source builds also offer builds without the UI.

Windows (PowerShell):

# 1. Download the installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1

2. (Optional but recommended) Inspect the script

notepad install.ps1

3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)

Unblock-File .\install.ps1

4. Run it

.\install.ps1

Note: If you see a script execution policy error, run Set-ExecutionPolicy -Scope Process Bypass first, or invoke with PowerShell -ExecutionPolicy Bypass -File .\install.ps1.

Options: --skip-config (binary only, no agent setup), --dir= (custom location).

Antivirus note: Microsoft Defender may flag a release binary as
Trojan:Script/Wacatac.B!ml. This is a known false positive; typically 61 of
~62 engines return clean, and the same detection family hits gh, llama.cpp,
Godot and Microsoft's own Go toolchain. See
Antivirus False Positives for the
evidence, how to verify the artifacts yourself, and how to report it if you
think we are wrong.

Restart your coding agent. Say "Index this project": done.

Manual install

1. Download the archive for your platform from the latest release:

  • codebase-memory-mcp--.tar.gz (macOS/Linux) or .zip (Windows)
2. Extract and install (each archive includes install.sh or install.ps1):

macOS / Linux:

   tar xzf codebase-memory-mcp-*.tar.gz
   ./install.sh
   

Windows (PowerShell):

   Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .
   Unblock-File .\install.ps1
   .\install.ps1
   

3. Restart your coding agent.

The install command automatically strips macOS quarantine attributes and ad-hoc signs the binary; no manual xattr/codesign needed.

Agent setup: skills, profiles, and hooks

Installation also equips supported coding agents to use the graph in daily work. The native install command detects clients and installs the integration pieces their documented formats support:

| Component | What it adds | |-----------|--------------| | MCP configuration | Connects the client to the local server and its tools. | | Instructions and skills | Explains graph-first exploration, index freshness, coverage checks, and when to read source. | | Scout, Verify, and Auditor profiles | Offers fast provisional lookup, task-directed verification, or bounded full verification, where custom agents are supported. | | Session and compaction hooks | Restores graph context at supported lifecycle events. | | Search and read hooks | Adds relevant graph context to supported searches and flags recorded coverage gaps after supported file reads. |

Hook augmentation is context-only and fail-open: it does not replace or block the requested tool call. Features vary by client and platform; some clients use durable instructions or a parent-agent handoff instead of hooks or direct subagent MCP access. Codex users review and trust installed hooks through /hooks. See Multi-Agent Support and Sessions, compaction, and subagents for exact support and activation requirements.

Hooks are enabled by default. Run codebase-memory-mcp install --no-hooks to remove CBM-managed hooks while keeping MCP registration and other integration files; the choice persists for later installs and updates. Run codebase-memory-mcp install --hooks to re-enable them, or inspect the current preference with codebase-memory-mcp config get install_hooks.

Session Coordination Daemon

CBM automatically shares one per-account coordination daemon across Claude Code, Codex, OpenCode, and every other configured client. There is no opt-in setting for MCP servers or hook clients: the first daemon-backed CBM session starts it, each session registers its own work, and a session-managed daemon stops after the final session. A daemon started with daemon start remains running until stopped. The daemon owns long-lived background services such as watchers, shared indexing jobs, and the optional UI. Closing one session cancels work owned only by that session, while work still needed by another session continues.

The detached daemon does not depend on an MCP frontend's stderr. It keeps owner-only durable records under the canonical ${CBM_CACHE_DIR}/logs directory (default ~/.cache/codebase-memory-mcp/logs):

| File | Contents | |------|----------| | cbm-daemon.log | Daemon lifecycle, watcher/indexing, UI, resource, and error events. | | daemon-conflicts.ndjson | Exact-build, coordination-ABI, and cache-root admission conflicts. | | activation-events.ndjson | Install/update/uninstall activation progress and outcomes. |

Thin frontends still write immediate startup and session-specific errors to their own stderr; MCP JSON-RPC stdout remains clean.

All active CBM processes must run the exact same version, executable build, coordination ABI, and canonical cache root. Equivalent CBM_CACHE_DIR aliases resolve to the same root; a genuinely different root is rejected while any CBM process is active. MCP servers, hooks, one-shot CLI commands, temporary index workers, and the daemon share a crash-safe OS admission barrier; starting an ordinary conflicting process fails before doing work and records an explicit conflict in ${CBM_CACHE_DIR}/logs/daemon-conflicts.ndjson.

The native install and uninstall commands are the deliberate exception to that conflict rule. For installation, download, verification, and private same-filesystem staging finish before activation so a bad candidate never disrupts active work. The native update command prints the installer command that performs the update. Activation then publishes account-wide maintenance intent, asks the daemon and every temporary local operation to cancel, and waits to a finite deadline for all coordinated CBM processes to exit. It holds the admission and lifetime barriers exclusively while changing the active binary, configuration, PATH, or indexes. New CBM work cannot enter during this window. Activation progress and results are recorded in ${CBM_CACHE_DIR}/logs/activation-events.ndjson, and a successful command tells you to restart open coding-agent sessions so they launch the activated build.

Package-manager setup (npm, PyPI, or Go) verifies and caches the native executable for that package. It does not replace the active native installation and therefore does not stop running CBM sessions. When that cached binary is executed, it still enters the same exact-build admission barrier. The shell and PowerShell installers invoke the verified candidate's native install command, so they do receive the full account-wide activation guarantee.

The ordinary cli mode runs one command locally, but it is not disconnected from the daemon above: it connects to the shared coordination daemon (starting one if none is already running) for that same admission barrier plus per-project locks on graph mutations. Its connection is a cli_session: it does not register a project watcher or open a browser, and it holds the admission lease only for the command's lifetime. The shared daemon may serve Lens according to its UI configuration and available assets. If the command's own connection is what started the daemon, that daemon exits again once the command closes and no other session is attached; if a daemon was already running, the command simply joins and leaves it exactly as found. While the command is running, a temporary monitor separately lets activation cancel that operation and its supervised worker safely; the monitor exits with the command and never becomes a standing daemon. See CLI Mode for details.

CBM Lens Beta: code visualization and source navigation

CBM Lens is an optional visual companion to the MCP server, currently in open beta (v0.0.1). Standard native releases include its browser interface, so you can launch Lens directly after installation; UI-enabled source builds include it too. It builds on CodeAtlasWeb by Bernhard Jackiewicz (design and tracking in #1964). Lens is served on loopback. Browser AI downloads its optional model only after you enable it; inference stays on-device. Each panel names where its facts come from, and what the index did not record is shown as a gap. Start the local server:

codebase-memory-mcp daemon start --open --port=9749

The browser opens at http://127.0.0.1:9749. A permanent daemon keeps the UI available after the command exits. Use daemon status to inspect it and daemon stop when you are finished. For an MCP session, --ui=true --port=9749 enables the same shared UI. Active clients must use the same executable build and cache directory.

Open your first repository

1. Open the project menu and choose Add project index. You can also use Alt+P. 2. Choose a local repository folder and name the index. Files stay in place. 3. Start indexing and follow its reported status. You can close the dialog while it runs and reopen its activity from the project menu. 4. Open the indexed project. Start with Architecture for an overview or Explore to read a file.

To bookmark a view, use ?project=&workspace=architecture. Other workspace values are explore, galaxy, adr, coverage, and system.

| Workspace | What you can do | |-----------|-----------------| | Explore | Navigate the indexed file tree and read source in Monaco. File impact shows what depends on the open file; Code details shows the callers, calls, references and related tests of the symbol under the caret. | | Galaxy | Search and focus graph nodes, load their neighbors layer by layer, switch to hierarchy, follow a path, and open source. Back and Forward return to earlier views. The coverage shadow marks known gaps around the loaded graph. | | Architecture | Explore the folder map, entry points, routes, hotspots, system structure, and behavior paths. Select a node or connection to inspect its evidence. | | ADR | Read and edit the project's architecture decision record. Save explicitly; the document is stored with the index and shared with manage_adr. | | Coverage | Check indexed, partially parsed, skipped, and excluded paths, together with available freshness information. | | System | Inspect daemon activity, indexes, and logs. Filter logs by project, severity, or text. |

Architecture views

Drag a 3D view to orbit, scroll to zoom, and select a node or edge to inspect it. Edge colors distinguish relationships, and pulses indicate their direction. Reduced-motion preferences pause the pulses. Large views show their limits and omitted counts. A missing edge can reflect an indexing or display limit, so check Coverage and the source before drawing conclusions.

Chat with your codebase locally

Open Chat with the panel button at the top right to ask about the code you are looking at. In Explore it uses the open file or the exact text you have selected; in Galaxy it uses the selected node and its loaded neighbors. You can also attach graph evidence through Add context.

1. Click the robot icon at the top right to open the agent configuration. 2. Choose a local model. The default Qwen2.5 Coder 0.5B downloads about 567 MB; Qwen3 0.6B, LFM2.5 1.2B and Qwen3.5 2B are larger options. All need WebGPU with shader-f16 support. 3. Click Download & load. Model files come from Hugging Face; inference runs in your browser, with no hosted chat API or API key. A model that is already in the browser cache loads with Load model (cached, no download). 4. Ask a question. The composer shows the file or selection that will accompany it. Select a smaller range when you want to focus the answer.

Questions about callers and callees, such as "Who calls cbm_pipeline_run?", are answered from the loaded graph without the model, and the answer says so. When you select a symbol, the chat lists its indexed facts and the lines of its code, and the model adds one sentence; that sentence is left out when it claims something the source does not show. Text written by the model is labelled as such.

The recording asks who calls arena_grow and what it calls, with both answers listed directly from the indexed graph beside the selected symbol. Still image of a model explanation and graph answer.

https://github.com/DeusData/codebase-memory-mcp/blob/HEAD/Chat with your codebase locally in CBM Lens Beta: callers and callees of arena_grow answered directly from the indexed graph

The chat history is kept for 24 hours in this browser, per project. Each new message uses the source currently open in the reader; earlier source snapshots are not silently accumulated, and messages about another file or selection are not sent along. If a prompt is too long for the model, older messages are left out first; if it still does not fit, CBM Lens asks you to select less code instead of cutting the code. This chat explains the context you give it; it cannot edit files or run tools. Check its answers against the source. The small default model words things loosely, especially in languages other than English.

Search

Cmd+K or Ctrl+K opens the Galaxy search. It finds symbols, files and folders by name or path in the whole index, also nodes that are not loaded yet. For callers and callees, ask in the chat; the answer is listed from the graph.

Architecture decisions

The ADR workspace keeps an unsaved draft per project in this browser tab. It checks whether the stored document changed before saving, but the API does not provide an atomic document lock. The editor accepts up to 8,000 UTF-8 bytes

GitHub Stars & Activity

48,094Stars
3,962Forks
554Open issues
CLanguage

GitHub Popularity

GitHub stars48,094
Forks3,962
Open issues554
Primary languageC
LicenseMIT
Stars gained today51
Created2026-02-24
Last pushed2026-11-03

Trending History

Daily boardrank #85 · ▲ 51 stars

Related GitHub Projects

1

morluto / rea

TypeScript★ 465,160⑂ 0
→
2

affaan-m / ECC

JavaScript★ 304,932⑂ 0
→
3

deepseek-ai / deepseek-harness

TypeScript★ 282,715⑂ 0
→
4

NousResearch / hermes-agent

Python★ 264,057⑂ 0
→
5

firecrawl / firecrawl

TypeScript★ 202,471⑂ 0
→
6

anthropics / skills

Python★ 196,375⑂ 0
→
7

DietrichGebert / ponytail

JavaScript★ 192,510⑂ 0
→
8

farion1231 / cc-switch

Rust★ 155,113⑂ 0
→

More Trending Repositories