memory-lancedb-pro

memory-lancedb-pro

面向 OpenClaw AI Agent 的生产级长期记忆系统（v1.1.0-beta.8）。使用 LanceDB 提供持久化智能记忆存储，支持向量与 BM25 混合检索、LLM 驱动的智能提取、Weibull 衰减生命周期管理，以及多范围隔离。

完整技术细节（阈值、公式、数据库架构、源文件映射）请参阅 references/full-reference.md。

---

应用最优配置（分步工作流）

当用户说“帮我启用最佳配置”“应用最优配置”或类似的话时，请严格按照以下流程操作：

步骤 1 — 展示配置方案并让用户选择

清晰地比较以下三个方案，然后请用户选择一个：

---

方案 A — 🏆 全面强大（品质最佳）

• 嵌入：Jina jina-embeddings-v5-text-small（任务感知型，1024 维）
• 重排器：Jina jina-reranker-v3（交叉编码器，使用同一密钥）
• 大模型：OpenAI gpt-4o-mini（智能提取）
• 所需密钥：JINA_API_KEY + OPENAI_API_KEY
• 获取密钥：Jina → https://jina.ai/api-key · OpenAI → https://platform.openai.com/api-keys
• 费用：两者均为付费服务（Jina 提供有额度限制的免费层级）
• 适用场景：生产部署，追求最高检索质量

方案 B — 💰 经济实惠（免费重排器）

• 嵌入：Jina jina-embeddings-v5-text-small
• 重排器：SiliconFlow BAAI/bge-reranker-v2-m3（提供免费层级）
• 大模型：OpenAI gpt-4o-mini
• 所需密钥：JINA_API_KEY + SILICONFLOW_API_KEY + OPENAI_API_KEY
• 获取密钥：Jina → https://jina.ai/api-key · SiliconFlow → https://cloud.siliconflow.cn/account/ak · OpenAI → https://platform.openai.com/api-keys
• 费用：Jina 嵌入需付费，SiliconFlow 重排器提供免费层级，OpenAI 需付费
• 适用场景：注重成本，同时仍希望使用重排功能的部署

方案 C — 🟢 简单（仅使用 OpenAI）

• 嵌入：OpenAI text-embedding-3-small
• 重排器：无（仅进行向量与 BM25 融合，不使用交叉编码器）
• 大模型：OpenAI gpt-4o-mini
• 所需密钥：仅需 OPENAI_API_KEY
• 获取密钥：https://platform.openai.com/api-keys
• 费用：仅需支付 OpenAI 费用
• 适用场景：已有 OpenAI 账户且希望尽量简化配置的用户

方案 D — 🖥️ 完全本地运行（Ollama，无需 API 密钥）

• 嵌入：Ollama mxbai-embed-large（1024 维，推荐）或 nomic-embed-text:v1.5（768 维，更轻量）
• 重排器：无 — Ollama 没有交叉编码器重排器；检索仅使用向量与 BM25 融合
• 大模型：通过兼容 OpenAI 的端点使用 Ollama — 推荐使用能可靠输出 JSON/结构化内容的模型：
  • qwen3:8b（推荐 — JSON 输出效果最佳，原生支持结构化输出，约 5.2GB）
  • qwen3:14b（质量更高，约 9GB，需要 16GB VRAM）
  • llama4:scout（多模态 MoE，10M ctx，约 12GB）
  • mistral-small3.2（24B，128K ctx，指令遵循能力出色，约 15GB）
  • mistral-nemo（12B，128K ctx，高效，约 7GB）
• 所需密钥：无 — 完全本地运行，不会调用外部 API
• 前置条件：
  • 已安装 Ollama：https://ollama.com/download
  • 已拉取模型（参见下方步骤 5）
  • Ollama 正在运行：macOS = 从“应用程序”中启动应用；Linux = systemctl start ollama 或 ollama serve
• 费用：免费（仅需硬件成本）
• 内存要求：mxbai-embed-large 约 670MB；qwen3:8b 约 5.2GB；qwen3:14b 约 9GB；llama4:scout 约 12GB；mistral-small3.2 约 15GB
• 权衡：不使用交叉编码器重排 = 检索精度低于方案 A/B；智能提取的质量取决于本地大模型 — 如果提取结果杂乱无用，请设置 "smartExtraction": false
• 适用场景：对隐私敏感的部署、隔离网络环境、API 费用为零的需求

---

用户选择方案后，请在一条消息中询问：

1. 请提供所选方案所需的 API 密钥（直接粘贴，或回复“已设置为环境变量”）
2. OpenClaw Gateway 进程中是否已设置这些环境变量？（如果不确定，请回答“否”）
3. 你的 openclaw.json 位于哪里？（如果希望我自动查找，可跳过）

如果用户已在上下文中说明服务提供商或密钥，请跳过询问并继续操作。

在收集并验证 API 密钥之前（见下方步骤 2），请勿继续步骤 2。

步骤 2 — 验证 API 密钥（必须执行 — 不要跳过）

在修改任何配置之前，先运行所选方案的所有密钥检查。 如果任何检查失败，请停止并告知用户哪个密钥未通过以及原因。不要继续执行步骤 3。

方案 A / 方案 B — Jina 嵌入检查：

curl -s -o /dev/null -w "%{http_code}" \
  https://api.jina.ai/v1/embeddings \
  -H "Authorization: Bearer <JINA_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"jina-embeddings-v5-text-small","input":["test"]}'

方案 A / B / C — OpenAI 检查：

curl -s -o /dev/null -w "%{http_code}" \
  https://api.openai.com/v1/models \
  -H "Authorization: Bearer <OPENAI_API_KEY>"

方案 B — SiliconFlow 重排检查：

curl -s -o /dev/null -w "%{http_code}" \
  https://api.siliconflow.com/v1/rerank \
  -H "Authorization: Bearer <SILICONFLOW_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"BAAI/bge-reranker-v2-m3","query":"test","documents":["test doc"]}'

方案 D — Ollama 检查：

curl -s -o /dev/null -w "%{http_code}" http://localhost:11434/api/tags

结果说明：

HTTP 代码	含义	操作
200 / 201	密钥有效，额度可用	✅ 继续
401 / 403	密钥无效或已过期	❌ 停止 — 请用户检查密钥
402	需要付款 / 额度不足	❌ 停止 — 请用户为账户充值
429	请求频率受限或超出额度	❌ 停止 — 请用户检查账单/额度
000 / 连接被拒绝	服务无法访问	❌ 停止 — 请用户检查网络 / Ollama 是否正在运行

如果任何检查失败： 准确告知用户哪个提供商未通过检查、收到的 HTTP 代码以及需要修复的内容。在所有必需的密钥都通过检查之前，不要继续安装。

