OpenViking接入Claude Code：让编码Agent拥有持久记忆的完整教程

OpenViking接入Claude Code：让编码Agent拥有持久记忆的完整教程

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking

OpenViking 是一个面向 AI Agent 的自进化上下文数据库（Self-evolving Context Database），统一了 Agent 记忆、知识 RAG 与技能管理。本教程带你用一条命令为 Claude Code 装上"持久记忆"：跨项目、跨会话自动召回相关记忆并捕获新内容，全程无需模型主动调用任何工具。

为什么编码 Agent 需要持久记忆

上面的场景你一定很熟悉：让 AI 助手"按之前的风格把看板做完"，结果它回答"非常抱歉，我没有保留上一次对话的内容"。这就是没有记忆系统时 Coding Agent 的普遍痛点：

• 上下文随会话消失：关掉终端，之前讨论过的架构决策、命名约定、审美偏好全部丢失
• 内置记忆有容量天花板：Claude Code 自带的MEMORY.md是扁平 markdown 文件，约 200 行就要靠手动维护，且只能整体塞进上下文
• 无法跨项目复用经验：在 A 项目里踩过的坑、定下的规范，到 B 项目里又要重新教一遍

OpenViking 的思路是把记忆从"文件"升级为"数据库"：服务端做向量化存储 + LLM 驱动的实体/偏好/事件抽取，客户端每轮对话自动检索相关记忆注入上下文、自动回写新内容。多个 Agent（需求拆解、代码生成、审查）可以共享同一份 MEMORY 记忆体，形成闭环：

插件工作原理：挂载到 Claude Code 的生命周期节点

官方记忆插件（源码位于examples/claude-code-memory-plugin）通过 hooks 挂载到 Claude Code 的多个生命周期节点，实现"无感记忆"：

生命周期节点	插件行为
每次用户输入前	检索 OpenViking，在 token 预算内注入相关记忆块
每轮回复结束后	自动捕获并异步存储新对话内容
会话启动时	注入用户画像与记忆索引
上下文压缩 / 会话结束时	提交所有待归档的消息记录
启动子代理时	为子 Agent 分配相互隔离的记忆会话

记忆在服务端组织成语义化的层级树——偏好、事件、实体各有相关度打分，召回时按需展开：

所有写入操作都是异步的，不会阻塞对话；注入的记忆块在回写前会被自动剥离，避免"记忆自污染"。

一键安装步骤（3 分钟搞定）

1. 运行安装脚本

Claude Code 与 Codex 共用同一个安装脚本，它会依次询问界面语言、要安装的 harness、下载源和 OpenViking 凭据，所有步骤幂等，重复执行安全：

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

脚本会自动完成三件事：写入~/.openviking/ovcli.conf连接配置、从远程 marketplace 安装openviking-memory插件、注册状态栏。若你已在云端或远程部署了 OpenViking 服务，把 API Key 贴进向导即可；纯本地模式（http://127.0.0.1:1933，无鉴权）可直接跳过配置。

提示：也可以先 clone 仓库https://gitcode.com/GitHub_Trending/op/OpenViking后，在仓库根目录执行claude plugin marketplace add "$(pwd)/examples"注册本地 marketplace——开发场景下这样改 hook 脚本下次触发即生效，无需重装。

2. 启动并验证

claude

重启后输入以下命令即可确认接入成功：

• /plugins→ Installed 列表中出现openviking-memory，子项openvikingMCP 显示已连接
• /mcp→ 显示你的服务器 URL 与有效认证信息
• /openviking-memory:ov→ 查看服务健康、召回/注入统计

装好之后，即便在全新会话里随口提起几周前的话题，Claude Code 也能准确"想起来"。你在多轮里随口说的"背景要深色科技感、列表左右分栏"这类偏好，都会被抽取进记忆体，下次直接命中：

状态栏与常用配置

插件会在输入框下方渲染一行状态栏，一眼掌握记忆工作状况：OV ✓ │ ↩ 6 mem · 50ms表示刚注入 6 条记忆、耗时 50ms；OV ✗ offline则表示服务器不可达。

最常用的一批环境变量（完整清单见examples/claude-code-memory-plugin/README_CN.md）：

环境变量	默认值	作用
OPENVIKING_AUTO_RECALL	true	每次输入前自动召回记忆
OPENVIKING_AUTO_CAPTURE	true	每轮结束后自动捕获新记忆
OPENVIKING_BYPASS_SESSION	false	设为1一次性跳过当前会话的全部 hooks
OPENVIKING_DEBUG	false	设为1输出调试日志到~/.openviking/logs/cc-hooks.log

多租户场景再补上OPENVIKING_ACCOUNT和OPENVIKING_USER即可实现团队内按人隔离的记忆空间。

故障排查清单

现象	修复方法
插件未激活	重跑安装脚本，或检查~/.openviking/ovcli.conf是否存在
召回为空	执行curl http://localhost:1933/health检查服务器连通性
MCP 连到 127.0.0.1 而非远程	修正ovcli.conf中的url字段后重启 Claude Code
401 / 403 认证失败	核对 API Key；多租户还需确认 account / user 配置

总结

用一句话回顾：OpenViking 记忆插件 = 一条安装命令 + 零模型改动的持久记忆。它把 Agent 记忆从"手动维护的 markdown 文件"升级为"服务端向量数据库 + 自动抽取"，与 Claude Code 内置MEMORY.md互补共存。核心模块都在examples/claude-code-memory-plugin/目录下，hooks、MCP 代理、配置脚本结构清晰，非常适合想深入定制召回策略的读者阅读。现在就把你的编码 Agent 的记忆升级起来吧 🚀

【免费下载链接】OpenVikingSelf-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.项目地址: https://gitcode.com/GitHub_Trending/op/OpenViking