@remnic/plugin-pi

Remnic memory and context for Pi Coding Agent.

This package is the first-class Remnic extension for Pi. It uses Pi's extension hooks directly, so Remnic can recall context before a model call, observe useful session events after the turn, expose Remnic MCP tools inside Pi, and coordinate Pi compaction with Remnic's long-context memory archive.

What It Does

• Recalls relevant Remnic context in Pi's context hook before an agent turn.
• Observes Pi user, assistant, and tool messages with sourceFormat: "pi".
• Flushes Remnic long-context memory before Pi compacts a session.
• Records Pi compaction checkpoints and token deltas back to Remnic.
• Registers Remnic MCP tools as Pi tools when daemon authentication is configured.
• Persists lightweight dedupe state with Pi custom entries so repeated turns are not re-observed.

Recommended Install

Install through the Remnic CLI. This writes the Pi auto-discovery wrapper, private connector config, and local operator notes into Pi's extension directory.

npm install -g @remnic/cli
remnic daemon start
remnic connectors install pi

The connector installer writes:

• ~/.pi/agent/extensions/remnic/index.ts
• ~/.pi/agent/extensions/remnic/remnic.config.json
• ~/.pi/agent/extensions/remnic/README.md

The generated remnic.config.json contains the Remnic daemon URL, namespace, and connector auth token. Remnic writes it with owner-only permissions where the platform supports file modes.

To install the token and connector config without writing the Pi extension files:

remnic connectors install pi --config installExtension=false

Direct Pi Load

You can also load the npm package directly from Pi after configuring the daemon URL and auth token:

pi -e npm:@remnic/plugin-pi

For direct loading, provide either REMNIC_PI_CONFIG or the default config file at ~/.pi/agent/extensions/remnic/remnic.config.json.

Configuration

The extension loads configuration in this order:

1. REMNIC_PI_CONFIG
2. ~/.pi/agent/extensions/remnic/remnic.config.json

Supported environment variables:

| Variable | Description | | --- | --- | | REMNIC_PI_CONFIG | Path to the Remnic Pi JSON config file | | REMNIC_DAEMON_URL | Remnic daemon URL when the config file does not set remnicDaemonUrl | | REMNIC_PI_AUTH_TOKEN | Connector token when the config file does not set authToken | | PI_CODING_AGENT_DIR | Pi agent home override used to resolve the extension directory | | PI_AGENT_HOME | Alternate Pi agent home override | | PI_HOME | Alternate Pi agent home override |

Supported config keys:

| Key | Default | Description | | --- | --- | --- | | remnicDaemonUrl | http://127.0.0.1:4318 | Remnic HTTP/MCP daemon URL | | authToken | unset | Connector token generated by remnic connectors install pi | | namespace | unset | Remnic namespace for recall, observe, store, and LCM requests | | recallMode | auto | Recall mode: auto, minimal, full, graph_mode, or no_recall | | recallTopK | 8 | Maximum recalled results | | recallBudgetChars | 12000 | Maximum recalled context injected into Pi | | recallEnabled | true | Enable context-hook recall | | observeEnabled | true | Enable Pi turn observation | | observeSkipExtraction | false | Archive observed messages without extraction | | compactionEnabled | true | Enable LCM flush and checkpoint coordination | | mcpToolsEnabled | true | Register Remnic MCP tools as Pi tools | | statusEnabled | true | Set Pi UI status from daemon health | | requestTimeoutMs | 60000 | HTTP/MCP request timeout |

Boolean-like strings such as "false", "0", "no", and "off" are treated as false.

Example:

{
  "remnicDaemonUrl": "http://127.0.0.1:4318",
  "namespace": "work",
  "recallMode": "auto",
  "recallTopK": 8,
  "recallBudgetChars": 12000,
  "recallEnabled": true,
  "observeEnabled": true,
  "compactionEnabled": true,
  "mcpToolsEnabled": true,
  "statusEnabled": true,
  "requestTimeoutMs": 60000
}

Pi Commands

The extension registers these Pi slash commands:

| Command | Description | | --- | --- | | /remnic-status | Check Remnic daemon health | | /remnic-recall <query> | Recall Remnic context for a query | | /remnic-remember <memory> | Explicitly store a memory | | /remnic-lcm-search <query> | Search archived Pi context | | /remnic-why | Inspect the last recall explanation | | /remnic-compact | Request Pi compaction with Remnic LCM coordination |

Security And Boundaries

• Remnic routes Pi traffic with the active Pi session key, working directory, and configured namespace.
• MCP tool calls strip caller-provided sessionKey, namespace, and cwd before the extension injects trusted values from the Pi runtime.
• The connector config stores the daemon token locally and is written with 0600 permissions by the Remnic installer.
• Invalid config values fail closed instead of silently falling back to unsafe defaults.
• The default daemon URL is local: http://127.0.0.1:4318.

Troubleshooting

If Pi cannot reach Remnic, start the daemon and check the configured URL:

remnic daemon start
remnic status

If commands return 401 or MCP tools do not appear, reinstall the connector so the Pi config receives a fresh token:

remnic token generate pi
remnic connectors install pi --force

If Pi uses a non-default home directory, set one of the supported Pi home variables before installing:

PI_CODING_AGENT_DIR=/path/to/pi/agent remnic connectors install pi

Development

From the Remnic monorepo:

pnpm install
pnpm --filter @remnic/plugin-pi test
pnpm --filter @remnic/plugin-pi build

The package exports:

• @remnic/plugin-pi - Pi extension entrypoint and createRemnicPiExtension
• @remnic/plugin-pi/publisher - Remnic connector publisher used by remnic connectors install pi

More

• Full integration guide: https://github.com/joshuaswarren/remnic/blob/main/docs/integration/pi.md
• Remnic: https://github.com/joshuaswarren/remnic
• Pi Coding Agent: https://pi.dev