如果用户表示密钥已作为环境变量设置在网关进程中，请使用内联替换的 ${VAR_NAME} 运行检查，或请用户暂时粘贴密钥以供验证。

步骤 3 — 查找 openclaw.json

按以下顺序检查这些位置：

# Most common locations
ls ~/.openclaw/openclaw.json
ls ~/openclaw.json
# Ask the gateway where it's reading config from
openclaw config get --show-path 2>/dev/null || echo "not found"

如果找不到，请向用户询问路径。

步骤 4 — 读取当前配置

# Read and display current plugins config before changing anything
openclaw config get plugins.entries.memory-lancedb-pro 2>/dev/null
openclaw config get plugins.slots.memory 2>/dev/null

检查现有内容 — 切勿盲目覆盖已有设置。

步骤 5 — 根据所选方案构建合并后的配置

使用所选方案对应的配置块。如果用户直接提供了实际 API 密钥，请将其内联替换；如果用户确认网关进程已设置环境变量，则保留 ${ENV_VAR} 语法。

方案 A 配置（plugins.entries.memory-lancedb-pro.config）：

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "rerank": "cross-encoder",
    "rerankProvider": "jina",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankApiKey": "${JINA_API_KEY}",
    "candidatePoolSize": 12,
    "minScore": 0.6,
    "hardMinScore": 0.62,
    "filterNoise": true
  },
  "sessionMemory": { "enabled": false }
}

方案 B 配置：

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "rerank": "cross-encoder",
    "rerankProvider": "siliconflow",
    "rerankModel": "BAAI/bge-reranker-v2-m3",
    "rerankEndpoint": "https://api.siliconflow.com/v1/rerank",
    "rerankApiKey": "${SILICONFLOW_API_KEY}",
    "candidatePoolSize": 12,
    "minScore": 0.5,
    "hardMinScore": 0.55,
    "filterNoise": true
  },
  "sessionMemory": { "enabled": false }
}

方案 C 配置：

{
  "embedding": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "text-embedding-3-small",
    "baseURL": "https://api.openai.com/v1"
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "filterNoise": true,
    "minScore": 0.3,
    "hardMinScore": 0.35
  },
  "sessionMemory": { "enabled": false }
}

方案 D 配置（按需替换模型 — 建议用于大模型的 qwen3:8b，以及用于嵌入的 mxbai-embed-large）：

{
  "embedding": {
    "apiKey": "ollama",
    "model": "mxbai-embed-large",
    "baseURL": "http://localhost:11434/v1",
    "dimensions": 1024
  },
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 4000,
  "llm": {
    "apiKey": "ollama",
    "model": "qwen3:8b",
    "baseURL": "http://localhost:11434/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "filterNoise": true,
    "minScore": 0.25,
    "hardMinScore": 0.28
  },
  "sessionStrategy": "none"
}

方案 D 前置条件 — 应用配置前运行：

# 1. Verify Ollama is running (should return JSON with model list)
curl http://localhost:11434/api/tags

# 2. Pull embedding model (choose one):
ollama pull mxbai-embed-large          # recommended: 1024-dim, beats text-embedding-3-large, ~670MB
ollama pull snowflake-arctic-embed2    # best multilingual local option, ~670MB
ollama pull nomic-embed-text:v1.5      # classic stable, 768-dim, ~270MB

# 3. Pull LLM for Smart Extraction (choose one based on RAM):
ollama pull qwen3:8b           # recommended: best JSON/structured output, ~5.2GB
ollama pull qwen3:14b          # better quality, ~9GB, needs 16GB VRAM
ollama pull llama4:scout       # multimodal MoE, 10M ctx, ~12GB
ollama pull mistral-small3.2   # 24B, 128K ctx, excellent, ~15GB
ollama pull mistral-nemo       # 12B, 128K ctx, efficient, ~7GB

# 4. Verify models are installed
ollama list

# 5. Quick sanity check — embedding endpoint works:
curl http://localhost:11434/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"model":"mxbai-embed-large","input":"test"}'
# Should return a JSON with a 1024-element vector

如果 Smart Extraction 生成乱码/无效输出： 本地大模型可能无法可靠地支持结构化 JSON。请先尝试 qwen3:8b — 它原生支持结构化输出。如果仍然失败，请禁用：

{ "smartExtraction": false }

如果 Ollama 位于其他主机或 Docker 中： 将 http://localhost:11434/v1 替换为实际主机地址，例如 http://192.168.1.100:11434/v1。同时在 Ollama 进程中设置 OLLAMA_HOST=0.0.0.0，以允许远程连接。

对于 plugins.entries.memory-lancedb-pro.config 配置块，请将其合并到现有的 openclaw.json 中，而不是替换整个文件。只针对 memory 插件配置部分进行编辑。

步骤 6 — 应用配置

先读取当前的 openclaw.json，然后对 plugins.entries.memory-lancedb-pro 部分进行精确编辑。使用与你的安装方式匹配的模板：

方法 1 — openclaw plugins install（通过插件管理器安装的插件）： 无需设置 load.paths 或 allow — 插件管理器已注册该插件。

{
  "plugins": {
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "<<OPTIMAL CONFIG HERE>>"
        }
      }
    }
  }
}

方法 2 — 通过 git clone 使用手动路径（工作区插件）： 必须同时设置 load.paths 和 allow — 工作区插件默认处于禁用状态。

{
  "plugins": {
    "load": { "paths": ["plugins/memory-lancedb-pro"] },
    "allow": ["memory-lancedb-pro"],
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "<<OPTIMAL CONFIG HERE>>"
        }
      }
    }
  }
}

步骤 7 — 验证并重启

openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | rg "memory-lancedb-pro"

预期输出应确认：

• memory-lancedb-pro: smart extraction enabled
• memory-lancedb-pro@...: plugin registered

步骤 8 — 验证

openclaw plugins info memory-lancedb-pro
openclaw hooks list --json | grep -E "before_agent_start|agent_end|command:new"
openclaw memory-pro stats

然后进行快速冒烟测试：

1. 存储：调用 memory_store，设置 text: "test memory for verification"
2. 回忆：调用 memory_recall，设置 query: "test memory"
3. 确认已返回该记忆

---

安装

快速安装（适合初学者）

对于新用户，社区的一键安装程序会自动处理所有事项——路径检测、架构验证、自动更新、提供方选择和回滚：

curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/setup-memory.sh -o setup-memory.sh
bash setup-memory.sh

选项：--dry-run（仅预览）、--beta（包含预发布版本）、--ref v1.2.0（固定版本）、--selfcheck-only、--uninstall。

