pi-cmp · Codebase Memory

Codebase Memory tools (cbm_*) for pi. They answer structural questions about a codebase from a local tree-sitter knowledge graph — before pi falls back to slow grep/read loops.

The extension proxies each tool call to the codebase-memory-mcp server, which maintains a graph of symbols, call chains, and relationships per project.

Quick start

cd /path/to/this/repo
pi install "$(pwd)"

Then /reload in pi (or restart pi) and verify:

pi list

Related MCP server: fw-context-mcp

What's included

Extension tools only — no MCP configuration to maintain. The extension spawns and talks to the local codebase-memory-mcp server itself.

Requirements

• Node.js 22.19.0 or newer

• The codebase-memory-mcp server binary on PATH, or point the CBM_BINARY environment variable at it

codebase-memory-mcp is a separate project; install it from its own source before using these tools.

Usage

1. Start pi inside a project

cd /path/to/project
pi

2. Index the project (once)

Ask pi:

Index this project with cbm_index_repository.

Subsequent queries use the local .codebase-memory/ index in the project.

3. Ask structural questions

Good prompts:

Use Codebase Memory. Explain how authentication reaches the request handler.
Use Codebase Memory. What calls PlanBoostSession?
Use Codebase Memory. What would break if I change UserRepository?
Use Codebase Memory. Show files under internal/services and important symbols.

Tool choice

• cbm_get_architecture / cbm_search_graph for broad "how does this work?" questions

• cbm_trace_path when you already know a function name and want callers/callees

• cbm_search_graph for declarations and symbol names, not arbitrary text

• cbm_search_code for literal text, exact identifiers, or distinctive strings

• cbm_detect_changes before refactors — blast radius of uncommitted changes

How it works

pi extensions are not MCP configuration files. This package registers native pi tools, and each tool proxies one JSON-RPC request to the local codebase-memory-mcp process over stdio:

pi agent
  -> pi-cmp extension tool
  -> codebase-memory-mcp process (cwd = your project)
  -> .codebase-memory/ graph database in the current project
  -> structured result back to pi

Additional behavior:

• On session_start the project cache is reset; before_agent_start injects tool-choice guidance into the system prompt.

• Tools default to the project matching pi's current working directory; pass project explicitly (see cbm_list_projects) to query others.

• cbm_index_status compares the indexed git HEAD against the repository's current HEAD for real freshness proof (no fabricated timestamps).

• cbm_delete_project requires interactive confirmation when pi has a UI.

• Long-running tools (cbm_index_repository) use a 10-minute timeout; others default to 20 seconds. Errors surface as diagnostics with secrets redacted.

Development

npm install
npm run typecheck   # tsc --noEmit
npm test            # vitest run

Install the local checkout into pi:

pi install /path/to/pi-cmp

Repository layout

pi-cmp/
├── extensions/     # extension source only (logic lives here)
│   ├── index.ts        # entry point: registers tools, injects guidance
│   ├── tools.ts        # cbm_* tool definitions (typebox schemas)
│   ├── mcp-client.ts   # spawns codebase-memory-mcp, JSON-RPC over stdio
│   ├── project.ts      # project resolution from list_projects output
│   └── sync-check.ts   # git-HEAD freshness annotation for index_status
├── __tests__/      # vitest tests (mirror the files above)
├── package.json    # pi manifest: "pi": { "extensions": ["./extensions"] }
└── tsconfig.json