pi Coding Agent 扩展

为 pi 提供跨会话长期记忆和 context takeover。扩展基于 pi 原生扩展 API 构建（pi 不支持 MCP）：每个 prompt 前自动召回、每个 turn 后自动捕获，并可由 OpenViking 在 pi 的 context hook 中用归档 overview 替换已 commit 的本地历史。

源码：examples/pi-coding-agent-extension

工作方式

Session 开始时注入 OpenViking profile 块，并恢复 takeover 状态，包括 pi -c 续跑所需的 branch 水位。
每个 prompt 向 OpenViking server 做语义召回，把命中的记忆作为隐藏上下文注入。
每个 turn 把用户与助手消息（含结构化工具调用）捕获进 OpenViking session；takeover 模式会在 synced token 压力超过阈值后 commit，并在模型上下文中只保留近期 live tail。
Context takeover 默认开启。context hook 会先注入来自最新 archive overview 的 [OpenViking Session Context]，再把 recall 结果插入最新用户消息。
原生工具 viking_search、viking_read、viking_browse、viking_remember、viking_forget、viking_add_resource、viking_archive_expand 供模型按需查询和写入记忆。
底部状态栏显示 OV ✓ … 连接与捕获状态；/viking 命令查看状态，/viking commit 强制 commit。
模型误用本地 read/bash 读取 viking:// URI 时会被拦截，并提示改用 viking_read / viking_search。

前置条件

pi coding agent（npm i -g @earendil-works/pi-coding-agent）
OpenViking HTTP server——用 curl http://localhost:1933/health 确认可达

安装

pi 与其他记忆插件共用同一个安装器。它会询问语言、要安装的 harness、下载源和 OpenViking 凭据；每一步都是幂等的。

bash

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

在 GitHub 访问困难的地区，可从火山引擎 TOS 镜像运行同一个安装器：

bash

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

安装器会把扩展复制到 ~/.pi/agent/extensions/openviking（保留已有的 config.json），用 pi install 完成注册，并配置 ~/.openviking/ovcli.conf。

也可以从仓库 checkout 手动复制：

bash

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

配置

凭据解析顺序是 OPENVIKING_* 环境变量、~/.openviking/ovcli.conf、~/.openviking/ov.conf——与 Claude Code、Codex、OpenCode 插件共用。尚未配置时可运行一次向导：

bash

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

~/.pi/agent/extensions/openviking/config.json 只保留行为旋钮，重装时会保留你的修改：

json

{
  "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 是 fail-open：如果 pending 写入无法 flush、commit 失败、archive overview 尚未生成，或 branch 指纹不匹配，pi 会继续保留完整本地历史，或回退到默认 compaction。验证边界推进时可设置 OV_DEBUG_LOG=/tmp/ov-pi.log。

验证

启动 pi。连接成功后底部状态栏出现 OV ✓ 段，/viking 会打印当前 session 映射。问 pi 一个你在早前会话里提到过的事情，确认召回生效。

故障排查

问题	排查方向
状态栏显示 `OV ✗` 或提示 "server not reachable"	`curl http://localhost:1933/health`；检查 `~/.openviking/ovcli.conf` 中的 endpoint
扩展没有加载	`pi list` 应能看到 `extensions/openviking`；重跑安装器或执行 `pi install ~/.pi/agent/extensions/openviking`
报错提到 `@mariozechner/*`	pi 迁移到 `@earendil-works/*` 之前的旧副本——重跑安装器
OpenViking 返回 401 / 403	检查 `OPENVIKING_API_KEY`；trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER`
recall 为空	确认 server 中已有记忆，且 prompt 长度超过 `minQueryLength`

完整工具、配置与设计说明见扩展 README。

pi Coding Agent 扩展 ​

工作方式 ​

前置条件 ​

安装 ​

配置 ​

验证 ​

故障排查 ​

pi Coding Agent 扩展

工作方式

前置条件

安装

配置

验证

故障排查