来源：https://github.com/CortexReach/toolbox/tree/main/memory-lancedb-pro-setup

---

要求

• 推荐使用 Node.js 24（最低要求为 Node 22 LTS，22.16+）
• LanceDB ≥ 0.26.2
• OpenAI SDK ≥ 6.21.0
• TypeBox 0.34.48

安装方式 1 — 通过 OpenClaw 插件管理器（推荐）

# Install from npm registry (@beta tag = latest pre-release, e.g. 1.1.0-beta.8)
openclaw plugins install memory-lancedb-pro@beta

# Install stable release from npm (@latest tag, e.g. 1.0.32)
openclaw plugins install memory-lancedb-pro

# Or install from a local git clone — use master branch (matches npm @beta)
git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git /tmp/memory-lancedb-pro
openclaw plugins install /tmp/memory-lancedb-pro

npm 与 GitHub 分支：@beta 从 npm registry 安装（而非直接从 GitHub 安装）。该仓库有两个长期维护的分支：master 是发布分支（与 npm @beta 一致），main 较旧且落后。如果你想要与已发布的 beta 版本相匹配的代码，请始终克隆 master。

然后绑定 memory 插槽并添加配置（请参阅下方的“配置”部分）：

{
  "plugins": {
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": { "<<your config here>>" }
      }
    }
  }
}

重启并验证：

openclaw gateway restart
openclaw plugins info memory-lancedb-pro

安装方式 2 — 使用 git clone 和手动路径（开发用路径 A）

⚠️ 重要：在 OpenClaw 中，工作区插件（通过 git 克隆的路径）默认处于禁用状态。你必须显式启用它们。

# 1. Clone into workspace
cd /path/to/your/openclaw/workspace
git clone -b master https://github.com/CortexReach/memory-lancedb-pro.git plugins/memory-lancedb-pro
cd plugins/memory-lancedb-pro && npm install

添加到 openclaw.json——必须同时设置 enabled: true 并添加 allow 条目：

{
  "plugins": {
    "load": { "paths": ["plugins/memory-lancedb-pro"] },
    "allow": ["memory-lancedb-pro"],
    "slots": { "memory": "memory-lancedb-pro" },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "embedding": {
            "apiKey": "${JINA_API_KEY}",
            "model": "jina-embeddings-v5-text-small",
            "baseURL": "https://api.jina.ai/v1",
            "dimensions": 1024,
            "taskQuery": "retrieval.query",
            "taskPassage": "retrieval.passage",
            "normalized": true
          }
        }
      }
    }
  }
}

验证并重启：

openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | rg "memory-lancedb-pro"

预期日志输出：

• memory-lancedb-pro: smart extraction enabled
• memory-lancedb-pro@...: plugin registered

安装方式 3 — 现有部署（路径 B）

在 plugins.load.paths 中使用绝对路径。添加到 plugins.allow。绑定 memory 插槽：plugins.slots.memory = "memory-lancedb-pro"。设置 plugins.entries.memory-lancedb-pro.enabled: true。

然后重启并验证：

openclaw config validate
openclaw gateway restart
openclaw logs --follow --plain | rg "memory-lancedb-pro"

新用户首次安装检查清单

插件成功启动后，确定适用的场景并执行相应步骤：

---

场景 A — 从内置的 memory-lancedb 插件迁移（最常见的升级路径）

旧插件将数据存储在 LanceDB 的 ~/.openclaw/memory/lancedb 中。使用迁移命令：

# 1. Check if old data exists and is readable
openclaw memory-pro migrate check

# 2. Preview what would be migrated (dry run)
openclaw memory-pro migrate run --dry-run

# 3. Run the actual migration
openclaw memory-pro migrate run

# 4. Verify migrated data
openclaw memory-pro migrate verify
openclaw memory-pro stats

如果旧数据库位于非默认路径：

openclaw memory-pro migrate check --source /path/to/old/lancedb
openclaw memory-pro migrate run --source /path/to/old/lancedb

---

场景 B — 已有以 JSON 格式导出的记忆

如果你拥有标准 JSON 导出格式的记忆：

# Preview import (dry run)
openclaw memory-pro import memories.json --scope global --dry-run

# Import
openclaw memory-pro import memories.json --scope global

预期的 JSON 架构：

{
  "version": "1.0",
  "memories": [
    {
      "text": "Memory content (required)",
      "category": "preference|fact|decision|entity|other",
      "importance": 0.7,
      "timestamp": 1234567890000
    }
  ]
}

---

场景 C — 记忆存储在 Markdown 文件中（AGENTS.md、MEMORY.md 等）

不支持直接导入 Markdown——导入命令只接受 JSON。你需要先进行转换。

手动转换方法：

1. 打开包含记忆的 Markdown 文件
2. 为每条记忆创建一个包含 text、category、importance 的 JSON 对象
3. 按照上述架构保存为 JSON 文件
4. 运行 openclaw memory-pro import

或者直接在 Agent 中使用 memory_store 工具逐条存储：

memory_store(text="<extracted memory>", category="fact", importance=0.8)

**注意：**基于 Markdown 的记忆文件（MEMORY.md、AGENTS.md）是工作区上下文文件，与 LanceDB 记忆库不同。只有在你希望通过 memory_recall 搜索这些内容时，才需要迁移它们。

---

场景 D — 全新安装，没有先前的记忆

无需迁移。通过快速冒烟测试验证插件是否正常工作：

openclaw memory-pro stats     # should show 0 memories

然后开始对话——autoCapture 将自动开始存储记忆。

---

LanceDB 版本兼容性

LanceDB 版本变更无需手动操作。

该插件依赖 npm 包 @lancedb/lancedb ^0.26.2——安装或更新插件时会自动安装。你无需手动安装或升级 LanceDB。

LanceDB 0.26+ 更改了数字列的返回方式（timestamp、importance、_distance、_score 使用 Arrow BigInt 类型）。插件会在运行时通过内部 Number(...) 强制转换透明地处理此问题——切换 LanceDB 版本时无需运行迁移命令。

**简而言之：**LanceDB 版本兼容性完全自动处理。请参阅下表，了解各维护命令的适用时机。

升级插件代码与数据

命令区别（重要）：

命令	适用时机
openclaw plugins update memory-lancedb-pro	发布新版本后更新插件代码（仅限通过 npm 安装的插件）
openclaw plugins update --all	一次性更新所有通过 npm 安装的插件
openclaw memory-pro upgrade	补全早于智能记忆架构的 memory-lancedb-pro 旧条目（缺少 L0/L1/L2 元数据和 6 类系统）——与 LanceDB 版本无关
openclaw memory-pro migrate	从独立的内置插件 memory-lancedb 一次性迁移到 Pro
openclaw memory-pro reembed	切换嵌入模型或提供方后，重新生成所有嵌入

