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

What's included

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

Tool	Description
cbm_search_graph	Symbol search by name pattern or natural-language query
cbm_trace_path	Call chains: who calls a function (inbound), what it calls (outbound)
cbm_get_code_snippet	Full source for one symbol with metrics
cbm_get_architecture	High-level codebase overview (languages, entry points, hotspots)
cbm_search_code	Literal text / exact identifier search over indexed files
cbm_get_graph_schema	Node/edge labels and relationship patterns
cbm_query_graph	Read-only openCypher queries
cbm_detect_changes	Map git changes to affected symbols with blast radius
cbm_list_projects	All indexed projects with node/edge counts
cbm_index_status	Index health (indexed, stale, or missing) with git-HEAD freshness proof
cbm_index_repository	Index a repository (one-time; auto-sync keeps it fresh)
cbm_delete_project	Remove a project from the knowledge graph (requires UI confirmation)
cbm_manage_adr	Create, update, or read Architecture Decision Records
cbm_ingest_traces	Ingest runtime traces to validate service-to-service edges

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