Skip to main content
Glama
DeusData

codebase-memory-mcp

by DeusData
OverviewSchemaRelated ServersScoreDiscussions
Local

codebase-memory-mcp

GitHub Release License CI Tests Languages Hybrid LSP Agents Pure C Platform OpenSSF Scorecard SLSA 3 VirusTotal arXiv

The fastest and most efficient code intelligence engine for AI coding agents. Full-indexes an average repository in milliseconds, the Linux kernel (28M LOC, 75K files) in 3 minutes. Answers structural queries in under 1ms. Ships as a native executable with a small verified runtime-asset set for macOS, Linux, and Windows — download, run install, done.

High-quality parsing through tree-sitter AST analysis across all 162 languages, enhanced with Hybrid LSP semantic type resolution for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — producing a persistent knowledge graph of functions, classes, call chains, HTTP routes, and cross-service links. 15 MCP tools. No language runtime, hosted service, or API key. Plug and play across 45 supported automatic/conditional client surfaces.

Research — The design and benchmarks behind this project are described in the preprint Codebase-Memory: Tree-Sitter-Based Knowledge Graphs for LLM Code Exploration via MCP (arXiv:2603.27277). Evaluated across 31 real-world repositories: 83% answer quality, 10× fewer tokens, 2.1× fewer tool calls vs. file-by-file exploration.

Security & Trust — This tool reads your codebase and writes to your agent configuration files. That is what it is designed to do. If you prefer to audit before running, the full source is here. For each release product, three behaviourally identical executable candidates (unstripped, debug-stripped, stripped) are submitted to VirusTotal before testing; the selected candidate is then packaged with its SHA-256 unchanged. Release notes link every measured candidate result. Publication permits only the narrowly documented single-Microsoft !ml tolerance in SECURITY.md. All processing happens 100% locally; your code never leaves your machine. Found a security issue? We want to know — see SECURITY.md. Security is Priority #1 for us.

Why codebase-memory-mcp

  • Extreme indexing speed — Linux kernel (28M LOC, 75K files) in 3 minutes. RAM-first pipeline: LZ4 compression, in-memory SQLite, fused Aho-Corasick pattern matching. Memory released after indexing.

  • Plug and play — native executable plus authenticated release-owned assets for macOS (arm64/amd64), Linux (arm64/amd64), and Windows (amd64). The native install needs no Docker, language runtime, or API keys. Download → install → restart agent → done.

  • 162 languages — vendored tree-sitter grammars compiled into the binary. Nothing to install, nothing that breaks.

  • 120x fewer tokens — 5 structural queries: ~3,400 tokens vs ~412,000 via file-by-file search. One graph query replaces dozens of grep/read cycles.

  • 45 supported automatic/conditional client surfaces — install configures detected clients and safely activates conditional clients only when their documented platform, marker, or explicit existing config path is present. See Multi-Agent Support for the complete matrix and manual/UI-only boundaries.

  • Built-in graph visualization — 3D interactive UI at localhost:9749, served from the binary itself.

  • Infrastructure-as-code indexing — Dockerfiles, Kubernetes manifests, and Kustomize overlays indexed as graph nodes with cross-references. Resource nodes for K8s kinds, Module nodes for Kustomize overlays with IMPORTS edges to referenced resources.

  • 15 MCP tools — search, trace, architecture, impact analysis, targeted index-coverage checks, Cypher queries, dead code detection, cross-service HTTP linking, ADR management, and more.

Related MCP server: Orihime

Quick Start

One-line install (macOS / Linux):

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

With graph visualization UI:

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

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=<path> (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.

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

    • codebase-memory-mcp-<os>-<arch>.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.

The install command auto-detects installed coding agents and configures their documented MCP entries plus durable instructions, skills, and lifecycle hooks where supported.

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 the final session shuts it down. 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, update, and uninstall commands are the deliberate exception to that conflict rule. Download, verification, and private same-filesystem staging happen first so a bad candidate never disrupts active work. 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 publishes a coherent private cached runtime set. Sidecars are replaced before the executable with per-file atomic renames; an interrupted multi-file publication is detected and repaired on the next launch rather than being described as one crash-atomic filesystem transaction. 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 is intentionally separate: it runs one command locally and never starts or connects to the coordination daemon, registers a daemon session, or starts watchers/UI. Its only shared state is the OS admission barrier plus per-project locks for graph mutations. While the command is running, a temporary monitor 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.

Graph Visualization UI

The graph UI is built into the binary — every install on every channel has it. Then run it:

codebase-memory-mcp --ui=true --port=9749

Open http://localhost:9749 in your browser. The UI is owned by the shared coordination daemon, so concurrent agent sessions do not start duplicate HTTP servers.

Auto-Index

Enable automatic indexing on MCP session start:

codebase-memory-mcp config set auto_index true

When enabled, new projects are indexed automatically on first connection. Previously-indexed projects are registered with the background watcher for ongoing git-based change detection. Configurable file limit: config set auto_index_limit 50000.

Watcher registration is controlled separately by auto_watch (default true). Set config set auto_watch false to keep a session from registering its project with the background watcher — useful when working across many projects and you want each session contained to explicit indexing.

To turn the watcher off entirely, set config set watcher_enabled false (default true): the background poll thread never starts and no project is registered, while auto_index and manual index_repository keep working. Unlike auto_watch — which is consulted per session — watcher_enabled is read once when the background daemon starts, so run codebase-memory-mcp daemon stop after changing it; reconnecting your MCP client alone will not restart the daemon. See docs/CONFIGURATION.md.

Keeping Up to Date

Updates run from the install script on every platform, not from inside the running binary. codebase-memory-mcp update validates your flags and then prints the exact command to run:

# macOS / Linux
bash "<install-dir>/install.sh"
# Windows
powershell -ExecutionPolicy Bypass -File "<install-dir>\install.ps1"

The install script is placed next to the binary at install time, so the printed path resolves beside the executable. It is idempotent, so re-running it is the update: it stops the daemon, retires the running binary, installs the new one, and cleans up.

Why it works this way. On Windows it is a hard requirement — a running executable cannot replace its own image, so the swap has to happen from a process that is not the binary being replaced. On macOS and Linux it is a deliberate choice: an in-process updater is structurally a downloader (fetch an archive, verify it, unpack it, mark a file executable, run it), and shipping that composite in every binary to serve a command most people run a handful of times is a poor trade. The release archives now carry no download URLs at all, and cbm makes no network request of its own accord — it does not check for new versions in the background, and nothing phones home. You find out about releases from the install script, your package manager, or GitHub.

If PowerShell refuses to run the script because the file came from the internet, Unblock-File it first.

Installed through npm or pip? Update with your package manager on every platform (npm install -g codebase-memory-mcp@latest / pip install -U codebase-memory-mcp).

Uninstall

codebase-memory-mcp uninstall

Removes owned agent config entries, skills, hooks, instructions, and the installed binary. Existing graph indexes are listed and deleted only after confirmation.

The install script placed beside the binary is reported, not deleted — uninstall prints its path and the rm command for it. It is left alone on purpose: it may be your own copy, a symlink into a checkout, or managed by a package manager, and an uninstaller should not delete a file it cannot prove it owns.

Features

Graph & analysis

  • Architecture overview: get_architecture returns languages, packages, entry points, routes, hotspots, boundaries, layers, and clusters in a single call

  • Architecture Decision Records: manage_adr persists architectural decisions across sessions

  • Louvain community detection: Discovers functional modules by clustering call edges

  • Git diff impact mapping: detect_changes maps uncommitted changes to affected symbols with risk classification

  • Call graph: Resolves function calls across files and packages (import-aware, type-inferred)

  • Dead code detection: Finds functions with zero callers, excluding entry points

  • Cypher-like queries: MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name

Search

  • Semantic search (semantic_query): vector search across the entire graph, powered by bundled Nomic nomic-embed-code embeddings (40K tokens, 768d int8) compiled into the binary — no API key, no Ollama, no Docker. 11-signal combined scoring (TF-IDF, RRI, API/Type/Decorator signatures, AST profiles, data flow, Halstead-lite, MinHash, module proximity, graph diffusion).

  • BM25 full-text search via SQLite FTS5 with cbm_camel_split tokenizer (camelCase / snake_case aware)

  • Structural search (search_graph): regex name patterns, label filters, min/max degree, file scoping

  • Code search (search_code): graph-augmented grep over indexed files only

Cross-service linking

  • HTTP route ↔ call-site matching with confidence scoring

  • gRPC, GraphQL, tRPC service detection with protobuf Route extraction

  • Channel detection (EMITS / LISTENS_ON) for Socket.IO, EventEmitter, and generic pub-sub patterns across 8 languages with constant resolution

Cross-repo intelligence

  • CROSS_* edges link nodes across multiple repos indexed under the same store

  • Multi-galaxy 3D UI layout for cross-repo architecture visualization

  • Cross-repo architecture summary combining services, routes, and dependencies across the indexed fleet

Edge types (selected)

  • CALLS — a callable is invoked at the source site

  • CALL_REFERENCE — a callable is used at a supported reference site (for example, a direct value argument) and resolves to one exact target

  • USAGE — an identifier is used, but a unique callable target is not proven (including ambiguous or complex expressions)

  • IMPORTS, DEFINES, IMPLEMENTS, INHERITS

  • HTTP_CALLS, ASYNC_CALLS (cross-service)

  • EMITS, LISTENS_ON (channels)

  • DATA_FLOWS with arg-to-param mapping + field access chains

  • SIMILAR_TO (MinHash + LSH near-clone detection, Jaccard scored)

  • SEMANTICALLY_RELATED (vocabulary-mismatch, same-language, score ≥ 0.80)

Indexing pipeline

  • 158 vendored tree-sitter grammars compiled into the binary

  • Generic package / module resolution — bare specifiers like @myorg/pkg, github.com/foo/bar, use my_crate::foo resolved via manifest scanning (package.json, go.mod, Cargo.toml, pyproject.toml, composer.json, pubspec.yaml, pom.xml, build.gradle, mix.exs, *.gemspec)

  • Infrastructure-as-code indexing — Dockerfiles, Kubernetes manifests, Kustomize overlays as graph nodes

  • Hybrid LSP semantic type resolution for Python, TypeScript / JavaScript / JSX / TSX, PHP, C#, Go, C, C++, Java, Kotlin, Rust, and Perl — a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers including tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, and rust-analyzer (parameter binding, return-type inference, generic substitution, JSX component dispatch, JSDoc inference for plain JS files, namespace + trait + late-static-binding resolution for PHP, file-scoped namespaces + records + LINQ method syntax for C#, class-hierarchy + overload + lambda resolution for Java, extension-function + scope-function resolution for Kotlin, trait-method + UFCS resolution for Rust)

  • RAM-first pipeline: LZ4 compression, in-memory SQLite, single dump at end. Memory released after.

Distribution & operation

  • Native runtime set, zero infrastructure services: SQLite-backed, persists to ~/.cache/codebase-memory-mcp/

  • Auto-sync: Background watcher detects file changes and re-indexes automatically

  • Route nodes: REST endpoints are first-class graph entities

  • CLI mode: codebase-memory-mcp cli search_graph '{"project": "my-project", "name_pattern": ".*Handler.*"}'

  • Available on: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, go install

Team-Shared Graph Artifact

Commit a single compressed file to your repo and your teammates skip the reindex.

.codebase-memory/graph.db.zst is a zstd-compressed snapshot of the knowledge graph that lives next to your source. When you index, the artifact is written or refreshed; when a teammate clones the repo and runs codebase-memory-mcp for the first time, the artifact is decompressed and incremental indexing fills in their local diff.

  • Format: SQLite database, indexes stripped, VACUUM INTO compacted, then zstd 1.5.7 compressed (8–13:1 ratio typical)

  • Two tiers:

    • Best (zstd -9 + index strip + VACUUM INTO) — written on explicit index_repository

    • Fast (zstd -3) — written by the watcher for low-latency incremental updates

  • Bootstrap: when no local DB exists but the artifact is present, index_repository imports the artifact first, then runs incremental indexing — avoiding the full reindex cost

  • No merge pain: a .codebase-memory/.gitattributes line with merge=ours is auto-created on first export, so concurrent edits don't produce conflicts on the binary artifact

  • Commit it deliberately: the artifact is rewritten on every index, including the watcher's Fast tier, and git stores each rewrite as a full new blob. Committing every refresh is what turns a 20 MB file into gigabytes of history — one team reached ~6 GB across ~350 commits of this single path. Pick a cadence (a release, a milestone, a nightly job) rather than committing every save.

  • Git LFS, if it must move on every commit: track it from the repo-root .gitattributes and leave the auto-created .codebase-memory/.gitattributes in place — the nearer file goes on supplying merge=ours, and only filter comes from the root:

    .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text

    Track only the .zst; artifact.json is small and carries the schema version. The attribute applies to future commits only, so a repo that already has the blobs in history needs git-filter-repo to rewrite them first. Two costs to weigh before adopting it: GitHub meters LFS storage and bandwidth, and its objects cannot be pruned without contacting support; and every teammate needs git lfs install — without it their checkout leaves a pointer file where the artifact should be, the integrity-checked import refuses it, and they fall back to a full reindex.

  • Optional: never committed unless you want it. Add .codebase-memory/ to .gitignore if you prefer everyone to reindex from scratch.

The result is similar in spirit to graphify's graphify-out/ directory, but as a single compressed file with explicit two-tier export, integrity-checked import, and zero merge friction.

How It Works

codebase-memory-mcp is a structural analysis backend — it builds and queries the knowledge graph. It does not include an LLM. Instead, it relies on your MCP client (Claude Code, or any MCP-compatible agent) to be the intelligence layer.

You: "what calls ProcessOrder?"

Agent calls: trace_path(function_name="ProcessOrder", direction="inbound")

codebase-memory-mcp: executes graph query, returns structured results

Agent: presents the call chain in plain English

Why no built-in LLM? Other code graph tools embed an LLM for natural language → graph query translation. This means extra API keys, extra cost, and another model to configure. With MCP, the agent you're already talking to is the query translator.

Performance

Benchmarked on Apple M3 Pro:

Operation

Time

Notes

Linux kernel full index

3 min

28M LOC, 75K files → 4.81M nodes, 7.72M edges

Linux kernel fast index

1m 12s

1.88M nodes

Django full index

~6s

49K nodes, 196K edges

Cypher query

<1ms

Relationship traversal

Name search (regex)

<10ms

SQL LIKE pre-filtering

Dead code detection

~150ms

Full graph scan with degree filtering

Trace call path (depth=5)

<10ms

BFS traversal

RAM-first pipeline: All indexing runs in memory (LZ4 HC compressed read, in-memory SQLite, single dump at end). Memory is released back to the OS after indexing completes.

Token efficiency: Five structural queries consumed ~3,400 tokens via codebase-memory-mcp versus ~412,000 tokens via file-by-file grep exploration — a 99.2% reduction.

To measure comparable quality, latency, and agent-efficiency metrics on your own workload, see Measuring quality, latency, and agent savings. Exact reproduction of the figures above requires the original inputs and raw artifacts.

Troubleshooting & Diagnostics

codebase-memory-mcp runs 100% locally and collects no telemetry — your code, queries, environment, and usage never leave your machine. That privacy guarantee also means that when you hit something we can't reproduce on our side (a slow memory climb over hours, a performance regression, a leak that only appears after days of real use), we have no data at all unless you choose to send it. Here is how to capture it yourself.

Capture a diagnostics log

Set CBM_DIAGNOSTICS=1 before the first daemon-backed MCP session starts, then reproduce the problem (let it run as long as it takes — a slow leak needs time to show in the trend). The shared daemon captures this setting from the session that starts it. If it is already running, close all daemon-backed sessions so it exits before changing the setting. The daemon creates a fresh owner-private cbm-diagnostics-<pid>-<random> directory below the system temp directory ($TMPDIR or /tmp on macOS/Linux, %TEMP% on Windows). The exact paths are recorded by the diagnostics.start event in ${CBM_CACHE_DIR}/logs/cbm-daemon.log:

File

What it is

trajectory.ndjson

The memory trajectory — one JSON line every 5 s with rss, committed (Windows commit charge), peak_*, page_faults, fd, and queries. This is the file we need for memory/leak reports — the trend over time is what pinpoints a leak. It is kept on disk after the server exits (so you can grab it post-mortem) and rotates to trajectory.ndjson.1 past ~8 MB.

snapshot.json

The latest snapshot only — handy for a quick live check. Removed on clean exit.

The private randomized directory prevents another local account from pre-placing a link or special file at a predictable diagnostics path. Its <pid> component is the shared daemon's process ID, also recorded by the daemon.start event. Set the variable consistently in the env block of each agent's MCP server config, or export it before launching the first session.

What to share

When you open a memory/performance issue, attach the .ndjson trajectory — it contains no source code or query text, only resource counters. If you'd rather not attach a file, paste it (or an agent's summary of it) into the issue: your assistant can read the NDJSON directly and report whether rss/committed grow monotonically, how fast, and relative to query count — which is exactly what we need to find the cause.