何时需要运行 memory-pro upgrade？

如果你在引入智能记忆格式之前安装了 memory-lancedb-pro（即条目的元数据中缺少 memory_category），请运行此命令。需要升级的迹象：

• memory_recall 返回结果，但没有有意义的类别
• memory-pro list --json 显示条目没有 l0_abstract / l1_overview 字段

安全升级顺序：

# 1. Backup first
openclaw memory-pro export --scope global --output memories-backup.json

# 2. Preview what would change
openclaw memory-pro upgrade --dry-run

# 3. Run upgrade (uses LLM by default for L0/L1/L2 generation)
openclaw memory-pro upgrade

# 4. Verify results
openclaw memory-pro stats
openclaw memory-pro search "your known keyword" --scope global --limit 5

升级选项：

openclaw memory-pro upgrade --no-llm          # skip LLM, use simple text truncation
openclaw memory-pro upgrade --batch-size 5    # slower but safer for large collections
openclaw memory-pro upgrade --limit 50        # process only first N entries
openclaw memory-pro upgrade --scope global    # limit to one scope

插件管理命令

openclaw plugins list                           # show all discovered plugins
openclaw plugins info memory-lancedb-pro        # show plugin status and config
openclaw plugins enable memory-lancedb-pro      # enable a disabled plugin
openclaw plugins disable memory-lancedb-pro     # disable without removing
openclaw plugins update memory-lancedb-pro      # update npm-installed plugin
openclaw plugins update --all                   # update all npm plugins
openclaw plugins doctor                         # health check for all plugins
openclaw plugins install ./path/to/plugin       # install local plugin (copies + enables)
openclaw plugins install @scope/plugin@beta     # install from npm registry
openclaw plugins install -l ./path/to/plugin    # symlink for dev (no copy)

需要重启网关：在运行 plugins install、plugins enable、plugins disable、plugins update 或更改 openclaw.json 后，必须重启网关。重启前，更改不会生效。

openclaw gateway restart

容易遗漏的设置步骤

1. 任何更改后都必须重启网关：安装、启用、禁用、更新或更改 openclaw.json 中的配置后，必须运行 openclaw gateway restart——更改不会热重载。
2. 工作区插件默认处于禁用状态：执行 git clone 后，必须添加 plugins.allow: ["memory-lancedb-pro"] 和 plugins.entries.memory-lancedb-pro.enabled: true——否则插件不会加载，且不会显示任何提示。
3. 网关进程中的环境变量：${OPENAI_API_KEY} 要求在 OpenClaw Gateway 服务 进程中设置环境变量，而不只是设置在 Shell 中。
4. 绝对路径与相对路径：对于现有部署，始终在 plugins.load.paths 中使用绝对路径。
5. baseURL 而不是 baseUrl：嵌入（以及 LLM）配置字段是 baseURL（URL 大写），而不是 baseUrl。大小写错误会导致架构验证错误：“must NOT have additional properties”。另请注意，必需的 /v1 后缀：应为 http://localhost:11434/v1，而不是 http://localhost:11434。不要与 agents.defaults.memorySearch.remote.baseUrl 混淆，后者的大小写不同。
6. jiti 缓存失效：修改插件下的 .ts 文件后，在运行 openclaw gateway restart 之前，先运行 rm -rf /tmp/jiti/。
7. 未知插件 ID = 错误：OpenClaw 会将 entries、allow、deny 或 slots 中的未知 ID 视为验证错误。引用插件 ID 之前，必须确保它可被发现。
8. 单独配置 LLM：如果嵌入和 LLM 使用不同的提供商，请单独配置 llm 部分，否则会回退使用嵌入的密钥和 URL。
9. 作用域隔离：多作用域需要显式映射 scopes.agentAccess——否则，Agent 只能看到 global 作用域。
10. 会话记忆钩子：在 /new 命令触发——请通过实际调用 /new 进行测试。
11. 重排器凭据：切换提供商时，同时更新 rerankApiKey 和 rerankEndpoint。
12. 假设默认值之前先检查配置：运行 openclaw config get plugins.entries.memory-lancedb-pro，以验证实际加载的内容。
13. 通过环境变量自定义配置/状态路径：OpenClaw 支持以下环境变量来设置自定义路径：
    • OPENCLAW_HOME — 设置根配置/数据目录（默认：~/.openclaw/）
    • OPENCLAW_CONFIG_PATH — 覆盖 openclaw.json 的绝对路径
    • OPENCLAW_STATE_DIR — 覆盖运行时状态/数据目录 如果默认的 ~/.openclaw/ 路径不适用，请在 OpenClaw Gateway 进程的环境中设置这些变量。

安装后验证

openclaw doctor                                 # full health check (recommended)
openclaw config validate                        # config schema check only
openclaw plugins info memory-lancedb-pro        # plugin status
openclaw plugins doctor                         # plugin-specific health
openclaw hooks list --json | grep memory        # confirm hooks registered
openclaw memory-pro stats
openclaw memory-pro list --scope global --limit 5

完整的冒烟测试清单：

• ✅ 插件信息显示 enabled: true，且配置已加载
• ✅ 钩子包含 before_agent_start、agent_end、command:new
• ✅ 通过工具完成一次 memory_store → memory_recall 往返调用
• ✅ 一次精确 ID 搜索命中
• ✅ 一次自然语言搜索命中
• ✅ 如果已启用会话记忆：进行一次真实的 /new 测试

---

故障排除 — 错误消息速查

配置验证工具（来自 CortexReach/toolbox）：

# Download once
curl -fsSL https://raw.githubusercontent.com/CortexReach/toolbox/main/memory-lancedb-pro-setup/scripts/config-validate.mjs -o config-validate.mjs
# Run against your openclaw.json
node config-validate.mjs
# Or validate a specific config snippet
node config-validate.mjs --json '{"embedding":{"baseURL":"http://localhost:11434/v1","model":"bge-m3","apiKey":"ollama"}}'

退出代码 0 = 通过/警告，1 = 发现错误。

