{
"markdown": "# codebase-memory-mcp\n\n[](https://github.com/DeusData/codebase-memory-mcp/releases/latest)\n[](LICENSE)\n[](https://github.com/DeusData/codebase-memory-mcp/actions/workflows/dry-run.yml)\n[](https://github.com/DeusData/codebase-memory-mcp)\n[](https://github.com/DeusData/codebase-memory-mcp)\n[](#hybrid-lsp)\n[](https://github.com/DeusData/codebase-memory-mcp)\n[](https://github.com/DeusData/codebase-memory-mcp)\n[](https://github.com/DeusData/codebase-memory-mcp/releases/latest)\n[](https://scorecard.dev/viewer/?uri=github.com/DeusData/codebase-memory-mcp)\n[](https://slsa.dev)\n[](https://github.com/DeusData/codebase-memory-mcp/releases/latest)\n[](https://arxiv.org/abs/2603.27277)\n\n**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.\n\nHigh-quality parsing through [tree-sitter](https://tree-sitter.github.io/tree-sitter/) AST analysis across all 162 languages, enhanced with [**Hybrid LSP** semantic type resolution](#hybrid-lsp) 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.\n\n> **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*](https://arxiv.org/abs/2603.27277) (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.\n\n> **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](https://github.com/DeusData/codebase-memory-mcp). 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](SECURITY.md#our-release-policy). All processing happens 100% locally; your code never leaves your machine. Found a security issue? We want to know — see [SECURITY.md](SECURITY.md). Security is Priority #1 for us.\n\n
\n \n \n Built-in 3D graph visualization — explore your knowledge graph at localhost:9749\n
\n\n## Why codebase-memory-mcp\n\n- **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.\n- **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.\n- **162 languages** — vendored tree-sitter grammars compiled into the binary. Nothing to install, nothing that breaks.\n- **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.\n- **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](#multi-agent-support) for the complete matrix and manual/UI-only boundaries.\n- **Built-in graph visualization** — 3D interactive UI at `localhost:9749`, served from the binary itself.\n- **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.\n- **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.\n\n## Quick Start\n\n**One-line install** (macOS / Linux):\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash\n```\n\nWith graph visualization UI:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash\n```\n\n**Windows** (PowerShell):\n```powershell\n# 1. Download the installer\nInvoke-WebRequest -Uri https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.ps1 -OutFile install.ps1\n\n# 2. (Optional but recommended) Inspect the script\nnotepad install.ps1\n\n# 3. Unblock the downloaded file (removes Mark-of-the-Web restriction added by browsers/Invoke-WebRequest)\nUnblock-File .\\install.ps1\n\n# 4. Run it\n.\\install.ps1\n\n```\n\n> **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`.\n\nOptions: `--skip-config` (binary only, no agent setup), `--dir=` (custom location).\n\n> **Antivirus note:** Microsoft Defender may flag a release binary as\n> `Trojan:Script/Wacatac.B!ml`. This is a known false positive — typically 61 of\n> ~62 engines return clean, and the same detection family hits `gh`, llama.cpp,\n> Godot and Microsoft's own Go toolchain. See\n> [Antivirus False Positives](SECURITY.md#antivirus-false-positives) for the\n> evidence, how to verify the artifacts yourself, and how to report it if you\n> think we are wrong.\n\nRestart your coding agent. Say **\"Index this project\"** — done.\n\n\nManual install\n\n1. **Download** the archive for your platform from the [latest release](https://github.com/DeusData/codebase-memory-mcp/releases/latest):\n - `codebase-memory-mcp--.tar.gz` (macOS/Linux) or `.zip` (Windows)\n\n2. **Extract and install** (each archive includes `install.sh` or `install.ps1`):\n\n macOS / Linux:\n ```bash\n tar xzf codebase-memory-mcp-*.tar.gz\n ./install.sh\n ```\n\n Windows (PowerShell):\n ```powershell\n Expand-Archive codebase-memory-mcp-windows-amd64.zip -DestinationPath .\n Unblock-File .\\install.ps1\n .\\install.ps1\n ```\n\n3. **Restart** your coding agent.\n\nThe `install` command automatically strips macOS quarantine attributes and ad-hoc signs the binary — no manual `xattr`/`codesign` needed.\n\n\nThe `install` command auto-detects installed coding agents and configures their documented MCP entries plus durable instructions, skills, and lifecycle hooks where supported.\n\n### Session Coordination Daemon\n\nCBM 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.\n\nThe 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`):\n\n| File | Contents |\n|------|----------|\n| `cbm-daemon.log` | Daemon lifecycle, watcher/indexing, UI, resource, and error events. |\n| `daemon-conflicts.ndjson` | Exact-build, coordination-ABI, and cache-root admission conflicts. |\n| `activation-events.ndjson` | Install/update/uninstall activation progress and outcomes. |\n\nThin frontends still write immediate startup and session-specific errors to their own stderr; MCP JSON-RPC stdout remains clean.\n\nAll 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`.\n\nThe 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.\n\nPackage-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.\n\nThe 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](#cli-mode) for details.\n\n### Graph Visualization UI\n\nThe graph UI is built into the binary — every install on every channel has it. Then run it:\n\n```bash\ncodebase-memory-mcp --ui=true --port=9749\n```\n\nOpen `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.\n\n### Auto-Index\n\nEnable automatic indexing on MCP session start:\n\n```bash\ncodebase-memory-mcp config set auto_index true\n```\n\nWhen 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`.\n\nWatcher 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.\n\nTo 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](docs/CONFIGURATION.md#2-cli-managed-runtime-settings).\n\n### Keeping Up to Date\n\n**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:\n\n```bash\n# macOS / Linux\nbash \"/install.sh\"\n```\n\n```powershell\n# Windows\npowershell -ExecutionPolicy Bypass -File \"\\install.ps1\"\n```\n\nThe 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.\n\nWhy 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.\n\nIf PowerShell refuses to run the script because the file came from the internet, `Unblock-File` it first.\n\nInstalled 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`).\n\n### Uninstall\n\n```bash\ncodebase-memory-mcp uninstall\n```\n\nRemoves owned agent config entries, skills, hooks, instructions, and the installed binary. Existing graph indexes are listed and deleted only after confirmation.\n\nThe 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.\n\n## Features\n\n### Graph & analysis\n- **Architecture overview**: `get_architecture` returns languages, packages, entry points, routes, hotspots, boundaries, layers, and clusters in a single call\n- **Architecture Decision Records**: `manage_adr` persists architectural decisions across sessions\n- **Louvain community detection**: Discovers functional modules by clustering call edges\n- **Git diff impact mapping**: `detect_changes` maps uncommitted changes to affected symbols with risk classification\n- **Call graph**: Resolves function calls across files and packages (import-aware, type-inferred)\n- **Dead code detection**: Finds functions with zero callers, excluding entry points\n- **Cypher-like queries**: `MATCH (f:Function)-[:CALLS]->(g) WHERE f.name = 'main' RETURN g.name`\n\n### Search\n- **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).\n- **BM25 full-text search** via SQLite FTS5 with `cbm_camel_split` tokenizer (camelCase / snake_case aware)\n- **Structural search** (`search_graph`): regex name patterns, label filters, min/max degree, file scoping\n- **Code search** (`search_code`): graph-augmented grep over indexed files only\n\n### Cross-service linking\n- **HTTP** route ↔ call-site matching with confidence scoring\n- **gRPC, GraphQL, tRPC** service detection with protobuf Route extraction\n- **Channel detection** (`EMITS` / `LISTENS_ON`) for Socket.IO, EventEmitter, and generic pub-sub patterns across 8 languages with constant resolution\n\n### Cross-repo intelligence\n- **`CROSS_*` edges** link nodes across multiple repos indexed under the same store\n- **Multi-galaxy 3D UI layout** for cross-repo architecture visualization\n- **Cross-repo architecture summary** combining services, routes, and dependencies across the indexed fleet\n\n### Edge types (selected)\n- `CALLS` — a callable is invoked at the source site\n- `CALL_REFERENCE` — a callable is used at a supported reference site (for example, a direct value argument) and resolves to one exact target\n- `USAGE` — an identifier is used, but a unique callable target is not proven (including ambiguous or complex expressions)\n- `IMPORTS`, `DEFINES`, `IMPLEMENTS`, `INHERITS`\n- `HTTP_CALLS`, `ASYNC_CALLS` (cross-service)\n- `EMITS`, `LISTENS_ON` (channels)\n- `DATA_FLOWS` with arg-to-param mapping + field access chains\n- `SIMILAR_TO` (MinHash + LSH near-clone detection, Jaccard scored)\n- `SEMANTICALLY_RELATED` (vocabulary-mismatch, same-language, score ≥ 0.80)\n\n### Indexing pipeline\n- **158 vendored tree-sitter grammars** compiled into the binary\n- **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`)\n- **Infrastructure-as-code indexing** — Dockerfiles, Kubernetes manifests, Kustomize overlays as graph nodes\n- **[Hybrid LSP semantic type resolution](#hybrid-lsp)** 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)\n- **RAM-first pipeline**: LZ4 compression, in-memory SQLite, single dump at end. Memory released after.\n\n### Distribution & operation\n- **Native runtime set, zero infrastructure services**: SQLite-backed, persists to `~/.cache/codebase-memory-mcp/`\n- **Auto-sync**: Background watcher detects file changes and re-indexes automatically\n- **Route nodes**: REST endpoints are first-class graph entities\n- **CLI mode**: `codebase-memory-mcp cli search_graph '{\"project\": \"my-project\", \"name_pattern\": \".*Handler.*\"}'`\n- **Available on**: npm, PyPI, Homebrew, Scoop, Winget, Chocolatey, AUR, `go install`\n\n## Team-Shared Graph Artifact\n\nCommit a single compressed file to your repo and your teammates skip the reindex.\n\n`.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.\n\n- **Format**: SQLite database, indexes stripped, `VACUUM INTO` compacted, then zstd 1.5.7 compressed (8–13:1 ratio typical)\n- **Two tiers**:\n - **Best** (`zstd -9` + index strip + `VACUUM INTO`) — written on explicit `index_repository`\n - **Fast** (`zstd -3`) — written by the watcher for low-latency incremental updates\n- **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\n- **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\n- **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.\n- **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:\n ```gitattributes\n .codebase-memory/graph.db.zst filter=lfs diff=lfs merge=lfs -text\n ```\n 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.\n- **Optional**: never committed unless you want it. Add `.codebase-memory/` to `.gitignore` if you prefer everyone to reindex from scratch.\n\nThe 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.\n\n## How It Works\n\ncodebase-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.\n\n```\nYou: \"what calls ProcessOrder?\"\n\nAgent calls: trace_path(function_name=\"ProcessOrder\", direction=\"inbound\")\n\ncodebase-memory-mcp: executes graph query, returns structured results\n\nAgent: presents the call chain in plain English\n```\n\n**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.\n\n## Performance\n\nBenchmarked on Apple M3 Pro:\n\n| Operation | Time | Notes |\n|-----------|------|-------|\n| **Linux kernel full index** | **3 min** | 28M LOC, 75K files → 4.81M nodes, 7.72M edges |\n| Linux kernel fast index | 1m 12s | 1.88M nodes |\n| Django full index | ~6s | 49K nodes, 196K edges |\n| Cypher query | <1ms | Relationship traversal |\n| Name search (regex) | <10ms | SQL LIKE pre-filtering |\n| Dead code detection | ~150ms | Full graph scan with degree filtering |\n| Trace call path (depth=5) | <10ms | BFS traversal |\n\n**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.\n\n**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**.\n\nTo measure comparable quality, latency, and agent-efficiency metrics on your own workload, see [Measuring quality, latency, and agent savings](docs/MEASURING_SAVINGS.md). Exact reproduction of the figures above requires the original inputs and raw artifacts.\n\n## Troubleshooting & Diagnostics\n\ncodebase-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.\n\n### Capture a diagnostics log\n\nSet `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--` 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`:\n\n| File | What it is |\n|------|------------|\n| `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. |\n| `snapshot.json` | The latest snapshot only — handy for a quick live check. Removed on clean exit. |\n\nThe private randomized directory prevents another local account from pre-placing a link or special file at a predictable diagnostics path. Its `` 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.\n\n### What to share\n\nWhen 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.\n\n## Installation\n\n### Pre-built Binaries\n\n| Platform | Archive |\n|----------|---------|\n| macOS (Apple Silicon) | `codebase-memory-mcp-darwin-arm64.tar.gz` |\n| macOS (Intel) | `codebase-memory-mcp-darwin-amd64.tar.gz` |\n| Linux (x86_64) | `codebase-memory-mcp-linux-amd64.tar.gz` |\n| Linux (ARM64) | `codebase-memory-mcp-linux-arm64.tar.gz` |\n| Windows (x86_64) | `codebase-memory-mcp-windows-amd64.zip` |\n\nEvery 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.\n\n> **Windows note**: SmartScreen may show a warning for unsigned software. Click **\"More info\"** → **\"Run anyway\"**. Verify integrity with `checksums.txt`.\n\n### Setup Scripts\n\n\nAutomated download + install\n\n**macOS / Linux:**\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup.sh | bash\n```\n\n**Windows (PowerShell):**\n\n```powershell\nirm https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/scripts/setup-windows.ps1 | iex\n```\n\n\n\n### AUR (Arch Linux)\n\n```bash\nyay -S codebase-memory-mcp-bin\n```\n\n```bash\nparu -S codebase-memory-mcp-bin\n```\n\nThe `codebase-memory-mcp-bin` package is available at: https://aur.archlinux.org/packages/codebase-memory-mcp-bin\n\n### Nix (flake)\n\nThe flake exposes two server packages plus the standalone frontend:\n\n| Package | Contents |\n|---------|----------|\n| `default` (`codebase-memory-mcp`) | Standard server, no UI |\n| `codebase-memory-mcp-ui` | Server with the graph UI embedded (`--ui=true` works) |\n| `graph-ui` | Just the built frontend assets (`dist/`) |\n\nRun directly without installing:\n\n```bash\n# Standard server\nnix run github:DeusData/codebase-memory-mcp\n\n# Server with the embedded graph UI\nnix run github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui -- --ui=true --port=9749\n# then open http://127.0.0.1:9749\n```\n\nOr build a binary into `./result/bin/codebase-memory-mcp`:\n\n```bash\nnix build github:DeusData/codebase-memory-mcp # standard\nnix build github:DeusData/codebase-memory-mcp#codebase-memory-mcp-ui # with UI\n```\n\nWorking 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`.\n\n> **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.\n\n### Install via Claude Code\n\n```\nYou: \"Install this MCP server: https://github.com/DeusData/codebase-memory-mcp\"\n```\n\n### Build from Source\n\n\nPrerequisites: C compiler + zlib\n\n| Requirement | Check | Install |\n|-------------|-------|---------|\n| **C compiler** (gcc or clang) | `gcc --version` or `clang --version` | macOS: `xcode-select --install`, Linux: `apt install build-essential` |\n| **C++ compiler** | `g++ --version` or `clang++ --version` | Same as above |\n| **zlib** | — | macOS: included, Linux: `apt install zlib1g-dev` |\n| **Git** | `git --version` | Pre-installed on most systems |\n\n\n\n```bash\ngit clone https://github.com/DeusData/codebase-memory-mcp.git\ncd codebase-memory-mcp\nscripts/build.sh --with-ui # the shipped composition (graph UI embedded)\nscripts/build.sh # without the UI (development only)\n# Binary at: build/c/codebase-memory-mcp (codebase-memory-mcp.exe on Windows)\n```\n\nEvery 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.\n\nRun the test suite (6,768 tests across 120 suites):\n\n```bash\nscripts/test.sh # full: clean sanitizer build + all suites + guards\nscripts/test.sh --suites # one suite, incremental, seconds\nbuild/c/test-runner --list-suites # what is available\n```\n\n`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:\n\n```bash\nscripts/ci/smoke-artifact.sh \n```\n\n`scripts/package-release.sh` is intentionally a lower-level immutable boundary:\nit accepts only an already-final `--selected-binary` plus its\n`--expected-sha256`; it never builds, strips, signs, or relinks the executable.\n\n### Manual MCP Configuration\n\n\nIf you prefer not to use the install command\n\nAdd to `~/.claude.json` (user scope) or project `.mcp.json`:\n\n```json\n{\n \"mcpServers\": {\n \"codebase-memory-mcp\": {\n \"command\": \"/path/to/codebase-memory-mcp\",\n \"args\": []\n }\n }\n}\n```\n\nRestart your agent. Verify with `/mcp` — you should see `codebase-memory-mcp` with 15 tools.\n\n\n\n## Multi-Agent Support\n\n`install` configures 45 client surfaces: 39 detected automatically and 6\nconditional or explicit. “Conditional” means the installer writes only when the\ndocumented platform or an explicit, already-existing config path proves the\ntarget is active. It never flips experimental feature flags, enables plugins,\nYOLO modes, global permission bypasses, or third-party instruction trust.\n\nWhere a client has a documented custom-agent format, the installer creates three\nexact-owned definitions from one canonical contract:\n\n- **Scout (Tier 1)** — about 3–4 narrow calls for fast positive, provisional discovery; no absence, exhaustive-impact, or dead-code claims.\n- **Verify (Tier 2, default)** — task-directed graph evidence, exact source checks, path coverage for every cited file, and scope coverage before negative claims.\n- **Auditor (Tier 3)** — bounded scope, current index generation, complete relevant pagination, broader relationship checks, and explicit unresolved limitations.\n\nEvery direct tier batches `check_index_coverage` for its evidence paths and reads\nflagged ranges or skipped/excluded files directly. A clean coverage result means\nonly “no recorded gap,” never proof of completeness. Clients without safe child\nMCP access receive the same three tiers as parent-handoff agents; the parent must\nsupply project, generation, pagination state, graph evidence, and coverage\nresults. Updates migrate only byte-identical prior Verify definitions and never\noverwrite user-modified agents.\n\n| Agent | Activation | MCP config | Durable context / augmentation |\n|-------|------------|------------|--------------------------------|\n| Claude Code | Detected | `~/.claude.json` | Skill + three exact-tool graph agents; `SessionStart`, `SubagentStart`, non-blocking `PreToolUse` for `Grep`/`Glob`/`Bash`, and post-`Read` coverage |\n| Codex CLI | Detected | `$CODEX_HOME/config.toml` | Managed `AGENTS.md` activation pointer, skill, three read-only agents; `SessionStart` + `SubagentStart` |\n| Gemini CLI | Detected | `.gemini/settings.json` | `GEMINI.md`, three explicit read/graph-tool subagents; `BeforeTool`, `AfterTool` `read_file` coverage, and `SessionStart` |\n| Zed | Detected | platform `settings.json` (JSONC) | `AGENTS.md` + shared skill |\n| 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 |\n| Antigravity | Detected | `.gemini/config/mcp_config.json` | `.gemini/GEMINI.md` |\n| Aider | Detected | — | `CONVENTIONS.md` via `.aider.conf.yml` |\n| KiloCode | Detected | `.config/kilo/kilo.jsonc` | Rule + three graph-tool subagents with deny-by-default permissions |\n| VS Code | Detected | platform `Code/User/mcp.json` | `~/.copilot/skills`, three read-only agents, `sessionStart` + `subagentStart` |\n| Cursor | Detected | `.cursor/mcp.json` | Skill + three read-only parent-handoff agents; context hooks withheld because session injection races and `readonly` blocks MCP |\n| Windsurf | Detected | `~/.codeium/windsurf/mcp_config.json` | Always-on `global_rules.md` |\n| Augment / Auggie | Detected | `~/.augment/settings.json` | Rule, three read-only handoff subagents, `SessionStart` + post-`view` coverage |\n| OpenClaw | Detected | `$OPENCLAW_CONFIG_PATH` or state `openclaw.json` | Active-workspace `AGENTS.md` + `TOOLS.md`; compaction reinjection |\n| 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`) |\n| 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 |\n| Hermes | Detected | `$HERMES_HOME/config.yaml` | Skill + fail-open `pre_llm_call` context augmentation |\n| OpenHands | Detected | `.openhands/mcp.json` | Shared `.agents/skills/codebase-memory/SKILL.md` |\n| 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 |\n| Warp | Detected, skill only | UI, Warp Drive, or per invocation (manual) | Shared `~/.agents/skills/codebase-memory/SKILL.md` |\n| Qwen Code | Detected | `.qwen/settings.json` | `QWEN.md`, skill, three explicit read/graph-tool agents; `SessionStart`, `SubagentStart`, and post-`ReadFile` coverage |\n| GitHub Copilot CLI | Detected | `$COPILOT_HOME/mcp-config.json` | Instructions, skill, three read-only agents; `sessionStart` + `subagentStart` |\n| 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 |\n| Crush | Detected | `.config/crush/crush.json` | Managed context path with explicit parent-to-child handoff |\n| Goose | Detected | `.config/goose/config.yaml` | `.goosehints` |\n| Mistral Vibe | Detected | `$VIBE_HOME/config.toml` | `AGENTS.md`, skill, and three matched agent/prompt pairs with explicit read-only graph-tool allowlists |\n| 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 |\n| 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 |\n| Kimi Code CLI | Detected | `$KIMI_CODE_HOME/mcp.json` (default `~/.kimi-code`) | Same-root `AGENTS.md` + skill; fail-open `UserPromptSubmit` hook in `config.toml` |\n| 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 |\n| Rovo Dev CLI | Detected | configured override or `~/.rovodev/mcp.json` | Global `AGENTS.md`, skill + three read-only handoff subagents; no undocumented hook |\n| Amp | Detected | `~/.config/agents/skills/codebase-memory/mcp.json` | Colocated skill + `~/.config/amp/AGENTS.md`; no plugin |\n| 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 |\n| Tabnine | Detected | `~/.tabnine/mcp_servers.json` | MCP only; no experimental/YOLO setting |\n| Continue / cn | Conditional | Existing `~/.continue/config.yaml` or `$CBM_CONTINUE_CONFIG_PATH` | MCP only |\n| Visual Studio | Conditional, Windows | `~/.mcp.json` | MCP only |\n| TRAE | Conditional | Existing `$CBM_TRAE_CONFIG_PATH` | MCP only |\n| Roo Code | Conditional | Existing `$CBM_ROO_CONFIG_PATH` | MCP only |\n| Amazon Q Developer IDE | Detected | `~/.aws/amazonq/default.json` (preserves an existing `agents/default.json` or legacy `mcp.json`) | MCP only |\n| 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 |\n| IBM Bob Shell | Detected by `bob` | `~/.bob/mcp_settings.json` | Shared rule; no invented hook or agent |\n| Pochi | Detected | `~/.pochi/config.jsonc` (`mcp`) | `README.pochi.md`, skill, and three `readFile`-only parent-handoff agents |\n| Pi | Detected | — | `~/.pi/agent/AGENTS.md` + skill; MCP/subagents require an explicit reviewed extension |\n| IBM Bob IDE | Conditional | Existing `~/.bob/mcp.json` | Shared rule + IDE skill; no invented hook or agent |\n| 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` |\n| Sourcegraph Cody | Explicit opt-in | Existing `$CBM_CODY_CONFIG_PATH` | MCP only |\n\nFor Codex, install keeps only a tiny managed activation pointer in global\n`$CODEX_HOME/AGENTS.md`; all detailed behavior lives in the installed `codebase-memory` skill.\nFresh installs create the pointer, upgrades replace the legacy full managed block while preserving\nall user-owned bytes, and uninstall removes only the managed pointer.\n\n### Sessions, compaction, and subagents\n\nHooks installed by this project are fail-open and context-only. Claude Code's\n`PreToolUse` observes `Grep`/`Glob`/`Bash` and injects matching graph symbols as\n`additionalContext`; `PostToolUse` on `Read` adds targeted coverage context when\nthe graph could not fully parse or index that file. It never denies or replaces\nthe requested tool call.\n\nClaude Code, Codex CLI, Qwen Code, GitHub Copilot CLI, and VS Code's Copilot\nruntime receive paired session/subagent context where the vendor exposes a\ndocumented context-output contract. Codex users must review and trust installed\nhooks through `/hooks`; changing a hook definition changes its trust hash, so an\nupdate can require re-trust. Qoder uses `SessionStart`, `SubagentStart`, and\npost-`Read` coverage, including its documented PowerShell executor on Windows.\nKimi uses `UserPromptSubmit`, while Hermes uses `pre_llm_call`; both retain their\ndocumented Windows execution paths. Devin installs\n`UserPromptSubmit` and `PostCompaction` on macOS/Linux and adds `SessionStart`\nonly when Claude's equivalent managed hook is not present. GitLab Duo gets a\nnarrowly scoped macOS/Linux user `SessionStart` entry on its experimental hook\nsurface. GitLab Duo, Devin, and Factory hooks are withheld on Windows\nbecause those vendors do not document a deterministic shell/executor contract\nthere. Gemini CLI, Factory Droid, and Augment also add documented post-read/view\ncoverage context but expose no equivalent documented child-start context.\n\nFor runtimes without a stable context-producing lifecycle event, durable files\ncarry the contract across fresh sessions and compaction: verify the graph project\nand index freshness, query structural facts in the parent, then pass the project,\nqualified symbols, paths, and call-chain evidence in every delegated task.\nClaude, Codex, Gemini, Kiro, Qwen, Copilot, CodeBuddy, OpenCode, Kilo, Vibe,\nQoder, Junie, Factory, and Grok Build receive Scout, Verify, and Auditor graph profiles.\nKiro embeds this MCP server with `--tool-profile scout` for Scout and\n`--tool-profile analysis` for Verify/Auditor. Junie registers equivalent named\nserver aliases because its subagent schema filters by server rather than by\nindividual tool. Both process profiles use positive allowlists: Scout exposes\nseven fast inspection tools, Analysis exposes eleven, and future or mutating\ntools remain unavailable until explicitly reviewed. If either Junie alias\ncollides with user configuration, the installer preserves it and installs\nparent-handoff profiles instead. Qoder combines its documented named-server\nselection with exact tier-specific MCP tool IDs. Factory uses exact registered\nMCP tool IDs without its additive `mcpServers` field, which would expose the\nwhole server. Codex, Kilo, Vibe, and other capable formats likewise enumerate\nthe narrowest supported tool set. Rovo, Cursor, Augment, Pochi, and Cline use parent handoff where direct\nchild MCP is unavailable or unsafe; Pochi is limited to `readFile`, and Cline\nchild agents cannot use MCP.\n\nCline's file hooks auto-activate when present, and current Cline does not\nreliably consume their context output, so automatic adapters are withheld and\nolder owned adapters are cleaned up. CodeBuddy's beta, version-gated hooks are\nnot auto-installed. Junie's EAP\n`SessionStart` output is documented as ignored, so no context hook is installed.\nJunie custom agents remain EAP-dependent. Qoder can resolve higher-priority\nproject or plugin agents before user agents with the same name; reload the\nclient after installation or profile changes.\nCursor context\nhooks are withheld: session context injection has a known race, `subagentStart`\nis control-only, and read-only subagents cannot safely receive MCP access. Grok Build's\npassive hook events (`SessionStart`, `SubagentStart`, `PostToolUse`) discard\nstdout and `PreToolUse` honors only deny/rewrite decisions, so its context hooks\nare withheld; Grok also reads Claude and Cursor MCP, skill, and hook files\nthrough its compat layer, and the native `config.toml` entry shadows that copy\nby name. Rovo\nhas no documented session context-output hook, and Bob\ndocuments neither a suitable hook nor a custom-agent surface. Those surfaces are\nnot approximated with invented augmentation. Kimi plugins, Amp plugins, and\nGitLab experimental global skills remain opt-in.\n\nOpenClaw reinjects the `Codebase Knowledge Graph (codebase-memory-mcp)` AGENTS\nsection after compaction and places the same guidance in `TOOLS.md`, the bootstrap\nfiles inherited by its subagents. Automatic augmentation covers the active/default\nworkspace. Separate `agents.list[].workspace` directories require making that\nworkspace active for installation or copying the managed block there.\n\nThe installed Claude shim is named `cbm-code-discovery-gate` for backward\ncompatibility; despite the legacy name, it never gates or blocks.\n\n### Manual or UI-managed integrations\n\nThese are intentionally not counted as automatic installs: Qodo MCP is added\nthrough its UI and may be governed by enterprise allowlists; Warp MCP is managed\nthrough Warp Drive/UI or per invocation (only the shared skill is automatic);\nJetBrains AI Assistant / ACP is IDE-managed; GitHub Copilot coding agent, Jules,\nand CodeRabbit are cloud/repository-managed; Replit exposes a remote/service\nintegration rather than a stable local user-global client; BLACKBOX AI does not\ndocument a stable arbitrary user-global MCP/instruction/agent schema; Plandex has\nno stable global registry safe to mutate; and SWE-agent uses explicit YAML and is\nno longer a suitable automatic global target.\n\n## CLI Mode\n\nEvery 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.\n\nCommands 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.\n\nWhen 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.\n\nLarge compact-tree tables may start with a response-local `_refs` directory and an explicit `_ref_rule`. A cell such as `@0+handler.go` reconstructs to ref `0`'s prefix plus `handler.go`. References are local to that sibling `` table and expansion is non-recursive: entries inside `_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.\n\nLean 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.\n\nEvery 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:`. A valid preserved value that literally begins with the reserved `@bytes:` or `@utf8:` prefix is emitted as `@utf8:`, 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.\n\nUse `cli --help` to see the flags generated from that tool's input schema:\n\n```bash\ncodebase-memory-mcp cli index_repository --repo-path /path/to/repo\ncodebase-memory-mcp cli list_projects\n\n# Use the \"name\" returned by list_projects as the project value.\ncodebase-memory-mcp cli search_graph --project my-project --name-pattern '.*Handler.*' --label Function\ncodebase-memory-mcp cli trace_path --project my-project --function-name Search --direction both\ncodebase-memory-mcp cli query_graph --project my-project --query 'MATCH (f:Function) RETURN f.name LIMIT 5'\n\n# Force human-readable progress without contaminating stdout.\ncodebase-memory-mcp cli --progress index_repository --repo-path /path/to/repo\n# Suppress automatic terminal progress and non-error diagnostics.\ncodebase-memory-mcp cli --quiet list_projects --format json\ncodebase-memory-mcp cli search_graph --project my-project --label Function --format json\ncodebase-memory-mcp cli list_projects --format json --detail stats | jq '.projects[].name'\n```\n\nJSON 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.\n\n## MCP Tools\n\n### Indexing\n\n| Tool | Description |\n|------|-------------|\n| `index_repository` | Index a repository into the graph. Auto-sync keeps it fresh after that. |\n| `list_projects` | List all indexed projects with node/edge counts. |\n| `delete_project` | Remove a project and all its graph data. |\n| `index_status` | Check indexing status of a project. |\n\n### Querying\n\n| Tool | Description |\n|------|-------------|\n| `search_graph` | Structural, BM25, and semantic search. Page structural rows with `offset`/`limit` and ranked semantic rows independently with `semantic_offset`/`semantic_limit`. |\n| `trace_path` | BFS traversal — who calls a function and what it calls (alias: `trace_call_path`). Depth 1-5. |\n| `detect_changes` | Map git diff to affected symbols + blast radius with risk classification. |\n| `query_graph` | Execute Cypher-like graph queries (read-only). |\n| `get_graph_schema` | Node/edge counts, relationship patterns, property definitions per label. Run this first. |\n| `get_code_snippet` | Read source code for a function by qualified name. |\n| `get_architecture` | Codebase overview: languages, packages, routes, hotspots, clusters, ADR. |\n| `search_code` | Grep-like text search within indexed project files. |\n| `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. |\n| `ingest_traces` | Ingest runtime traces to validate HTTP_CALLS edges. |\n\n`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.\n\n`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.\n\n## Graph Data Model\n\n### Node Labels\n\n`Project`, `Package`, `Folder`, `File`, `Module`, `Class`, `Function`, `Method`, `Interface`, `Enum`, `Type`, `Route`, `Resource`\n\n### Edge Types\n\n`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`\n\n### Qualified Names\n\n`get_code_snippet` uses qualified names: `..`. Use `search_graph` to discover them first.\n\n### Supported Cypher (openCypher read subset)\n\n`query_graph` is a read-only openCypher subset:\n\n- **Clauses**: `MATCH`, `OPTIONAL MATCH`, multiple `MATCH`, `WHERE`, `WITH` (+ `WITH … WHERE`), `RETURN`, `ORDER BY`, `SKIP`, `LIMIT`, `DISTINCT`, `UNWIND`, `UNION` / `UNION ALL`, `CASE`.\n- **Patterns**: labelled nodes, label alternation `(n:A|B)`, relationship types/direction, variable-length paths `[*1..3]`, inline property maps.\n- **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]-() }`).\n- **Aggregates**: `count` (+`DISTINCT`), `sum`, `avg`, `min`, `max`, `collect`.\n- **Functions**: `labels`, `type`, `id`, `keys`, `properties`; `toLower/toUpper/toString/toInteger/toFloat/toBoolean`; `size`, `length`, `trim/ltrim/rtrim`, `reverse`; `coalesce`, `substring`, `replace`, `left`, `right`.\n\nAnything 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.\n\n## Ignoring Files\n\nLayered: hardcoded patterns (`.git`, `node_modules`, etc.) → `.gitignore` hierarchy → `.cbmignore` (project-specific, gitignore syntax). Symlinks are always skipped.\n\nSee [docs/cbmignore.md](docs/cbmignore.md) for the full `.cbmignore` how-to: syntax, precedence across the ignore layers, and negation semantics.\n\n## Configuration\n\n```bash\ncodebase-memory-mcp config list # show all settings\ncodebase-memory-mcp config set auto_index true # auto-index on session start\ncodebase-memory-mcp config set auto_index_limit 50000 # max files for auto-index\ncodebase-memory-mcp config set auto_watch false # don't register background git watcher (default: true)\ncodebase-memory-mcp config set watcher_enabled false # stop the watcher thread entirely (default: true)\ncodebase-memory-mcp config reset auto_index # reset to default\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `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. |\n| `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. |\n| `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`. |\n| `CBM_DOWNLOAD_URL` | *(GitHub releases)* | Override the download URL for updates. Used for testing or self-hosted deployments. |\n| `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 `in",
"bytes": 60000,
"sha": "d5e4c7c0674a70aa86d07f2db29f1f3bd02f797796d625e7da3837fe2c89e918",
"repo_slug": "deusdata/codebase-memory-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_deusdata_codebase_memory_mcp_1fd8d16b/readme"
}
![\"Graph](\"docs/graph-ui-screenshot.png\")
\n