Installation

Pre-built Binaries

Platform

Archive

macOS (Apple Silicon)

codebase-memory-mcp-darwin-arm64.tar.gz

macOS (Intel)

codebase-memory-mcp-darwin-amd64.tar.gz

Linux (x86_64)

codebase-memory-mcp-linux-amd64.tar.gz

Linux (ARM64)

codebase-memory-mcp-linux-arm64.tar.gz

Windows (x86_64)

codebase-memory-mcp-windows-amd64.zip

Every release includes checksums.txt with SHA-256 hashes. The executable is self-contained — no adjacent data file is required. Linux -portable archives contain the fully static builds; ordinary platform archives use their native system ABI.

Windows note: SmartScreen may show a warning for unsigned software. Click "More info" → "Run anyway". Verify integrity with checksums.txt.

Setup Scripts

macOS / Linux:

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

Windows (PowerShell):

irm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex

AUR (Arch Linux)

yay -S codebase-memory-mcp-bin
paru -S codebase-memory-mcp-bin

The codebase-memory-mcp-bin package is available at: https://aur.archlinux.org/packages/codebase-memory-mcp-bin

Nix (flake)

The flake exposes two server packages plus the standalone frontend:

Package

Contents

default (codebase-memory-mcp)

Standard server, no UI

codebase-memory-mcp-ui

Server with the graph UI embedded (--ui=true works)

graph-ui

Just the built frontend assets (dist/)

Run directly without installing:

# Standard server
nix run github:DeusData/codebase-memory-mcp

# Server with the embedded graph UI
nix run github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui -- --ui=true --port=9749
# then open http://127.0.0.1:9749

Or build a binary into ./result/bin/codebase-memory-mcp:

nix build github:DeusData/codebase-memory-mcp                          # standard
nix build github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui   # with UI

Working in a clone? Use . in place of the flake URL, e.g. nix run .#codebase-memory-mcp-ui -- --ui=true, or drop into a shell that puts the binary on PATH with nix shell .#codebase-memory-mcp-ui.

Note: launched by hand (not from an MCP client) the server exits as soon as stdin closes — that's normal MCP behaviour. Keep stdin open while testing the UI, e.g. sleep infinity | codebase-memory-mcp --ui=true --port=9749. The codebase-memory-mcp-ui package embeds the UI at build time; nix run'ing the standard default package with --ui=true will refuse to start the HTTP server.

Install via Claude Code

You: "Install this MCP server: https://github.com/DeusData/codebase-memory-mcp"

Build from Source

Requirement

Check

Install

C compiler (gcc or clang)

gcc --version or clang --version

macOS: xcode-select --install, Linux: apt install build-essential

C++ compiler

g++ --version or clang++ --version

Same as above

zlib

—

macOS: included, Linux: apt install zlib1g-dev

Git

git --version

Pre-installed on most systems

git clone https://github.com/DeusData/codebase-memory-mcp.git
cd codebase-memory-mcp
scripts/build.sh --with-ui          # the shipped composition (graph UI embedded)
scripts/build.sh                    # without the UI (development only)
# Binary at: build/c/codebase-memory-mcp   (codebase-memory-mcp.exe on Windows)

Every platform ships one self-contained executable: the graph UI and the agent integration templates are linked into the binary, so an extracted archive is immediately complete.

Run the test suite (6,768 tests across 120 suites):

scripts/test.sh                     # full: clean sanitizer build + all suites + guards
scripts/test.sh --suites <name>     # one suite, incremental, seconds
build/c/test-runner --list-suites   # what is available

scripts/test.sh is the same entry the CI gates run, so a local pass means the same thing a CI pass does. The canonical local artifact-flow check builds both stripped/unstripped candidates, defaults to the stripped candidate for this explicitly unscanned local run, packages those exact bytes, extracts the archive, and smokes it:

scripts/ci/smoke-artifact.sh <linux|darwin|windows> <amd64|arm64>

scripts/package-release.sh is intentionally a lower-level immutable boundary: it accepts only an already-final --selected-binary plus its --expected-sha256; it never builds, strips, signs, or relinks the executable.

Manual MCP Configuration

Add to ~/.claude.json (user scope) or project .mcp.json:

{
  "mcpServers": {
    "codebase-memory-mcp": {
      "command": "/path/to/codebase-memory-mcp",
      "args": []
    }
  }
}

Restart your agent. Verify with /mcp — you should see codebase-memory-mcp with 15 tools.

Multi-Agent Support

install configures 45 client surfaces: 39 detected automatically and 6 conditional or explicit. “Conditional” means the installer writes only when the documented platform or an explicit, already-existing config path proves the target is active. It never flips experimental feature flags, enables plugins, YOLO modes, global permission bypasses, or third-party instruction trust.

Where a client has a documented custom-agent format, the installer creates three exact-owned definitions from one canonical contract:

  • Scout (Tier 1) — about 3–4 narrow calls for fast positive, provisional discovery; no absence, exhaustive-impact, or dead-code claims.

  • Verify (Tier 2, default) — task-directed graph evidence, exact source checks, path coverage for every cited file, and scope coverage before negative claims.

  • Auditor (Tier 3) — bounded scope, current index generation, complete relevant pagination, broader relationship checks, and explicit unresolved limitations.

Every direct tier batches check_index_coverage for its evidence paths and reads flagged ranges or skipped/excluded files directly. A clean coverage result means only “no recorded gap,” never proof of completeness. Clients without safe child MCP access receive the same three tiers as parent-handoff agents; the parent must supply project, generation, pagination state, graph evidence, and coverage results. Updates migrate only byte-identical prior Verify definitions and never overwrite user-modified agents.

Agent

Activation

MCP config

Durable context / augmentation

Claude Code

Detected

~/.claude.json

Skill + three exact-tool graph agents; SessionStart, SubagentStart, non-blocking PreToolUse for Grep/Glob/Bash, and post-Read coverage

Codex CLI

Detected

$CODEX_HOME/config.toml

AGENTS.md, skill, three read-only agents; SessionStart + SubagentStart

Gemini CLI

Detected

.gemini/settings.json

GEMINI.md, three explicit read/graph-tool subagents; BeforeTool, AfterTool read_file coverage, and SessionStart

Zed

Detected

platform settings.json (JSONC)

AGENTS.md + shared skill

OpenCode

Detected

$OPENCODE_CONFIG or resolved global config

AGENTS.md, skill, three deny-by-default read-only agents; plugin adds grep/glob graph lookup, post-read coverage, first-tool-result session context, and post-compaction reinjection

Antigravity

Detected

.gemini/config/mcp_config.json

.gemini/GEMINI.md

Aider

Detected

—

CONVENTIONS.md via .aider.conf.yml

KiloCode

Detected

.config/kilo/kilo.jsonc

Rule + three graph-tool subagents with deny-by-default permissions

VS Code

Detected

platform Code/User/mcp.json

~/.copilot/skills, three read-only agents, sessionStart + subagentStart

Cursor

Detected

.cursor/mcp.json

Skill + three read-only parent-handoff agents; context hooks withheld because session injection races and readonly blocks MCP

Windsurf

Detected

~/.codeium/windsurf/mcp_config.json

Always-on global_rules.md

Augment / Auggie

Detected

~/.augment/settings.json

Rule, three read-only handoff subagents, SessionStart + post-view coverage

OpenClaw

Detected

$OPENCLAW_CONFIG_PATH or state openclaw.json

Active-workspace AGENTS.md + TOOLS.md; compaction reinjection

Kiro

Detected

$KIRO_HOME/settings/mcp.json

Steering, skill, three JSON agents with isolated Scout/Analysis-profile MCP and explicit graph-tool selectors (includeMcpJson: false)

Junie

Detected

.junie/mcp/mcp.json

Skill + three graph subagents for EAP-capable builds; Scout and Analysis server aliases hard-limit the tier tool surfaces; no ineffective EAP SessionStart hook

Hermes

Detected

$HERMES_HOME/config.yaml

Skill + fail-open pre_llm_call context augmentation

OpenHands

Detected

.openhands/mcp.json

Shared .agents/skills/codebase-memory/SKILL.md

Cline

Detected

~/.cline/mcp.json + ${CLINE_DATA_DIR:-~/.cline/data}/settings/cline_mcp_settings.json

Rule + skill; automatic file hooks withheld because they auto-activate and their output is not reliably consumed; child agents cannot use MCP

Warp

Detected, skill only

UI, Warp Drive, or per invocation (manual)

Shared ~/.agents/skills/codebase-memory/SKILL.md