错误消息	根本原因	修复方法
must NOT have additional properties + config.embedding	嵌入配置中的字段名称拼写错误（例如，用 baseUrl 代替 baseURL）	对照下方的架构表检查所有字段名称——字段名称区分大小写
must NOT have additional properties（顶层配置）	插件配置中包含未知的顶层字段	删除或更正该字段
memory-lancedb-pro: plugin not found / 插件未加载且无提示	plugins.allow 缺失（git-clone 安装）或 enabled: false	添加 plugins.allow: ["memory-lancedb-pro"] 并设置 enabled: true，然后重启
Unknown plugin id 验证错误	插件尚不可发现时，就已在 entries/slots 中引用	先安装/注册插件，再添加配置引用
${OPENAI_API_KEY} 未展开 / 即使已设置环境变量仍出现身份验证错误	网关进程环境中未设置环境变量	在运行 OpenClaw 网关的服务中设置环境变量，而不只是设置在 shell 中
Hook（before_agent_start、agent_end）未触发	安装/更改配置后未重启网关	运行 openclaw gateway restart
使用 Ollama 时出现嵌入错误	baseURL 格式错误	必须为 http://localhost:11434/v1（包含 /v1），字段必须是 baseURL，而不是 baseUrl
对话后 memory-pro stats 显示 0 条记录	autoCapture 为 false，或未达到 extractMinMessages 要求	设置 autoCapture: true；至少需要 extractMinMessages（默认值为 2）轮对话
助手回复前未注入记忆	autoRecall 为 false（架构默认值）	显式设置 "autoRecall": true
编辑插件 .ts 文件后出现 jiti 缓存错误	编译缓存过期	运行 rm -rf /tmp/jiti/，然后运行 openclaw gateway restart

---

配置

最简快速入门

{
  "embedding": {
    "provider": "openai-compatible",
    "apiKey": "${OPENAI_API_KEY}",
    "model": "text-embedding-3-small"
  },
  "autoCapture": true,
  "autoRecall": true,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "sessionMemory": { "enabled": false }
}

注意： 插件架构中默认禁用 autoRecall——新部署时请显式将其设置为 true。

最佳生产配置（推荐）

嵌入和重排均使用 Jina，提供最佳检索质量：

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "~/.openclaw/memory/lancedb-pro",
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "enableManagementTools": false,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "rerank": "cross-encoder",
    "rerankProvider": "jina",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankApiKey": "${JINA_API_KEY}",
    "candidatePoolSize": 12,
    "minScore": 0.6,
    "hardMinScore": 0.62,
    "filterNoise": true,
    "lengthNormAnchor": 500,
    "timeDecayHalfLifeDays": 60,
    "reinforcementFactor": 0.5,
    "maxHalfLifeMultiplier": 3
  },
  "sessionMemory": { "enabled": false, "messageCount": 15 }
}

这些设置的优势：

• Jina 嵌入：面向任务的向量（taskQuery/taskPassage），针对检索进行了优化
• 混合模式 0.7/0.3：兼顾语义理解与精确关键词匹配
• Jina reranker v3：交叉编码器重排可显著提升相关性
• candidatePoolSize: 12 + minScore: 0.6：强力过滤可减少噪声
• captureAssistant: false：避免存储 Agent 生成的模板化内容
• sessionMemory: false：避免会话摘要污染检索结果

完整配置（所有选项）

{
  "embedding": {
    "apiKey": "${JINA_API_KEY}",
    "model": "jina-embeddings-v5-text-small",
    "baseURL": "https://api.jina.ai/v1",
    "dimensions": 1024,
    "taskQuery": "retrieval.query",
    "taskPassage": "retrieval.passage",
    "normalized": true
  },
  "dbPath": "~/.openclaw/memory/lancedb-pro",
  "autoCapture": true,
  "autoRecall": true,
  "captureAssistant": false,
  "smartExtraction": true,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini",
    "baseURL": "https://api.openai.com/v1"
  },
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "enableManagementTools": false,
  "retrieval": {
    "mode": "hybrid",
    "vectorWeight": 0.7,
    "bm25Weight": 0.3,
    "minScore": 0.3,
    "hardMinScore": 0.35,
    "rerank": "cross-encoder",
    "rerankProvider": "jina",
    "rerankModel": "jina-reranker-v3",
    "rerankEndpoint": "https://api.jina.ai/v1/rerank",
    "rerankApiKey": "${JINA_API_KEY}",
    "candidatePoolSize": 20,
    "recencyHalfLifeDays": 14,
    "recencyWeight": 0.1,
    "filterNoise": true,
    "lengthNormAnchor": 500,
    "timeDecayHalfLifeDays": 60,
    "reinforcementFactor": 0.5,
    "maxHalfLifeMultiplier": 3
  },
  "scopes": {
    "default": "global",
    "definitions": {
      "global": { "description": "Shared knowledge" },
      "agent:discord-bot": { "description": "Discord bot private" }
    },
    "agentAccess": {
      "discord-bot": ["global", "agent:discord-bot"]
    }
  },
  "sessionStrategy": "none",
  "memoryReflection": {
    "storeToLanceDB": true,
    "injectMode": "inheritance+derived",
    "agentId": "memory-distiller",
    "messageCount": 120,
    "maxInputChars": 24000,
    "thinkLevel": "medium"
  },
  "selfImprovement": {
    "enabled": true,
    "beforeResetNote": true,
    "ensureLearningFiles": true
  },
  "mdMirror": { "enabled": false },
  "decay": {
    "recencyHalfLifeDays": 30,
    "recencyWeight": 0.4,
    "frequencyWeight": 0.3,
    "intrinsicWeight": 0.3,
    "betaCore": 0.8,
    "betaWorking": 1.0,
    "betaPeripheral": 1.3
  },
  "tier": {
    "coreAccessThreshold": 10,
    "coreCompositeThreshold": 0.7,
    "coreImportanceThreshold": 0.8,
    "workingAccessThreshold": 3,
    "workingCompositeThreshold": 0.4,
    "peripheralCompositeThreshold": 0.15,
    "peripheralAgeDays": 60
  }
}

---

配置字段参考

嵌入

字段	类型	默认值	描述
apiKey	string	—	API 密钥（支持 ${ENV_VAR}）；使用数组可在多个密钥间故障转移
model	string	—	模型标识符
baseURL	string	提供商默认值	API 端点
dimensions	number	提供商默认值	向量维度
taskQuery	string	—	查询嵌入的任务提示（retrieval.query）
taskPassage	string	—	段落嵌入的任务提示（retrieval.passage）
normalized	boolean	false	请求 L2 归一化嵌入
provider	string	openai-compatible	提供商类型选择器
chunking	boolean	true	对超出嵌入上下文限制的文档自动分块

顶层

字段	类型	默认值	描述
dbPath	string	~/.openclaw/memory/lancedb-pro	LanceDB 数据目录
autoCapture	boolean	true	在 Agent 回复后自动提取记忆（通过 agent_end 钩子）
autoRecall	boolean	false（模式默认值）	在 Agent 处理前注入记忆——需显式设为 true
captureAssistant	boolean	false	在提取中包含助手消息
smartExtraction	boolean	true	由大模型驱动的 6 类提取
extractMinMessages	number	2	触发提取前所需的最少对话轮次
extractMaxChars	number	8000	发送给提取大模型的最大上下文字符数
enableManagementTools	boolean	false	将 CLI 管理工具注册为 Agent 工具
autoRecallMinLength	number	15	触发自动召回所需的最少提示词字符数（CJK 为 6）
autoRecallMinRepeated	number	0	同一记忆在同一会话中再次注入前所需的最少轮次
sessionStrategy	string	systemSessionMemory	会话管线：memoryReflection / systemSessionMemory / none

