# @vforvaick/pi-codebase-memory-mcp

Unofficial [pi coding agent](https://github.com/badlogic/pi-coding-agent) extension wrapping the [`codebase-memory-mcp`](https://github.com/DeusData/codebase-memory-mcp) binary.

Not affiliated with DeusData/codebase-memory-mcp. MIT.

## What it does

- Registers 9 `cbm_*` tools the LLM can call: `cbm_index`, `cbm_projects`, `cbm_search`, `cbm_trace`, `cbm_architecture`, `cbm_snippet`, `cbm_query` (Cypher), `cbm_changes` (impact analysis), `cbm_coverage`.
- **Freshness gate**: auto-reindexes the graph (mode=`moderate`) before any read query when source has changed. The CBM binary's native watcher is inert in CLI / MCP-stdio mode (its daemon worker log stays 0 bytes, never fires), so without this gate the graph goes stale after every edit until a manual `cbm_index`.
- `project` is auto-inferred from the session cwd, so callers rarely pass it.

## Prerequisites

1. [pi coding agent](https://github.com/badlogic/pi-coding-agent) installed.
2. `codebase-memory-mcp` binary on `PATH`. Install from upstream:
   ```bash
   curl -fsSL https://raw.githubusercontent.com/DeusData/codebase-memory-mcp/main/install.sh | bash
   ```
   Verify: `codebase-memory-mcp --version`.

## Install

```bash
pi install npm:@vforvaick/pi-codebase-memory-mcp
```

After install, restart pi.

## Usage

In any repo:

```
cbm_index               # one-time index (mode=moderate)
cbm_search .*Router.*   # find symbols
cbm_trace myFunction --direction both
cbm_architecture
```

Once indexed, the graph auto-refreshes after edits (see **Freshness gate** below). Tools auto-appear in the function list.

## Freshness gate

The extension keeps a per-cwd dirty flag, bumped by pi lifecycle hooks:

- `session_start` -> mark cwd dirty (forces one reindex on first query, catches cross-session drift)
- `tool_execution_end` for `edit` / `write` / `bash` / `ctx_execute` / `apply_patch` (on success) -> mark dirty
- `user_bash` -> mark dirty conservatively

Before each read query (`cbm_search`, `cbm_trace`, etc.) the extension calls `ensureFresh(cwd)`: if the cwd is dirty or git HEAD has drifted since the last index, it reindexes (mode=`moderate`) then serves the query. Race-safe via a per-cwd in-flight lock + dirty generation counter.

**What the gate does NOT catch**: mutations from external editors or other terminals (VSCode, `sed` in another shell) after the first query in a session. For those, run `cbm_index` manually.

## Configuration

- `CBM_BIN` environment variable overrides the binary path. Default: `codebase-memory-mcp` (looked up on `PATH`).

## Compatibility

- Tested against `codebase-memory-mcp` v0.9.0.
- Support policy: current + previous minor of `codebase-memory-mcp`.
- Known v0.9.0 quirk: `check_index_coverage` returns "unknown tool" via MCP. This extension routes it through `cli` mode, where it works. Tool list parity (advertised vs callable) is tracked upstream.

## Security

- Runs the `codebase-memory-mcp` binary with the same filesystem access as your pi session.
- No telemetry. No network calls. Source is open - review before install.
- pi packages run with full system access; review the source at the repo before installing.

## License

MIT. (C) vforvaick.

## Contributing

PRs welcome at [github.com/vforvaick/pi-codebase-memory-mcp](https://github.com/vforvaick/pi-codebase-memory-mcp).