metainsight-context-engine

v0.1.0

Published

8 days ago

Cloud-based context engine for token-efficient memory management (backed by Tencent COS CI)

0High
0Medium
0Low

shawnmzhang

context-engine memory cloud tencent-cos openclaw metainsight ai-memory vector-search

MetaInsight Context Engine

Token-efficient context management with cloud-based memory retrieval, powered by Tencent COS + CI.

简介

MetaInsight Context Engine 是一个 OpenClaw 上下文引擎插件，通过腾讯云 COS（对象存储）和 CI（数据万象）提供云端语义记忆检索能力。它可以将本地记忆文件自动同步到云端，并在每轮对话前智能召回与当前问题最相关的历史记忆、图片和文档，注入到 LLM 的上下文中。

核心能力

🧠 记忆自动召回 — 每轮对话前从云端向量数据库检索相关记忆片段
📁 本地记忆同步 — 自动将 MEMORY.md、每日日志和引用的图片/文档同步到云端
🔍 多模态搜索 — 支持文本语义搜索（DocSearch）和图片搜索（ImageSearch）
🛠 LLM 工具 — 注册 cloud_memory_search 工具，LLM 可主动搜索云端记忆
☁️ 基础设施自动化 — 启动时自动创建存储桶、数据集和绑定，全部幂等

前置要求

OpenClaw >= 2026.3.11
腾讯云账号，需获取以下凭证：
- SecretId / SecretKey — API 密钥管理
- APPID — 同一页面可查看

⚠️ 需要上传到 CI 数据万象。 ⚠️ 目前智能检索仅支持 ap-beijing、ap-shanghai、ap-chengdu 三个区域。

权限要求

插件需要腾讯云账号具备以下 API 权限：

| 权限类别 | 所需权限说明 | | -------------- | ------------------------------------------------------------------------------------------- | | 存储桶操作 | 创建存储桶（PUT Bucket）、查询存储桶（GET Bucket）、设置存储桶配置等 | | 文件操作 | 上传文件（PUT Object）、下载文件（GET Object）、删除文件（DELETE Object）、列出文件等 | | 数据集操作 | 创建数据集（CreateDataset）、绑定数据集（CreateDatasetBinding）、搜索数据集等 CI 接口 |

🔑 子账号用户注意：如果您使用的是 CAM 子账号（子用户），需要联系主账号管理员为其授予上述 COS + CI 相关权限。可通过 CAM 策略管理绑定预设策略 QcloudCOSFullAccess + QcloudCIFullAccess，或创建自定义策略授权所需接口。

存储桶与数据集

推荐使用自动创建：插件启动时会自动检测并创建所需的存储桶（Bucket）和数据集（Dataset），无需手动操作。只需配置好必填的凭证信息即可。

如果您选择手动指定已有的存储桶或数据集名称，请确保：

地域一致 — 存储桶和数据集必须位于同一地域，且仅支持 ap-beijing、ap-shanghai、ap-chengdu
存储桶名称格式 — COS 存储桶的完整名称格式为 {bucket}-{appId}，配置中只需填写 bucket 部分（如 openclaw-metainsight），插件会自动拼接 APPID
数据集绑定 — 手动创建的数据集需要正确绑定到对应的 COS 存储桶路径前缀，否则搜索功能无法正常工作

安装

方式一：通过 OpenClaw CLI 安装（推荐）

openclaw plugins install metainsight-context-engine

更新插件

openclaw plugins update metainsight-context-engine

方式二：手动安装

将插件目录放置到 OpenClaw 的 extensions/ 目录下，然后安装依赖：

cd extensions/metainsight-context-engine
npm install --omit=dev

配置

编辑 ~/.openclaw/openclaw.json，添加插件配置：

{
  "plugins": {
    "slots": {
      "contextEngine": "metainsight-context-engine"
    },
    "entries": {
      "metainsight-context-engine": {
        "enabled": true,
        "config": {
          // === 必填 ===
          "secretId": "AKIDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "secretKey": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "appId": "1253311026",

          // === 可选（建议不填, 以下均为默认值）===
          "bucket": "openclaw-metainsight", // 推荐留空或使用默认值，插件会自动创建
          "region": "ap-beijing", // 推荐留空或使用默认值，插件会自动创建
          "datasetName": "", // 推荐留空或使用默认值，插件会自动创建
          "agentId": "", // 默认取当前 agent 上下文中的 agentId
          "memoryAutoRecall": true,
          "localMemorySync": true,
          "maxRecallResults": 3,
          "minScore": 0.5,
          "matchThreshold": 60,

          // === 同步文件类型（建议不填, 默认值如下，可按需增减）===
          "syncFileExtensions": [".png", ".jpg", ".jpeg", ".gif", ".bmp", ".webp", ".svg", ".ico", ".tiff", ".tif", ".avif", ".heic", ".heif", ".pdf", ".doc", ".docx", ".xls", ".xlsx", ".ppt", ".pptx", ".txt", ".csv", ".md", ".rtf"]
        }
      }
    }
  }
}

配置项一览

必填项

| 配置项 | 类型 | 说明 | | ----------- | ------ | ------------------------------- | | secretId | string | 腾讯云 SecretId | | secretKey | string | 腾讯云 SecretKey | | appId | string | 腾讯云 APPID（如 1253311026） |

核心配置(建议不填, 使用插件全自动处理)

