# pi-cmp · Codebase Memory

Codebase Memory tools (`cbm_*`) for [pi](https://pi.dev). 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

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

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

```bash
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_check_index_coverage` | Per-path/scope coverage metadata — which files were skipped or partially indexed |
| `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

```bash
cd /path/to/project
pi
```

### 2. Index the project (once)

Ask pi:

```text
Index this project with cbm_index_repository.
```

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

### 3. Ask structural questions

Good prompts:

```text
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:

```text
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

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

Install the local checkout into pi:

```bash
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
```