大模型（用于智能提取）

字段	类型	默认值	描述
llm.apiKey	string	回退为 embedding.apiKey	大模型 API 密钥
llm.model	string	openai/gpt-oss-120b	用于提取的大模型
llm.baseURL	string	回退为 embedding.baseURL	大模型端点

检索

字段	类型	默认值	描述
mode	string	hybrid	hybrid / vector（模式中不存在仅使用 bm25 的选项）
vectorWeight	number	0.7	向量搜索的权重
bm25Weight	number	0.3	BM25 全文搜索的权重
minScore	number	0.3	最低相关性阈值
hardMinScore	number	0.35	重排序后的硬性截断阈值
rerank	string	cross-encoder	重排序策略：cross-encoder / lightweight / none
rerankProvider	string	jina	jina / siliconflow / voyage / pinecone / vllm（Docker Model Runner）
rerankModel	string	jina-reranker-v3	重排序模型名称
rerankEndpoint	string	提供方默认值	重排序 API URL
rerankApiKey	string	—	重排序 API 密钥
candidatePoolSize	number	20	最终筛选前进行重排序的候选项数量
recencyHalfLifeDays	number	14	新鲜度衰减半衰期
recencyWeight	number	0.1	新近程度在评分中的权重
timeDecayHalfLifeDays	number	60	记忆时效衰减因子
reinforcementFactor	number	0.5	基于访问次数的半衰期乘数（0–2，设为 0 可禁用）
maxHalfLifeMultiplier	number	3	强化增益的硬性上限
filterNoise	boolean	true	过滤拒绝响应、问候语等
lengthNormAnchor	number	500	归一化的参考长度（字符）

访问强化说明： 强化仅对白名单中的 source: "manual" 生效——自动召回不会强化记忆，以防噪声放大。

会话策略（v1.1.0+）

使用 sessionStrategy（顶层字段）配置会话流水线：

值	行为
"systemSessionMemory" （默认）	内置会话记忆（更简单）
"memoryReflection"	由大模型驱动的高级反思，支持继承／衍生注入
"none"	禁用会话摘要

memoryReflection 配置（在 sessionStrategy: "memoryReflection" 时使用）：

字段	类型	默认值	说明
storeToLanceDB	boolean	true	将反思持久化到 LanceDB
writeLegacyCombined	boolean	true	同时写入旧版组合行
injectMode	string	inheritance+derived	inheritance-only / inheritance+derived
agentId	string	—	专用反思 Agent（例如 "memory-distiller"）
messageCount	number	120	反思中包含的消息数
maxInputChars	number	24000	发送给反思大模型的字符数上限
timeoutMs	number	20000	反思大模型超时时间（毫秒）
thinkLevel	string	medium	推理深度：off / minimal / low / medium / high
errorReminderMaxEntries	number	3	注入反思的错误条目数上限
dedupeErrorSignals	boolean	true	注入前对错误信号去重

memoryReflection.recall 子对象（控制检索哪些过往反思并注入）：

字段	类型	默认值	说明
mode	string	fixed	检索模式：fixed / dynamic
topK	number	6	检索的反思条目数上限（最多 20）
includeKinds	array	["invariant"]	要包含的类型：invariant / derived
maxAgeDays	number	45	要检索的反思的最长时间范围
maxEntriesPerKey	number	10	每个作用域键的条目数上限
minRepeated	number	2	条目至少出现的次数，达到后才会被纳入
minScore	number	0.18	最低相关性分数（范围：0–5）
minPromptLength	number	8	触发检索所需的提示词最短长度

会话记忆（已弃用——仅用于旧版兼容）

⚠️ 自 v1.1.0 起，sessionMemory 是旧版兼容垫片。 建议改用 sessionStrategy。

• sessionMemory.enabled: true → 映射到 sessionStrategy: "systemSessionMemory"
• sessionMemory.enabled: false → 映射到 sessionStrategy: "none"

字段	类型	默认值	说明
sessionMemory.enabled	boolean	false	旧版：启用 /new 时的会话摘要
sessionMemory.messageCount	number	15	旧版：映射到 memoryReflection.messageCount

自我改进治理

字段	类型	默认值	说明
selfImprovement.enabled	boolean	true	启用自我改进工具（如 self_improvement_log）——默认开启
selfImprovement.beforeResetNote	boolean	true	会话重置前注入学习提醒
selfImprovement.skipSubagentBootstrap	boolean	true	跳过子 Agent 的引导流程
selfImprovement.ensureLearningFiles	boolean	true	如果 LEARNINGS.md / ERRORS.md 缺失，则自动创建

工具激活规则：

• self_improvement_log：需要 selfImprovement.enabled: true（默认值——除非明确禁用，否则处于启用状态）
• self_improvement_extract_skill + self_improvement_review：还需要 enableManagementTools: true

Markdown 镜像

字段	类型	默认值	说明
mdMirror.enabled	boolean	false	将记忆条目镜像为 .md 文件
mdMirror.dir	string	—	Markdown 镜像文件的目录

衰减

字段	类型	默认值	描述
decay.recencyHalfLifeDays	number	30	Weibull 衰减的基础半衰期
decay.recencyWeight	number	0.4	新近度在生命周期评分中的权重（不同于 retrieval.recencyWeight）
decay.frequencyWeight	number	0.3	访问频率的权重
decay.intrinsicWeight	number	0.3	重要性 × 置信度的权重
decay.betaCore	number	0.8	核心记忆的 Weibull 形状参数
decay.betaWorking	number	1.0	工作记忆的 Weibull 形状参数
decay.betaPeripheral	number	1.3	外围记忆的 Weibull 形状参数
decay.coreDecayFloor	number	0.9	核心层级的最低生命周期评分
decay.workingDecayFloor	number	0.7	工作层级的最低生命周期评分
decay.peripheralDecayFloor	number	0.5	外围层级的最低生命周期评分
decay.staleThreshold	number	0.3	低于此评分时，记忆被视为过时
decay.searchBoostMin	number	0.3	应用于生命周期评分的最低搜索加权值
decay.importanceModulation	number	1.5	生命周期评分中重要性的乘数

层级管理