Qwen Code

Detected

.qwen/settings.json

QWEN.md, skill, three explicit read/graph-tool agents; SessionStart, SubagentStart, and post-ReadFile coverage

GitHub Copilot CLI

Detected

$COPILOT_HOME/mcp-config.json

Instructions, skill, three read-only agents; sessionStart + subagentStart

Factory Droid

Detected

.factory/mcp.json

AGENTS.md, skill, three droids with exact per-tier graph-tool lists (without additive whole-server exposure); SessionStart + post-Read coverage on macOS/Linux, withheld on Windows

Crush

Detected

.config/crush/crush.json

Managed context path with explicit parent-to-child handoff

Goose

Detected

.config/goose/config.yaml

.goosehints

Mistral Vibe

Detected

$VIBE_HOME/config.toml

AGENTS.md, skill, and three matched agent/prompt pairs with explicit read-only graph-tool allowlists

Grok Build

Detected

$GROK_HOME/config.toml

Owned rules/codebase-memory.md, skill, three graph agents with named-server mcpInheritance and exact server__tool dispatcher ids; context hooks withheld because its passive hook events discard stdout

Qoder CLI

Detected

~/.qoder/settings.json

Skill, three directly MCP-attached agents with named-server scoping and exact per-tier graph-tool lists; SessionStart, SubagentStart, and post-Read coverage, including documented PowerShell execution on Windows

Kimi Code CLI

Detected

$KIMI_CODE_HOME/mcp.json (default ~/.kimi-code)

Same-root AGENTS.md + skill; fail-open UserPromptSubmit hook in config.toml

GitLab Duo CLI

Detected

$GLAB_CONFIG_DIR/duo/mcp.json or platform fallback

Fail-open user SessionStart on macOS/Linux; hook withheld on Windows; no experimental global skill enablement

Rovo Dev CLI

Detected

configured override or ~/.rovodev/mcp.json

Global AGENTS.md, skill + three read-only handoff subagents; no undocumented hook

Amp

Detected

~/.config/agents/skills/codebase-memory/mcp.json

Colocated skill + ~/.config/amp/AGENTS.md; no plugin

Devin CLI / Local

Detected

~/.config/devin/config.json (platform app-data path on Windows)

Same-root AGENTS.md + skill; macOS/Linux UserPromptSubmit + PostCompaction, and SessionStart only when Claude does not already provide it; hooks withheld on Windows

Tabnine

Detected

~/.tabnine/mcp_servers.json

MCP only; no experimental/YOLO setting

Continue / cn

Conditional

Existing ~/.continue/config.yaml or $CBM_CONTINUE_CONFIG_PATH

MCP only

Visual Studio

Conditional, Windows

~/.mcp.json

MCP only

TRAE

Conditional

Existing $CBM_TRAE_CONFIG_PATH

MCP only

Roo Code

Conditional

Existing $CBM_ROO_CONFIG_PATH

MCP only

Amazon Q Developer IDE

Detected

~/.aws/amazonq/default.json (preserves an existing agents/default.json or legacy mcp.json)

MCP only

CodeBuddy Code CLI

Detected

~/.codebuddy/.mcp.json (preserves an active deprecated/legacy file)

CODEBUDDY.md, skill, three read-only graph agents; beta hooks are not auto-installed

IBM Bob Shell

Detected by bob

~/.bob/mcp_settings.json

Shared rule; no invented hook or agent

Pochi

Detected

~/.pochi/config.jsonc (mcp)

README.pochi.md, skill, and three readFile-only parent-handoff agents

Pi

Detected

—

~/.pi/agent/AGENTS.md + skill; MCP/subagents require an explicit reviewed extension

IBM Bob IDE

Conditional

Existing ~/.bob/mcp.json

Shared rule + IDE skill; no invented hook or agent

Oh My Pi (omp)

Detected

Effective agent directory (OMP_PROFILE / PI_CODING_AGENT_DIR; default ~/.omp/agent/mcp.json)

Skill and three direct-MCP graph-tool subagents (Scout/Verify/Auditor); preserves user AGENTS.md

Sourcegraph Cody

Explicit opt-in

Existing $CBM_CODY_CONFIG_PATH

MCP only

Sessions, compaction, and subagents

Hooks installed by this project are fail-open and context-only. Claude Code's PreToolUse observes Grep/Glob/Bash and injects matching graph symbols as additionalContext; PostToolUse on Read adds targeted coverage context when the graph could not fully parse or index that file. It never denies or replaces the requested tool call.

Claude Code, Codex CLI, Qwen Code, GitHub Copilot CLI, and VS Code's Copilot runtime receive paired session/subagent context where the vendor exposes a documented context-output contract. Codex users must review and trust installed hooks through /hooks; changing a hook definition changes its trust hash, so an update can require re-trust. Qoder uses SessionStart, SubagentStart, and post-Read coverage, including its documented PowerShell executor on Windows. Kimi uses UserPromptSubmit, while Hermes uses pre_llm_call; both retain their documented Windows execution paths. Devin installs UserPromptSubmit and PostCompaction on macOS/Linux and adds SessionStart only when Claude's equivalent managed hook is not present. GitLab Duo gets a narrowly scoped macOS/Linux user SessionStart entry on its experimental hook surface. GitLab Duo, Devin, and Factory hooks are withheld on Windows because those vendors do not document a deterministic shell/executor contract there. Gemini CLI, Factory Droid, and Augment also add documented post-read/view coverage context but expose no equivalent documented child-start context.

For runtimes without a stable context-producing lifecycle event, durable files carry the contract across fresh sessions and compaction: verify the graph project and index freshness, query structural facts in the parent, then pass the project, qualified symbols, paths, and call-chain evidence in every delegated task. Claude, Codex, Gemini, Kiro, Qwen, Copilot, CodeBuddy, OpenCode, Kilo, Vibe, Qoder, Junie, Factory, and Grok Build receive Scout, Verify, and Auditor graph profiles. Kiro embeds this MCP server with --tool-profile scout for Scout and --tool-profile analysis for Verify/Auditor. Junie registers equivalent named server aliases because its subagent schema filters by server rather than by individual tool. Both process profiles use positive allowlists: Scout exposes seven fast inspection tools, Analysis exposes eleven, and future or mutating tools remain unavailable until explicitly reviewed. If either Junie alias collides with user configuration, the installer preserves it and installs parent-handoff profiles instead. Qoder combines its documented named-server selection with exact tier-specific MCP tool IDs. Factory uses exact registered MCP tool IDs without its additive mcpServers field, which would expose the whole server. Codex, Kilo, Vibe, and other capable formats likewise enumerate the narrowest supported tool set. Rovo, Cursor, Augment, Pochi, and Cline use parent handoff where direct child MCP is unavailable or unsafe; Pochi is limited to readFile, and Cline child agents cannot use MCP.

Cline's file hooks auto-activate when present, and current Cline does not reliably consume their context output, so automatic adapters are withheld and older owned adapters are cleaned up. CodeBuddy's beta, version-gated hooks are not auto-installed. Junie's EAP SessionStart output is documented as ignored, so no context hook is installed. Junie custom agents remain EAP-dependent. Qoder can resolve higher-priority project or plugin agents before user agents with the same name; reload the client after installation or profile changes. Cursor context hooks are withheld: session context injection has a known race, subagentStart is control-only, and read-only subagents cannot safely receive MCP access. Grok Build's passive hook events (SessionStart, SubagentStart, PostToolUse) discard stdout and PreToolUse honors only deny/rewrite decisions, so its context hooks are withheld; Grok also reads Claude and Cursor MCP, skill, and hook files through its compat layer, and the native config.toml entry shadows that copy by name. Rovo has no documented session context-output hook, and Bob documents neither a suitable hook nor a custom-agent surface. Those surfaces are not approximated with invented augmentation. Kimi plugins, Amp plugins, and GitLab experimental global skills remain opt-in.

OpenClaw reinjects the Codebase Knowledge Graph (codebase-memory-mcp) AGENTS section after compaction and places the same guidance in TOOLS.md, the bootstrap files inherited by its subagents. Automatic augmentation covers the active/default workspace. Separate agents.list[].workspace directories require making that workspace active for installation or copying the managed block there.

The installed Claude shim is named cbm-code-discovery-gate for backward compatibility; despite the legacy name, it never gates or blocks.

Manual or UI-managed integrations

These are intentionally not counted as automatic installs: Qodo MCP is added through its UI and may be governed by enterprise allowlists; Warp MCP is managed through Warp Drive/UI or per invocation (only the shared skill is automatic); JetBrains AI Assistant / ACP is IDE-managed; GitHub Copilot coding agent, Jules, and CodeRabbit are cloud/repository-managed; Replit exposes a remote/service integration rather than a stable local user-global client; BLACKBOX AI does not document a stable arbitrary user-global MCP/instruction/agent schema; Plandex has no stable global registry safe to mutate; and SWE-agent uses explicit YAML and is no longer a suitable automatic global target.

CLI Mode

Every MCP tool can be invoked as a local, one-shot command. CLI tools neither start nor connect to the coordination daemon and leave no standing process behind. They hold a crash-safe exact-build admission lease only for the command lifetime. index_repository is the only exception internally: it starts a temporary, exact-build supervised worker for the index, then stops that worker before the CLI command exits; the worker holds its own lease until exit.

Commands that mutate graph data use shared OS-backed, per-project locks. This serializes conflicting work from CLI and MCP sessions on the same project while allowing unrelated projects to proceed independently.

When stderr is an interactive terminal, the CLI automatically shows lifecycle and indexing progress. Pass --progress to force the same feedback when stderr is redirected or the command is run non-interactively. Pass --quiet to disable automatic terminal progress and ordinary diagnostics while retaining errors; it cannot be combined with --progress or outer cli --verbose. Routine informational logs are quiet by default; pass outer cli --verbose to include them. Progress and logs use stderr while stdout remains reserved for the command result. Read tools return a compact tree by default; pass a tool's --format json for machine-readable payload JSON, or outer --json for the full MCP envelope.

Large compact-tree tables may start with a response-local <section>_refs directory and an explicit <section>_ref_rule. A cell such as @0+handler.go reconstructs to ref 0's prefix plus handler.go. References are local to that sibling <section> table and expansion is non-recursive: entries inside <section>_refs are always literal prefixes. This is limited to declared path and qualified-name columns and activates only when the exact rendered table is at least 15% and 64 bytes smaller and a conservative model-neutral token-shape proxy also improves by at least 1%. Search and trace likewise render direct and prefix-grouped tree shapes and keep the smaller complete representation, so singleton or scattered answers do not pay directory overhead. Keys are declared once per table but never cryptically abbreviated, and --format json keeps stable literal strings for machine consumers. Both gates are deterministic; exact token counts still depend on the caller's tokenizer.

Lean responses truncate semantically, never by cutting arbitrary bytes from code or identifiers. Ranked graph rows are retained ahead of raw grep rows and diagnostic summaries; omitted rows/sections report totals, has_more, and a strictly advancing continuation offset or cursor. If even the first whole row cannot fit, CBM asks for a higher budget and emits no self-looping cursor. max_output_tokens is model-neutral sizing guidance: CBM enforces a deterministic ceiling of four UTF-8 bytes per requested token, so it is not a tokenizer-exact count. Detail flags such as diagnostics, source_mode, and detail opt into heavier fields. search_code pages ranked rows with result_limit/result_offset (limit remains a compatibility alias), raw rows with raw_limit/raw_offset, and directory summaries with directory_limit/directory_offset. Raw lines default to a UTF-8-safe match-centered preview; each row reports content_start_byte, returned/total byte counts, match byte bounds when known, and a content continuation offset. Pass raw_content_offset to page the original line without moving the raw-row cursor. match_limit and source_max_lines bound per-result details, with exact omission metadata. detect_changes pages changed files, impacted symbols, and module summaries independently; prefer its snapshot-bound *_cursor continuations, which reject changed commits, worktree bytes, graph generation, or semantic arguments instead of silently skipping or duplicating rows.

Every response is standard UTF-8. Identifiers, paths, and raw search previews preserve POSIX byte-string identities: a preserved value containing malformed UTF-8 is emitted reversibly as @bytes:<lowercase hex of every original byte>. A valid preserved value that literally begins with the reserved @bytes: or @utf8: prefix is emitted as @utf8:<original value>, so decoding is unambiguous: strip one @utf8: prefix for literal UTF-8, or hex-decode one @bytes: prefix for original bytes. Ordinary valid UTF-8 is unchanged and pays no output-token overhead. To keep code readable, source bodies replace malformed UTF-8 with U+FFFD; use the pageable raw search preview when byte-exact source inspection is required.

Use cli <tool> --help to see the flags generated from that tool's input schema:

codebase-memory-mcp cli index_repository --repo-path /path/to/repo
codebase-memory-mcp cli list_projects