| 配置项 | 类型 | 默认值 | 说明 | | ------------- | ------ | ---------------------- | ----------------------------------------------------------------------------------------- | | agentId | string | "" | Agent ID，用于多 agent 数据隔离。留空则自动取当前 agent 上下文中的 agentId | | bucket | string | openclaw-metainsight | COS 存储桶名称（推荐使用默认值，插件自动创建；手动指定需确保地域一致） | | region | string | ap-beijing | COS 区域，仅支持 ap-beijing / ap-shanghai / ap-chengdu | | datasetName | string | "" | CI 数据集名称（推荐使用默认值，插件自动创建；手动指定需确保与存储桶同地域且正确绑定） |

记忆召回(建议不填, 使用插件全自动处理)

| 配置项 | 类型 | 默认值 | 说明 | | ------------------ | ------- | ------ | ------------------------------------- | | memoryAutoRecall | boolean | true | 每轮对话前自动从云端召回相关记忆 | | maxRecallResults | number | 3 | 每轮最多召回的记忆片段数 | | minScore | number | 0.5 | 搜索结果最低相关性分数（0-1） | | matchThreshold | number | 60 | 匹配阈值 0-100（CI 推荐 80，默认 60） |

本地记忆同步(建议不填, 使用插件全自动处理)

| 配置项 | 类型 | 默认值 | 说明 | | -------------------- | -------- | ------ | ------------------------------------------- | | localMemorySync | boolean | true | 启用本地记忆文件同步到云端 | | syncLongTermMemory | boolean | true | 同步 MEMORY.md（需 localMemorySync=true） | | syncDailyLogs | boolean | true | 同步每日日志（需 localMemorySync=true） | | syncFileExtensions | string[] | 见下方 | 扫描并上传的文件扩展名 |

.png, .jpg, .jpeg, .gif, .bmp, .webp, .svg, .ico, .tiff, .tif, .avif, .heic, .heif,
.pdf, .doc, .docx, .xls, .xlsx, .ppt, .pptx, .txt, .csv, .md, .rtf

工作原理

启动阶段

Gateway 启动
    │
    ├─ 注册 CloudContextEngine
    ├─ 注册 cloud_memory_search 工具
    ├─ 注册 Hooks（llm_input / llm_output / before_prompt_build / after_tool_call）
    ├─ 启动文件系统监听（MEMORY.md + memory/ 目录）
    │
    └─ 异步初始化（fire-and-forget）：
         ├─ 清除磁盘哈希缓存（确保全量重新评估）
         ├─ 初始化 COS SDK + Bootstrap 云端资源
         │    ├─ 创建存储桶（如不存在）
         │    └─ 创建 3 个数据集 + COS 绑定
         │         ├─ {agentId}-memory  (DocSearch  → workspace/)
         │         ├─ {agentId}-image   (ImageSearch → asset/)
         │         └─ {agentId}-document (DocSearch  → asset/)
         │
         └─ 全量本地记忆同步（最多重试 3 次）
              ├─ 扫描 MEMORY.md + memory/*.md
              ├─ SHA-256 哈希比对 → 仅上传变更文件
              └─ 提取并上传引用的图片/文档资产

每轮对话

用户发送消息
    │
    ▼
before_prompt_build Hook
    ├─ 清理用户消息（去除时间戳、元数据）
    ├─ 并行搜索 3 个数据集（memory / image / document）
    └─ 将检索结果注入上下文：
         ├─ 记忆片段 → 替换系统提示中的 "Memory Recall" 层
         ├─ 能力声明 → prependSystemContext
         └─ 图片/文档 → prependContext（用户消息前）
    │
    ▼
LLM 生成响应
    ├─ llm_input  → 缓存系统提示（供下轮检索用）
    └─ llm_output → 保存响应到调试文件
    │
    ▼
如果 LLM 写入了记忆文件
    └─ after_tool_call → 立即同步到云端
    │
    ▼
文件系统监听检测到记忆文件变更
    └─ 1 秒去抖后自动同步到云端
    │
    ▼
每 5 轮触发一次全量本地记忆同步

云端存储结构

{bucket}-{appId}/
└── openclaw-{agentId}/
    ├── workspace/          ← 记忆文件（memory 数据集绑定此前缀）
    │   └── memory/
    │       ├── MEMORY.md
    │       └── 2026-03-17.md
    └── asset/              ← 图片和文档（image + document 数据集绑定此前缀）
        ├── screenshot.png
        └── report.pdf

调试

插件会在以下位置保存调试文件：

~/.openclaw/debug/system-prompts/ — 每轮的完整系统提示
~/.openclaw/debug/llm-outputs/ — LLM 的原始响应

哈希缓存文件：

~/.openclaw/.sync-hash-cache.json — 本地文件的 SHA-256 哈希缓存（启动时自动清空）

常见问题

传了图片 / 下载了文件，但云端搜索没有返回结果

插件的自动同步依赖 LLM 在操作完成后主动写入短期记忆文件（memory/YYYY-MM-DD.md），然后 after_tool_call Hook 才会将变更同步到云端。但 LLM 有时会在完成用户请求后直接回复，跳过写入记忆这一步，导致云端没有对应的记录。

解决办法：直接告诉龙虾立即同步，例如：

"立即同步短期记忆" "把刚才的操作写入今天的短期记忆"

龙虾收到指令后会将操作记录写入当日日志，插件会自动检测到文件变更并上传到云端，后续对话即可召回。

自动同步的触发时机（无需手动干预的场景）：

LLM 通过 write_to_file / replace_in_file 等工具写入了记忆文件 → after_tool_call Hook 立即同步
每 5 轮对话自动触发一次全量本地记忆同步
Gateway 重启时执行全量同步

依赖服务

| 服务 | 用途 | | --------------------------------------------------- | -------------------------------- | | 腾讯云 COS | 对象存储，存放记忆文件和资产 | | 腾讯云 CI | 数据万象，提供向量索引和语义搜索 |

许可

与 OpenClaw 主项目保持一致。