ishenwei/nexus
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ee7778036f29d6ccf6d7d5877bfebfb0a2f0ca89
nexus/openclaw/xinghui/memory-lancedb-pro-guide.md

14 KiB
Raw Blame History

大多数 AI 智能体都有"失忆症"——每次新对话，之前聊过的全部清零。

memory-lancedb-pro 是 OpenClaw 的生产级长期记忆插件，把你的智能体变成一个真正的 AI 记忆助理——自动捕捉重要信息，让噪音自然衰减，在恰当的时候回忆起恰当的内容。无需手动标记，无需复杂配置。

没有记忆——每次都从零开始：

你： "缩进用 tab，所有函数都要加错误处理。" （下一次会话） 你： "我都说了用 tab 不是空格！" 😤 （再下一次会话） 你： "……我真的说了第三遍了，tab，还有错误处理。"

有了 memory-lancedb-pro——你的智能体学会了、记住了：

你： "缩进用 tab，所有函数都要加错误处理。" （下一次会话——智能体自动回忆你的偏好） 智能体： （默默改成 tab 缩进，并补上错误处理） ✅ 你： "上个月我们为什么选了 PostgreSQL 而不是 MongoDB？" 智能体： "根据我们 2 月 12 日的讨论，主要原因是……" ✅

这就是 AI 记忆助理 的价值——学习你的风格，回忆过去的决策，提供个性化的回应，不再让你重复自己。

你能得到的

自动捕捉 智能体从每次对话中学习——不需要手动调用 memory_store

智能提取 LLM 驱动的 6 类分类：用户画像、偏好、实体、事件、案例、模式

智能遗忘 Weibull 衰减模型——重要记忆留存，噪音自然消退

混合检索 向量 + BM25 全文搜索，融合交叉编码器重排序

上下文注入 相关记忆在每次回复前自动浮现

多作用域隔离 按智能体、按用户、按项目隔离记忆边界

任意 Provider OpenAI、Jina、Gemini、Ollama 或任意 OpenAI 兼容 API

完整工具链 CLI、备份、迁移、升级、导入导出——生产可用

社区维护的 安装脚本 一条命令搞定安装、升级和修复：

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

脚本覆盖的完整场景和其他社区工具，详见下方 生态工具。

通过 OpenClaw CLI（推荐）：

openclaw plugins install memory-lancedb-pro@beta

或通过 npm：

npm i memory-lancedb-pro@beta

如果用 npm 安装，你还需要在 openclaw.json 的 plugins.load.paths 中添加插件安装目录的 绝对路径。这是最常见的安装问题。

在 openclaw.json 中添加配置：