# Use the "name" returned by list_projects as the project value.
codebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function
codebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both
codebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Function) RETURN f.name LIMIT 5'

# Force human-readable progress without contaminating stdout.
codebase-memory-mcp cli --progress index_repository --repo-path /path/to/repo
# Suppress automatic terminal progress and non-error diagnostics.
codebase-memory-mcp cli --quiet list_projects --format json
codebase-memory-mcp cli search_graph --project my-project --label Function --format json
codebase-memory-mcp cli list_projects --format json --detail stats | jq '.projects[].name'

JSON arguments can also be piped on stdin, for tools that take arguments. A tool whose input schema declares none — list_projects — never reads stdin, so it stays responsive when it inherits a pipe the caller never closes (the default for child_process.spawn and similar wrappers). Inline JSON remains accepted for backward compatibility but is deprecated in favor of flags, --args-file, or stdin.

MCP Tools

Indexing

Tool

Description

index_repository

Index a repository into the graph. Auto-sync keeps it fresh after that.

list_projects

List all indexed projects with node/edge counts.

delete_project

Remove a project and all its graph data.

index_status

Check indexing status of a project.

Querying

Tool

Description

search_graph

Structural, BM25, and semantic search. Page structural rows with offset/limit and ranked semantic rows independently with semantic_offset/semantic_limit.

trace_path

BFS traversal — who calls a function and what it calls (alias: trace_call_path). Depth 1-5.

detect_changes

Map git diff to affected symbols + blast radius with risk classification.

query_graph

Execute Cypher-like graph queries (read-only).

get_graph_schema

Node/edge counts, relationship patterns, property definitions per label. Run this first.

get_code_snippet

Read source code for a function by qualified name.

get_architecture

Codebase overview: languages, packages, routes, hotspots, clusters, ADR.

search_code

Grep-like text search within indexed project files.

manage_adr

CRUD for Architecture Decision Records (get reads, update replaces the whole document, set_sections rewrites only the named sections and leaves every other byte untouched, sections lists headings). Query modes do not wait behind a same-project reindex; writes remain serialized.

ingest_traces

Ingest runtime traces to validate HTTP_CALLS edges.

manage_adr(mode='set_sections') writes one or more sections by name and splices them into the stored document, so text outside the named sections — including a preamble, code fences and section ordering — is preserved byte-for-byte. Any ## Heading works, not just the conventional PURPOSE / STACK / ARCHITECTURE / PATTERNS / TRADEOFFS / PHILOSOPHY set; names match exactly, including case. Writing the same section twice is a no-op, so a retry after a lost response cannot duplicate content.

manage_adr query modes (get and sections) use the server's cached query store so they can proceed while a same-project reindex is running. If another process publishes a replacement store during reindexing, they can return the pre-publication ADR until idle eviction refreshes that cache. Updates remain serialized through the project mutation guard.

Graph Data Model

Node Labels

Project, Package, Folder, File, Module, Class, Function, Method, Interface, Enum, Type, Route, Resource

Edge Types

CONTAINS_PACKAGE, CONTAINS_FOLDER, CONTAINS_FILE, DEFINES, DEFINES_METHOD, IMPORTS, CALLS, CALL_REFERENCE, HTTP_CALLS, ASYNC_CALLS, IMPLEMENTS, HANDLES, USAGE, CONFIGURES, WRITES, MEMBER_OF, TESTS, USES_TYPE, FILE_CHANGES_WITH

Qualified Names

get_code_snippet uses qualified names: <project>.<path_parts>.<name>. Use search_graph to discover them first.

Supported Cypher (openCypher read subset)

query_graph is a read-only openCypher subset:

  • Clauses: MATCH, OPTIONAL MATCH, multiple MATCH, WHERE, WITH (+ WITH … WHERE), RETURN, ORDER BY, SKIP, LIMIT, DISTINCT, UNWIND, UNION / UNION ALL, CASE.

  • Patterns: labelled nodes, label alternation (n:A|B), relationship types/direction, variable-length paths [*1..3], inline property maps.

  • WHERE: = <> < <= > >=, AND/OR/XOR/NOT, IN, CONTAINS, STARTS WITH, ENDS WITH, IS [NOT] NULL, regex =~, label test n:Label, and EXISTS { (n)-[:TYPE]->() } (single-hop existence — great for dead-code, e.g. WHERE NOT EXISTS { (f)<-[:CALLS]-() }).

  • Aggregates: count (+DISTINCT), sum, avg, min, max, collect.

  • Functions: labels, type, id, keys, properties; toLower/toUpper/toString/toInteger/toFloat/toBoolean; size, length, trim/ltrim/rtrim, reverse; coalesce, substring, replace, left, right.

Anything outside this subset (write/MERGE/CALL clauses, unsupported functions, list/map literals, comprehensions, path functions, parameters) fails with a clear unsupported … error rather than returning empty results.

Ignoring Files

Layered: hardcoded patterns (.git, node_modules, etc.) → .gitignore hierarchy → .cbmignore (project-specific, gitignore syntax). Symlinks are always skipped.

See docs/cbmignore.md for the full .cbmignore how-to: syntax, precedence across the ignore layers, and negation semantics.

Configuration

codebase-memory-mcp config list                          # show all settings
codebase-memory-mcp config set auto_index true           # auto-index on session start
codebase-memory-mcp config set auto_index_limit 50000    # max files for auto-index
codebase-memory-mcp config set auto_watch false          # don't register background git watcher (default: true)
codebase-memory-mcp config set watcher_enabled false     # stop the watcher thread entirely (default: true)
codebase-memory-mcp config reset auto_index              # reset to default

Environment Variables

Variable

Default

Description

CBM_ALLOWED_ROOT

(unset)

Confine index_repository to paths within this directory. When set, a repo_path that resolves (after symlink / .. resolution) outside this root is refused, and the same check now applies to the graph UI's POST /api/index route rather than only to the MCP tool. Unset imposes no containment restriction — but see the always-on limits below, which apply whether or not this is set. Useful when the server may be driven by an untrusted caller, e.g. agentic or multi-tenant deployments.

CBM_CACHE_DIR

~/.cache/codebase-memory-mcp

Override the database storage directory. All project indexes and config are stored here. One account can use only one canonical cache root at a time; close active CBM sessions/commands before switching it.

CBM_DIAGNOSTICS

false

Set to 1 or true to enable the shared daemon's periodic snapshot.json and retained trajectory.ndjson below a fresh owner-private directory in the system temp directory. Exact paths are logged by diagnostics.start.

CBM_DOWNLOAD_URL

(GitHub releases)

Override the download URL for updates. Used for testing or self-hosted deployments.

CBM_LOG_LEVEL

role-aware

Set the minimum log level. Thin MCP/CLI/hook frontends default to warn; the detached daemon and its supervised index workers default to info so lifecycle and liveness records remain available. Accepted values (case-insensitive): debug, info, warn, error, none — or their numeric equivalents 0–4. A physical worker retains INFO liveness records even under a stricter override because its private log drives the supervisor's no-progress timeout. Frontend messages go to that session's stderr; detached daemon events go to ${CBM_CACHE_DIR}/logs/cbm-daemon.log. Stdout is reserved for MCP JSON-RPC.

CBM_WORKERS

(detected)

Override the parallel-indexing worker count returned by cbm_default_worker_count. Useful inside containers where sysconf(_SC_NPROCESSORS_ONLN) reports host CPUs rather than the cgroup's effective quota. Range 1–256; invalid values are ignored with a warning.

CBM_MEM_BUDGET_MB

(detected)

Override the in-memory graph budget with an explicit cap in MiB, taking precedence over the ram_fraction × total_RAM default. Useful on bare-metal hosts without a cgroup limit, or to pin a budget below the cgroup limit so headroom is left for sibling processes. Must be a positive integer; it is clamped to detected total RAM (logged as mem.budget.clamped), and non-numeric or non-positive values are ignored with a warning (mem.budget.env.invalid).

CBM_DUMP_VERIFY_MIN_RATIO

0.5

After indexing, compare persisted SQLite node count to the in-memory dump count. When persisted nodes fall below this fraction of committed nodes (and committed > 50), index_repository returns status:"degraded" instead of silent indexed. Range 0–1; set 0 to disable. Invalid values are ignored with a warning.

Environment used by daemon-owned components—such as diagnostics, daemon logging, and process-wide indexing resource limits—is captured from the first daemon-backed session that starts the daemon. Later sessions join that process and cannot replace those values. To change them, close all daemon-backed sessions, update the relevant agent configurations consistently, and restart a session. CBM_ALLOWED_ROOT remains session-specific, a conflicting CBM_CACHE_DIR is rejected, and one-shot CLI commands read their own environment without starting the daemon.

# Store indexes in a custom directory
export CBM_CACHE_DIR=~/my-projects/cbm-data

Custom File Extensions

The JSON config files support a single key, extra_extensions, which maps additional file extensions to supported languages. Useful for framework-specific extensions like .blade.php (Laravel) or .mjs (ES modules). (For other tunables, see Environment Variables and the config subcommand above.)

Need the full config-file reference? See docs/CONFIGURATION.md.

Per-project (in your repo root):

// .codebase-memory.json
{"extra_extensions": {".blade.php": "php", ".mjs": "javascript"}}

Global (applies to all projects):

// ~/.config/codebase-memory-mcp/config.json  (or $XDG_CONFIG_HOME/...)
{"extra_extensions": {".twig": "html", ".phtml": "php"}}

Each entry maps an extension (which must start with .) to a language name. Language names are matched case-insensitively. Accepted values (aliases in parentheses) are:

bash (sh), c, c++ (cpp), c# (csharp), clojure, cmake, cobol, common lisp (commonlisp, lisp), css, cuda, dart, dockerfile, elixir, elm, emacs lisp (emacslisp), erlang, f# (fsharp), form, fortran, glsl, go, graphql, groovy, haskell, hcl (terraform), html, ini, java, javascript, json, julia, kotlin, lean, lua, magma, makefile, markdown, matlab, meson, nix, objective-c (objc), ocaml, perl, php, protobuf, python, r, ruby, rust, scala, scss, sql, svelte, swift, toml, tsx, typescript, verilog, vimscript, vue, wolfram, xml, yaml, zig.

Project config overrides global for conflicting extensions. An entry whose language name is unknown, or whose extension does not start with ., is skipped and a warning is logged to stderr (shown at the default info log level). Missing config files are ignored.

Persistence

SQLite databases stored at ~/.cache/codebase-memory-mcp/. Persists across restarts (WAL mode, ACID-safe). To reset: rm -rf ~/.cache/codebase-memory-mcp/.

Troubleshooting

Problem

Fix

/mcp doesn't show the server

Check .mcp.json path is absolute. Restart agent. Test: echo '{}' | /path/to/binary should output JSON.

index_repository fails

Pass absolute path: index_repository(repo_path="/absolute/path")

trace_path returns 0 results

Use search_graph(name_pattern=".*PartialName.*") first to find the exact name.

Queries return wrong project results

Add project="name" parameter. Use list_projects to see names.

Binary not found after install

Add to PATH: export PATH="$HOME/.local/bin:$PATH"

UI not loading

Ensure you ran --ui=true. Check http://localhost:9749.

Hybrid LSP

Semantic type resolution beyond tree-sitter.

Tree-sitter alone gives a syntactic AST. That handles naming, structure, and call sites well, but it can't tell you that user.profile.display_name() resolves to Profile.display_name declared three modules away — tree-sitter doesn't track imports, generics, inheritance, or stdlib types.

codebase-memory-mcp ships a lightweight C implementation of language type-resolution algorithms, structurally inspired by and compatible with major language servers (tsserver / typescript-go, pyright, gopls, Roslyn, Eclipse JDT, rust-analyzer), embedded directly into the native executable. No language server process, no per-project setup, no API key. We call this layer Hybrid LSP: it runs alongside tree-sitter on every parse and refines invocation resolution (CALLS / RESOLVED_CALLS) and callable-value resolution (CALL_REFERENCE, with ambiguous values retained as USAGE) using type information, so the resulting graph mirrors what an IDE "Go to Definition" would resolve.

Languages with full Hybrid LSP:

Language

What it handles

Python (new in v0.7.0)

imports + dotted submodule walks, dataclasses, Self return types, generics, @property, match/case class patterns, SQLAlchemy 2.0 Mapped[T], Pydantic BaseModel, typing.Annotated / ClassVar / Final / InitVar, async/await, classmethod/staticmethod, narrowing (isinstance / is not None / walrus), typing.cast / assert_type, common stdlib (logging, pathlib, json, functools). Target ~95% resolution on idiomatic code.

TypeScript / JavaScript / JSX / TSX

generics, JSX component dispatch, JSDoc inference for plain JS, .d.ts declarations, module re-exports, method chaining via return-type propagation, per-file overlay chained to a shared cross-file registry

