pi-cbm

Pi extension that exposes codebase-memory-mcp as native Pi tools. `codebase-memory-mcp provides a fast local code graph. pi-cbm adds auto-indexing and adapts it for Pi agents in a way that is deliberately optimized for agent workflows and token saving.

This package does not implement an MCP client. It uses codebase-memory-mcp cli --json <tool> <args> and registers the core tools directly with Pi. When a Pi session starts, it automatically indexes the current git root, or a safe non-git working directory when enabled, in full mode in the background, then periodically refreshes it so graph tools stay current.

What makes this different

• Token-saving output by default. Several upstream tools return rich graph metadata, fingerprints, scores, and raw analysis fields. pi-cbm strips less-useful metadata by default and returns compact, location-first results. Use include_metadata: true when you need the full upstream payload.
• Source compaction controls. Tools that may return code support full_output and max_symbol_lines. Normal-sized symbols are returned directly; oversized code blocks are compacted and the full uncompacted JSON is saved to a temp file.
• Symbol-first helpers. Upstream get_code_snippet works best when you already know the exact qualified_name. pi-cbm adds resolve_symbol and read_symbol so the agent can start from a normal symbol name, disambiguate with file/class/route filters, and only read source when the match is unambiguous.
• Safe-by-default symbol reading. read_symbol fails closed on ambiguity: it returns candidate identities instead of guessing and reading the wrong source. When exactly one symbol matches, it calls upstream get_code_snippet and can optionally include compact direct callers/callees.
• Batch source-reading workflows. get_code_snippets, read_symbols, and search_and_read_symbols let agents inspect several relevant symbols in one tool call instead of looping through many single-symbol calls. These batch tools keep the same compact metadata defaults while preserving essential locations, per-item ambiguity/error results, and source compaction controls.
• Current project stays indexed. On Pi session start, the extension indexes the current git root, or a safe non-git working directory when enabled, in full mode and refreshes it periodically in the background. Root, home, system, and common builtin OS directories are never auto-indexed.
• Project inference for cwd workflows. Most tools accept optional project, but for normal current-repo work the extension infers the indexed project from Pi's current working directory.
• Query tools only. The agent gets code-exploration tools, not administrative controls. index_repository and list_projects are used internally for background indexing and project inference; destructive/admin MCP tools such as project deletion are not registered as Pi tools.

Security

Pi extensions run with your local user permissions. This extension also shells out to the codebase-memory-mcp binary installed on your machine, so install both this package and codebase-memory-mcp only from sources you trust.

Requirements: install codebase-memory-mcp

Install codebase-memory-mcp first. These are the upstream recommended install paths.

macOS / Linux

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

With the optional graph visualization UI:

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

Windows PowerShell

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

# 2. Optional but recommended: inspect the script
notepad install.ps1

# 3. Run it
.\install.ps1

Useful installer options from upstream:

• --ui — install the graph visualization variant.
• --skip-config — install the binary only, without configuring other agents.
• --dir=<path> — install to a custom location.

Arch Linux AUR

yay -S codebase-memory-mcp-bin

or:

paru -S codebase-memory-mcp-bin

Manual release archive

Download the archive for your platform from the latest codebase-memory-mcp release:

• codebase-memory-mcp-<platform>-<arch>.tar.gz for macOS/Linux.
• codebase-memory-mcp-windows-amd64.zip for Windows.
• codebase-memory-mcp-ui-... variants include the graph visualization UI.

Then extract and run the included installer:

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

Windows PowerShell:

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

If the binary is not on PATH, set:

export CODEBASE_MEMORY_MCP_BIN="$HOME/.local/bin/codebase-memory-mcp"

Install

pi install npm:pi-cbm

Or test for one run:

pi -e npm:pi-cbm

Tools

Registers:

• get_graph_schema
• get_architecture
• search_graph
• resolve_symbol
• read_symbol
• read_symbols
• search_code
• get_code_snippet
• get_code_snippets
• search_and_read_symbols
• trace_path
• query_graph
• detect_changes

Most tools accept optional project. When omitted, the extension infers it from indexed project roots matching Pi's current working directory. Agents should omit project for cwd/current-project work and provide it only when intentionally querying an external indexed project.

Commands

/cbm

Open the pi-cbm settings menu:

• /cbm menu — show the interactive settings menu.
• /cbm status — show auto-index settings.
• /cbm enable-non-git — auto-index safe non-git working directories.
• /cbm disable-non-git — only auto-index git repositories.

Non-git auto-indexing is enabled by default to preserve normal cwd workflows. The unsafe-path guard is always enabled: filesystem roots, home directories, system directories, and common macOS/Linux builtin directories are skipped with a status message explaining why.

Notes:

• Use search_graph first for symbol/workflow/route/class/function discovery and “where is X implemented?” questions. Use a small limit for targeted lookup.
• Use search_and_read_symbols when you need to both discover implementation locations and inspect source for the top matches. Prefer it over search_graph followed by many individual snippet reads. Keep read_limit small, usually 3–8.
• Use resolve_symbol when you know a symbol name but need the exact qualified_name or need to disambiguate candidates.
• Use read_symbol when you know a symbol name plus enough disambiguators, such as file_path, parent_class, label, route_path, or route_method, and want source only if the match is unambiguous.
• Use read_symbols when you know multiple concrete symbol names and need their source in one call. Each item fails closed on ambiguity like read_symbol; retry only ambiguous items with stronger disambiguators.
• read_symbol fails closed on ambiguity; if it returns candidates, retry with more disambiguators or use get_code_snippet with an exact qualified_name.
• read_symbol supports neighbors: "callers" | "callees" | "both" plus neighbor_limit for direct, compact, source-free surrounding call context. Use trace_path for multi-hop workflow or impact tracing.
• Use get_code_snippet when you already have an exact qualified_name; prefer read_symbol when you have a concrete symbol name plus disambiguators but not the exact qualified_name.
• Use get_code_snippets when you already have multiple exact qualified_name values from search, trace, or query results. Prefer it over repeated get_code_snippet calls.
• If the query is a symbol name, prefer resolve_symbol/read_symbol; if it is an exact non-symbol string or you need all textual occurrences, use search_code.
• Use search_code for exact literal text/regex searches such as env vars, config keys, route strings, error messages, constants, template text, comments, and docstrings.
• Use trace_path after identifying an anchor symbol when you need callers, callees, workflow, dependency, data-flow, or blast-radius context. Keep depth shallow by default.
• Use get_code_snippet only after search_graph/search_code identifies the exact symbol. Keep snippet retrieval targeted instead of bulk-reading many symbols.
• Use get_architecture for broad orientation in unfamiliar repos, not targeted implementation lookup. Requested aspects may be absent if the index has no data for them.
• Use get_graph_schema before non-trivial query_graph queries, and keep query_graph returned columns narrow.
• Use detect_changes for diff review or blast-radius analysis, not ordinary code lookup.
• Read obvious README/package/deployment/config manifest paths directly instead of forcing graph tools into file-inspection work.
• trace_path auto-resolves short function/method names when there is a single unambiguous match; otherwise it returns candidate qualified_names. It also supports explicit plugin-side exclude_paths filters.
• Exploration tools such as search_graph, get_code_snippet, trace_path, get_architecture, search_code, and detect_changes default to compact, location-first output. Less-useful upstream graph metadata such as fingerprints, token fields, and raw metrics is hidden unless include_metadata: true is set.
• Batch/source tools such as get_code_snippets, read_symbols, and search_and_read_symbols use the same compact metadata defaults: they preserve essential identity such as file_path, start_line, end_line, qualified_name, signatures, and route fields while stripping less-useful raw graph metadata unless include_metadata: true is set.
• Compact output hides analysis metadata, not edit-critical location identity. Symbol-like outputs preserve file_path, start_line, and end_line when available, and the plugin enriches missing locations for resolver, trace, and architecture outputs where possible.
• Code/source-heavy tools support full_output and max_symbol_lines. By default, normal-sized symbols are returned in full and only oversized function/method/class-sized blocks are compacted.
• search_code defaults to compact output with small context to avoid flooding the agent context, and oversized per-symbol contexts are compacted unless full_output=true or max_symbol_lines is increased. If a result is compacted/truncated, agents should retry the same codebase-memory tool with a higher max_symbol_lines or full_output=true before falling back to file reads/grep.
• query_graph normalizes common numeric metric columns in the returned rows for easier agent consumption, while still relying on upstream for query execution/order.

Typical workflow

Ask Pi:

Give me the architecture overview.

The extension indexes and periodically refreshes the current repo in the background, so the agent should usually go straight to get_architecture, search_graph, get_code_snippet, trace_path, search_code, or query_graph for structural code exploration. Administrative index operations remain available through the codebase-memory-mcp CLI when needed.