Integrations

Pi Package

Give the Pi coding agent durable continuity with Basic Memory: recall and capture commands, model-callable tools, and opt-in automatic recall and capture.

The Basic Memory package for Pi (@basicmemory/pi-basic-memory) gives Pi durable continuity: capture a working thread, start fresh later, and recall the decision, rationale, blocker, and next step from a real Basic Memory note. It works over the bm CLI by default, or over MCP through pi-mcp-adapter.

The package is open source and lives in the basic-memory monorepo — browse the source in integrations/pi. New in v0.24.

Requires Pi 0.85.1 or newer, Node.js 22.19 or newer, and the Basic Memory CLI (v0.24+) on Pi's PATH.

Installation

Preview the install

bm install pi --dry-run

The preview lists the files it would copy into ~/.pi/agent/packages/basic-memory and the pi install command it would run to register them.

Install

bm install pi --yes

Use --local to register the package in the current workspace's .pi/settings.json instead of for your user. If a file you already have differs from the bundled copy, the install stops; review it and rerun with --replace. Your Basic Memory config and credentials aren't read or changed.

Configure the project

Restart Pi and run /skill:basic-memory-pi-setup, or create .pi/basic-memory.json in the project yourself (see Configuration).

Verify

Run /bm-status to see the configured project, workspace trust, and whether automatic recall and capture are on.

You can also install from a checkout of the repository with pi install /path/to/basic-memory/integrations/pi.

Configuration

Create .pi/basic-memory.json in a project you trust:

{
  "transport": "cli",
  "project": "main",
  "captureFolder": "pi/sessions",
  "useHookFlow": true,
  "autoRecall": true,
  "autoCapture": true
}

Key	Default	What it does
`transport`	`cli`	`cli` runs the `bm` CLI; `mcp` uses `pi-mcp-adapter`
`project` / `projectId`	unset	The Basic Memory project to use (`projectId` wins when both are set)
`captureFolder`	`pi/sessions`	Folder for Pi session checkpoints
`recallTimeframe`	`7d`	Search window for recall
`useHookFlow`	`true`	Use the shared `bm hook ... --harness pi` lifecycle commands for automatic recall and capture
`autoRecall`	`true`	Recall once before the first agent turn
`autoCapture`	`true`	Capture after settled turns and before compaction
`captureMinChars`	`80`	Minimum session text before auto-capture
`bmPath` / `bmCommand`	`bm`	Override how the CLI is launched

The package never changes your global Basic Memory default project.

Workspace trust

Automatic recall and capture run only when both of these are true:

.pi/basic-memory.json names a project, and
the workspace is trusted: BASIC_MEMORY_PI_TRUST_WORKSPACE=1 is set in Pi's environment.

BASIC_MEMORY_PI_TRUST_WORKSPACE=1 pi

Without them, /bm-status reports automatic recall and capture as blocked and says why, and manual recall shows setup guidance — nothing falls through to an unrelated default project. Set autoRecall or autoCapture to false and /bm-status reports them as off (configured).

Executable overrides from a workspace config (bmPath, bmCommand) are also gated: set BASIC_MEMORY_PI_TRUST_BM_COMMAND=1 only in workspaces you trust.

Commands and tools

Command or tool	What it does
`/bm-status`	Show the configured project (or `unconfigured`), workspace trust, and whether automatic recall and capture are on, off, or blocked
`/bm-recall [topic]`	Search recent Pi checkpoints and insert them as fenced reference data
`/bm-capture [title]`	Save the current working thread as a `pi_session` note
`bm_recall`	Recall tool the model can call
`bm_capture`	Capture tool the model can call

The package also ships two Pi skills, basic-memory-pi and basic-memory-pi-setup, with bundled references for writing notes, capturing, resuming, and tracking tasks.

Recalled notes are inserted as reference data, not instructions.

MCP mode

To use the Basic Memory MCP server instead of the CLI, install the adapter:

pi install npm:pi-mcp-adapter

Then set the transport:

{
  "transport": "mcp",
  "project": "my-project"
}

MCP mode requires an explicit project and BASIC_MEMORY_PI_TRUST_WORKSPACE=1. If the adapter isn't installed, Pi keeps working and /bm-status reports the missing dependency.

Next Steps

Tau

Recall and capture for the Tau coding agent.

Harness Capture

The shared bm hook lifecycle Pi uses.

Agent Skills

Instruction packs that teach agents to use Basic Memory well.

GitHub Repository

Source code and full configuration reference.

Edit this pageorReport an issue

Tau Extension

Give the Tau coding agent persistent Basic Memory: startup recall, knowledge capture as work settles, checkpoints before compaction, and shared session, task, and decision notes.

Code Project Documentation

Keep living project documentation alongside your code using Basic Memory and your AI assistant