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.

Tool calls and results are captured as dedicated tool parts, and tool_output is reported verbatim. Truncation is the server's job: output larger than tool_output_externalization.threshold_chars (default 20000) is written to the session's tool-result store, and the part keeps a synopsis stub plus tool_output_ref, so the original stays readable through /api/v1/sessions/{id}/tool-results.

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
pi install ~/.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 and peer-scoping knobs, and reinstalls preserve your edits. Connection and authentication credentials still come from the shared sources above:

{
  "peerId": "",
  "workspacePeer": true,
  "peerSource": "git",
  "recallPeerScope": "all",
  "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": []
}

An explicit peer from OPENVIKING_PEER_ID, ovcli.conf, or ov.conf takes precedence over config.json's peerId. The local peerId takes precedence over the workspace-derived peer, which is used only when workspacePeer is enabled and neither explicit source provides a peer.

peerSource decides how that workspace peer is derived. The default "git" uses the repository's normalized origin URL ([email protected]:volcengine/OpenViking.git becomes github.com-volcengine-openviking), falling back to the repository root path, so every clone, worktree, and subdirectory of one repository shares a single peer; outside a repository no peer is sent at all, and what is remembered there goes to your user-level space at viking://user/<you>/memories. "cwd" restores the earlier behavior — the working directory with every non-alphanumeric character replaced by - — "none" (like OPENVIKING_WORKSPACE_PEER=0) sends no peer at all, and a template such as "team-{dir}", or a list of templates tried in order, builds your own. To give a directory outside a repository its own memory, set OPENVIKING_PEER_ID for it (Give a Directory Its Own Peer).

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 OPENVIKING_DEBUG_LOG=/tmp/ov-pi.log when validating boundary advances; the log is JSON Lines, one record per event. OV_DEBUG_LOG is a deprecated alias that still works.

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

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

See also

• Capability Reference