OpenViking Pi 编码 Agent 扩展为 Pi 会话接入长期语义记忆与上下文接管【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本篇技术指南以 OpenViking 仓库中 examples/pi-coding-agent-extension/README.md 为骨架系统讲解如何为 Piearendil-works/pi-coding-agent接入 OpenViking 长期记忆每次提示前自动同步召回、每轮对话后自动捕获沉淀并通过context钩子让 OpenViking 以归档概览接管长上下文。读完本文你将掌握完整的安装配置流程、全部配置项语义、事件驱动的运行架构、召回/捕获/上下文接管三条核心链路的实现原理以及故障排查方法。背景为什么需要为 Pi 接 OpenVikingPi 自带基于MEMORY.md的扁平文件记忆但它以整份文件载入上下文、无法跨项目共享、容量受限于上下文窗口。OpenViking 作为面向 AI Agent 的上下文数据库提供向量检索 结构化抽取 服务端存储天然弥补这些短板。Pi 扩展的设计吸取了 OpenViking 全部三个 Agent 插件OpenClaw、Claude Code、Hermes的经验教训来自 OpenClaw同步召回、阈值触发提交、双作用域搜索来自 Claude Code 插件最成熟、生产级紧凑前提交、子 Agent 隔离、全面剥离注入块、会话恢复再水合、分数阈值、bypass 模式来自 Hermes反模式过期预取用上一轮查询召回、晚一轮注入被明确摒弃。具体设计见 DESIGN.md上下文接管层见 TAKEOVER.md。前置要求OpenViking 服务器需支持viking://~主目录别名home alias。召回通过viking://~/memories与viking://~/skills指向调用者自己的上下文空间无 uid 的viking://user/memories简写会被新版本服务器拒绝。快速开始前置条件已安装 Pi 编码 Agentnpm i -g earendil-works/pi-coding-agentNode.js 18扩展的 TypeScript 运行时依赖Pi 本身也要求 18一个可达的 OpenViking 服务器本地或远程。1. 准备 OpenViking 服务器本地启动或指向远程服务器均可默认端口为1933本地模式无需认证。两种方式的完整步骤见 快速入门指南。启动后验证curl http://localhost:1933/health # 或你的远程 URL2. 安装扩展使用共享安装器bash examples/memory-plugin-shared/install.sh --harness pi安装器会把扩展复制到~/.pi/agent/extensions/openviking并通过pi install注册下次启动pi时自动加载。所有 TypeScript 文件由 Pi 内置的jiti转译器直接加载——无需构建步骤、零 npm 依赖、不依赖 MCP 服务器全部通信走 OpenViking REST API见 client.ts 中基于 Node 内置fetch实现的OVClient。3. 配置可选凭据按以下优先级解析OPENVIKING_*环境变量 →~/.openviking/ovcli.conf→~/.openviking/ov.conf。需要配置远程服务器时运行配置向导node ~/.pi/agent/extensions/openviking/scripts/setup.mjs~/.pi/agent/extensions/openviking/config.json负责行为与 peer 作用域旋钮连接与认证凭据仍来自上述共享来源。仓库自带的默认配置见 config.json{ enabled: true, syncTurns: true, peerId: , workspacePeer: true, recallPeerScope: all, recallTokenBudget: 2000, scoreThreshold: 0.35, minQueryLength: 3, profileTokenBudget: 10000, resumeContextBudget: 32000, commitTokenThreshold: 20000, takeover: { enabled: true, tokenThreshold: 30000, keepRecentTurns: 3, overviewBudget: 3000, overviewPollMs: 2000, overviewPollMax: 15 } }凭据环境变量一览环境变量含义OPENVIKING_URLOpenViking 服务器 URLOPENVIKING_API_KEY/OPENVIKING_BEARER_TOKENBearer tokenOPENVIKING_ACCOUNT受信模式下的 accountOPENVIKING_USER受信模式下的 userOPENVIKING_PEER_ID行为者 peer idOPENVIKING_WORKSPACE_PEER默认根据工作区 git 身份派生行为者 peer设0则不发送 peerOPENVIKING_RECALL_PEER_SCOPEall以分数惩罚召回其他项目记忆actor仅见全局加当前项目OPENVIKING_DEBUG_LOG将 JSON Lines 调试记录写入该路径。OV_DEBUG_LOG为兼容旧配置的废弃别名4. 启动 Pipi启动后扩展显示[OpenViking]状态行viking_search、viking_remember等工具自动注册记忆跨会话持久化无需额外设置。配置参考所有字段位于config.json默认值如下。config.ts 中loadConfig会先合并config.json与默认值再叠加环境变量最后用clampInt/clampNumber对数值型字段做范围钳制越界值自动回退到边界或默认值并用resolveEffectivePeerId解析最终 peer。调谐字段字段默认值说明enabledtrue设false完全禁用扩展Peer 作用域字段默认值说明peerId本地显式 peer 回退值共享凭据来源优先workspacePeertrue未设显式 peer 时从工作区 git 身份派生 peerfalse不发送 peerrecallPeerScopeallactor严格按当前 peer 召回all宽泛召回召回调谐字段默认值说明recallTokenBudget2000内联召回内容的 token 预算recallMaxContentChars500每条搜索结果的内容上限字符recallPreferAbstracttrue可用时优先取 L0 摘要而非 L2 全文recallLimit10遗留的配额缩放输入会换算为六个编码类别配额不是最终条数上限scoreThreshold0.35最低相关度分数0–1minQueryLength3查询短于 N 字符时跳过召回recallLedgertrue持久化注入块并重新应用到历史用户消息保持 provider 前缀缓存命中召回注入账本Recall LedgerPi 的context钩子交给扩展的是会话消息的深拷贝因此注入的openviking-context块永远不会写回会话存储。若不补偿每次请求的历史与上一轮 provider 实际看到的都不一致严格前缀的提示缓存DeepSeek 等 OpenAI 兼容 provider会从第一条注入消息起全部 miss#4137。账本以“稳定的 Pi entry id 内容哈希”为键把哪个块注入到哪条用户消息记录在~/.openviking/pi-recall-ledger/session.json并在每次请求时重放使前缀跨轮保持逐字节一致同时最新消息仍获得基于当前查询的全新召回。设recallLedger: false或OPENVIKING_RECALL_LEDGER0可关闭。丢失账本文件只会损失一次缓存命中下一轮自动对齐稳定的 entry id 让被压缩保留的消息和/tree分支即使活动上下文位置变化也能恢复各自原本的注入块。注意recallLimit从 1 到 5 的显式取值会产生总配额 6 的效果因为每个编码类别都保留一个检索槽位。需要精确上限的直接 API 集成应配置类别quotas对应实现见 shared/recall-core.mjs 的CODING_QUOTA_WEIGHTS与scaleQuotas。捕获调谐字段默认值说明captureModesemanticsemantic始终捕获或keyword触发式捕获captureMaxLength24000捕获决策用的净化文本最大长度captureAssistantTurnstrue是否包含 assistant 轮文本 工具 USE 输入captureToolResultsfalse是否包含工具结果输出噪声大默认关闭captureToolMaxChars1000000单个工具部件tool_output的保护上限超长输出由服务器外部化commitTokenThreshold20000触发客户端提交的待处理 token 阈值commitKeepRecentCount10提交后保留的活动尾部条数上下文接管Context Takeover接管默认开启。OpenViking 提交归档历史并轮询会话概览后context钩子把已被覆盖的对话轮次替换为一条合成的[OpenViking Session Context]用户消息同时保留最近的活动尾部。完整模型、运行流程与失败模式见 TAKEOVER.md。字段默认值说明takeover.enabledtrue允许 OpenViking 通过context钩子拥有长上下文takeover.tokenThreshold30000触发提交与边界推进的已同步 token 压力takeover.keepRecentTurns3完整保真的最近用户轮次数takeover.overviewBudget3000注入的归档概览 token 预算takeover.overviewPollMs2000提交后轮询概览的间隔takeover.overviewPollMax15提交后最多轮询次数超限则 fail-open注入调谐字段默认值说明profileTokenBudget10000用户画像块的 token 预算resumeContextBudget32000会话恢复时归档概览的 token 预算其他字段默认值说明bypassPatterns[]跳过扩展处理的 glob 模式按process.cwd()匹配logLevelerrorsilent、error或infodebugLogPath写入 JSON Lines 调试记录的路径为空则禁用Peer 身份机制一个仓库一份记忆扩展默认从进程工作区的 git 身份派生 peer优先取仓库的规范化originURL否则取仓库根路径。git 仓库外不发送 peer那里记住的内容进入用户级空间viking://user/you/memories。命名规则示例gitgithub.com:volcengine/OpenViking.git变为github.com-volcengine-openviking路径回退沿用旧规则——每个非字母数字字符替换为-如/Users/x/Dev/OpenViking变为-Users-x-Dev-OpenViking。因此同一个仓库在子目录、worktree、克隆副本、不同机器上保持同一个 peer而 fork 的不同 origin 则彼此隔离。实现见 shared/workspace-peer.mjsgit预设在{git_remote}解析失败后回退{git_root}。几点关键行为扩展不读取工作区.openviking/config.json写在那里的peer.id无效生效的 peer 通过X-OpenViking-Actor-Peer头发送并作为peer_id存入被捕获的会话消息见 client.ts 的headers()优先级共享凭据来源的显式 peerOPENVIKING_PEER_ID、ovcli.conf、ov.confconfig.json的peerId 工作区派生旧路径派生 peer 下写入的记忆在默认宽泛召回扫描用户下所有 peer下仍可达。召回默认宽泛模式全局记忆、当前工作区、其他工作区记忆都可能被召回其中其他工作区带分数惩罚且渲染靠后。设OPENVIKING_RECALL_PEER_SCOPEactor进入隔离模式仅见全局加当前工作区。当单台 bot 服务多个真实用户时如 zouk、vikingbot、AstrBot务必使用隔离模式并显式指定 actor peer否则一个人的记忆会被召回进另一个人的会话。架构与事件流┌──────────────────────────────────────────────────────┐ │ Pi Coding Agent │ │ │ │ session_start before_agent_start context turn_end│ │ session_before_compact session_shutdown │ └────────┬──────────────────┬───────────┬──────────────┘ │ │ │ │ ┌───────────────▼───────────▼────────┐ │ │ extension modules (.ts) │ │ │ client / sync / recall / tools │──────► OpenViking │ └─────────────────────────────────────┘ Server │ (HTTP API) │ ┌──────────────────────────────────────┐ └──► 7 registered LLM tools │ │ viking_search / viking_read / … │ └──────────────────────────────────────┘扩展是单个 TypeScript 文件目录由 Pi 的jiti转译器加载。事件与扩展动作的对应关系入口见 index.tsPi 事件扩展动作session_start健康检查 → 派生 OV 会话 → 构建画像上下文 → 恢复接管状态before_agent_start为pi -c做幂等启动 将当前提示排入召回队列contextUI 渲染后执行当前提示召回然后注入接管与召回上下文turn_end提取分支条目 → 写入或排队 OV 消息 → 可能推进边界session_before_compact接管模式下返回 OV 概览作为 pi 压缩摘要否则提交待处理消息session_shutdown持久化接管状态或做最终非接管提交值得注意的工程细节session_start中的 OV 链路健康检查、会话创建、画像构建对远程服务器约耗时 2 秒若阻塞session_start会拖慢每次 Pi 启动因此start()用startPromise记忆化并 fire-and-forgetbefore_agent_start会等待同一在途链路保证首轮仍能拿到画像与召回。召回同步而非过期与 Hermes 的过期预取不同用上一轮查询召回、晚一轮注入本扩展通过context事件用当前用户提示检索 OpenViking。Pi 在钩子触发前已渲染用户提交的消息所以召回延迟不会把消息挡在屏幕外结果仍以openviking-context块注入同一个模型轮次。带来的收益会话首轮立即获得相关上下文会话内的话题切换得到正确召回无需等待下一轮才看到相关记忆。实现上召回让服务器一次请求组装上下文块POST /api/v1/search/searchmodecontext、purposecodingtoken 预算、详情分级、跨轮去重与其他 harness 完全共享不支持该端点的部署回退到/api/v1/search/recall该结果会被缓存只有首轮承担探针开销。回退与能力探测的完整降级逻辑含context-face与peer-scope磁盘记忆见 shared/recall-core.mjs。记忆污染防护在推送轮次到 OpenViking 之前共享捕获净化逻辑会剥掉openviking-context等注入块防止“召回上下文被当作用户消息再捕获回去”的自引用污染循环。接管模式下适配器改用忠实捕获faithful capture致谢与短轮次也会保留因为它们之后可能只通过 OV 归档概览呈现空文本、斜杠命令与 OpenViking 状态消息仍被过滤。非接管模式下的shouldCapture()过滤管线则更为激进长度上下限、斜杠命令、纯标点、纯疑问句、keyword 触发词模式详见 DESIGN.md。工具调用保留工具捕获保留结构化的工具部件有界的输入与输出记忆抽取器看到 Agent 做了什么而不索引无界的原始输出。assistant 轮还会追加工具摘要行如[assistant used tools: read, edit, bash]让抽取器理解 Agent 的实际行为序列。LLM 工具扩展注册 7 个工具Pi 的模型可随时调用参数 schema 与执行逻辑见 tools.ts工具说明viking_search在记忆、资源与技能间做语义搜索viking_read按 abstract / overview / full 三级读取viking://URIviking_browse列出目录内容或 stat 一个viking://URIviking_remember将事实或偏好存入长期记忆以[Remember — category]前缀消息写入提交时由抽取器拾取viking_forget按 URI 或搜索查询删除记忆查询删除要求最强匹配分数 0.8viking_add_resource将 URL 摄入 OpenViking 供索引检索HTTP only服务器不支持本地文件路径viking_archive_expand把归档会话展开回原始对话读取viking://session/{id}的 overview另外可在 Pi 聊天中输入/viking命令显示连接状态、会话信息并支持commit参数触发手动同步提交见 index.ts 的registerCommand。与 Pi 内置记忆对比Pi 内置MEMORY.md文件系统记忆。本扩展是它的补充而非替代特性内置MEMORY.mdOpenViking 扩展存储扁平 Markdown向量库 结构化抽取检索整份载入上下文语义相似度 排序 token 预算作用域单项目跨项目、跨会话、跨 Agent容量受上下文限制无限服务端存储抽取手动规则LLM 驱动的实体 / 偏好 / 事件抽取子 Agent与父进程相同隔离会话 类型化 Agent 命名空间与 Claude Code 插件对比两者共享同一核心设计互相借鉴特性Claude Code 插件Pi 扩展架构钩子脚本.mjs MCP 委派原生 TypeScript 扩展召回时机同步UserPromptSubmit 钩子同步context 事件工具交付OV 服务器 MCP 端点16 个工具pi.registerTool()7 个工具写入路径分离 worker异步异步 promisePi 事件循环安装claude plugin install 安装脚本复制目录 → 自动发现记忆索引无仅手电筒式搜索模型有地图模型——模型知道 OV 知道什么子 Agent 隔离显式钩子管理天然进程级隔离扩展结构examples/pi-coding-agent-extension/ ├── config.json # 默认配置编辑以定制 ├── config.ts # 配置加载器默认值 config.json 合并 ├── client.ts # OpenViking HTTP 客户端fetch 响应包装 ├── sync.ts # 轮次捕获、写队列、会话生命周期 ├── recall.ts # 带排序与预算的同步召回 ├── takeover.ts # 围绕 lib/takeover-core.mjs 的薄 Pi 绑定 ├── tools.ts # 7 个注册工具 /viking 命令 ├── lib/takeover-core.mjs # 纯上下文接管状态机 ├── index.ts # 扩展入口事件处理器 ├── TAKEOVER.md # 上下文接管设计 └── README.md全部 TypeScript 文件由 Pi 内置jiti转译器直接加载——除 Node.js 外零依赖。完整设计规范三个 OV 插件的对比、详细事件流、设计理由、为任意 Agent harness 构建 OV 扩展的实现指导见 DESIGN.md。故障排查症状原因解决办法扩展未加载config.json 中enabled: false设enabled: true首个提示无召回OpenViking 服务器未运行或 URL 错误curl http://localhost:1933/healthpi -c恢复后工具不显示已知 Pi 问题恢复时工具不重注册已内置解决——工具在before_agent_start注册加载时崩溃OV 服务器 URL 错误或网络问题检查logLevel与服务器可达性无记忆抽取OV 配置的嵌入/抽取模型错误检查 OV 的embedding/vlm配置接管从不推进待处理 addMessage 重放、提交或概览轮询失败设OPENVIKING_DEBUG_LOG/tmp/ov-pi.log并重试/viking commit接管层还有一组专门的失败模式健康检查失败则保持断开但 Pi 正常运行addMessage 重放失败则边界不推进、本地全量历史保持可见提交失败则待处理 token 压力保持概览未就绪则下次阈值或手动/viking commit重试分支指纹不匹配则边界重置为 0 直到下次成功推进压缩接管失败则返回undefined走 Pi 默认压缩并配有真实端到端验证脚本OPENVIKING_URL... OPENVIKING_API_KEY... E2E_LLM_API_KEY... bash examples/pi-coding-agent-extension/scripts/e2e-live.sh支持通过E2E_LLM_BASE_URL、E2E_LLM_MODEL、E2E_LLM_API覆盖任意 OpenAI 或 Anthropic 兼容端点。许可证Apache-2.0与 OpenViking 项目一致。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenViking Pi 编码 Agent 扩展：为 Pi 会话接入长期语义记忆与上下文接管
OpenViking Pi 编码 Agent 扩展为 Pi 会话接入长期语义记忆与上下文接管【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking本篇技术指南以 OpenViking 仓库中 examples/pi-coding-agent-extension/README.md 为骨架系统讲解如何为 Piearendil-works/pi-coding-agent接入 OpenViking 长期记忆每次提示前自动同步召回、每轮对话后自动捕获沉淀并通过context钩子让 OpenViking 以归档概览接管长上下文。读完本文你将掌握完整的安装配置流程、全部配置项语义、事件驱动的运行架构、召回/捕获/上下文接管三条核心链路的实现原理以及故障排查方法。背景为什么需要为 Pi 接 OpenVikingPi 自带基于MEMORY.md的扁平文件记忆但它以整份文件载入上下文、无法跨项目共享、容量受限于上下文窗口。OpenViking 作为面向 AI Agent 的上下文数据库提供向量检索 结构化抽取 服务端存储天然弥补这些短板。Pi 扩展的设计吸取了 OpenViking 全部三个 Agent 插件OpenClaw、Claude Code、Hermes的经验教训来自 OpenClaw同步召回、阈值触发提交、双作用域搜索来自 Claude Code 插件最成熟、生产级紧凑前提交、子 Agent 隔离、全面剥离注入块、会话恢复再水合、分数阈值、bypass 模式来自 Hermes反模式过期预取用上一轮查询召回、晚一轮注入被明确摒弃。具体设计见 DESIGN.md上下文接管层见 TAKEOVER.md。前置要求OpenViking 服务器需支持viking://~主目录别名home alias。召回通过viking://~/memories与viking://~/skills指向调用者自己的上下文空间无 uid 的viking://user/memories简写会被新版本服务器拒绝。快速开始前置条件已安装 Pi 编码 Agentnpm i -g earendil-works/pi-coding-agentNode.js 18扩展的 TypeScript 运行时依赖Pi 本身也要求 18一个可达的 OpenViking 服务器本地或远程。1. 准备 OpenViking 服务器本地启动或指向远程服务器均可默认端口为1933本地模式无需认证。两种方式的完整步骤见 快速入门指南。启动后验证curl http://localhost:1933/health # 或你的远程 URL2. 安装扩展使用共享安装器bash examples/memory-plugin-shared/install.sh --harness pi安装器会把扩展复制到~/.pi/agent/extensions/openviking并通过pi install注册下次启动pi时自动加载。所有 TypeScript 文件由 Pi 内置的jiti转译器直接加载——无需构建步骤、零 npm 依赖、不依赖 MCP 服务器全部通信走 OpenViking REST API见 client.ts 中基于 Node 内置fetch实现的OVClient。3. 配置可选凭据按以下优先级解析OPENVIKING_*环境变量 →~/.openviking/ovcli.conf→~/.openviking/ov.conf。需要配置远程服务器时运行配置向导node ~/.pi/agent/extensions/openviking/scripts/setup.mjs~/.pi/agent/extensions/openviking/config.json负责行为与 peer 作用域旋钮连接与认证凭据仍来自上述共享来源。仓库自带的默认配置见 config.json{ enabled: true, syncTurns: true, peerId: , workspacePeer: true, recallPeerScope: all, recallTokenBudget: 2000, scoreThreshold: 0.35, minQueryLength: 3, profileTokenBudget: 10000, resumeContextBudget: 32000, commitTokenThreshold: 20000, takeover: { enabled: true, tokenThreshold: 30000, keepRecentTurns: 3, overviewBudget: 3000, overviewPollMs: 2000, overviewPollMax: 15 } }凭据环境变量一览环境变量含义OPENVIKING_URLOpenViking 服务器 URLOPENVIKING_API_KEY/OPENVIKING_BEARER_TOKENBearer tokenOPENVIKING_ACCOUNT受信模式下的 accountOPENVIKING_USER受信模式下的 userOPENVIKING_PEER_ID行为者 peer idOPENVIKING_WORKSPACE_PEER默认根据工作区 git 身份派生行为者 peer设0则不发送 peerOPENVIKING_RECALL_PEER_SCOPEall以分数惩罚召回其他项目记忆actor仅见全局加当前项目OPENVIKING_DEBUG_LOG将 JSON Lines 调试记录写入该路径。OV_DEBUG_LOG为兼容旧配置的废弃别名4. 启动 Pipi启动后扩展显示[OpenViking]状态行viking_search、viking_remember等工具自动注册记忆跨会话持久化无需额外设置。配置参考所有字段位于config.json默认值如下。config.ts 中loadConfig会先合并config.json与默认值再叠加环境变量最后用clampInt/clampNumber对数值型字段做范围钳制越界值自动回退到边界或默认值并用resolveEffectivePeerId解析最终 peer。调谐字段字段默认值说明enabledtrue设false完全禁用扩展Peer 作用域字段默认值说明peerId本地显式 peer 回退值共享凭据来源优先workspacePeertrue未设显式 peer 时从工作区 git 身份派生 peerfalse不发送 peerrecallPeerScopeallactor严格按当前 peer 召回all宽泛召回召回调谐字段默认值说明recallTokenBudget2000内联召回内容的 token 预算recallMaxContentChars500每条搜索结果的内容上限字符recallPreferAbstracttrue可用时优先取 L0 摘要而非 L2 全文recallLimit10遗留的配额缩放输入会换算为六个编码类别配额不是最终条数上限scoreThreshold0.35最低相关度分数0–1minQueryLength3查询短于 N 字符时跳过召回recallLedgertrue持久化注入块并重新应用到历史用户消息保持 provider 前缀缓存命中召回注入账本Recall LedgerPi 的context钩子交给扩展的是会话消息的深拷贝因此注入的openviking-context块永远不会写回会话存储。若不补偿每次请求的历史与上一轮 provider 实际看到的都不一致严格前缀的提示缓存DeepSeek 等 OpenAI 兼容 provider会从第一条注入消息起全部 miss#4137。账本以“稳定的 Pi entry id 内容哈希”为键把哪个块注入到哪条用户消息记录在~/.openviking/pi-recall-ledger/session.json并在每次请求时重放使前缀跨轮保持逐字节一致同时最新消息仍获得基于当前查询的全新召回。设recallLedger: false或OPENVIKING_RECALL_LEDGER0可关闭。丢失账本文件只会损失一次缓存命中下一轮自动对齐稳定的 entry id 让被压缩保留的消息和/tree分支即使活动上下文位置变化也能恢复各自原本的注入块。注意recallLimit从 1 到 5 的显式取值会产生总配额 6 的效果因为每个编码类别都保留一个检索槽位。需要精确上限的直接 API 集成应配置类别quotas对应实现见 shared/recall-core.mjs 的CODING_QUOTA_WEIGHTS与scaleQuotas。捕获调谐字段默认值说明captureModesemanticsemantic始终捕获或keyword触发式捕获captureMaxLength24000捕获决策用的净化文本最大长度captureAssistantTurnstrue是否包含 assistant 轮文本 工具 USE 输入captureToolResultsfalse是否包含工具结果输出噪声大默认关闭captureToolMaxChars1000000单个工具部件tool_output的保护上限超长输出由服务器外部化commitTokenThreshold20000触发客户端提交的待处理 token 阈值commitKeepRecentCount10提交后保留的活动尾部条数上下文接管Context Takeover接管默认开启。OpenViking 提交归档历史并轮询会话概览后context钩子把已被覆盖的对话轮次替换为一条合成的[OpenViking Session Context]用户消息同时保留最近的活动尾部。完整模型、运行流程与失败模式见 TAKEOVER.md。字段默认值说明takeover.enabledtrue允许 OpenViking 通过context钩子拥有长上下文takeover.tokenThreshold30000触发提交与边界推进的已同步 token 压力takeover.keepRecentTurns3完整保真的最近用户轮次数takeover.overviewBudget3000注入的归档概览 token 预算takeover.overviewPollMs2000提交后轮询概览的间隔takeover.overviewPollMax15提交后最多轮询次数超限则 fail-open注入调谐字段默认值说明profileTokenBudget10000用户画像块的 token 预算resumeContextBudget32000会话恢复时归档概览的 token 预算其他字段默认值说明bypassPatterns[]跳过扩展处理的 glob 模式按process.cwd()匹配logLevelerrorsilent、error或infodebugLogPath写入 JSON Lines 调试记录的路径为空则禁用Peer 身份机制一个仓库一份记忆扩展默认从进程工作区的 git 身份派生 peer优先取仓库的规范化originURL否则取仓库根路径。git 仓库外不发送 peer那里记住的内容进入用户级空间viking://user/you/memories。命名规则示例gitgithub.com:volcengine/OpenViking.git变为github.com-volcengine-openviking路径回退沿用旧规则——每个非字母数字字符替换为-如/Users/x/Dev/OpenViking变为-Users-x-Dev-OpenViking。因此同一个仓库在子目录、worktree、克隆副本、不同机器上保持同一个 peer而 fork 的不同 origin 则彼此隔离。实现见 shared/workspace-peer.mjsgit预设在{git_remote}解析失败后回退{git_root}。几点关键行为扩展不读取工作区.openviking/config.json写在那里的peer.id无效生效的 peer 通过X-OpenViking-Actor-Peer头发送并作为peer_id存入被捕获的会话消息见 client.ts 的headers()优先级共享凭据来源的显式 peerOPENVIKING_PEER_ID、ovcli.conf、ov.confconfig.json的peerId 工作区派生旧路径派生 peer 下写入的记忆在默认宽泛召回扫描用户下所有 peer下仍可达。召回默认宽泛模式全局记忆、当前工作区、其他工作区记忆都可能被召回其中其他工作区带分数惩罚且渲染靠后。设OPENVIKING_RECALL_PEER_SCOPEactor进入隔离模式仅见全局加当前工作区。当单台 bot 服务多个真实用户时如 zouk、vikingbot、AstrBot务必使用隔离模式并显式指定 actor peer否则一个人的记忆会被召回进另一个人的会话。架构与事件流┌──────────────────────────────────────────────────────┐ │ Pi Coding Agent │ │ │ │ session_start before_agent_start context turn_end│ │ session_before_compact session_shutdown │ └────────┬──────────────────┬───────────┬──────────────┘ │ │ │ │ ┌───────────────▼───────────▼────────┐ │ │ extension modules (.ts) │ │ │ client / sync / recall / tools │──────► OpenViking │ └─────────────────────────────────────┘ Server │ (HTTP API) │ ┌──────────────────────────────────────┐ └──► 7 registered LLM tools │ │ viking_search / viking_read / … │ └──────────────────────────────────────┘扩展是单个 TypeScript 文件目录由 Pi 的jiti转译器加载。事件与扩展动作的对应关系入口见 index.tsPi 事件扩展动作session_start健康检查 → 派生 OV 会话 → 构建画像上下文 → 恢复接管状态before_agent_start为pi -c做幂等启动 将当前提示排入召回队列contextUI 渲染后执行当前提示召回然后注入接管与召回上下文turn_end提取分支条目 → 写入或排队 OV 消息 → 可能推进边界session_before_compact接管模式下返回 OV 概览作为 pi 压缩摘要否则提交待处理消息session_shutdown持久化接管状态或做最终非接管提交值得注意的工程细节session_start中的 OV 链路健康检查、会话创建、画像构建对远程服务器约耗时 2 秒若阻塞session_start会拖慢每次 Pi 启动因此start()用startPromise记忆化并 fire-and-forgetbefore_agent_start会等待同一在途链路保证首轮仍能拿到画像与召回。召回同步而非过期与 Hermes 的过期预取不同用上一轮查询召回、晚一轮注入本扩展通过context事件用当前用户提示检索 OpenViking。Pi 在钩子触发前已渲染用户提交的消息所以召回延迟不会把消息挡在屏幕外结果仍以openviking-context块注入同一个模型轮次。带来的收益会话首轮立即获得相关上下文会话内的话题切换得到正确召回无需等待下一轮才看到相关记忆。实现上召回让服务器一次请求组装上下文块POST /api/v1/search/searchmodecontext、purposecodingtoken 预算、详情分级、跨轮去重与其他 harness 完全共享不支持该端点的部署回退到/api/v1/search/recall该结果会被缓存只有首轮承担探针开销。回退与能力探测的完整降级逻辑含context-face与peer-scope磁盘记忆见 shared/recall-core.mjs。记忆污染防护在推送轮次到 OpenViking 之前共享捕获净化逻辑会剥掉openviking-context等注入块防止“召回上下文被当作用户消息再捕获回去”的自引用污染循环。接管模式下适配器改用忠实捕获faithful capture致谢与短轮次也会保留因为它们之后可能只通过 OV 归档概览呈现空文本、斜杠命令与 OpenViking 状态消息仍被过滤。非接管模式下的shouldCapture()过滤管线则更为激进长度上下限、斜杠命令、纯标点、纯疑问句、keyword 触发词模式详见 DESIGN.md。工具调用保留工具捕获保留结构化的工具部件有界的输入与输出记忆抽取器看到 Agent 做了什么而不索引无界的原始输出。assistant 轮还会追加工具摘要行如[assistant used tools: read, edit, bash]让抽取器理解 Agent 的实际行为序列。LLM 工具扩展注册 7 个工具Pi 的模型可随时调用参数 schema 与执行逻辑见 tools.ts工具说明viking_search在记忆、资源与技能间做语义搜索viking_read按 abstract / overview / full 三级读取viking://URIviking_browse列出目录内容或 stat 一个viking://URIviking_remember将事实或偏好存入长期记忆以[Remember — category]前缀消息写入提交时由抽取器拾取viking_forget按 URI 或搜索查询删除记忆查询删除要求最强匹配分数 0.8viking_add_resource将 URL 摄入 OpenViking 供索引检索HTTP only服务器不支持本地文件路径viking_archive_expand把归档会话展开回原始对话读取viking://session/{id}的 overview另外可在 Pi 聊天中输入/viking命令显示连接状态、会话信息并支持commit参数触发手动同步提交见 index.ts 的registerCommand。与 Pi 内置记忆对比Pi 内置MEMORY.md文件系统记忆。本扩展是它的补充而非替代特性内置MEMORY.mdOpenViking 扩展存储扁平 Markdown向量库 结构化抽取检索整份载入上下文语义相似度 排序 token 预算作用域单项目跨项目、跨会话、跨 Agent容量受上下文限制无限服务端存储抽取手动规则LLM 驱动的实体 / 偏好 / 事件抽取子 Agent与父进程相同隔离会话 类型化 Agent 命名空间与 Claude Code 插件对比两者共享同一核心设计互相借鉴特性Claude Code 插件Pi 扩展架构钩子脚本.mjs MCP 委派原生 TypeScript 扩展召回时机同步UserPromptSubmit 钩子同步context 事件工具交付OV 服务器 MCP 端点16 个工具pi.registerTool()7 个工具写入路径分离 worker异步异步 promisePi 事件循环安装claude plugin install 安装脚本复制目录 → 自动发现记忆索引无仅手电筒式搜索模型有地图模型——模型知道 OV 知道什么子 Agent 隔离显式钩子管理天然进程级隔离扩展结构examples/pi-coding-agent-extension/ ├── config.json # 默认配置编辑以定制 ├── config.ts # 配置加载器默认值 config.json 合并 ├── client.ts # OpenViking HTTP 客户端fetch 响应包装 ├── sync.ts # 轮次捕获、写队列、会话生命周期 ├── recall.ts # 带排序与预算的同步召回 ├── takeover.ts # 围绕 lib/takeover-core.mjs 的薄 Pi 绑定 ├── tools.ts # 7 个注册工具 /viking 命令 ├── lib/takeover-core.mjs # 纯上下文接管状态机 ├── index.ts # 扩展入口事件处理器 ├── TAKEOVER.md # 上下文接管设计 └── README.md全部 TypeScript 文件由 Pi 内置jiti转译器直接加载——除 Node.js 外零依赖。完整设计规范三个 OV 插件的对比、详细事件流、设计理由、为任意 Agent harness 构建 OV 扩展的实现指导见 DESIGN.md。故障排查症状原因解决办法扩展未加载config.json 中enabled: false设enabled: true首个提示无召回OpenViking 服务器未运行或 URL 错误curl http://localhost:1933/healthpi -c恢复后工具不显示已知 Pi 问题恢复时工具不重注册已内置解决——工具在before_agent_start注册加载时崩溃OV 服务器 URL 错误或网络问题检查logLevel与服务器可达性无记忆抽取OV 配置的嵌入/抽取模型错误检查 OV 的embedding/vlm配置接管从不推进待处理 addMessage 重放、提交或概览轮询失败设OPENVIKING_DEBUG_LOG/tmp/ov-pi.log并重试/viking commit接管层还有一组专门的失败模式健康检查失败则保持断开但 Pi 正常运行addMessage 重放失败则边界不推进、本地全量历史保持可见提交失败则待处理 token 压力保持概览未就绪则下次阈值或手动/viking commit重试分支指纹不匹配则边界重置为 0 直到下次成功推进压缩接管失败则返回undefined走 Pi 默认压缩并配有真实端到端验证脚本OPENVIKING_URL... OPENVIKING_API_KEY... E2E_LLM_API_KEY... bash examples/pi-coding-agent-extension/scripts/e2e-live.sh支持通过E2E_LLM_BASE_URL、E2E_LLM_MODEL、E2E_LLM_API覆盖任意 OpenAI 或 Anthropic 兼容端点。许可证Apache-2.0与 OpenViking 项目一致。【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考