pi-codebase-memory

A pi package that bridges the codebase-memory-mcp server into pi as native tools. Gives your agent a fast, local tree-sitter knowledge graph of your repos — structural code search, call-path tracing, architecture overviews, and change-impact analysis in milliseconds, with far fewer tokens than file-by-file grepping.

Fork note: This is a maintained fork of porameht/pi-codebase-memory-mcp with critical bug fixes, proper pi extension lifecycle, Windows support, and TUI stability improvements. See Changelog below.

• Server: codebase-memory-mcp (single static binary, MCP over stdio, 100% local, zero dependencies)
• Upstream: DeusData/codebase-memory-mcp

Requirements

The codebase-memory-mcp binary installed locally:

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

(macOS/Linux; Windows via install.ps1. Also on Homebrew, Scoop, AUR, npm, PyPI.) The binary is resolved from CBM_MCP_BIN, then ~/.local/bin/codebase-memory-mcp[.exe], then your PATH.

Install

From this fork (recommended — includes all fixes):

pi install git:github.com/TheFuchsen/pi-codebase-memory

Or try it without installing:

pi -e ./path/to/pi-codebase-memory

What you get

• Extension — spawns the local codebase-memory-mcp server over stdio, discovers its tools dynamically, and registers each as a pi tool with a cbm_ prefix.
• cbm_connect tool — always available, so the agent can start (or restart) the server mid-session and pick up newly discovered tools immediately.
• /cbm command — status and reconnect from the TUI (/cbm, /cbm reconnect).
• Safety gate — cbm_delete_project pops a confirmation dialog before wiping a project's graph (disable with CBM_CONFIRM=off).
• Skill — codebase-memory, teaching the agent the index → search → trace → query workflow.

Tools (discovered dynamically)

Indexing: cbm_index_repository, cbm_list_projects, cbm_delete_project, cbm_index_status

Querying: cbm_search_graph, cbm_trace_path, cbm_detect_changes, cbm_query_graph, cbm_get_graph_schema, cbm_get_code_snippet, cbm_get_architecture, cbm_search_code, cbm_manage_adr, cbm_ingest_traces

Example prompts

• "Index this project."
• "What calls ProcessOrder?"
• "Find every function matching .*Handler.*."
• "Give me an architecture overview of this repo."
• "What's the blast radius of my current git changes?"
• "Show the source for the Search function."

Configuration

Environment variable	Default	Purpose
CBM_MCP_BIN	(auto)	Absolute path to the codebase-memory-mcp binary (overrides auto-detection)
CBM_CONFIRM	on	Set to off to skip the confirmation dialog for cbm_delete_project

Notes

• Tools are discovered at connection time; the set may change between server versions.
• If the binary isn't installed when pi starts, pi still starts normally — install it, then ask the agent to connect (cbm_connect).
• Index with an absolute repo_path. After the first index, a background watcher keeps the graph fresh.

Changelog

v0.2.0 — This fork

Complete rewrite of the extension to follow pi's extension API correctly. The original port (v0.1.2) was a rushed simplification that stripped critical functionality and violated pi's lifecycle conventions.

Fixed

• stderr leak corrupting TUI — StdioClientTransport now uses stderr: "ignore" and sets CBM_LOG_LEVEL=error in the child environment. The server's structured info-level logs (level=info msg=mem.init...) no longer inject into pi's terminal and break rendering. (upstream issue)

• No timeout on MCP calls — Added CONNECT_TIMEOUT_MS (15s) and CALL_TIMEOUT_MS (5min). Without timeouts, a hung server (e.g., indexing a large repo) blocked the tool call indefinitely with no way to cancel.

• No timeout on connection — Server startup is now bounded by a 15-second timeout. Previously, if the binary was missing or crashed on launch, getClient() hung forever.

• Resources started at module load — MCP client startup deferred to session_start per pi extension best practices. The original spawned the child process during factory execution, before the session was ready.

• No cleanup on session shutdown — Added session_shutdown handler to close the MCP client connection. The original leaked the child process and stdio transport when the session ended.

• Windows binary detection — Appends .exe extension on Windows (~/.local/bin/codebase-memory-mcp.exe). The original only checked for the Unix path without the extension.

• Incomplete execute signature — Tool execute now accepts the full (toolCallId, params, signal, onUpdate, ctx) signature. This enables proper cancellation via signal, progress streaming via onUpdate, and access to ctx.cwd / ctx.signal.

• Overly broad error handling — Respawn-and-retry now only triggers on connection-level failures (timeouts, ECONNRESET, EPIPE, spawn errors, ENOENT). The original reconnected on ANY error, including tool logic errors like invalid parameters or missing repos.

• No connection deduplication — Shared connecting promise prevents race conditions when multiple parallel tool calls trigger reconnects simultaneously.

• Unsafe JSON Schema → TypeBox cast — Replaced (inputSchema as unknown as TSchema) with a proper jsonSchemaToTypeBox() converter that translates JSON Schema types, objects, arrays, enums, and required fields into TypeBox schemas. The blind cast worked by coincidence and could fail on complex schemas.

• Missing /cbm command — Restored the status and reconnect command (/cbm, /cbm reconnect). It was removed in v0.1.2's "simplify" commit but still referenced in the SKILL.md.

• Missing image passthrough — Restored toPiContent() conversion for MCP image content blocks. The original stripped image support during simplification.

• Missing promptSnippet on dynamic tools — Dynamically registered tools now include promptSnippet for discoverability in pi's system prompt "Available tools" section.

• Missing details on tool results — Results now include { binary, mcpTool } metadata for debugging and state tracking.

• Missing custom rendering — Restored renderCall and renderResult for proper TUI display (compact first-line preview, expanded full output, error states, partial/streaming indicators).

Changed

• Version bumped to 0.2.0 (lifecycle changes are semver-breaking for extension consumers).
• Extension grew from 103 to 507 lines — the "simplify" commit removed more than it kept.

v0.1.2 — Original port (porameht)

• Simplified extension (dropped custom renderers, /cbm command, image passthrough, timeouts).
• README refreshed.

v0.1.1 — Original port

• Renamed npm package to pi-codebase-memory-mcp.

v0.1.0 — Original port

• Initial release: bridges the codebase-memory-mcp stdio server into pi.
• Dynamic discovery of MCP tools with cbm_ prefix.
• cbm_connect tool and /cbm command.
• Confirmation gate for cbm_delete_project.
• codebase-memory skill.

License

MIT