pi-codebase-memory-hooks

Pi-facing lifecycle, native-tool, and hook adapters for 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

pi install npm:pi-codebase-memory-hooks

You can pin an exact version for reproducible setups:

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:

/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

/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

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:

CBM_BIN=/opt/codebase-memory-mcp pi

CBM_HOOKS_DEBUG=1 pi

Installation alternatives

Install from the Git repository when testing unreleased changes:

pi install git:github.com/ramaaudra/pi-codebase-memory-hooks

Or load a local clone:

pi install /absolute/path/to/pi-codebase-memory-hooks

Remove the Pi package with:

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

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

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. 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
• Pi package catalog
• codebase-memory-mcp
• Report an issue