字段	类型	默认值	描述
tier.coreAccessThreshold	number	10	晋升为核心层级所需的访问次数
tier.coreCompositeThreshold	number	0.7	晋升为核心层级所需的生命周期评分
tier.coreImportanceThreshold	number	0.8	晋升为核心层级所需的最低重要性
tier.workingAccessThreshold	number	3	晋升为工作层级所需的访问次数
tier.workingCompositeThreshold	number	0.4	晋升为工作层级所需的生命周期评分
tier.peripheralCompositeThreshold	number	0.15	低于此评分时会降级
tier.peripheralAgeDays	number	60	过时记忆降级的年龄阈值

---

MCP 工具

核心工具（自动注册）

memory_recall — 通过混合检索搜索长期记忆

参数	类型	必填	默认值	备注
query	string	是	—	搜索查询
limit	number	否	5	最多 20
scope	string	否	—	要搜索的特定范围
category	enum	否	—	preference|fact|decision|entity|reflection|other

memory_store — 将信息保存到长期记忆

参数	类型	必填	默认值	备注
text	string	是	—	要记住的信息
importance	number	否	0.7	范围 0–1
category	enum	否	—	记忆分类
scope	string	否	agent:<id>	目标范围

memory_forget — 通过搜索或直接 ID 删除记忆

参数	类型	必填	备注
query	string	二选一	用于定位记忆的搜索查询
memoryId	string	二选一	完整 UUID 或至少 8 个字符的前缀
scope	string	否	搜索／删除范围

memory_update — 更新记忆（保留原始时间戳；更新 preference／entity 文本时会创建新的版本化行并保留历史记录）

参数	类型	必填	备注
memoryId	string	是	完整 UUID 或至少 8 个字符的前缀
text	string	否	新内容（会触发重新嵌入；preference／entity 会创建取代版本）
importance	number	否	新评分 0–1
category	enum	否	新分类

管理工具（使用 enableManagementTools: true 启用）

memory_stats — 使用统计

• scope (string，可选)：按范围筛选

memory_list — 列出近期记忆并进行筛选

• limit (number，可选，默认值为 10，最大值为 50)、scope、category、offset（分页）

自我改进工具

self_improvement_log 默认已启用（selfImprovement.enabled: true）。self_improvement_extract_skill 和 self_improvement_review 还需要设置 enableManagementTools: true。

self_improvement_log — 将学习/错误条目记录到 LEARNINGS.md / ERRORS.md

参数	类型	必填	说明
type	枚举	是	"learning" 或 "error"
summary	字符串	是	单行摘要
details	字符串	否	详细背景
suggestedAction	字符串	否	防止问题再次发生的操作
category	字符串	否	学习：correction|best_practice|knowledge_gap；错误：correction|bug_fix|integration_issue
area	字符串	否	frontend|backend|infra|tests|docs|config
priority	字符串	否	low|medium|high|critical

self_improvement_extract_skill — 根据学习条目创建技能框架

参数	类型	必填	默认值	说明
learningId	字符串	是	—	格式为 LRN-YYYYMMDD-001 或 ERR-*
skillName	字符串	是	—	使用小写字母和连字符
sourceFile	枚举	否	LEARNINGS.md	LEARNINGS.md|ERRORS.md
outputDir	字符串	否	"skills"	相对输出目录

self_improvement_review — 汇总治理待办事项（无参数）

---

智能提取

LLM 驱动的自动记忆分类与存储，会在对话结束后触发。

启用

{
  "smartExtraction": true,
  "extractMinMessages": 2,
  "extractMaxChars": 8000,
  "llm": {
    "apiKey": "${OPENAI_API_KEY}",
    "model": "gpt-4o-mini"
  }
}

最简配置（复用嵌入 API 密钥，无需单独的 llm 配置块）：

{
  "embedding": { "apiKey": "${OPENAI_API_KEY}", "model": "text-embedding-3-small" },
  "smartExtraction": true
}

禁用：{ "smartExtraction": false }

6 类分类

输入类别	存储为	去重行为
用户资料	fact	始终合并（自动整合）
偏好	preference	有条件合并
实体	entity	有条件合并
事件	decision	仅追加（不合并）
案例	fact	仅追加（不合并）
模式	other	有条件合并

每条记忆的 L0/L1/L2 分层内容

• L0（摘要）：单句索引（至少 5 个字符）
• L1（概览）：结构化 Markdown 摘要
• L2（内容）：完整的叙述细节

两阶段去重

1. 向量预筛选：相似度 ≥ 0.7 时查找候选项
2. LLM 判定：CREATE | MERGE | SKIP | SUPPORT | CONTEXTUALIZE | CONTRADICT

---

嵌入提供商

提供商	模型	基础 URL	维度	说明
Jina（推荐）	jina-embeddings-v5-text-small	https://api.jina.ai/v1	1024	最新（2026 年 2 月），支持任务感知 LoRA，32K 上下文
Jina（多模态）	jina-embeddings-v4	https://api.jina.ai/v1	1024	文本 + 图像，基于 Qwen2.5-VL
OpenAI	text-embedding-3-large	https://api.openai.com/v1	3072	OpenAI 中质量最佳（MTEB 64.6%）
OpenAI	text-embedding-3-small	https://api.openai.com/v1	1536	成本效益高
DashScope（阿里巴巴）	text-embedding-v4	https://dashscope.aliyuncs.com/compatible-mode/v1	1024	推荐中文用户使用；也支持重排（见下方说明）
Google Gemini	gemini-embedding-2-preview	https://generativelanguage.googleapis.com/v1beta/openai/	3072	最新（2026 年 3 月），多模态，支持 100 多种语言
Google Gemini	gemini-embedding-001	https://generativelanguage.googleapis.com/v1beta/openai/	3072	稳定的纯文本模型
Ollama（本地）	mxbai-embed-large	http://localhost:11434/v1	1024	推荐的本地模型 — 超越 text-embedding-3-large
Ollama（本地）	snowflake-arctic-embed2	http://localhost:11434/v1	1024	最佳本地多语言选项
Ollama（本地）	nomic-embed-text:v1.5	http://localhost:11434/v1	768	轻量经典模型，270MB

DashScope 重排说明： DashScope 不是 rerankProvider 枚举值，但其重排 API 的响应与 Jina 兼容。使用 rerankProvider: "jina" 并指定 DashScope 的端点：

"retrieval": {
  "rerank": "cross-encoder",
  "rerankProvider": "jina",
  "rerankModel": "qwen3-rerank",
  "rerankEndpoint": "https://dashscope.aliyuncs.com/compatible-api/v1/reranks",
  "rerankApiKey": "${DASHSCOPE_API_KEY}"
}

多密钥故障转移： 将 apiKey 设置为数组，以便在发生 429/503 错误时进行轮询轮换。

