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 权限：

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

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

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

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

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"]
        }
      }
    }
  }
}

.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 重启时执行全量同步

与 OpenClaw 主项目保持一致。