pi-codebase-memory-hooks

# pi-codebase-memory-hooks [](https://www.npmjs.com/package/pi-codebase-memory-hooks) [](https://pi.dev/packages) Pi-facing lifecycle, native-tool, and hook adapters for [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp). This package generates a package-owned native Pi bridge with schema-aware `cbm_*` tools and delegates every graph, index, and hook operation to the official `codebase-memory-mcp` CLI. It does not use Pi MCP transport or write `mcp.json`. > [!WARNING] > Pi extensions run with full system access. Review the source before installing. `/cbm-install` downloads the pinned official CBM installer from GitHub, verifies its SHA-256 checksum, and executes it with `bash`; use that command only when you trust the source and the network connection. ## What is included - **Native graph context hooks** — forward Pi lifecycle, `grep`, `find`, and `read` events to the official CBM hook frontend. Failures pass through silently. - **Native CBM tool facade** — register schema-aware `cbm_*` tools, keep advanced tools lazy, bound output, and invoke the official CLI through stdin. - **Bootstrap commands** — delegate first install, managed update, bridge refresh, and explicit project indexing to the official installer/CLI. - **Codebase Memory skill** — the knowledge-graph workflow for choosing the native `cbm_search_graph`, `cbm_trace_path`, `cbm_get_code_snippet`, and related tools. - **`AGENTS.md` template** — the same managed guidance that codebase-memory-mcp can add for other coding agents. The package does not bundle the CBM binary. The binary and generated native bridge are installed explicitly by `/cbm-install` or by your own setup. `full_output`, `max_output_chars`, and `timeout_ms` are native-bridge controls, not arguments understood by the CBM CLI. They are removed before forwarding the request. Normal output is passed through; oversized text is compacted with a temp-file recovery path, and `full_output: true` asks the bridge to return it directly. ## Quick start ### 1. Install the Pi package ```bash pi install npm:pi-codebase-memory-hooks ``` You can pin an exact version for reproducible setups: ```bash pi install npm:pi-codebase-memory-hooks@0.2.0 ``` Restart Pi or run `/reload` after installing so the extension is loaded. ### 2. Install and configure codebase-memory-mcp Inside Pi, run: ```text /cbm-install ``` The command shows a native lifecycle plan, asks for confirmation before mutation, and then: 1. delegates first install to the documented installer from the pinned latest-tested CBM release; 2. delegates managed updates to the adjacent official installer; 3. preserves externally managed binaries (Homebrew, mise, nix, and similar owners); 4. generates the package-owned schema-aware native Pi bridge; and 5. skips indexing by default. Use `/cbm-install --index` or `/cbm-index` when indexing is intentional. It never writes `~/.pi/agent/mcp.json`, and it reuses a usable managed binary unless `--force` is supplied. Restart Pi or run `/reload` after a successful bridge refresh. ### 3. Check readiness ```text /cbm-status ``` This reports the active/managed binary paths, generated bridge readiness, release compatibility, and project status from the native canonical resolver. ### Try without installing ```bash pi -e npm:pi-codebase-memory-hooks ``` This loads the package for the current Pi run only. ## Commands | Command | Purpose | | --- | --- | | `/cbm-install` | Delegate install/update and refresh the native Pi bridge. Indexing is skipped by default. | | `/cbm-install --index` | Opt in to indexing the current project after setup. | | `/cbm-install --no-index` | Explicitly skip project indexing. | | `/cbm-install --dry-run` | Show the lifecycle plan without consent prompts or mutations. | | `/cbm-install --yes` | Give explicit consent in a non-interactive runner. | | `/cbm-install --dir <path>` | Select the official managed install directory. | | `/cbm-install --force` | Run the official managed lifecycle even when the binary is already present. `-f` is an alias. | | `/cbm-index` | Index the current project without changing binary or bridge state. | | `/cbm-status` | Show read-only binary, bridge, release, and project-index status. | | `/reload` | Reload installed packages and MCP tools after setup changes. | All install, bridge-refresh, and indexing work is explicit. Nothing downloads or changes Pi's configuration merely because the package was loaded. If CBM is available, read-only native hook calls may run during agent and tool events. ## How the hooks work | Capability | Pi event | Behavior | | --- | --- | --- | | Session and subagent guidance | `before_agent_start` | Delegates the native graph-first lifecycle context to CBM. | | `grep` enrichment | `tool_result` | Adds matching graph symbols and locations to successful `grep` results. | | `find` enrichment | `tool_result` | Adds indexed files matching the requested pattern to successful `find` results. | | Read coverage | `tool_result` | Warns when a supported code file has no graph nodes in an indexed project. | The enrichment hooks invoke the official `codebase-memory-mcp hook-augment` frontend. They do not parse graph output, list projects, infer coverage, or impose a second timeout policy. CBM owns daemon admission, canonical paths, query formatting, coverage, and its documented hook deadline. The adapter caps injected hook context and avoids adding a context block already present in the result. If CBM is unavailable or a lookup fails, Pi keeps the original result unchanged. Enrichment is intentionally quiet when: - the CBM binary cannot be found; - the working directory is not inside an indexed project; or - the tool result is an error. The `grep` and `find` augmentations are the Pi equivalent of CBM's Claude Code `PreToolUse` hooks: Pi can modify tool input, but it cannot attach `additionalContext` beside a tool call, so context is added to the returned result instead. ## Configuration | Variable | Default | Effect | | --- | --- | --- | | `CBM_BIN` | unset | Explicit binary fallback when the bridge is missing or incompatible. A ready bridge's embedded path is authoritative. | | `CBM_INSTALL_DIR` | `~/.local/bin` | Destination used by `/cbm-install`; `~` is expanded. | | `PI_CODING_AGENT_DIR` | `~/.pi/agent` | Pi agent directory where the generated native bridge is written. | | `CBM_HOOKS_DISABLE` | unset | Set to `1` or `true` to disable both hooks and bootstrap commands. | | `CBM_HOOKS_DEBUG` | unset | Set to `1` or `true` to log hook and CLI failures to stderr. | Examples: ```bash CBM_BIN=/opt/codebase-memory-mcp pi ``` ```bash CBM_HOOKS_DEBUG=1 pi ``` ## Installation alternatives Install from the Git repository when testing unreleased changes: ```bash pi install git:github.com/ramaaudra/pi-codebase-memory-hooks ``` Or load a local clone: ```bash pi install /absolute/path/to/pi-codebase-memory-hooks ``` Remove the Pi package with: ```bash pi remove npm:pi-codebase-memory-hooks ``` Removing the Pi package does not remove an already-installed CBM binary or generated native bridge. ## Package layout ```text extensions/ ├── cbm-graph-context.ts # Thin Pi → official hook-augment adapter ├── cbm-bootstrap.ts # /cbm-install, /cbm-index, and /cbm-status ├── cbm-bridge.ts # Schema-aware native bridge source generator ├── cbm-lifecycle.ts # Native lifecycle phase/outcome seam └── cbm-native.ts # Official installer/CLI process effects skills/ └── codebase-memory/ └── SKILL.md # Codebase Memory workflow AGENTS.md # Optional static managed-context template ``` ## Development ```bash npm install npm run typecheck npm test npm pack --dry-run ``` `package.json` declares the Pi resources under the `pi` key and includes the `pi-package` keyword so the package can be discovered by the [Pi package catalog](https://pi.dev/packages). Pi supplies `@earendil-works/pi-coding-agent` at runtime; it is kept as an optional peer dependency and is not bundled. ## Troubleshooting ### `/cbm-status` says the binary or bridge is unavailable Run `/cbm-install`, or set `CBM_BIN` to an existing executable path. The default managed location is `~/.local/bin/codebase-memory-mcp`. A bridge generated by an unsupported or old CBM release is reported as incompatible rather than silently replaced by a local implementation. ### The current project is not indexed Run `/cbm-index`, or run `/cbm-install --index`. Installation deliberately skips indexing unless you opt in. ### MCP tools are not visible after installation Run `/reload` or restart Pi. The native bridge is generated by `/cbm-install` and loaded at session start. ### The hooks appear silent This is expected outside an indexed project, when the native daemon is unavailable, or when the active release is below the supported range. Set `CBM_HOOKS_DEBUG=1` and restart Pi to inspect adapter failures. ## Compatibility gate The declared supported range currently starts at CBM `0.10.4`; `0.10.4` is the latest tested release. Older or malformed versions are rejected. Newer versions are accepted with a forward-compatibility warning. The generated bridge is a default native Pi extension with schema-aware `cbm_*` tools, lazy advanced tools, bounded output, an embedded official binary path, and machine-readable CLI results. The pinned installer script is SHA-256 verified. Legacy generic `{ args: string }` bridges are reported as incompatible and regenerated. Bootstrap is intentionally macOS/Linux-only in this first lifecycle pass. Hook and status adapters remain path-safe and cross-platform; Windows users should run the official PowerShell installer directly. ## Learn more - [Pi package documentation](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/packages.md) - [Pi package catalog](https://pi.dev/packages) - [codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) - [Report an issue](https://github.com/ramaaudra/pi-codebase-memory-hooks/issues)