{ "plugins": { "slots": { "memory": "memory-lancedb-pro" }, "entries": { "memory-lancedb-pro": { "enabled": true, "config": { "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 } } } } } }

为什么用这些默认值？

  • autoCapture + smartExtraction → 智能体自动从每次对话中学习

  • autoRecall → 相关记忆在每次回复前自动注入

  • extractMinMessages: 2 → 正常两轮对话即触发提取

  • sessionMemory.enabled: false → 避免会话摘要在初期污染检索结果

验证并重启：

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

你应该能看到：

  • memory-lancedb-pro: smart extraction enabled

  • memory-lancedb-pro@...: plugin registered

完成！你的智能体现在拥有长期记忆了。

更多安装路径（已有用户、升级） 已在使用 OpenClaw？

  • 在 plugins.load.paths 中添加插件的 绝对路径

  • 绑定记忆插槽：plugins.slots.memory = "memory-lancedb-pro"

  • 验证：openclaw plugins info memory-lancedb-pro && openclaw memory-pro stats

从 v1.1.0 之前的版本升级？

1) 备份

openclaw memory-pro export --scope global --output memories-backup.json

2) 试运行

openclaw memory-pro upgrade --dry-run

3) 执行升级

openclaw memory-pro upgrade

4) 验证

openclaw memory-pro stats

详见 CHANGELOG-v1.1.0.md 了解行为变更和升级说明。

memory-lancedb-pro 是核心插件。社区围绕它构建了配套工具，让安装和日常使用更加顺畅：

CortexReach/toolbox/memory-lancedb-pro-setup

不只是简单的安装器——脚本能智能处理各种常见场景：

你的情况 脚本会做什么

从未安装 全新下载 → 安装依赖 → 选择配置 → 写入 openclaw.json → 重启

通过 git clone 安装，卡在旧版本 自动 git fetch + checkout 到最新 → 重装依赖 → 验证

配置中有无效字段 自动检测并通过 schema 过滤移除不支持的字段

通过 npm 安装 跳过 git 更新，提醒你自行运行 npm update

openclaw CLI 因无效配置崩溃 降级方案：直接从 openclaw.json 文件读取工作目录路径

extensions/ 而非 plugins/ 从配置或文件系统自动检测插件位置

已是最新版 仅执行健康检查，不做改动

bash setup-memory.sh # 安装或升级 bash setup-memory.sh --dry-run # 仅预览 bash setup-memory.sh --beta # 包含预发布版本 bash setup-memory.sh --uninstall # 还原配置并移除插件

内置 Provider 预设：Jina / DashScope / SiliconFlow / OpenAI / Ollama，或自带任意 OpenAI 兼容 API。

CortexReach/memory-lancedb-pro-skill

安装这个 Skill，你的 AI 智能体（Claude Code 或 OpenClaw）就能深度掌握 memory-lancedb-pro 的所有功能。只需说 "help me enable the best config" 即可获得：

  • 7 步引导式配置流程，提供 4 套部署方案：

满血版（Jina + OpenAI）/ 省钱版（免费 SiliconFlow 重排序）/ 简约版（仅 OpenAI）/ 全本地版（Ollama，零 API 成本）

  • 全部 9 个 MCP 工具 的正确用法：memory_recall、memory_store、memory_forget、memory_update、memory_stats、memory_list、self_improvement_log、self_improvement_extract_skill、self_improvement_review

Claude Code 安装：

git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.claude/skills/memory-lancedb-pro

OpenClaw 安装：

git clone https://github.com/CortexReach/memory-lancedb-pro-skill.git ~/.openclaw/workspace/skills/memory-lancedb-pro-skill

架构

┌─────────────────────────────────────────────────────────┐ │ index.ts (入口) │ │ 插件注册 · 配置解析 · 生命周期钩子 │ └────────┬──────────┬──────────┬───────────────┘ │ │ │ ┌────▼───┐ ┌────▼───┐ ┌───▼────┐ ┌──▼──────────┐ │ store │ │embedder│ │retriever│ │ scopes │ │ .ts │ │ .ts │ │ .ts │ │ .ts │ └────────┘ └────────┘ └────────┘ └─────────────┘ │ │ ┌────▼───┐ ┌─────▼──────────┐ │migrate │ │noise-filter.ts │ │ .ts │ │adaptive- │ └────────┘ │retrieval.ts │ └────────────────┘

┌─────────────┐ ┌──────────┐ │ tools.ts │ │ cli.ts │ │ (智能体 API)│ │ (CLI) │ └─────────────┘ └──────────┘

查询 → embedQuery() ─┐ ├─→ 混合融合 → 重排序 → 生命周期衰减加权 → 长度归一化 → 过滤 查询 → BM25 全文 ─────┘

向量搜索 — 基于 LanceDB ANN 的语义相似度（余弦距离）

BM25 全文搜索 — 通过 LanceDB FTS 索引进行精确关键词匹配

混合融合 — 以向量分数为基础，BM25 命中结果获得加权提升

可配置权重 — vectorWeight、bm25Weight、minScore

内置 Jina、SiliconFlow、Voyage AI 和 Pinecone 适配器

兼容任意 Jina 兼容端点（如 Hugging Face TEI、DashScope）

混合打分：60% 交叉编码器 + 40% 原始融合分数

优雅降级：API 失败时回退到余弦相似度

阶段 效果

混合融合 结合语义召回和精确匹配召回

交叉编码器重排序 提升语义精确命中的排名

生命周期衰减加权 Weibull 时效性 + 访问频率 + 重要性 × 置信度

长度归一化 防止长条目主导结果（锚点：500 字符）

硬最低分 移除无关结果（默认：0.35）

MMR 多样性 余弦相似度 > 0.85 → 降权

智能提取

  • LLM 驱动的 6 类提取：用户画像、偏好、实体、事件、案例、模式

  • L0/L1/L2 分层存储：L0（一句话索引）→ L1（结构化摘要）→ L2（完整叙述）

  • 两阶段去重：向量相似度预过滤（≥0.7）→ LLM 语义决策（CREATE/MERGE/SKIP）

  • 类别感知合并：profile 始终合并，events/cases 仅追加

Weibull 衰减引擎

  • 综合分数 = 时效性 + 频率 + 内在价值

  • 三级晋升：外围 ↔ 工作 ↔ 核心，阈值可配置

  • 访问强化：频繁被召回的记忆衰减更慢（类似间隔重复机制）

  • 重要性调制半衰期：重要记忆衰减更慢

作用域

  • 内置作用域：global、agent:、custom:、project:、user:

  • 通过 scopes.agentAccess 实现智能体级别的访问控制

  • 默认：每个智能体访问 global + 自己的 agent: 作用域

自动捕捉

  • 自动捕捉（agent_end）：从对话中提取偏好/事实/决策/实体，去重后每轮最多存储 3 条

  • 自动回忆（before_agent_start）：注入 上下文（最多 3 条）

  • 过滤低质量内容：智能体拒绝回复、元问题、打招呼

  • 跳过检索：打招呼、斜杠命令、简单确认、表情符号

  • 强制检索：记忆关键词（"记得"、"之前"、"上次"）

  • 中文感知阈值（中文：6 字符 vs 英文：15 字符）

CLI 命令

列出记忆

openclaw memory-pro list [--scope global] [--category fact] [--limit 20] [--json]

搜索记忆

openclaw memory-pro search "查询" [--scope global] [--limit 10] [--json]

查看统计

openclaw memory-pro stats [--scope global] [--json]

删除单条

openclaw memory-pro delete

批量删除

openclaw memory-pro delete-bulk --scope global [--before 2025-01-01] [--dry-run]

导出

openclaw memory-pro export [--scope global] [--output memories.json]

导入

openclaw memory-pro import memories.json [--scope global] [--dry-run]

重新生成向量

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]

