Add: AI agents structure article and memory-lancedb-pro guide
This commit is contained in:
473
openclaw/xinghui/memory-lancedb-pro-guide.md
Normal file
473
openclaw/xinghui/memory-lancedb-pro-guide.md
Normal file
@@ -0,0 +1,473 @@
|
||||
大多数 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
|
||||
Reference in New Issue
Block a user