PHP (new in v0.7.0)

namespaces, traits, late-static-binding, PHPDoc inference, parameter binding, return-type inference

C# (new in v0.7.0)

global usings, file-scoped namespaces, records (incl. C# 12 primary constructors), LINQ method syntax, async Task<T> / ValueTask<T> unwrap, generic methods, this / base dispatch, var inference, common BCL stdlib

Go (sharpened in v0.7.0)

pre-built per-package cross-file registry, generics, embedded structs, interface satisfaction, package-aware import resolution

C / C++ (sharpened in v0.7.0)

pre-built per-language cross-file registry shared across C and C++; C side handles macros + typedef chains + header-vs-source linking; C++ side handles templates, namespaces, auto inference, and method resolution via class hierarchy

Java (new in v0.8.0)

imports (single-type, on-demand, static), class hierarchies with this / super dispatch, generics, annotations, overload matching by arity and parameter types, lambdas / method references bound to functional interfaces, field-type inference, common JDK stdlib

Kotlin (new in v0.8.0)

imports + same-package resolution, classes / objects / companion objects, extension functions, data classes, nullable-type unwrapping, scope functions (let / apply / run / also / with), infix calls, common stdlib

Rust (new in v0.8.0)

use declarations + module paths, impl blocks and trait methods, struct fields, generics with trait bounds, operator-trait desugaring, derive-macro method synthesis, UFCS static paths, common std prelude

Perl

packages + @ISA / use parent / use base inheritance with method-resolution-order dispatch, SUPER:: calls, Exporter (use Foo qw(...)) import maps, bless / ref($class)||$class self-type inference, qualified Pkg::sub static calls, curated perlfunc + CPAN OOP stdlib; unresolved receivers emit no edge (zero-edge guarantee)

Two-layer architecture:

  1. Tree-sitter pass — fast, syntactic, runs for every one of the 162 languages. Extracts definitions, calls, imports.

  2. Hybrid LSP pass — type-aware, runs above the tree-sitter pass per-language. Refines call edges using the import graph plus a per-file or pre-built cross-file definition registry. Languages without a Hybrid LSP pass yet fall back to textual resolution, so you always get some answer.

The result is a knowledge graph accurate enough to drive trace_path across packages, inheritance hierarchies, and stdlib calls — without paying for a language server process per project.

Language Support

162 languages, all parsed via vendored tree-sitter grammars compiled into the binary. Benchmarked against 64 real open-source repositories (78 to 49K nodes):

Tier

Score

Languages

Excellent (>= 90%)

Lua, Kotlin, C++, Perl, Objective-C, Groovy, C, Bash, Zig, Swift, CSS, YAML, TOML, HTML, SCSS, HCL, Dockerfile

Good (75-89%)

Python, TypeScript, TSX, Go, Rust, Java, R, Dart, JavaScript, Erlang, Elixir, Scala, Ruby, PHP, C#, SQL

Functional (< 75%)

OCaml, Haskell

Also supported (not yet benchmarked): Ada, Agda, Apex, Assembly (NASM), Astro, AWK, Beancount, BibTeX, Bicep, Bitbake, Blade, Cairo, Cap'n Proto, Clojure, CMake, COBOL, Common Lisp, Crystal, CSV, CUDA, D, Devicetree, Diff, .env, Elm, Emacs Lisp, F#, Fennel, Fish, FORM, Fortran, FunC, GDScript, .gitattributes, .gitignore, Gleam, GLSL, GN, Go module, Go template, GraphQL, Hare, HLSL, Hyprlang, INI, ISPC, Janet, Jinja2, JSDoc, JSON, JSON5, Jsonnet, Julia, Just, Kconfig, KDL, Lean 4, Linker Script, Liquid, LLVM IR, Luau, Magma, Makefile, Markdown, MATLAB, Mermaid, Meson, Move, Nickel, Nim, Nix, Odin, Pascal, Pkl, PO (gettext), Pony, PowerShell, Prisma, .properties, Protobuf, Puppet, PureScript, Racket, Regex, requirements.txt, ReScript, RON, reStructuredText, Scheme, Slang, Smali, Smithy, Solidity, SOQL, SOSL, Squirrel, SSH config, Starlark, Svelte, Sway, SystemVerilog, TableGen, Tcl, Teal, Templ, Thrift, TLA+, Typst, Verilog, VHDL, Vim script, Vue, WGSL, WIT, Wolfram, XML, Zsh.

Architecture

src/
  main.c              Entry point (MCP stdio server + CLI + install/update/config)
  daemon/             Per-account session coordination, IPC, lifecycle, shared jobs/watchers
  mcp/                MCP server (15 tools, JSON-RPC 2.0, session detection, auto-index)
  cli/                Install/uninstall/update/config (45 client surfaces, hooks, instructions)
  store/              SQLite graph storage (nodes, edges, traversal, search, Louvain)
  pipeline/           Multi-pass indexing (structure → definitions → calls → HTTP links → config → tests)
  cypher/             Cypher query lexer, parser, planner, executor
  discover/           File discovery (.gitignore, .cbmignore, symlink handling)
  watcher/            Background auto-sync (git polling, adaptive intervals)
  traces/             Runtime trace ingestion
  ui/                 Local HTTP server + verified external 3D-UI asset pack
  foundation/         Platform abstractions (threads, filesystem, logging, memory)
internal/cbm/         Vendored tree-sitter grammars (162 languages) + AST extraction engine

Security

Every release is verified through a multi-layer pipeline before publication:

  • VirusTotal — all 24 executable candidates (unstripped, debug-stripped and stripped) across the eight release products are scanned before smoke/soak (clean is preferred and only the single-Microsoft !ml tolerance documented in SECURITY.md may pass; the number of engines that returned a decisive result is recorded as evidence but is VirusTotal fleet availability, not a pass condition). The selected executable is packaged without changing its SHA-256, release notes link the verdict for the exact bytes shipped, and the full per-candidate evidence is published alongside the release as TSVs for anyone auditing the selection. Every distinct object extracted from the shipped containers — install.sh, install.ps1, LICENSE, THIRD_PARTY_NOTICES.md, the MCPB manifest.json and the unpacked UI assets — is then scanned as well, so the full published surface is covered, not just the executables.

  • SLSA Level 3 — cryptographic build provenance generated by the trusted GitHub Actions build workflow; verify with gh attestation verify <file> --repo DeusData/codebase-memory-mcp --signer-workflow DeusData/codebase-memory-mcp/.github/workflows/_build.yml

  • Sigstore cosign — keyless signatures on all artifacts; bundles included in every release

  • SHA-256 checksums — checksums.txt published with every release; verified by both install scripts before extraction

  • CodeQL SAST — blocks release pipeline if any open alerts remain

  • No language-runtime dependency chain — libraries are vendored at compile time; the small release-owned runtime assets are checksum-verified and content-addressed

v0.7.0 VirusTotal scans

Binary

SHA-256

VirusTotal

linux-amd64

8e12bb2d6ead7f20a6d3...

0/72 ✅

linux-arm64

10f7136bfbf3950c6b2a...

0/72 ✅

darwin-arm64

7062a7408906344bf4f8...

0/72 ✅

darwin-amd64

28c6d640e1a0ac7bfcab...

0/72 ✅

windows-amd64

9c3ddcf78368fd4fa891...

0/72 ✅

Scan links for every release are also included in the GitHub Release notes automatically.

License

MIT

Available Tools

15 tools
check_index_coverageCheck index coverageA
DestructiveIdempotent

Check authoritative indexing-coverage metadata for exact repository-relative paths and bounded path scopes. Use this after graph discovery for every cited or operated-on file; use scopes before negative/exhaustive claims because fully skipped files cannot appear in normal graph results. Returns coverage status separately from filesystem metadata freshness, plus structured parse-error ranges and direct-source fallback actions. The signal is best-effort: indexed_no_recorded_gap is not a completeness guarantee. At least one of 'paths' or 'scopes' is required; the call is rejected at runtime if both are omitted.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsNoRepository-relative files to check exactly. Required if 'scopes' is omitted.
scopesNoRepository-relative path prefixes; use . for the project root. Required if 'paths' is omitted.
projectYes
scope_limitNo
scope_offsetNo

TDQS

A3.6/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description contradicts the annotations. It presents this as a read-only metadata check ("Check authoritative indexing-coverage metadata", "Returns coverage status") and even notes the signal is best-effort and not a completeness guarantee. However, annotations declare destructiveHint: true and openWorldHint: false. The destructive flag implies side effects, and openWorldHint false contradicts the "not a completeness guarantee" caveat. These are serious inconsistencies that undermine trust.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-organized into four sentences. It front-loads the core purpose, then provides usage guidance, return-value summary, caveat, and runtime requirement. Every sentence adds unique value without redundant filler, and the length is appropriate for the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 params, no output schema), the description covers most operational needs: how to use, when to use, what is returned, and a critical caveat. It even names a specific status value (indexed_no_recorded_gap). However, it omits explanation of pagination (scope_limit/scope_offset) and the meaning of project, and the annotation contradictions weaken overall contextual completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is only 40% (paths and scopes have descriptions, project/scope_limit/scope_offset do not). The description adds important context about paths and scopes, such as requiring at least one and runtime rejection if both omitted. However, it does not explain project, scope_limit, or scope_offset, leaving pagination and required project identification undocumented. It partially compensates but not fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: "Check authoritative indexing-coverage metadata for exact repository-relative paths and bounded path scopes." It identifies the specific verb (check), resource (indexing-coverage metadata), and scope (paths/scopes), which distinguishes it from sibling tools like search_graph or index_repository.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides strong usage guidance: "Use this after graph discovery for every cited or operated-on file" and "use scopes before negative/exhaustive claims because fully skipped files cannot appear in normal graph results." It explains when to use scopes vs paths, but does not explicitly name alternative tools or state when not to use this tool, so it falls just short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_projectDelete projectC
DestructiveIdempotent

Delete a project from the index

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as destructive and idempotent, but the description adds no extra behavioral context—such as whether the deletion is permanent, what exactly gets removed, or side effects. It merely repeats the action without disclosing anything beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely brief and front-loaded, fitting for a simple tool. It wastes no words, though it could arguably add useful details in the same or slightly more space.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that this is a destructive operation with no output schema and a single undocumented parameter, the description is insufficient. It lacks usage guidance, parameter explanation, and behavioral detail, leaving the agent under-informed for safe invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has a single 'project' parameter with 0% description coverage, and the tool description does not clarify what a valid value looks like (e.g., name, ID, path). The word 'project' is repeated without adding semantic meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (delete) and the resource (a project from the index). It is specific and distinguishes itself from sibling tools such as list_projects and index_repository by naming the deletion effect.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, prerequisites, or consequences. The description simply restates the action without context about appropriate scenarios or caveats.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

detect_changesDetect changesA
DestructiveIdempotent

Map a git diff to its BLAST RADIUS. Resolves changed files to the symbols they define, then runs ONE multi-source graph traversal to the transitive impact set. RESPONSE: base + merge_base SHA, changed_files list, then impacted = prefix-grouped tree rows (name label hop; full qn = group prefix + dot + name) + an impacted_modules rollup; impacted_total + truncated are exact. Seeds (the changed symbols) are excluded from impacted; a changed file reached from another changed file is not counted as extra impact. format="json" returns the same model as structured JSON.

ParametersJSON Schema
NameRequiredDescriptionDefault
depthNoMax traversal hops from the changed symbols.
limitNoPer-symbol impacted rows shown (nearest hops first). impacted_total is always exact and the impacted_modules rollup always complete regardless.
scopeNofiles: changed files only (no traversal). impact (default): files + the transitive impact set.
sinceNoGit ref or tag to compare from (e.g. HEAD~5, v0.5.0). Diffs <ref>...HEAD.
formatNotree
projectYes
directionNoinbound (default) = the blast radius: transitive CALLERS of the changed symbols. outbound = what the changed code depends on. both = union.inbound
base_branchNomain

TDQS

