pi Coding Agent Extension

Give pi cross-session long-term memory and context takeover. The extension is built on pi's native extension API (pi does not support MCP): recall happens automatically before every prompt, conversation turns are captured after every turn, and OpenViking can replace committed local history with an archive overview in pi's context hook.

Source: examples/pi-coding-agent-extension

How it works

• Session start injects your OpenViking profile block and restores takeover state, including the branch watermark used by pi -c.
• Every prompt runs semantic recall against the OpenViking server and injects matching memories as hidden context.
• Every turn captures user and assistant messages (including structured tool calls) into an OpenViking session; takeover mode commits once synced-token pressure crosses the threshold and then keeps only the recent live tail in model context.
• Context takeover is enabled by default. The context hook injects [OpenViking Session Context] from the latest archive overview before recall is added to the latest user turn.
• Native tools viking_search, viking_read, viking_browse, viking_remember, viking_forget, viking_add_resource, viking_archive_expand let the model query and update memory on demand.
• A footer status segment (OV ✓ …) shows connection and capture state; the /viking command prints status, and /viking commit forces a commit.
• Accidental read/bash calls on viking:// URIs are blocked with a hint pointing back to viking_read / viking_search.

Prerequisites

• pi coding agent (npm i -g @earendil-works/pi-coding-agent)
• An OpenViking HTTP server — verify with curl http://localhost:1933/health

Install

pi shares the unified installer with the other memory plugins. It asks for your language, harnesses, download source, and OpenViking credentials; every step is idempotent.

bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/memory-plugin-shared/install.sh) --harness pi

In regions where GitHub is hard to reach, run the same installer from the Volcengine TOS mirror:

bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)

The installer copies the extension into ~/.pi/agent/extensions/openviking (preserving an existing config.json), registers it with pi install, and configures ~/.openviking/ovcli.conf.

Manual copy from a repo checkout also works:

git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
mkdir -p ~/.pi/agent/extensions
cp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking

Configure

Credentials resolve from OPENVIKING_* environment variables, then ~/.openviking/ovcli.conf, then ~/.openviking/ov.conf — shared with the Claude Code, Codex, and OpenCode plugins. Run the wizard once if you have not configured them yet:

node ~/.pi/agent/extensions/openviking/scripts/setup.mjs

~/.pi/agent/extensions/openviking/config.json holds behavior knobs only, and reinstalls preserve your edits:

{
  "recallLimit": 6,
  "scoreThreshold": 0.35,
  "recallTokenBudget": 2000,
  "profileTokenBudget": 10000,
  "resumeContextBudget": 32000,
  "commitTokenThreshold": 20000,
  "commitKeepRecentCount": 10,
  "takeover": {
    "enabled": true,
    "tokenThreshold": 30000,
    "keepRecentTurns": 3,
    "overviewBudget": 3000,
    "overviewPollMs": 2000,
    "overviewPollMax": 15
  },
  "captureAssistantTurns": true,
  "bypassPatterns": []
}

Takeover is fail-open: if pending writes cannot flush, commit fails, the archive overview is not ready, or the branch fingerprint no longer matches, pi keeps full local history or falls back to its default compaction. Set OV_DEBUG_LOG=/tmp/ov-pi.log when validating boundary advances.

Verify

Start pi. Once connected, the footer shows an OV ✓ status segment, and /viking prints the current session mapping. Ask pi about something you mentioned in an earlier session to confirm recall.

Troubleshooting

Issue	What to check
OV ✗ in the footer or "server not reachable"	curl http://localhost:1933/health; check the endpoint in ~/.openviking/ovcli.conf
Extension does not load	pi list should show extensions/openviking; re-run the installer or pi install ~/.pi/agent/extensions/openviking
Import errors mentioning @mariozechner/*	Stale copy from before pi's move to @earendil-works/* — re-run the installer
401 / 403 from OpenViking	Verify OPENVIKING_API_KEY; for trusted-mode deployments, also verify OPENVIKING_ACCOUNT and OPENVIKING_USER
Recall is empty	Confirm the server has indexed memories and the prompt is longer than minQueryLength

For the full tool, configuration, and design reference, see the extension README.