迁移

openclaw memory-pro migrate check|run|verify [--source /path]

OAuth 登录

openclaw memory-pro auth login [--provider openai-codex] [--model gpt-5.4] [--oauth-path /abs/path/oauth.json] openclaw memory-pro auth status openclaw memory-pro auth logout

Embedding 服务商 兼容 任意 OpenAI 兼容 Embedding API：

服务商 模型 Base URL 维度

Jina（推荐） jina-embeddings-v5-text-small https://api.jina.ai/v1 1024

OpenAI text-embedding-3-small https://api.openai.com/v1 1536

Voyage voyage-4-lite / voyage-4 https://api.voyageai.com/v1 1024 / 1024

Google Gemini gemini-embedding-001 https://generativelanguage.googleapis.com/v1beta/openai/ 3072

Ollama（本地） nomic-embed-text http://localhost:11434/v1 取决于模型

重排序服务商 交叉编码器重排序通过 rerankProvider 支持多个服务商：

服务商 rerankProvider 示例模型

Jina（默认） jina jina-reranker-v3

SiliconFlow（有免费额度） siliconflow BAAI/bge-reranker-v2-m3

Voyage AI voyage rerank-2.5

Pinecone pinecone bge-reranker-v2-m3

故障排除

在 LanceDB 0.26+ 上，某些数值列可能以 BigInt 形式返回。升级到 memory-lancedb-pro >= 1.0.14——插件现在会在运算前使用 Number(...) 进行类型转换。

AI 智能体铁律

将以下内容复制到你的 AGENTS.md，让智能体自动遵守这些规则。

规则 1 — 双层记忆存储

每个踩坑/经验教训 → 立即存储两条记忆：

  • 技术层：踩坑：[现象]。原因：[根因]。修复：[方案]。预防：[如何避免] (category: fact, importance >= 0.8)
  • 原则层：决策原则 ([标签])：[行为规则]。触发：[何时]。动作：[做什么] (category: decision, importance >= 0.85)

规则 2 — LanceDB 数据质量

条目必须简短且原子化（< 500 字符）。不存储原始对话摘要或重复内容。

规则 3 — 重试前先回忆

任何工具调用失败时，必须先用 memory_recall 搜索相关关键词，再重试。

规则 4 — 确认目标代码库

修改前确认你操作的是 memory-lancedb-pro 还是内置 memory-lancedb。

规则 5 — 修改插件代码后清除 jiti 缓存

修改 plugins/ 下的 .ts 文件后，必须先执行 rm -rf /tmp/jiti/ 再重启 openclaw gateway。

数据库 Schema

字段 类型 说明

id string (UUID) 主键

text string 记忆文本（全文索引）

vector float[] Embedding 向量

category string 存储类别：preference / fact / decision / entity / reflection / other

scope string 作用域标识（如 global、agent:main）

importance float 重要性分数 0-1

timestamp int64 创建时间戳（毫秒）

metadata string (JSON) 扩展元数据

v1.1.0 常用 metadata 字段：l0_abstract、l1_overview、l2_content、memory_category、tier、access_count、confidence、last_accessed_at

状态：Beta——通过 npm i memory-lancedb-pro@beta 安装。使用 latest 的稳定版用户不受影响。

功能 说明

智能提取 LLM 驱动的 6 类提取，支持 L0/L1/L2 元数据。禁用时回退到正则模式。

生命周期评分 Weibull 衰减集成到检索中——高频和高重要性记忆排名更高。

层级管理 三级系统（核心 → 工作 → 外围），自动晋升/降级。

反馈：GitHub Issues · 回退：npm i memory-lancedb-pro@latest

Reference in New Issue View Git Blame Copy Permalink