A3.5/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description consistently describes a read-only analysis operation ('Map', 'Resolves', 'runs... traversal', 'RESPONSE') with no mention of any side effects. This directly contradicts the annotations readOnlyHint=false and destructiveHint=true, which imply a destructive, non-read-only operation. Since the description gives no clue about what might be destructive, it is a serious annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but entirely purposeful. It starts with a clear purpose statement and then packs essential behavioral details—output shape, exact counts, seed exclusion, and JSON format behavior—without redundant phrasing or filler. Every clause adds value for a tool with this complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description thoroughly covers the output model, including base/merge_base SHA, changed_files, impacted tree rows, rollup, exact counts, and seed exclusion. However, it omits any mention of the destructive side effect implied by annotations, and it does not explain the required project parameter or the base_branch semantics. Given the annotation mismatch, the description is not fully complete for safe and correct usage.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 63%, and most parameters (depth, limit, scope, format, direction) are already documented in the schema. The description adds useful detail about format='json' returning the same model and explains the response structure, but it does not clarify remaining parameters like project, since, or base_branch beyond the schema. Overall, it supplements the schema without fully compensating for the gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Map a git diff to its BLAST RADIUS', a specific verb-plus-resource statement that clearly identifies the tool's purpose. It further explains the process of resolving changed files to symbols and performing a multi-source graph traversal, distinguishing it from sibling graph/search tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context on how to use the tool via the scope parameter (files vs impact) and direction parameter (inbound/outbound/both), but it does not explicitly name sibling tools as alternatives or state when not to use this tool. This is clear context without explicit exclusions or comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_architectureGet architectureA
DestructiveIdempotent

Get high-level architecture overview. DEFAULT (no aspects) is a compact summary — overview counts, languages, packages, entry_points; request more via aspects:[...] (structure, dependencies, routes, hotspots, boundaries, layers, clusters, file_tree) or ["all"]. 'clusters' runs Leiden community detection over the call/import graph, surfacing the de-facto modules (label, member count, cohesion score, representative top_nodes, binding packages/edge_types) — the real architectural seams, which often cut across the folder layout. Optional path scopes analysis to nodes under that directory prefix (file_path).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoOptional directory prefix to scope architecture (e.g. apps/hoa)
aspectsNoAspects to include. 'all' = everything; 'overview' = compact summary (all except file_tree); omit = all. 'cycles' is opt-in ONLY (never via all/overview): it scans the whole call graph for circular CALLS dependencies (SCCs of size > 1).
projectYes

TDQS

A3.7/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description describes a read-only analysis tool, but annotations mark destructiveHint:true and readOnlyHint:false. This is a direct contradiction, as the description never mentions any destructive or mutating behavior. Per the rubric, this scores 1.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Every sentence adds value: it front-loads the core purpose, then efficiently explains defaults, aspects, clusters, and path scoping. There is no filler; the length is justified by the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the most important behaviors: defaults, aspect selection, cluster specifics, path scoping, and cycles. Given the tool's complexity and lack of output schema, it could benefit from describing typical return structure, but it provides enough detail for a high-level overview tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds substantial meaning beyond the schema: it explains the default behavior when no aspects are provided, the semantics of each aspect (especially clusters with its algorithm and output fields), optional path scoping, and the opt-in nature of cycles. This far exceeds the brief schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Get high-level architecture overview,' a specific verb+resource statement. It clearly explains the tool's purpose and contrasts with siblings by focusing on architecture analysis rather than graph queries or code snippets.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when an architecture overview is needed and details how to request aspects, but it does not explicitly state when to use this tool over alternatives or provide exclusions. The context is clear but lacks direct alternative differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_code_snippetGet code snippetA
DestructiveIdempotent

Read source code for a function/class/symbol. IMPORTANT: First call search_graph to find the exact qualified_name, then pass it here. This is a read tool, not a search tool. Accepts full qualified_name (exact match) or short function name (returns suggestions if ambiguous). If the response carries a 'coverage_note', the file was only partially indexed — constructs in the noted line ranges may be missing from the graph (best-effort signal); prefer grep there and treat the returned source as ground truth.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYes
qualified_nameYesFull qualified_name from search_graph, or short function name
include_neighborsNo

TDQS

A3.8/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotation contradiction: The description claims 'This is a read tool' (implying safe, non-destructive) while annotations set readOnlyHint=false and destructiveHint=true. This directly contradicts the description's behavioral claim.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact yet dense, with the purpose front-loaded, followed by a critical workflow instruction and an important caveat. Every sentence earns its place without fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main workflow, ambiguous-name handling, and the coverage_note partial-indexing signal. However, it omits details about include_neighbors behavior and return format, and the destructive annotation contradiction undermines completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 33%, but the description adds meaning for qualified_name by explaining it can be a full qualified name or short name and that ambiguity yields suggestions. However, it says nothing about project or include_neighbors, which are undocumented in the schema and require clarification.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'Read source code for a function/class/symbol' — a specific verb and resource. It explicitly distinguishes itself from search tools ('This is a read tool, not a search tool') and references the sibling workflow with search_graph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides explicit usage instructions: 'First call search_graph to find the exact qualified_name, then pass it here.' Also gives when-not-to-use guidance ('not a search tool') and a fallback recommendation to use grep when coverage_note is present.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_graph_schemaGet graph schemaC
DestructiveIdempotent

Get the schema of the knowledge graph (node labels, edge types)

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYes

TDQS

C2.7/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations include destructiveHint=true, which directly contradicts the description's 'Get' implying a read-only operation. The description does not disclose any destructive behavior, creating an annotation contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, front-loaded with the verb and object, and the parenthetical adds relevant detail without waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is minimal and, given the contradictory annotations and undocumented parameter, insufficient for correct invocation. It hints at the return content but lacks guidance on the 'project' parameter and does not address the destructive hint.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has one required 'project' parameter with zero description coverage. The tool description does not explain what 'project' refers to or how it affects the schema retrieval, leaving the agent to guess.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the action (get), resource (knowledge graph schema), and scope (node labels, edge types), distinguishing it from sibling tools like search_graph or get_code_snippet.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, nor any prerequisites or conditions. The description simply states what it does without context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_repositoryIndex repositoryA
Idempotent

Index a repository into the knowledge graph. Special mode 'cross-repo-intelligence': skip extraction, only match Routes/Channels across projects to create CROSS_HTTP_CALLS/CROSS_ASYNC_CALLS/CROSS_CHANNEL edges. Requires target_projects param. Ensure target projects have fresh indexes first. COVERAGE: the response reports files that were NOT fully indexed — 'skipped' (not indexed at all: oversized/read/parse failures) and 'parse_partial' (indexed, but constructs inside the listed line ranges could not be parsed and MAY be missing from the graph). The embedded lists carry counts plus a FEW EXAMPLES only; the complete lists are in the per-run 'logfile' (path in the response) and queryable any time via index_status or structurally via query_graph(graph="missed"). Both signals are best-effort: absence of a flag is NOT a completeness guarantee; prefer grep inside flagged ranges. Separately, 'excluded' + 'not_indexed_files' list what was deliberately NOT indexed (gitignore/.cbmignore/skip-lists) — by design, not failures.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoAll modes run type-aware LSP call/usage resolution (per-file + cross-file). full: all files + similarity/semantic edges. moderate: filtered files + similarity/semantic. fast: filtered files, no similarity/semantic. cross-repo-intelligence: match Routes/Channels across projects.full
nameNoOverride the derived project name. Non-ASCII bytes are encoded and unsafe path characters are normalized.
repo_pathYesPath to the repository
persistenceNoWrite compressed artifact to .codebase-memory/graph.db.zst for team sharing. Teammates can bootstrap from the artifact instead of full re-indexing.
target_projectsNoProjects to search for cross-repo links (cross-repo-intelligence mode). Use ["*"] for all indexed projects. Run list_projects to see available projects.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes far beyond annotations by explaining coverage reporting (skipped, parse_partial, excluded), best-effort nature of flags, where complete lists reside (logfile, index_status, query_graph), and what counts as a failure vs. by-design exclusion. This adds rich behavioral context that annotations (idempotentHint, readOnlyHint) do not provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence adds value—covering main action, special mode, coverage interpretation, and exclusion semantics. It is organized with clear labels ('COVERAGE:', 'excluded') and front-loads the primary verb. Slightly verbose, but not wasteful given the tool's complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite no output schema, the description fully compensates by detailing what the response contains (skipped/parse_partial lists, logfile path), how to query missed items, and what constitutes deliberate exclusion. It addresses failure modes, best-effort caveats, and cross-project prerequisites, making it complete for a complex indexing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but the description enhances parameter meaning: it explains the cross-repo-intelligence prerequisite for target_projects, clarifies mode behavior beyond enum values, and describes persistence artifact usage. It stops short of defining every param's exact syntax but meaningfully supplements the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a clear, specific verb+resource: 'Index a repository into the knowledge graph.' It also details a special mode ('cross-repo-intelligence') with its distinct purpose, distinguishing this ingestion tool from query/read siblings like search_graph or index_status.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to use the cross-repo-intelligence mode (requires target_projects, needs fresh indexes on target projects). It also implies general indexing workflow by describing mode variants and prerequisites, though it doesn't explicitly contrast with alternatives like detect_changes or check_index_coverage for refresh scenarios.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

index_statusIndex statusA
DestructiveIdempotent

Get the indexing status of a project: node/edge counts, root path, git context, and the indexing-COVERAGE report — which files the indexer could NOT fully cover (best-effort signal): 'parse_partial' files WERE indexed but contain line ranges tree-sitter could not parse — constructs there MAY be missing from the graph (some are still recovered); 'skipped' files were not indexed at all (oversized/read/parse failure). Use this before trusting graph completeness on a file: if a file is listed, ALSO grep it (especially the flagged ranges). IMPORTANT: absence from these lists is NOT a completeness guarantee — the signal only marks what the indexer can detect. For structural queries over the misses use query_graph(graph="missed"). The report also carries 'not_indexed' — files/dirs excluded BY DESIGN (gitignore/.cbmignore/skip-lists): deliberate and deterministic, not failures; change the ignore rules and re-index to include them.

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYes
verboseNoInclude the git context block (worktree/shadow path variants). Only needed when debugging where an index lives — omitted by default to keep the status lean.

TDQS

A4.1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description thoroughly explains the behavior of the coverage report and its limitations, but annotations declare destructiveHint: true while the description clearly describes a read-only status operation ('Get the indexing status'). This direct contradiction makes the tool's safety profile ambiguous, earning a score of 1.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Despite its length, every sentence delivers substantive information about the report's contents, caveats, and usage. The structure is logical and uses clear punctuation to separate concepts like 'parse_partial', 'skipped', and 'not_indexed'. No wasteful repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description provides a comprehensive explanation of the returned status report: counts, paths, git context, and detailed explanations of coverage categories. It also covers edge cases, limitations, and next steps, making it highly complete for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaningful semantics for the 'verbose' parameter ('Include the git context block... only needed when debugging where an index lives'), explaining its default omission. The 'project' parameter is self-explanatory from the tool's purpose. With 50% schema coverage, the description compensates well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Get the indexing status of a project' and details the exact information returned (node/edge counts, root path, git context, coverage report). It also distinguishes from sibling tools by mentioning query_graph for structural queries over misses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'Use this before trusting graph completeness on a file', instructs to 'ALSO grep it' if a file is listed, and directs structural queries to query_graph with graph='missed'. It also clarifies that 'not_indexed' files are intentional exclusions and how to include them via re-indexing.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ingest_tracesIngest tracesC

Ingest runtime traces to enhance the knowledge graph

ParametersJSON Schema
NameRequiredDescriptionDefault
tracesYes
projectYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations provide no positive safety hints (readOnlyHint, idempotentHint, destructiveHint all false). The description tells us the tool modifies the knowledge graph but omits side effects, idempotency, whether existing traces are replaced or merged, or any required prior state. Since the description adds little beyond what the annotations already imply (a write operation), transparency is low.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence and not bloated, but it is under-specified. 'Ingest runtime traces to enhance the knowledge graph' is concise yet lacks the contextual substance needed for effective tool selection and invocation.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the two-parameter input with nested objects and no output schema, the description is far from complete. It does not explain trace structure, project identification, expected effects, or how this tool relates to index_repository or trace_path. The absence of return-value details further reduces completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the description does not mention the 'traces' or 'project' parameters at all. It offers no guidance on what format the trace objects should take or how the project parameter is used, leaving the agent to infer meaning solely from parameter names.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('ingest'), resource ('runtime traces'), and intended effect ('enhance the knowledge graph'). It distinguishes the tool from pure read/search siblings like search_graph or query_graph, though it does not explicitly differentiate from the closely related index_repository, which also enhances the graph.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives such as index_repository or trace_path. The phrase 'runtime traces' implies a use case, but there are no explicit when/when-not conditions, prerequisites, or links to sibling tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_projectsList projectsA
Read-onlyIdempotent

List all indexed projects

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, establishing the safety profile. The description adds no additional behavioral context such as output format, pagination, or potential side effects, so it contributes nothing beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that states the exact function without any extraneous words. It is concise and well-structured for a simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, the presence of thorough annotations, and the self-explanatory name, the description is mostly complete. However, without an output schema, it does not specify the shape or content of the returned list, which leaves a minor gap for an agent expecting detailed output.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters and zero required fields, so the input schema is empty. According to the rubric, a tool with no parameters receives a baseline of 4. The description appropriately indicates no parameters are needed, and nothing further is required.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'List all indexed projects' uses a specific verb and resource, clearly indicating it enumerates projects that have been indexed. It distinguishes itself from sibling tools like index_repository (which creates an index) and search_graph (which queries), leaving no ambiguity about its function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to choose this tool over alternatives. It does not mention use cases, prerequisites, or exclusions that would help an agent decide between list_projects and other tools such as index_status or check_index_coverage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