---

重排器提供商

提供商	rerankProvider	端点	模型	说明
Jina（默认）	jina	https://api.jina.ai/v1/rerank	jina-reranker-v3	最新的文本重排器（2025 年，基于 Qwen3，131K 上下文）
Jina（多模态）	jina	https://api.jina.ai/v1/rerank	jina-reranker-m0	多模态（文本+图像），文档包含图像时使用
SiliconFlow	siliconflow	https://api.siliconflow.com/v1/rerank	BAAI/bge-reranker-v2-m3	提供免费套餐
Voyage AI	voyage	https://api.voyageai.com/v1/rerank	rerank-2.5	发送 {model, query, documents}，不支持 top_n
Pinecone	pinecone	https://api.pinecone.io/rerank	bge-reranker-v2-m3	仅限 Pinecone 客户
vLLM / Docker Model Runner	vllm	自定义端点	任意兼容模型	通过 Docker Model Runner 自托管

Jina 密钥可同时用于嵌入和重排。

---

多范围隔离

范围格式	说明
global	所有 Agent 共享
agent:<id>	Agent 专属记忆
custom:<name>	自定义命名范围
project:<id>	项目专属记忆
user:<id>	用户专属记忆

默认访问范围：global + agent:<id>。多范围需要显式设置 scopes.agentAccess — 请参阅上方的完整配置。

要完全禁用记忆（解除槽位绑定，但不移除插件）：

{ "plugins": { "slots": { "memory": "none" } } }

---

记忆生命周期（威布尔衰减）

三个层级

层级	衰减下限	Beta	行为
核心	0.9	0.8	温和的次指数衰减
工作	0.7	1.0	标准指数衰减（默认）
边缘	0.5	1.3	快速的超指数衰减

升级/降级规则

• 边缘 → 工作： 访问次数 ≥ 3 且分数 ≥ 0.4
• 工作 → 核心： 访问次数 ≥ 10 且分数 ≥ 0.7 且重要性 ≥ 0.8
• 工作 → 边缘： 分数 < 0.15 或（年龄 > 60 天且访问次数 < 3）
• 核心 → 工作： 分数 < 0.15 且访问次数 < 3

---

混合检索

融合： weightedFusion = (vectorScore × 0.7) + (bm25Score × 0.3)

流程： RRF 融合 → Cross-Encoder 重排 → 生命周期衰减加权 → 长度归一化 → 最低分数硬性阈值 → MMR 多样性（余弦相似度 > 0.85 的结果降权）

重排： 60% 的 Cross-Encoder 分数 + 40% 的原始融合分数。API 调用失败时回退到余弦相似度。

特殊 BM25： 即使语义相似度较低，也会保留精确关键词匹配（BM25 ≥ 0.75）——避免丢失 API 密钥、工单编号等信息。

---

自适应检索触发

跳过以下内容： 问候语、斜杠命令、肯定回应（是 / 好的 / 谢谢）、后续指示（继续 / 请继续）、系统消息、较短的查询（英文 <15 个字符 / CJK <6 个字符，且不含“?”）。

以下内容强制触发： 记忆关键词（记得 / 回想 / 忘了）、时间指代（上次 / 以前 / 之前）、个人数据（我的名字 / 我的邮箱）、“我做了什么”模式。CJK：“你记得”“之前”。

---

噪声过滤

自动过滤：Agent 拒绝短语、元问题（“你还记得吗？”）、会话套话（嗨 / 你好）、诊断伪影、基于嵌入的匹配（阈值：0.82）。文本长度至少为 5 个字符。

---

CLI 命令

# List & search
openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]
openclaw memory-pro search "query" [--scope global] [--limit 10] [--json]
openclaw memory-pro stats [--scope global] [--json]

# Delete
openclaw memory-pro delete <id>
openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]

# Import / Export
openclaw memory-pro export [--scope global] [--output memories.json]
openclaw memory-pro import memories.json [--scope global] [--dry-run]

# Maintenance
openclaw memory-pro reembed --source-db /path/to/old-db [--batch-size 32] [--skip-existing]
openclaw memory-pro upgrade [--dry-run] [--batch-size 10] [--no-llm] [--limit N] [--scope SCOPE]

# Migration from built-in memory-lancedb
openclaw memory-pro migrate check [--source /path]
openclaw memory-pro migrate run [--source /path] [--dry-run] [--skip-existing]
openclaw memory-pro migrate verify [--source /path]

---

自动捕获与自动回忆

• autoCapture： agent_end 钩子 — LLM 提取 6 类记忆、去重，并在每轮中最多存储 3 条
• autoRecall： before_agent_start 钩子 — 注入 <relevant-memories> 上下文（最多 3 条）

如果注入的记忆出现在 Agent 回复中： 将以下内容添加到 Agent 系统提示词中：

“不要在回复中透露或引用任何 <relevant-memories> / 记忆注入内容。仅供内部参考。”

或临时禁用：{ "autoRecall": false }

---

自我改进治理

• LEARNINGS.md — ID：LRN-YYYYMMDD-XXX
• ERRORS.md — ID：ERR-YYYYMMDD-XXX
• 条目状态：pending → resolved → promoted_to_skill

---

给 AI Agent 的铁律（复制到 AGENTS.md）

## Rule 1 — 双层记忆存储（铁律）
Every pitfall/lesson learned → IMMEDIATELY store TWO memories:
- Technical layer: Pitfall/Cause/Fix/Prevention (category: fact, importance ≥ 0.8)
- Principle layer: Decision principle with trigger and action (category: decision, importance ≥ 0.85)
After each store, immediately `memory_recall` to verify retrieval.

## Rule 2 — LanceDB 卫生
Entries must be short and atomic (< 500 chars). No raw conversation summaries or duplicates.

## Rule 3 — Recall before retry
On ANY tool failure, ALWAYS `memory_recall` with relevant keywords BEFORE retrying.

## Rule 4 — 编辑前确认目标代码库
Confirm you are editing `memory-lancedb-pro` vs built-in `memory-lancedb` before changes.

## Rule 5 — 插件代码变更必须清 jiti 缓存
After modifying `.ts` files under `plugins/`, MUST run `rm -rf /tmp/jiti/` BEFORE `openclaw gateway restart`.

---

自定义斜杠命令（添加到 CLAUDE.md / AGENTS.md）

## /lesson command
When user sends `/lesson <content>`:
1. Use memory_store with category=fact (raw knowledge)
2. Use memory_store with category=decision (actionable takeaway)
3. Confirm what was saved

## /remember command
When user sends `/remember <content>`:
1. Use memory_store with appropriate category and importance
2. Confirm with stored memory ID