474 lines
14 KiB
Markdown
474 lines
14 KiB
Markdown
大多数 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 <id>
|
||
|
||
# 批量删除
|
||
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
|