manage_adrManage ADRC
Destructive

Create or update Architecture Decision Records

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNoupdate replaces the entire ADR document; sections only lists existing headings
contentNoComplete replacement document required by update
projectYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare destructiveHint=true, so the agent knows it is a destructive operation. But the description adds little behavioral detail, failing to disclose that 'update' replaces the entire ADR document or that get/sections are read-only modes. This underdiscloses the tool's full behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise, front-loaded sentence with no wasted words. While it is under-specified for the tool's complexity, that is a completeness issue, not a conciseness issue.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is insufficient for a tool with three parameters, an enum, no output schema, and destructive behavior. It omits the get/sections modes, the full-replacement semantic of update, and any usage context. The schema provides some help, but the description should give a more complete overview.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 67% of parameters (mode and content), which is decent. The tool description adds no additional parameter semantics, so the baseline of 3 applies; it does not compensate for the undocumented 'project' parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description identifies the tool as managing Architecture Decision Records with the verbs 'Create or update', which is specific and distinguishes it from sibling tools like get_architecture. However, it omits the 'get' and 'sections' modes present in the schema, making the purpose statement incomplete.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. There is no mention of scenarios, prerequisites, or exclusions, leaving the agent to infer usage from the schema alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_graphQuery graphA
DestructiveIdempotent

Execute a Cypher query against the knowledge graph for complex multi-hop patterns, aggregations, and cross-service analysis. The response includes 'total' (returned row count). There is a hard 100k row ceiling — for broad queries add LIMIT in the Cypher itself or use search_graph + offset/limit pagination instead. COMPLEXITY / BOTTLENECKS: every Function and Method node carries queryable complexity properties — cyclomatic (complexity), cognitive, loop_count, loop_depth (max nested-loop depth, a polynomial-degree proxy), plus interprocedural transitive_loop_depth (worst-case nested-loop degree propagated along CALLS edges) and a recursive flag. Additional hot-path signals: linear_scan_in_loop (count of find/contains/indexOf-style scans inside a loop — the hidden O(n^2) that loop_depth misses), alloc_in_loop (allocations/appends inside a loop), recursion_in_loop (a self-call inside a loop), unguarded_recursion (recursion with no conditionally-guarded base case), param_count and max_access_depth (structure smells). Find all hot-path candidates in one query, e.g. MATCH (f:Function) WHERE f.transitive_loop_depth >= 3 OR f.linear_scan_in_loop >= 1 RETURN f.qualified_name, f.transitive_loop_depth, f.linear_scan_in_loop ORDER BY f.transitive_loop_depth DESC. MISSED GRAPH: pass graph="missed" to query the best-effort miss graph instead — the file structure of ONLY the files the indexer could NOT fully index (Project → Folder → File nodes with CONTAINS_FOLDER/CONTAINS_FILE edges; each File carries kind ("parse_partial" = indexed but constructs in the flagged line ranges MAY be missing; or a skip phase) and detail (the line ranges / reason)). Example: MATCH (f:File) WHERE f.kind = "parse_partial" RETURN f.file_path, f.detail. Absence from this graph is NOT a completeness guarantee.

ParametersJSON Schema
NameRequiredDescriptionDefault
graphNoWhich graph to query: the code knowledge graph (default) or the missed graph (only files not fully indexed, laid out as their file structure).code
queryYesCypher query
projectYes
max_rowsNoOptional row limit. Default: unlimited up to a 100k row ceiling. No offset support — use search_graph for paginated browsing.

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds substantial behavioral context beyond annotations: the 100k row ceiling, node complexity properties (cyclomatic, cognitive, nested-loop depth, etc.), hot-path signals, and the semantics of the missed graph with its caveat about completeness. This is rich operational detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured and every sentence contributes value: purpose, response shape, row limit, complexity properties, missed graph semantics, and examples. It uses headers and a readable flow, making it dense but not verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity, the description is highly complete. It covers usage scenarios, limitations, alternative tools, graph variants, example queries, and the returned 'total' count. There is no output schema, but the description gives enough context with query examples and response details to guide invocation effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 75%, and the description significantly enriches the graph parameter by explaining the missed graph structure and its purpose, and clarifies max_rows behavior (no offset, 100k ceiling). It also provides an example Cypher query demonstrating parameter usage, which adds depth beyond the schema fields, though some parameter-level detail (like query validation) is absent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a Cypher query against the knowledge graph for complex multi-hop patterns, aggregations, and cross-service analysis. It distinguishes itself from sibling search_graph by explicitly mentioning pagination alternatives and different use cases.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides explicit when-to-use guidance: complex patterns, aggregations, cross-service analysis. It also gives clear alternatives: use search_graph for paginated browsing or when row limits are exceeded, and explains when to use the missed graph. The 100k row ceiling is mentioned with mitigation instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_codeSearch codeA
DestructiveIdempotent

Graph-augmented code search. Finds text patterns via grep, then enriches results with the knowledge graph: deduplicates matches into containing functions, ranks by structural importance (definitions first, popular functions next, tests last). Modes: compact (default, signatures only — token efficient), full (source capped at a 60-line window around the first match per hit; source_truncated marks the cut — use get_code_snippet for the complete symbol), files (just file paths). Use path_filter regex to scope results. TRUNCATION: enriched results are capped at limit (default 10). Response carries 'total_grep_matches' (raw grep hit count) and 'total_results' (deduplicated function count) — compare to limit to detect truncation. There is no offset parameter; to see more, raise limit or narrow the query with file_pattern / path_filter.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNocompact: signatures+metadata (default). full: with source. files: just file list.compact
limitNoMax enriched results per call. Default 10. Response includes 'total_grep_matches' and 'total_results' so callers can detect truncation. No offset parameter — raise limit or narrow with file_pattern / path_filter to see more.
regexNo
contextNoLines of context around each match (like grep -C). Only used in compact mode.
patternYes
projectYes
path_filterNoRegex filter on result file paths (e.g. ^src/ or \.(go|ts)$)
file_patternNoGlob for grep --include (e.g. *.go)

TDQS

A3.9/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies a purely read-only search operation with no destructive or mutating effects. However, the annotations set `destructiveHint: true` and `readOnlyHint: false`, directly contradicting the described behavior. This is a serious inconsistency that misleads the agent about potential side effects, warranting a score of 1 per the annotation contradiction rule.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is densely packed with essential information without redundancy. It is logically structured from the core mechanism, to modes, to truncation/pagination, with every sentence contributing predictive value. Despite its length, it remains concise and front-loaded with the most critical traits.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given there is no output schema, the description thoroughly explains return-related details including `total_grep_matches`, `total_results`, and `source_truncated`, along with mode-specific output differences. It also covers edge cases like truncation, the lack of an offset, and the alternative `get_code_snippet` for complete source. For a complex tool, this is remarkably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description significantly enriches schema parameters by explaining mode semantics (compact/full/files and their use cases), limit & truncation behavior, and the `source_truncated` flag. It also clarifies that `context` only applies in compact mode and elaborates on `path_filter` and `file_pattern` beyond their schema descriptions. With 63% schema coverage, the description compensates well for any gaps, though `pattern` and `project` remain minimally described.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly identifies the tool as 'Graph-augmented code search' with a specific verb+resource combination. It distinguishes itself from siblings by detailing grep-based text pattern matching plus knowledge graph enrichment, and explicitly contrasts with get_code_snippet for retrieving complete source, making its unique purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear guidance on when to use each mode (compact for token efficiency, full for source windows, files for just paths) and recommends `get_code_snippet` when complete symbols are needed. It also advises using `path_filter` to scope results and explains how to handle truncation. While it doesn't explicitly contrast with sibling search tools like search_graph, the context and alternatives are well stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_graphSearch graphA
DestructiveIdempotent

Search the code knowledge graph for functions, classes, routes, and variables. Use INSTEAD OF grep/glob when finding code definitions, implementations, or relationships. Three search modes: (1) query='update settings' for BM25 ranked full-text search with camelCase splitting and structural label boosting — recommended for natural-language discovery; (2) name_pattern='.regex.' for exact pattern matching; (3) semantic_query=[...] for vector cosine search that bridges vocabulary (finds 'publish' when you search 'send'). The three modes are independent and can be combined in a single call. RESPONSE: prefix-grouped tree rows by default — a shared (qn-prefix, file) group header printed once, then name label lines in out per row (full qn = group prefix + dot + name). in/out = selected degree across CALLS, USAGE, CALL_REFERENCE, INHERITS, and IMPLEMENTS; other edge types are excluded. These are NOT caller/callee counts — use trace_path for callers. Add per-node property columns via fields (e.g. ["complexity","signature","docstring"]); format="json" returns the SAME tree model as structured JSON. PAGINATION: results are capped at limit (default 50). The response always includes 'total' (full match count before limit) and 'has_more' (true when total > offset+returned). Detect truncation with has_more, then page by re-calling with offset=offset+limit until has_more is false. Narrow first via label/file_pattern/min_degree before paginating large result sets.

ParametersJSON Schema
NameRequiredDescriptionDefault
labelNo
limitNoMax results per call. Default 50. Response carries 'total' (full match count) and 'has_more' (true if truncated) so callers can detect the limit and paginate.
queryNoNatural-language or keyword full-text search using BM25 ranking. Tokens are split on whitespace; camelCase identifiers are indexed as individual words (updateCloudClient → update, cloud, client). Results are ranked with structural boosting: Functions/Methods +10, Routes +8, Classes/Interfaces +5. Noise labels (File/Folder/Module/Variable) are filtered out. When provided, name_pattern is ignored.
detailNoids: bare qualified-name enumeration (one column) — cheapest form for wide sweeps where per-row metadata is noise. default: full rows.default
fieldsNoExtra per-node property columns, e.g. complexity, cognitive, signature, docstring, return_type, is_test, lines(int). Core row columns (qn/label/file/lines/in/out) are always present — do not request them here. Missing values emit as empty cells.
formatNoResponse encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays).tree
offsetNoSkip the first N matching nodes. Combine with 'limit' to page: increment offset by limit and re-call while has_more is true.
projectYes
max_degreeNo
min_degreeNo
qn_patternNo
file_patternNo
name_patternNo
relationshipNo
semantic_queryNoMUST be an ARRAY of keyword strings (e.g. ["send","pubsub","publish"]) — NOT a single string. Each keyword is scored independently via per-keyword min-cosine; results reflect functions that score well on ALL keywords. Requires moderate/full index mode. Results appear in the 'semantic_results' field (separate from 'results').
include_connectedNo
exclude_entry_pointsNo

TDQS

A4.2/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations include destructiveHint: true and readOnlyHint: false, but the description describes a pure search tool with no mention of any destructive side effects or mutation. This is a contradiction between the description's implied read-only nature and the annotation's destructive flag.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but well-structured: it front-loads the core purpose, then details search modes, response format, and pagination. Every sentence carries useful information, and the structure aids comprehension for a complex tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 17 parameters and no output schema, the description fully explains the response tree model, column meanings, edge types, and pagination with total/has_more. It also gives practical guidance on narrowing results. This is complete for a tool of this complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is only 41%, but the description compensates by explaining query's BM25 ranking and camelCase splitting, name_pattern regex, semantic_query as an array, fields usage, format options, and pagination semantics. This adds substantial meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it searches the code knowledge graph for functions, classes, routes, and variables. It distinguishes itself from grep/glob and explicitly mentions using trace_path for callers, making the purpose and scope unmistakable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use INSTEAD of grep/glob...' and later states 'These are NOT caller/callee counts — use trace_path for callers.' This gives both when-to-use and when-not-to-use guidance, plus advice to narrow via label/file_pattern/min_degree.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

trace_pathTrace pathA
DestructiveIdempotent

