Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

docs: add Claude Code Memory Plugin example link and Chinese docs (#1228)

灿烂甜菜31577dae5f10
diff --git a/README.md b/README.md
index 3ea775d60..50d60a04d 100644
--- a/README.md
+++ b/README.md
@@ -534,6 +534,8 @@ After integrating OpenViking:
👉 **[View: OpenCode Memory Plugin Example](examples/opencode-memory-plugin/README.md)**
+👉 **[View: Claude Code Memory Plugin Example](examples/claude-code-memory-plugin/README.md)**
+
--
## Core Concepts
diff --git a/README_CN.md b/README_CN.md
index c64168e64..c63d14361 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -559,6 +559,8 @@ ov chat
👉 **[查看:OpenCode 记忆插件示例](examples/opencode-memory-plugin/README_CN.md)**
+👉 **[查看:Claude Code 记忆插件示例](examples/claude-code-memory-plugin/README_CN.md)**
+
## VikingBot 部署详情
OpenViking 有一个类似 nanobot 的机器人用于交互工作,现已可用。
diff --git a/README_JA.md b/README_JA.md
index d867e1531..9ebc971e6 100644
--- a/README_JA.md
+++ b/README_JA.md
@@ -495,6 +495,8 @@ OpenViking統合後:
👉 **[参照: OpenCodeメモリプラグインの例](examples/opencode-memory-plugin/README.md)**
+👉 **[参照: Claude Codeメモリプラグインの例](examples/claude-code-memory-plugin/README.md)**
+
--
## コアコンセプト
diff --git a/examples/claude-code-memory-plugin/README_CN.md b/examples/claude-code-memory-plugin/README_CN.md
new file mode 100644
index 000000000..6fef5cf95
--- /dev/null
+++ b/examples/claude-code-memory-plugin/README_CN.md
@@ -0,0 +1,305 @@
+# OpenViking Memory Plugin for Claude Code
+
+为 Claude Code 提供长期语义记忆功能,基于 [OpenViking](https://github.com/volcengine/OpenViking) 构建。
+
+> 移植自 [OpenClaw context-engine plugin](../openclaw-plugin/),并适配 Claude Code 的插件架构(MCP + hooks)。
+
+## 架构
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│ Claude Code │
+└────────┬──────────────────────────────────────┬──────────────────┘
+ │ │
+ UserPromptSubmit Stop
+ (命令 hook) (命令 hook)
+ │ │
+ ┌──────▼──────────┐ ┌────────▼─────────┐
+ │ auto-recall.mjs│ │ auto-capture.mjs │
+ │ │ │ │
+ │ stdin: │ │ stdin: │
+ │ user_prompt │ │ transcript_path │
+ │ │ │ │
+ │ 1. 解析查询 │ │ 1. 读取对话记录 │
+ │ 2. 搜索 OV │ │ 2. 提取对话轮次 │
+ │ 3. 排序筛选 │ │ 3. 捕获检查 │
+ │ 4. 读取内容 │ │ 4. 会话/提取 │
+ │ │ │ │
+ │ stdout: │ │ stdout: │
+ │ systemMessage │ │ decision:approve│
+ │ (记忆内容) │ │ (自动捕获) │
+ └──────┬──────────┘ └────────┬─────────┘
+ │ │
+ │ ┌──────────────┐ │
+ └────────►│ OpenViking │◄────────────┘
+ │ Server │
+ MCP tools ────►│ (Python) │
+ └──────────────┘
+
+ ┌──────────────────────────────────────┐
+ │ MCP Server (memory-server.ts) │
+ │ 显式使用的工具: │
+ │ • memory_recall (手动搜索) │
+ │ • memory_store (手动存储) │
+ │ • memory_forget (删除记忆) │
+ │ • memory_health (健康检查) │
+ └──────────────────────────────────────┘
+```
+
+在 `SessionStart` 时,当 Claude 暴露 `CLAUDE_PLUGIN_DATA` 变量时,插件会将其 Node 运行时引导至 `${CLAUDE_PLUGIN_DATA}/runtime`。否则,它会回退到 `~/.openviking/claude-code-memory-plugin/runtime`。这使得 MCP 适配器可以在 marketplace 安装后自愈,而无需将 `node_modules` 检入插件源码树。
+
+## 工作原理
+
+### 运行时引导(透明,会话启动时)
+
+1. Claude 启动会话 → `SessionStart` hook 触发
+2. `bootstrap-runtime.mjs` 计算 `package.json`、`package-lock.json` 和 `servers/memory-server.js` 的哈希值
+3. 如果运行时目录缺失或过期,将运行时文件复制到该目录
+4. 在该运行时目录中运行 `npm ci --omit=dev`
+5. 写入 `install-state.json`,以便后续会话跳过重新安装
+6. MCP 启动器也可以在需要时自行引导,如果它在 `SessionStart` 之前启动
+
+### 自动召回(透明,每轮对话)
+
+1. 用户提交消息 → `UserPromptSubmit` hook 触发
+2. `auto-recall.mjs` 从 stdin 读取 `user_prompt`
+3. 调用 OpenViking `/api/v1/search/find` 搜索 `viking://user/memories` 和 `viking://agent/memories`
+4. 使用查询感知评分对结果排序(叶子节点增强、偏好增强、时间增强、词法重叠)
+5. 读取排名靠前的叶子记忆的完整内容
+6. 通过 `systemMessage` 返回 → Claude 透明地看到 `<relevant-memories>` 上下文
+
+### 自动捕获(透明,停止时)
+
+1. Claude 完成回复 → `Stop` hook 触发
+2. `auto-capture.mjs` 从 stdin 读取 `transcript_path`
+3. 解析对话记录并提取最近的对话轮次,默认只保留用户轮次
+4. 对选定的用户轮次运行捕获决策逻辑(语义模式或关键词触发)
+5. 创建 OpenViking 临时会话 → 添加消息 → 提取记忆
+6. 记忆自动存储,无需 Claude 工具调用
+
+### MCP 工具(显式,按需)
+
+MCP 服务器提供工具,用于 Claude 或用户需要显式记忆操作时:
+- **memory_recall** — 手动语义搜索
+- **memory_store** — 手动记忆存储
+- **memory_forget** — 按 URI 或查询删除记忆
+- **memory_health** — 检查服务器状态
+
+## 与 OpenClaw 插件的区别
+
+| 方面 | OpenClaw 插件 | Claude Code 插件 |
+|------|--------------|------------------|
+| 自动召回 | `before_prompt_build` hook + `prependContext` | `UserPromptSubmit` 命令 hook + `systemMessage` |
+| 自动捕获 | `afterTurn` context-engine 方法 | `Stop` 命令 hook + 对话记录解析 |
+| 显式工具 | `api.registerTool()` | MCP 服务器(stdio 传输)|
+| 透明性 | 两者完全透明 | 两者完全透明 — 无额外 Claude 工具调用 |
+| 进程管理 | 插件管理本地子进程 | 用户单独启动 OpenViking |
+| 配置 | 带UI提示的插件配置模式 | 单一 JSON 配置文件 |
+| JS 运行时依赖 | 打包在插件进程中 | 首次 `SessionStart` 时安装到 `${CLAUDE_PLUGIN_DATA}` 或 `~/.openviking/claude-code-memory-plugin` |
+
+## 快速开始
+
+### 1. 安装 OpenViking
+
+```bash
+pip install openviking
+```
+
+Mac 用户
+```bash
+brew install pipx
+pipx ensurepath
+pipx install openviking
+```
+
+### 2. 创建配置
+
+如果还没有 `~/.openviking/ov.conf`,请创建:
+
+```bash
+mkdir -p ~/.openviking
+# 编辑 ov.conf:设置你的 embedding API key、model 等
+vim ~/.openviking/ov.conf
+```
+
+#### `~/.openviking/ov.conf`(本地模式)
+
+```json
+{
+ "server": { "host": "127.0.0.1", "port": 1933 },
+ "storage": {
+ "workspace": "/home/yourname/.openviking/data",
+ "vectordb": { "backend": "local" },
+ "agfs": { "backend": "local", "port": 1833 }
+ },
+ "embedding": {
+ "dense": {
+ "provider": "volcengine",
+ "api_key": "<your-ark-api-key>",
+ "model": "doubao-embedding-vision-251215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3",
+ "dimension": 1024,
+ "input": "multimodal"
+ }
+ },
+ "vlm": {
+ "provider": "volcengine",
+ "api_key": "<your-ark-api-key>",
+ "model": "doubao-seed-2-0-pro-260215",
+ "api_base": "https://ark.cn-beijing.volces.com/api/v3"
+ }
+}
+```
+
+> `root_api_key`:设置后,所有 HTTP 请求必须携带 `X-API-Key` 头。本地模式默认为 `null`(禁用认证)。
+
+可选添加 `claude_code` 部分用于插件特定覆盖:
+
+```json
+{
+ "claude_code": {
+ "agentId": "claude-code",
+ "recallLimit": 6,
+ "captureMode": "semantic",
+ "captureTimeoutMs": 30000,
+ "captureAssistantTurns": false,
+ "logRankingDetails": false
+ }
+}
+```
+
+### 3. 启动 OpenViking
+
+```bash
+openviking-server
+```
+
+### 4. 安装插件
+
+```bash
+/plugin marketplace add Castor6/openviking-plugins
+/plugin install claude-code-memory-plugin@openviking-plugin
+```
+
+### 5. 启动新的 Claude 会话
+
+```bash
+claude
+```
+
+首次会话会自动准备 MCP 适配器的 Node 运行时。默认使用 `${CLAUDE_PLUGIN_DATA}/runtime`,如果 Claude 未注入 `CLAUDE_PLUGIN_DATA` 则回退到 `~/.openviking/claude-code-memory-plugin/runtime`。marketplace 安装后无需手动 `npm install`。
+
+## 配置
+
+使用与 OpenViking 服务器和 OpenClaw 插件相同的 `~/.openviking/ov.conf`。
+
+通过环境变量覆盖路径:
+```bash
+export OPENVIKING_CONFIG_FILE="~/custom/path/ov.conf"
+```
+
+**连接信息**从 ov.conf 的 `server` 部分读取:
+
+| ov.conf 字段 | 用作 | 描述 |
+|-------------|------|------|
+| `server.host` + `server.port` | `baseUrl` | 派生 `http://{host}:{port}` |
+| `server.root_api_key` | `apiKey` | 认证用的 API key |
+
+**插件覆盖**放在可选的 `claude_code` 部分:
+
+| 字段 | 默认值 | 描述 |
+|------|-------|------|
+| `agentId` | `claude-code` | 用于记忆隔离的代理标识 |
+| `timeoutMs` | `15000` | 召回/通用请求的 HTTP 请求超时(毫秒)|
+| `autoRecall` | `true` | 每次用户提示时启用自动召回 |
+| `recallLimit` | `6` | 每轮注入的最大记忆数 |
+| `scoreThreshold` | `0.01` | 最小相关度分数(0-1)|
+| `minQueryLength` | `3` | 跳过非常短查询的召回 |
+| `logRankingDetails` | `false` | 为召回输出每个候选的 `ranking_detail` 日志;否则只输出简洁的排序摘要 |
+| `autoCapture` | `true` | 停止时启用自动捕获 |
+| `captureMode` | `semantic` | `semantic`(始终捕获)或 `keyword`(触发式)|
+| `captureMaxLength` | `24000` | 捕获的最大文本长度 |
+| `captureTimeoutMs` | `30000` | 自动捕获请求的 HTTP 请求超时(毫秒)|
+| `captureAssistantTurns` | `false` | 在自动捕获输入中包含助手轮次;默认只捕获用户 |
+
+## Hook 超时
+
+内置 hooks 有意设计为非对称:
+
+| Hook | 默认超时 | 说明 |
+|------|---------|------|
+| `SessionStart` | `120s` | 首次会话可能需要时间将运行时依赖安装到 `${CLAUDE_PLUGIN_DATA}` |
+| `UserPromptSubmit` | `8s` | 自动召回应保持快速,以免阻塞提示提交 |
+| `Stop` | `45s` | 给自动捕获足够时间完成并持久化增量状态 |
+
+保持 `claude_code.captureTimeoutMs` 低于 `Stop` hook 超时,以便脚本可以优雅失败并仍能更新其增量状态。
+
+## 调试日志
+
+当启用 `claude_code.debug` 或 `OPENVIKING_DEBUG=1` 时,hook 日志写入 `~/.openviking/logs/cc-hooks.log`。
+
+- `auto-recall` 现在默认记录关键阶段和简洁的 `ranking_summary`。
+- 仅在需要每个候选评分日志时设置 `claude_code.logRankingDetails=true`。
+- 对于深度诊断,推荐使用独立脚本 `scripts/debug-recall.mjs` 和 `scripts/debug-capture.mjs`,而不是一直开启详细的 hook 日志。
+
+## 运行时依赖引导
+
+插件将其运行时 npm 依赖保存在专用运行时目录中:
+
+- 优先使用 `${CLAUDE_PLUGIN_DATA}/runtime`,回退到 `~/.openviking/claude-code-memory-plugin/runtime`
+- `SessionStart` 使用 `npm ci --omit=dev` 安装或刷新依赖
+- `install-state.json` 记录活动清单和服务器哈希
+- MCP 启动也可以自行执行相同引导,因此首次运行安装不依赖 hook 顺序
+- 如果安装失败,Claude Code 仍可使用;只有显式 MCP 工具在下次成功引导前不可用
+
+## 插件结构
+
+```
+claude-code-memory-plugin/
+├── .claude-plugin/
+│ └── plugin.json # 插件清单
+├── hooks/
+│ └── hooks.json # SessionStart + UserPromptSubmit + Stop hooks
+├── scripts/
+│ ├── config.mjs # 共享配置加载器
+│ ├── runtime-common.mjs # 共享运行时路径 + 安装状态助手
+│ ├── bootstrap-runtime.mjs # SessionStart 运行时依赖安装器
+│ ├── start-memory-server.mjs # 从 plugin data runtime 启动 MCP 服务器
+│ ├── auto-recall.mjs # 自动召回 hook 脚本
+│ └── auto-capture.mjs # 自动捕获 hook 脚本
+├── servers/
+│ └── memory-server.js # 编译后的 MCP 服务器
+├── src/
+│ └── memory-server.ts # MCP 服务器源码
+├── .mcp.json # MCP 服务器定义
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## 与 Claude Code 内置记忆的关系
+
+Claude Code 有使用 `MEMORY.md` 文件的内置自动记忆系统。本插件与该系统**互补**:
+
+| 特性 | 内置记忆 | OpenViking 插件 |
+|------|---------|----------------|
+| 存储 | 扁平 markdown 文件 | 向量数据库 + 结构化提取 |
+| 搜索 | 完全加载到上下文 | 语义相似度搜索 |
+| 范围 | 每项目 | 跨项目、跨会话 |
+| 容量 | ~200 行(上下文限制)| 无限(服务器端存储)|
+| 提取 | 手动规则 | AI 驱动的实体提取 |
+
+## 故障排除
+
+| 症状 | 原因 | 解决方案 |
+|------|------|---------|
+| 未召回记忆 | 服务器未运行 | 启动 OpenViking 服务器 |
+| 自动捕获提取 0 条 | API key / model 错误 | 检查 `ov.conf` embedding 配置 |
+| MCP 工具不可用 | 首次运行时安装失败 | 启动新 Claude 会话重试引导,检查 SessionStart stderr 查看 npm 失败原因 |
+| 旧上下文被重复自动捕获 | `Stop` hook 在增量状态保存前超时 | 保持 `captureAssistantTurns=false`,提高 `Stop` hook 超时,并保持 `captureTimeoutMs` 低于该 hook 超时 |
+| Hook 超时 | 服务器慢/不可达 | 增加 `hooks/hooks.json` 中的 `Stop` hook 超时,并调整 `ov.conf` 中的 `claude_code.captureTimeoutMs` |
+| 日志太详细 | 启用了详细召回排序日志 | 正常使用时保持 `logRankingDetails=false`,使用调试脚本进行一次性检查 |
+
+## 许可证
+
+Apache-2.0 — 与 [OpenViking](https://github.com/volcengine/OpenViking) 相同。