Skip to content

pi.md

Latest commit

 

History

History
99 lines (72 loc) · 4.51 KB

pi.md

File metadata and controls

99 lines (72 loc) · 4.51 KB
Raw

Pi Coding Agent Integration

Remnic ships a native Pi Coding Agent extension through @remnic/plugin-pi. It uses Pi's extension hooks instead of wrapping Pi with a parallel runtime.

Using the Oh My Pi (omp) fork? The same runtime extension works there via the omp connector — see omp.md.

Install

Start the Remnic daemon, then install the connector:

remnic daemon start
remnic connectors install pi

The installer writes:

  • ~/.pi/agent/extensions/remnic/index.ts — Pi auto-discovery wrapper
  • ~/.pi/agent/extensions/remnic/remnic.config.json — private daemon URL, namespace, and auth token (0600)
  • ~/.pi/agent/extensions/remnic/README.md — local operator notes

To skip writing the Pi extension and only create the connector/token:

remnic connectors install pi --config installExtension=false

To target a non-default daemon or namespace:

remnic connectors install pi \
  --config remnicDaemonUrl=http://127.0.0.1:4318 \
  --config namespace=work

What The Extension Does

  • Uses Pi's context hook to recall relevant Remnic context before an agent turn.
  • Uses agent_end, turn_end, and session_shutdown hooks to observe Pi messages and tool activity with sourceFormat: "pi".
  • Uses session_before_compact to flush Remnic LCM for the active session before Pi compacts context.
  • Records the compaction token delta after Pi produces the compacted checkpoint.
  • Registers Remnic MCP tools as Pi tools when the Remnic daemon token is configured.
  • Persists lightweight dedupe state with Pi custom entries so repeated turns are not re-observed.

Pi Commands

The extension registers these Pi slash commands:

  • /remnic-status — check 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

Configuration

The extension loads configuration from:

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

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 requests
recallMode auto Recall mode: auto, minimal, full, graph_mode, or no_recall
recallTopK 8 Max recalled results
recallBudgetChars 12000 Max 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/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 for recall/observe/compaction/commands
startupRequestTimeoutMs 1000 Shorter timeout for startup-sensitive probes (MCP tools/list registration and the session_start health/status check) so a slow or offline daemon can't stall Pi boot

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

Remote daemons: raise startupRequestTimeoutMs. MCP tool registration happens once at session start (tools/list against the daemon) under this timeout, and a timeout is swallowed silently — the session simply runs without any remnic_* tools, while the separate (lighter) health probe can still report the daemon as ready. The 1000 default is tuned for a localhost daemon; when remnicDaemonUrl points at another machine (Tailscale/MagicDNS, VPN, LAN), one cold DNS resolution or relayed round trip can exceed it. Set "startupRequestTimeoutMs": 10000 for remote daemons, and prefer a stable Tailscale IP over a MagicDNS name on hosts where MagicDNS is not enabled.

API Surface

Pi uses the shared Remnic access layer:

  • POST /engram/v1/recall
  • POST /engram/v1/observe
  • POST /engram/v1/lcm/search
  • POST /engram/v1/lcm/compaction/flush
  • POST /engram/v1/lcm/compaction/record
  • POST /mcp for MCP tool discovery and calls

Both canonical remnic.* MCP tools and legacy engram.* aliases remain available through the daemon.