Trace paths through the code graph. Modes: calls (callers/callees), data_flow (value propagation with args at each hop), cross_service (through HTTP/async Route nodes). Use INSTEAD OF grep for callers, dependencies, impact analysis, or data flow tracing. RESPONSE: prefix-grouped tree rows — callees/callers grouped under their shared qn-prefix, name hop per row (full qn = group prefix + dot + name); exact callees_total/callers_total on every page = ALL nodes reachable within depth (transitive, not just direct; test files excluded unless include_tests). risk/args flags use a flat table. truncated: true + next = more rows — pass next back as cursor. format="json" returns the SAME tree model as structured JSON.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeNocalls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes, plus CROSS_* cross-repo edges (CROSS_HTTP_CALLS/ASYNC_CALLS/CHANNEL/GRPC_CALLS/GRAPHQL_CALLS/TRPC_CALLS) to hop into other services.calls
depthNo
limitNoRows per page. callees_total/callers_total always carry the exact full counts; when a page is truncated the response carries next — see cursor.
cursorNoResume token from a previous response's 'next' field. Pass it back with ALL other arguments identical to get the following page with no duplicates. Cursors outlive nothing: after a reindex you get a stale_cursor error — just re-run the original query.
formatNoResponse encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays).tree
projectYes
directionNoboth
edge_typesNo
risk_labelsNoAdd risk classification (CRITICAL/HIGH/MEDIUM/LOW) based on hop distance
function_nameYes
include_testsNoInclude test files in results. When false (default), test files are filtered out. When true, test nodes are included with a test column/marker.
parameter_nameNoFor data_flow mode: scope trace to a specific parameter name
include_evidenceNoAdd how each hop was resolved: a strategy class (lsp | language_rule | heuristic | unresolved) and the resolver's confidence. Off by default — it adds two columns per row. Use it to judge whether an edge is trustworthy, not to find edges.

TDQS

A3.9/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotation Contradiction. The annotations declare destructiveHint: true and readOnlyHint: false, while the description details a pure query/traversal operation (trace paths, follow edges, return rows) with zero mention of writes, deletions, or side effects. The description contradicts the destructive flag outright, and although it discloses rich response behavior, the metadata mismatch is disqualifying.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a dense single block but front-loads the core purpose and every sentence contributes (modes, usage, response format, totals, pagination, json parity). It could benefit from line breaks to improve scannability, but there is no filler or redundancy for a tool of this complexity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly bears the burden of explaining return values, and it does thoroughly: prefix grouping, hop format, transitive totals, flat risk/args tables, truncation/next, and JSON equivalence. Gaps remain, such as the behavior of the undocumented edge_types parameter, direction semantics in data_flow mode, and depth bounds, so it is not fully complete for a 13-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 62%, and the description adds meaningful semantics beyond the schema: it explains the prefix-grouped tree model, that callees_total/callers_total are transitive within depth, that test files are excluded unless include_tests, and that cursor must be passed back for pagination. It does not illuminate vague params like edge_types or direction, but it substantially enriches the meaning of mode, depth, limit, cursor, and format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb+resource: 'Trace paths through the code graph.' It then enumerates three distinct modes (calls, data_flow, cross_service) with concrete behaviors, and the 'INSTEAD OF grep' note separates it from sibling tools like search_code. This is precise and distinguishing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

'Use INSTEAD OF grep for callers, dependencies, impact analysis, or data flow tracing' is explicit when-to-use guidance with a clear exclusion of the grep-like alternative. It gives the agent a decision rule for tool selection without ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 15 tool updatesv0.10.4
    • Changedcheck_index_coverage4 fields changed
      • removedInput schema / anyOf
        [
  {
    "required": [
      "paths"
    ]
  },
  {
    "required": [
      "scopes"
    ]
  }
]
      • changedInput schema / properties / paths / description
        Before
        "Repository-relative files to check exactly."
        After
        "Repository-relative files to check exactly. Required if 'scopes' is omitted."
      • changedInput schema / properties / scopes / description
        Before
        "Repository-relative path prefixes; use . for the project root."
        After
        "Repository-relative path prefixes; use . for the project root. Required if 'paths' is omitted."
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changeddelete_project1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changeddetect_changes1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedget_architecture1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedget_code_snippet1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedget_graph_schema1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedindex_repository1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedindex_status1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedingest_traces1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedlist_projects1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedmanage_adr1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedquery_graph1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedsearch_code2 fields changed
      • addedInput schema / properties / limit / minimum
        1
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedsearch_graph1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
    • Changedtrace_path1 field changed
      • changedOutput schema / (root)
        Before
        {
  "additionalProperties": true,
  "type": "object"
}
        After
        null
  2. 11 tool updatesv0.10.0
    • Addedcheck_index_coverage
    • Addeddelete_project
    • Addeddetect_changes
    • Changedget_architecture2 fields changed
      • changedInput schema / properties / aspects / description
        Before
        "Aspects to include. 'all' = everything; 'overview' = compact summary (all except file_tree); omit = all."
        After
        "Aspects to include. 'all' = everything; 'overview' = compact summary (all except file_tree); omit = all. 'cycles' is opt-in ONLY (never via all/overview): it scans the whole call graph for circular CALLS dependencies (SCCs of size > 1)."
      • changedInput schema / properties / aspects / items / enum
        Before
        [
  "all",
  "overview",
  "structure",
  "dependencies",
  "routes",
  "languages",
  "packages",
  "entry_points",
  "hotspots",
  "boundaries",
  "layers",
  "file_tree",
  "clusters"
]
        After
        [
  "all",
  "overview",
  "structure",
  "dependencies",
  "routes",
  "languages",
  "packages",
  "entry_points",
  "hotspots",
  "boundaries",
  "layers",
  "file_tree",
  "clusters",
  "cycles"
]
    • Addedindex_status
    • Addedingest_traces
    • Addedlist_projects
    • Addedmanage_adr
    • Changedquery_graph1 field changed
      • addedInput schema / properties / graph
        {
  "default": "code",
  "description": "Which graph to query: the code knowledge graph (default) or the missed graph (only files not fully indexed, laid out as their file structure).",
  "enum": [
    "code",
    "missed"
  ],
  "type": "string"
}
    • Changedsearch_graph4 fields changed
      • addedInput schema / properties / detail
        {
  "default": "default",
  "description": "ids: bare qualified-name enumeration (one column) — cheapest form for wide sweeps where per-row metadata is noise. default: full rows.",
  "enum": [
    "ids",
    "default"
  ],
  "type": "string"
}
      • addedInput schema / properties / fields
        {
  "description": "Extra per-node property columns, e.g. complexity, cognitive, signature, docstring, return_type, is_test, lines(int). Core row columns (qn/label/file/lines/in/out) are always present — do not request them here. Missing values emit as empty cells.",
  "items": {
    "type": "string"
  },
  "type": "array"
}
      • addedInput schema / properties / format
        {
  "default": "tree",
  "description": "Response encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays).",
  "enum": [
    "tree",
    "json"
  ],
  "type": "string"
}
      • changedInput schema / properties / limit / description
        Before
        "Max results per call. Default 200. Response carries 'total' (full match count) and 'has_more' (true if truncated) so callers can detect the limit and paginate."
        After
        "Max results per call. Default 50. Response carries 'total' (full match count) and 'has_more' (true if truncated) so callers can detect the limit and paginate."
    • Changedtrace_path5 fields changed
      • addedInput schema / properties / cursor
        {
  "description": "Resume token from a previous response's 'next' field. Pass it back with ALL other arguments identical to get the following page with no duplicates. Cursors outlive nothing: after a reindex you get a stale_cursor error — just re-run the original query.",
  "type": "string"
}
      • addedInput schema / properties / format
        {
  "default": "tree",
  "description": "Response encoding. tree (default): prefix-grouped text rows. json: the SAME tree model as structured JSON (groups + column-ordered row arrays).",
  "enum": [
    "tree",
    "json"
  ],
  "type": "string"
}
      • addedInput schema / properties / include_evidence
        {
  "default": false,
  "description": "Add how each hop was resolved: a strategy class (lsp | language_rule | heuristic | unresolved) and the resolver's confidence. Off by default — it adds two columns per row. Use it to judge whether an edge is trustworthy, not to find edges.",
  "type": "boolean"
}
      • changedInput schema / properties / include_tests / description
        Before
        "Include test files in results. When false (default), test files are filtered out. When true, test nodes are included with is_test=true marker."
        After
        "Include test files in results. When false (default), test files are filtered out. When true, test nodes are included with a test column/marker."
      • addedInput schema / properties / limit
        {
  "default": 100,
  "description": "Rows per page. callees_total/callers_total always carry the exact full counts; when a page is truncated the response carries next — see cursor.",
  "maximum": 5000,
  "minimum": 1,
  "type": "integer"
}
  3. 14 tool updatesv0.9.0
    • Removeddelete_project
    • Removeddetect_changes
    • Changedget_architecture4 fields changed
      • addedInput schema / properties / aspects / description
        "Aspects to include. 'all' = everything; 'overview' = compact summary (all except file_tree); omit = all."
      • addedInput schema / properties / aspects / items / enum
        [
  "all",
  "overview",
  "structure",
  "dependencies",
  "routes",
  "languages",
  "packages",
  "entry_points",
  "hotspots",
  "boundaries",
  "layers",
  "file_tree",
  "clusters"
]
      • addedInput schema / properties / path
        {
  "description": "Optional directory prefix to scope architecture (e.g. apps/hoa)",
  "type": "string"
}
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Changedget_code_snippet1 field changed
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Changedget_graph_schema1 field changed
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Changedindex_repository2 fields changed
      • addedInput schema / properties / name
        {
  "description": "Override the derived project name. Non-ASCII bytes are encoded and unsafe path characters are normalized.",
  "type": "string"
}
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Removedindex_status
    • Removedingest_traces
    • Removedlist_projects
    • Removedmanage_adr
    • Changedquery_graph1 field changed
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Changedsearch_code1 field changed
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Changedsearch_graph1 field changed
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
    • Changedtrace_path2 fields changed
      • changedInput schema / properties / mode / description
        Before
        "calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes."
        After
        "calls: follow CALLS edges. data_flow: follow CALLS+DATA_FLOWS with arg expressions. cross_service: follow HTTP_CALLS+ASYNC_CALLS+DATA_FLOWS through Routes, plus CROSS_* cross-repo edges (CROSS_HTTP_CALLS/ASYNC_CALLS/CHANNEL/GRPC_CALLS/GRAPHQL_CALLS/TRPC_CALLS) to hop into other services."
      • changedOutput schema / (root)
        Before
        null
        After
        {
  "additionalProperties": true,
  "type": "object"
}
  4. 14 tool updatesv1.0.0
    • First observeddelete_project
    • First observeddetect_changes
    • First observedget_architecture
    • First observedget_code_snippet
    • First observedget_graph_schema
    • First observedindex_repository
    • First observedindex_status
    • First observedingest_traces
    • First observedlist_projects
    • First observedmanage_adr
    • First observedquery_graph
    • First observedsearch_code
    • First observedsearch_graph
    • First observedtrace_path
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation4/5

Most tools have clearly distinct purposes, but search_graph and search_code both serve code search, and index_status vs check_index_coverage have related coverage-reporting functions. The detailed descriptions help mitigate ambiguity, so only a couple of pairs could potentially be confused.

Naming Consistency4/5

The naming generally follows a verb_noun pattern (e.g., search_graph, query_graph, trace_path, delete_project). However, index_status is a noun phrase rather than verb-first, and manage_adr is somewhat vague, creating minor deviations from the dominant pattern.

Tool Count5/5

With 15 tools, the server is at the upper end of the ideal range but every tool addresses a distinct need for code intelligence: indexing, search, graph querying, tracing, impact analysis, and project management. The count feels well-scoped for the broad domain.

Completeness4/5

The server covers the full lifecycle for code indexing and querying: create (index_repository), read (search_graph, get_code_snippet, query_graph), update (ingest_traces, index_repository re-index), and delete (delete_project). Minor gaps include no dedicated tool for reading ADRs (only create/update) and no explicit fine-grained re-index command, but these are workable via existing tools.

Maintenance

ActivityActive
ResponsivenessWithin a week

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • trace-mcp

    nikolai-vysotskyi
    A
    license
    A
    quality
    A
    maintenance
    Framework-aware code intelligence MCP server that builds a cross-language dependency graph from source code. 53 integrations (Laravel, Django, Rails, Spring, NestJS, Next.js, and more) across 68 languages. 100+ tools for navigation, impact analysis, refactoring, security scanning, session memory, and CI/PR reports — up to 97% token reduction.
    28
    5,033
    102
    MIT

  • Orihime

    srinivasan-sundaresan95
    A
    license
    A
    quality
    C
    maintenance
    Cross-repository code knowledge graph MCP server for Java, Kotlin, JavaScript, and TypeScript. Indexes source code into embedded KuzuDB via tree-sitter and exposes 30+ tools for call-flow tracing, multi-hop taint analysis (OWASP/CWE/PCI/STIG), entry-point reachability filtering, performance hotspot detection, and license compliance — without reading source files. 95% fewer tokens vs source-read
    33
    1
    MIT

  • code-graph-mcp

    sdsrss
    A
    license
    Not graded
    quality
    A
    maintenance
    A high-performance code knowledge graph server implementing MCP, indexing codebases into a structured AST knowledge graph with semantic search, call graph traversal, and HTTP route tracing.
    3,126
    72
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/DeusData/codebase-memory-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server