pi-supermemory

Pi coding-agent extension that recalls and captures development memory through Supermemory.

The extension uses Supermemory's v4 API directly. Pi does not expose MCP servers natively, so this package complements the toolbox mcporter MCP bridge instead of replacing it.

Configuration

Set an API key in the Pi runtime environment:

SUPERMEMORY_API_KEY=...

By default, the extension uses a generic Supermemory container:

PI_SUPERMEMORY_CONTAINER_TAG=pi-supermemory

Set PI_SUPERMEMORY_CONTAINER_TAG to your own shared memory container if you want Pi to write into the same namespace as your other agents.

Supported environment variables:

• SUPERMEMORY_API_KEY, SUPERMEMORY_CC_API_KEY, or SUPERMEMORY_OPENCLAW_API_KEY
• PI_SUPERMEMORY_CONFIG
• PI_SUPERMEMORY_CONTAINER_TAG or SUPERMEMORY_CONTAINER_TAG
• PI_SUPERMEMORY_ENABLED
• SUPERMEMORY_API_BASE_URL
• PI_SUPERMEMORY_MAX_RECALL
• PI_SUPERMEMORY_AUTO_RECALL
• PI_SUPERMEMORY_AUTO_CAPTURE

Env vars always win over file-based configuration.

Policy files

The extension discovers and merges config files from the current working directory all the way up to ~. At each directory level it checks (in order of specificity):

.pi/supermemory.json
.pi/pi-supermemory.json
.pi/agent/pi-supermemory.json

Child directories override parent directories. Within the same directory, agent/pi-supermemory.json wins over pi-supermemory.json, which wins over supermemory.json.

Use PI_SUPERMEMORY_CONFIG to point at a single explicit file instead of hierarchical discovery.

Example

{
  "default": {
    "enabled": true,
    "containerTag": "pi-supermemory"
  },
  "directories": {
    "/workspace/app": {
      "containerTag": "app-memory"
    }
  },
  "models": {
    "local/no-memory-model": {
      "enabled": false
    },
    "openai-codex/gpt-5.5": {
      "containerTag": "codex-memory"
    }
  },
  "rules": [
    {
      "path": "/workspace/app",
      "modelPattern": "openai-codex/.*",
      "containerTag": "app-codex-memory",
      "permissions": "read-only"
    }
  ]
}

Override precedence

default -> longest matching directory -> matching model -> matching rule

Model overrides win over directory overrides. Rules win over everything (they combine path + model pattern). Env vars win over all file-based config.

Rules

Rules are the most specific override. Each rule has:

• path — directory scope (applies to this directory and all subdirectories unless overridden)
• modelPattern — optional regex matched against <provider>/<model> identifiers
• containerTag, enabled, maxRecall, etc. — same fields as other overrides
• permissions — "read-only", "write-only", or "read-write" (default)

When permissions is set, it controls whether the extension can search (read) and/or save (write) memories:

• read-only — search works, save is blocked
• write-only — save works, search is blocked
• read-write — both work (default)

If a subfolder defines its own rule, it overrides the parent rule.

Behavior

• Injects relevant Supermemory search results into Pi context before the model runs (if autoRecall is enabled and read is permitted).
• Captures completed user/assistant turns back to the same Supermemory container (if autoCapture is enabled and write is permitted).
• Splits oversized direct-memory writes into ordered chunks under Supermemory's per-memory content limit.
• Reports auto-capture save failures as concise warnings instead of surfacing extension stack traces.
• Registers tools:
  • supermemory_search
  • supermemory_save
  • supermemory_save_file
  • supermemory_status
• Registers command:
  • /supermemory status
  • /supermemory search <query>
  • /supermemory save <content>
  • /supermemory save-file <path> [containerTag]

Local development

npm install
npm test
npm run typecheck

The repo includes .pi/extensions/pi-supermemory/index.ts so Pi's DefaultResourceLoader can discover the extension locally.