OpenClaw Auto Memory Plugin with OpenViking

自动根据当前对话提取关键词从 OpenViking 三层记忆库 (L0/L1/L2) 检索相关记忆，并注入当前对话上下文。

🌟 核心功能

• 智能关键词提取: 自动从用户消息中提取中英文关键词
• 三层记忆检索:
  • L0 (摘要层): .abstract.md - 快速匹配 (~100 tokens)
  • L1 (概述层): .overview.md - 核心信息 (~2000 tokens)
  • L2 (详情层): 完整内容按需加载
• 多维度搜索: 支持 Agent/Resources/User 三层空间
• 上下文注入: 通过 before_prompt_build 将记忆注入 system prompt
• 多模式支持: CLI / HTTP API / 直接文件系统访问

📋 前置要求

1. OpenClaw >= 2026.2.23
2. OpenViking (以下任一方式)
   • OpenViking Server 运行在可访问的端口
   • OpenViking CLI (ov 命令可用)
   • 或直接访问 OpenViking 数据目录

安装 OpenViking

# Python 包
pip install openviking --upgrade

# 验证安装
ov --version

🔧 安装插件

# 复制到 OpenClaw 插件目录
copy . %USERPROFILE%\.openclaw\extensions\auto-memory\

# 重启 OpenClaw
openclaw gateway restart

⚙️ 配置

环境变量

| 变量名 | 说明 | 默认值 | |--------|------|--------| | OPENVIKING_MODE | 访问模式: auto/cli/http/fs | auto | | OPENVIKING_URL | HTTP API 地址 | http://127.0.0.1:1933 | | OPENVIKING_API_KEY | API Key | local-dev-key | | OPENVIKING_DATA_DIR | 数据目录 (FS 模式用) | ~/.openclaw/openviking_data/viking/default |

访问模式说明

| 模式 | 说明 | 适用场景 | |------|------|----------| | auto | 自动选择最佳方式 | 推荐 | | cli | 使用 ov 命令行 | CLI 可用且服务运行 | | http | 直接 HTTP API | 服务运行在可访问端口 | | fs | 直接读文件系统 | 服务不可用但数据存在 |

OpenClaw 配置

在 ~/.openclaw/config.json 中添加：

{
  "plugins": {
    "openclaw-auto-memory": {
      "enabled": true
    }
  }
}

📁 OpenViking 数据结构

插件按以下优先级搜索记忆：

~/.openclaw/openviking_data/viking/default/
├── user/
│   └── default/memories/        # 用户记忆 (最高优先级)
│       ├── entities/
│       ├── events/
│       └── preferences/
├── agent/
│   └── memories/                # Agent 记忆
└── resources/                   # 资源文件
    ├── 2026-02-19-lessons/
    ├── 2026-03-01/
    └── ...

每层目录包含：
├── .abstract.md     # L0: 一句话摘要
├── .overview.md     # L1: 详细概述
└── xxx.md           # L2: 完整内容

🚀 使用示例

测试连接

在 OpenClaw 对话中输入：

/memory-test

输出示例：

✅ CLI: openviking 0.3.3
✅ DataDir: C:\Users\xxx\.openclaw\openviking_data\viking\default
   Contents: agent, resources, session, user
❌ HTTP: Network error

手动检索记忆

/memory 数据库优化

自动检索流程

用户: "帮我优化一下那个数据库查询"
       ↓
[关键词提取] → ["数据库", "查询", "优化"]
       ↓
[L0 搜索] 快速匹配 .abstract.md
       ↓
[L1 加载] 读取匹配的 .overview.md
       ↓
[注入上下文] 添加到 system prompt
       ↓
AI: "基于之前的经验，我们可以添加索引..."

🔍 调试

# 查看 OpenClaw 日志
openclaw logs --follow | findstr "AutoMemory"

# 手动测试 ov 命令
ov find "数据库优化" --uri "viking://user/default/memories"

# 查看数据目录
ov ls viking:// --output json

📝 命令列表

| 命令 | 说明 | |------|------| | /memory <查询> | 手动检索相关记忆 | | /memory-test | 测试 OpenViking 连接状态 |

⚠️ 已知问题与解决

1. OpenClaw Hook Bug

问题: api.registerHook("message:received", ...) 注册后不触发
解决: 使用 api.on("message_received", ...) 替代

2. 服务端口不通

问题: OpenViking 服务 Running 但 1933 端口无法连接
解决: 插件会自动回退到 FS 模式，直接读取数据文件

3. 搜索结果为空

检查清单:

• [ ] 数据目录是否存在 .abstract.md 文件
• [ ] 关键词是否与内容匹配
• [ ] 使用 /memory-test 检查连接状态

🤝 贡献

欢迎提交 Issue 和 PR！

📄 许可证

MIT License