AI智能体长期记忆引擎：从向量检索到智能提取的架构实践

在构建智能对话系统时，长期记忆能力是提升用户体验的关键。其核心原理在于让AI能够跨会话记住用户偏好、项目上下文等关键信息，从而避免重复交互。传统方案多依赖向量数据库进行语义检索，但面临存储冗余、检索不准等挑战。为解决这些问题，现代记忆引擎引入了混合检索架构，结合向量搜索与BM25全文搜索，并利用轻量级LLM进行智能提取，将对话内容自动分类、结构化存储。这种技术显著提升了AI助手的个性化水平，使其在

weixin_30386713

376人浏览 · 2026-04-27 13:15:14

weixin_30386713 · 2026-04-27 13:15:14 发布

1. 项目概述：为AI智能体构建一个真正会“记住”的大脑

如果你用过Claude Code、Cursor或者Windsurf这类AI编程助手，一定遇到过这样的场景：昨天刚跟它说“我的项目用TypeScript，缩进用两个空格”，今天新建一个文件，它又问你“用Tab还是空格？”。这种“金鱼记忆”让AI助手显得很笨，每次对话都像初次见面，你得不断重复自己的偏好、项目背景和过去的决策。

这就是 长期记忆 缺失的问题。大多数AI智能体本质上是“无状态”的——它们处理完当前对话，上下文一清空，一切归零。 UltraMemory （也叫 memory-lancedb-pro ）要解决的，就是给这些智能体装上“海马体”，让它们能跨会话、跨时间、甚至跨不同的智能体实例，记住真正重要的信息。

简单说， UltraMemory 是一个 通用AI智能体长期记忆引擎 。它不是一个独立应用，而是一个插件，可以嵌入到OpenClaw、Claude Code等支持MCP（Model Context Protocol）协议的AI智能体平台中。一旦装上，你的智能体就从一个“健忘的临时工”，变成了一个“记得你所有习惯和项目历史的资深伙伴”。

它的核心价值在于“主动学习”和“精准回忆”。你不用手动敲 /remember 命令去存东西，智能体会在每次对话后，自动分析聊天内容，提取出关键信息（比如你的编程偏好、项目里的技术选型理由、某个复杂问题的解决方案），然后结构化地存起来。下次你提到相关话题，哪怕隔了好几周，它也能从记忆库里精准调出上下文，给出高度个性化的回答。

1.1 核心设计理念：不只是个向量数据库

市面上很多“AI记忆”方案，本质就是个向量数据库搭个简单前端。你把文本扔进去，它给你存成向量；你查的时候，它做最近邻搜索。这带来了几个问题：

存储冗余 ：同一件事你说过三遍，它就存三条几乎一样的向量，浪费空间还干扰检索。
检索不准 ：纯向量搜索对关键词匹配不友好。你问“上次关于PostgreSQL和MongoDB的讨论”，它可能返回一堆聊“数据库”的泛泛而谈，而不是你要的那次具体的技术对比。
记忆僵化 ：所有记忆同等重要，没有“新陈代谢”。三年前的项目细节和昨天的核心决策在检索权重上没区别，过时信息会污染当前上下文。
理解肤浅 ：存储的是原始文本片段，缺乏对信息类型（是个人偏好？还是技术方案？）和重要性的理解。

UltraMemory 的设计从一开始就瞄准了这些痛点，它的架构可以概括为 “混合检索 + 智能提取 + 动态生命周期管理” 。

混合检索 ：结合了 向量搜索 （理解语义相似性）和 BM25全文搜索 （精准匹配关键词）。比如你问“dark mode”，向量搜索能理解“深色主题”、“夜间模式”是同义词，BM25能确保精确包含“dark mode”这个词条的记录被优先召回。两者结果通过算法融合，取长补短。
智能提取 ：这是 v1.1.0 的核心。它用一个轻量级LLM（比如GPT-4o-mini）在后台分析对话，自动将信息分类存储。不是存整段聊天记录，而是提炼成结构化数据，比如：“类别：偏好，关键事实：用户喜欢深色模式，置信度：0.9”。这大大提升了存储效率和后续检索的准确性。
动态生命周期 ：记忆不是一成不变的。 UltraMemory 引入了 韦伯衰减模型 和 三层存储体系 。高频访问、高置信度的记忆会晋升到“核心层”，长期保留；低频、模糊的记忆会逐渐衰减，最终被归档或清理。这模拟了人脑的记忆机制，让智能体的“知识库”保持鲜活和高效。

1.2 它能做什么，适合谁用？

核心功能 ：

自动捕获 ：后台分析对话，自动提取并存储关键信息，无需手动干预。
智能分类 ：将记忆分为6大类：用户档案、偏好、实体、事件、案例、模式。
混合检索 ：向量+BM25搜索，结合交叉编码器重排序，返回最相关的结果。
记忆衰减 ：基于重要性、新鲜度和访问频率的动态权重调整。
多范围隔离 ：支持全局、单智能体、单项目、单用户等不同范围的记忆隔离，互不干扰。
即插即用 ：作为MCP服务器或OpenClaw插件，快速集成到现有AI工作流中。

适合的用户 ：

AI智能体开发者 ：为你构建的客服机器人、编码助手、创意伙伴添加长期记忆能力。
重度AI工具使用者 ：使用Claude Code、Cursor、Windsurf进行日常开发，受够了重复解释项目背景和个人偏好。
项目团队 ：希望AI助手能记住跨项目的技术决策、架构讨论，形成可查询的团队知识库。
研究者 ：需要实验不同记忆模型、检索算法对智能体长期交互效果的影响。

接下来，我们深入它的架构，看看这套系统是如何工作的。

2. 架构深度解析：一个记忆引擎是如何炼成的

UltraMemory 的代码结构清晰，遵循了单一职责原则。我们抛开表面的文件列表，直接看核心的数据流和决策逻辑。理解这个，你才能知道它为什么快，为什么准。

2.1 核心数据流：从对话到记忆，再到召回

当一个对话回合结束，触发 autoCapture 时，完整的处理流水线如下：

用户/智能体对话
        ↓
[噪声过滤器] (noise-filter.ts)
   ↓ 过滤掉问候语、拒绝回答、元问题等低价值内容
[自适应检索判断] (adaptive-retrieval.ts)
   ↓ 判断当前对话是否值得提取记忆（基于长度、关键词等）
[智能提取器] (smart-extractor.ts) ──── 关键！
   ↓ LLM分析文本，输出结构化记忆对象
        ├── 类别 (profile, preference, entity, event, case, pattern)
        ├── 层级 (L0摘要, L1概述, L2详情)
        ├── 关键事实 (结构化键值对)
        └── 去重决策 (CREATE, MERGE, SKIP, SUPERSEDE)
[存储层] (store.ts)
   ↓ 写入LanceDB，同时建立向量索引和FTS（全文搜索）索引
        ├── 向量字段 → 用于语义搜索
        └── 文本字段 → 用于BM25关键词搜索

(记忆存储完成)

当用户发起一个新查询，或者智能体在生成回复前自动触发 autoRecall 时，召回流水线启动：

用户查询 (或对话上下文)
        ↓
[检索器] (retriever.ts)
   ↓ 并行执行
        ├── 向量检索 (ANN近似最近邻，基于余弦相似度)
        └── BM25检索 (基于FTS索引的关键词匹配)
        ↓
[混合融合] (Hybrid Fusion)
   ↓ 加权合并两个结果集 (vectorWeight, bm25Weight)
[重排序] (Rerank)
   ↓ 使用交叉编码器模型对Top-K候选进行精细语义打分
[生命周期衰减引擎] (decay-engine.ts)
   ↓ 根据记忆的“年龄”、访问频率、内在重要性调整分数
[长度标准化] (Length Normalization)
   ↓ 避免过长的文本片段因包含更多关键词而获得不合理的高分
[最小分数过滤] (Hard Min Score)
   ↓ 剔除分数低于阈值（默认0.35）的无关结果
[MMR多样性筛选] (Maximal Marginal Relevance)
   ↓ 避免返回内容过于相似的结果，提升结果集的多样性
        ↓
最终排序的记忆列表，注入到智能体的提示词中

这个流水线的每一个环节都是可配置、可插拔的。比如，你可以关闭BM25只用向量，或者换用不同的重排序模型（Jina、SiliconFlow等）。

2.2 智能提取：LLM如何理解对话

这是 v1.1.0 版本区别于简单存储的核心。 smart-extractor.ts 里的LLM调用不是随便问的，它遵循一个精心设计的提示词工程。

提取的六个类别 ：

Profile（档案） ：关于用户或实体的静态属性。例如：“用户是后端工程师，主要使用Go语言。” 这类信息通常合并更新，而不是新增。
Preference（偏好） ：用户明确表达的好恶。例如：“不喜欢在代码中使用 any 类型。” “希望错误信息用中文输出。”
Entity（实体） ：对话中提到的具体对象，如产品名、库名、文件名、API端点。例如：“项目使用了 React-Query 库。” “配置文件是 docker-compose.yml 。”
Event（事件） ：在特定时间点发生的事。例如：“2024年3月15日，决定将数据库从MySQL迁移到PostgreSQL。”
Case（案例） ：一个问题及其解决方案。例如：“遇到‘Connection timeout’错误，解决方法是增加 pool_max_connections 参数。”
Pattern（模式） ：反复出现的行为或规则。例如：“每次部署前，用户都会先运行单元测试。” “用户总在周五下午进行代码审查。”

两层去重逻辑 ：

向量相似度粗筛 ：新提取的记忆会先和已有记忆进行向量相似度计算。如果相似度超过阈值（例如0.7），则进入下一步；否则直接创建新记忆。
LLM语义决策 ：对于高相似度的记忆对，LLM会判断它们的关系：
- CREATE ：是新信息，创建。
- MERGE ：是相同信息的补充，合并到现有记忆（尤其是 profile 和 preference ）。
- SKIP ：是重复信息，跳过。
- SUPERSEDE ：是新信息，且使旧信息过时，用新的替换旧的（例如，版本号更新）。

这种设计极大地减少了数据冗余，让记忆库保持精炼。

2.3 混合检索的融合策略：不是简单的RRF

很多系统用 倒数排名融合（RRF） ，公式是 score = 1 / (k + rank) 。 UltraMemory 在v2路线图中实现了真正的RRF，但在其默认的混合融合中，采用了一种更实用的加权调和方式。

假设一个记忆在向量搜索中得分0.8（归一化到0-1），在BM25搜索中排名第1（共10个结果）。它的融合分数可能是： final_score = (vectorWeight * 0.8) + (bm25Weight * (1 / (1 + 1))) （假设k=1） = (0.7 * 0.8) + (0.3 * 0.5) = 0.56 + 0.15 = 0.71

这里的关键是， BM25贡献的不是原始分数，而是基于排名的衰减分数 。这是因为不同查询的BM25分数范围差异很大，直接加权不穩定。这种设计保证了即使没有精确关键词匹配，语义相似的记忆也能靠向量分撑住；而一旦有精确匹配，BM25会给予强力助推。

实操心得 ： vectorWeight 和 bm25Weight 的默认值（0.7/0.3）是针对通用对话优化的。如果你的领域专业术语多、缩写多（比如医疗、法律），可以适当提高 bm25Weight （如0.5）。如果是创意写作、头脑风暴等语义发散的场景，可以提高 vectorWeight 。

2.4 记忆的生命周期：韦伯衰减与三层体系

记忆不是静态的。 UltraMemory 用 decay-engine.ts 和 tier-manager.ts 模拟了一个动态系统。

韦伯衰减模型 ：记忆的“强度” S(t) 随时间衰减，但衰减速度不是线性的，也非简单的指数。韦伯函数 S(t) = exp(-(t/λ)^k) 引入了形状参数 k ，可以模拟“先快后慢”或“先慢后快”的遗忘曲线。在 UltraMemory 中， t 是时间， λ 是半衰期，而 k 与记忆的“内在重要性”和“访问频率”相关。高频访问、高置信度的记忆，其 k 值更小，衰减更慢。

三层存储体系 ：

外围层（Peripheral） ：新提取的记忆默认在此层。它们是“短期记忆”，如果一段时间不被访问，会快速衰减并被清理。
工作层（Working） ：被成功召回并判定为“有用”（通过反馈机制）的记忆会晋升到此层。它们是“中期记忆”，衰减速度中等，是检索的主要来源。
核心层（Core） ：经过多次强化、极其重要或用户手动标记的记忆。它们是“长期记忆”，几乎不衰减，构成智能体的核心知识基。

晋升与降级 ： tier-manager.ts 会定期（或在每次召回后）扫描记忆，根据其衰减后的分数、访问次数等指标，决定是否在层级间移动。这形成了一个有机的、自维护的知识库。

3. 实战部署与配置详解

理论再好，落地才是关键。这里我以最常用的 OpenClaw插件 部署方式为例，带你走一遍完整的配置和调优过程。假设你已经在本地或服务器上运行了OpenClaw。

3.1 安装：推荐使用社区一键脚本

手动安装需要处理npm包、路径配置，容易踩坑。社区维护的 一键安装脚本 是首选，它智能处理了各种边缘情况。

# 下载并运行安装脚本
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环境。
从GitHub拉取最新版（或指定版本）的 memory-lancedb-pro 。
安装依赖。
交互式地让你选择嵌入模型提供商（Jina, OpenAI, Ollama等）并配置API密钥。
自动生成正确的 openclaw.json 配置片段，并合并到你的配置文件中。
重启OpenClaw网关服务。

如果你偏爱手动控制，也可以用OpenClaw CLI安装：

openclaw plugins install memory-lancedb-pro@beta

但请注意，用npm安装后， 必须在 openclaw.json 的 plugins.load.paths 里添加插件的绝对路径 ，这是新手最常见的坑。

3.2 核心配置项解读

安装后，你的 openclaw.json 里会多出一段配置。我们来拆解最关键的部分：

{
  "plugins": {
    "slots": { "memory": "memory-lancedb-pro" }, // 关键：将记忆槽位绑定到此插件
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          // 1. 嵌入模型配置 - 决定记忆的“理解”能力
          "embedding": {
            "provider": "openai-compatible",
            "apiKey": "${JINA_API_KEY}", // 从环境变量读取
            "model": "jina-embeddings-v5-text-small", // 推荐Jina，性价比高
            "baseURL": "https://api.jina.ai/v1",
            "dimensions": 1024,
            "taskQuery": "retrieval.query",
            "taskPassage": "retrieval.passage",
            "normalized": true // 输出归一化向量，必须为true
          },
          // 2. 数据库路径
          "dbPath": "~/.openclaw/memory/lancedb-pro",
          // 3. 自动化开关
          "autoCapture": true, // 自动提取记忆
          "autoRecall": true, // 自动在生成回复前注入相关记忆
          "smartExtraction": true, // 启用LLM智能提取（v1.1.0核心）
          // 4. 提取触发条件
          "extractMinMessages": 2, // 至少2条消息才触发提取（避免单句问候）
          "extractMaxChars": 8000, // 发送给LLM的最大字符数，控制成本
          // 5. 检索配置
          "retrieval": {
            "mode": "hybrid", // 混合模式
            "vectorWeight": 0.7,
            "bm25Weight": 0.3,
            "minScore": 0.3, // 初步分数阈值
            "rerank": "cross-encoder", // 启用重排序
            "rerankProvider": "jina",
            "rerankModel": "jina-reranker-v3",
            "candidatePoolSize": 20, // 重排序候选池大小
            "hardMinScore": 0.35, // 最终分数硬阈值，低于此值的结果被丢弃
            "recencyHalfLifeDays": 14, // 新鲜度半衰期（天）
            "timeDecayHalfLifeDays": 60 // 时间衰减半衰期（天）
          },
          // 6. LLM配置（用于智能提取）
          "llm": {
            "apiKey": "${OPENAI_API_KEY}",
            "model": "gpt-4o-mini", // 足够完成分类任务，成本低
            "baseURL": "https://api.openai.com/v1"
          },
          // 7. 会话记忆（谨慎开启）
          "sessionMemory": {
            "enabled": false // 初期建议关闭，避免会话摘要干扰长期记忆
          }
        }
      }
    }
  }
}

3.3 提供商选型指南：平衡效果、速度与成本

UltraMemory 的强大在于其开放性，支持多种后端服务。

嵌入模型选择（ embedding ） ：

追求最佳效果/性价比 ：选 Jina Embeddings V5 。它在MTEB基准测试上表现接近OpenAI，价格更低，且专为检索优化。 model 填 jina-embeddings-v5-text-small 或 jina-embeddings-v5-text-base 。
追求极致效果，不计成本 ：选 OpenAI text-embedding-3-large 。维度更高（3072），在复杂语义任务上略有优势。
完全本地化，零API成本 ：选 Ollama + Nomic Embed Text 。在本地运行Ollama，部署 nomic-embed-text 模型。需注意本地GPU资源消耗和速度。
其他选择 ：Voyage AI、Google Gemini Embedding、DashScope等，只要提供OpenAI兼容的API端点即可。

重排序模型选择（ rerank ） ：

默认推荐 ： Jina Reranker V3 。与Jina Embedding同一家，兼容性好，效果出色。
免费/低成本尝试 ： SiliconFlow 。提供免费的BGE Reranker模型，非常适合入门和测试。 rerankProvider 填 siliconflow ， rerankModel 填 BAAI/bge-reranker-v2-m3 。
本地部署 ：使用 Hugging Face Text Embeddings Inference (TEI) 部署一个开源的reranker模型（如BGE），然后将 rerankEndpoint 指向你的本地服务地址， rerankProvider 设为 jina （兼容模式）。

智能提取LLM选择（ llm ） ：

性价比之选 ： GPT-4o-mini 。处理分类和摘要任务绰绰有余，成本是GPT-4的十分之一。
更优性能 ： GPT-4o 。在复杂、模糊的对话中，分类和去重决策更准确。
本地/低成本 ：通过Ollama运行 Qwen2.5-7B-Instruct 或 Llama 3.1 8B 等模型。需确保模型有足够强的指令遵循和分类能力。

配置心得 ：初期搭建，建议采用 Jina Embedding + Jina Reranker + GPT-4o-mini 的组合。这个组合在效果、速度和成本上取得了很好的平衡。等跑通流程、积累了一定记忆数据后，再根据实际检索效果和账单，考虑是否升级LLM或尝试本地模型。

3.4 验证与监控

配置完成后，重启OpenClaw网关，并查看日志：

openclaw gateway restart
openclaw logs --follow --plain | grep -i "memory"

你应该看到类似这样的信息，表明插件已成功加载并初始化：

memory-lancedb-pro: plugin registered successfully
memory-lancedb-pro: smart extraction enabled with model gpt-4o-mini
memory-lancedb-pro: LanceDB store initialized at /path/to/db

现在，你可以开始和你的智能体对话了。进行几次有信息量的交流后，可以使用CLI工具检查记忆库：

# 查看记忆统计
openclaw memory-pro stats
# 列出最近存储的记忆
openclaw memory-pro list --limit 5
# 搜索特定主题的记忆
openclaw memory-pro search --query "数据库选型"

如果看到提取出的结构化记忆（分好类、有摘要），说明智能提取工作正常。

4. 高级特性与调优实战

基础功能跑通后，我们可以深入一些高级特性和调优技巧，让记忆引擎更贴合你的实际需求。

4.1 范围隔离：为不同任务划分记忆空间

默认情况下，所有记忆都存在 global 全局范围。但你可能不希望个人项目的偏好污染工作项目的记忆。 UltraMemory 通过 scopes 配置支持灵活的范围控制。

"scopes": {
  "default": "global",
  "definitions": {
    "global": { "description": "所有智能体共享的知识" },
    "agent:my-coder": { "description": "我的编程助手的私有记忆" },
    "project:web-app": { "description": "Web应用项目的记忆" },
    "user:alice": { "description": "用户Alice的个人记忆" }
  },
  "agentAccess": {
    "my-coder": ["global", "agent:my-coder", "project:web-app"],
    "customer-service-bot": ["global"] // 客服机器人只能访问全局记忆
  }
}

definitions ：定义可用的范围。范围名可以是任意字符串，但建议用 type:identifier 的格式保持清晰。
agentAccess ：定义每个智能体可以访问哪些范围。一个智能体可以访问多个范围，检索时会合并这些范围内的记忆。
使用：在调用 memory_store 或 memory_recall 工具时，可以通过 scope 参数指定目标范围。如果不指定，则使用 default 范围。

应用场景 ：你可以为每个Git仓库创建一个 project:<repo-name> 范围。当在这个仓库中工作时，让智能体只访问该项目的记忆，实现高度上下文化的辅助。

4.2 反馈循环与记忆权重学习

UltraMemory v2路线图中引入了 反馈权重EMA（指数移动平均） 。这是一个强大的特性，让记忆系统能够从你的行为中学习。

原理很简单：每个记忆都有一个 feedback_weight 字段（默认0.5）。

当智能体召回一个记忆并使用了它（例如，基于这个记忆给出了正确答案），该记忆的权重会通过EMA公式小幅上调。
当智能体召回一个记忆但被用户 忽略或纠正 ，该记忆的权重会下调。
这个 feedback_weight 会直接影响衰减引擎中的“内在重要性”分数，从而影响记忆的寿命和检索排名。

如何启用？ 这需要智能体端（如OpenClaw）在调用记忆工具后，通过额外的工具调用（如 memory_feedback ）来回传正/负反馈。目前这部分逻辑需要你根据具体的智能体框架进行集成。核心思想是建立一个闭环，让有用的记忆越来越强，无用的记忆逐渐淡出。

4.3 性能调优与问题排查

问题1：记忆提取不触发或提取内容少。

检查： extractMinMessages 设置是否过高？如果设为5，那么前4条消息的对话不会被分析。对于快速交互的场景，可以设为2。
检查： noise-filter 是否过滤得太激进？查看日志中是否有 [noise-filter] skipped 的记录。可以临时将 retrieval.filterNoise 设为 false 测试。
检查：LLM调用是否超时或失败？查看日志中 smart-extractor 相关的错误。可能是API密钥错误、网络问题或模型不可用。

问题2：检索结果不相关。

调整权重 ：尝试调整 vectorWeight 和 bm25Weight 。技术讨论多，则提高 bm25Weight ；创意发散多，则提高 vectorWeight 。
调整阈值 ：降低 minScore 和 hardMinScore 可以召回更多结果，但可能包含噪声；提高则更精确，但可能漏掉一些相关项。建议从0.3开始，根据观察调整。
检查重排序 ：确保 rerank 配置正确且服务可达。可以暂时关闭重排序（ "rerank": "none" ），看基础混合检索的结果是否合理，以排除重排序环节的问题。
查看调试信息 ：在v2的“完整评分追踪”特性中，设置 debug=true 参数可以查看记忆在每个管道阶段的得分，帮你定位是哪个环节导致了偏差。

问题3：数据库文件越来越大。

这是正常现象 。记忆在不断增加。 UltraMemory 的衰减和分层机制会自动清理低价值的外围层记忆。
手动管理 ：可以使用CLI工具 openclaw memory-pro delete-bulk --scope peripheral --older-than 30d 删除指定范围内30天前的记忆（谨慎操作）。
导出备份 ：定期使用 openclaw memory-pro export 导出重要记忆作为备份。

问题4：API调用成本过高。

智能提取LLM ：这是主要的成本来源。确保使用 gpt-4o-mini 而非 gpt-4o 。调整 extractMaxChars ，不要将过长的原始对话发送给LLM（默认8000很合理）。
嵌入模型 ：Jina比OpenAI便宜很多。如果使用本地Ollama，则无此成本。
重排序 ：SiliconFlow有免费额度。如果检索质量尚可，可以考虑关闭重排序（ "rerank": "none" ）作为临时方案。

4.4 与内置memory-lancedb的迁移

如果你之前使用的是OpenClaw内置的 memory-lancedb 插件，迁移到Pro版是平滑的。

备份旧数据 ：虽然迁移工具会处理，但事先备份总是好的。

运行迁移命令 ：

# 首先干跑预览
openclaw memory-pro migrate --dry-run
# 确认无误后执行
openclaw memory-pro migrate

更新配置 ：将 openclaw.json 中的插件名称从 memory-lancedb 改为 memory-lancedb-pro ，并应用新的配置格式。
验证：使用 openclaw memory-pro stats 查看迁移后的记忆统计，并用 openclaw memory-pro list 抽查几条记忆，确保内容完整。

迁移工具会将旧的向量数据重新编码（如果需要），并转换为新的、包含分类和层级的结构化格式。

5. 开发与扩展：深入代码与贡献

对于开发者来说， UltraMemory 的模块化设计使其易于理解和扩展。

5.1 核心模块扩展点

如果你想定制或添加功能，可以从以下几个文件入手：

src/smart-extractor.ts ：修改这里来改变LLM提取记忆的逻辑。例如，你可以增加新的记忆类别，或者修改给LLM的提示词（ systemPrompt 和 userPrompt 模板），以更好地适应你的领域术语。
src/retriever.ts ：检索流程的核心。你可以实现新的融合算法（替换 _hybridFusion 方法），或者添加新的重排序提供商（在 _rerank 方法中扩展）。
src/decay-engine.ts ：记忆衰减模型。如果你有更好的遗忘曲线算法，可以在这里替换默认的韦伯函数。
src/tier-manager.ts ：记忆分层策略。你可以修改晋升/降级的阈值逻辑，或者增加新的层级。
src/noise-filter.ts ：定义什么样的内容应该被过滤掉。你可以添加针对你业务场景的噪声模式。

5.2 添加一个新的嵌入模型提供商

假设你想接入一个新的、兼容OpenAI API的嵌入服务 AwesomeEmbed 。

在 src/embedder.ts 中 ，找到 _createOpenAICompatibleEmbedder 函数。该函数已经处理了通用的OpenAI兼容接口。你只需要确保你的服务提供商返回的JSON格式与OpenAI一致（通常都是 {“data”: [{“embedding”: […]}]} ）。

在配置中 ，你只需要正确设置 embedding.baseURL 和 embedding.model 参数。例如：

"embedding": {
  "provider": "openai-compatible",
  "apiKey": "${AWESOME_EMBED_API_KEY}",
  "model": "awesome-model-256d",
  "baseURL": "https://api.awesome-embed.com/v1",
  "dimensions": 256,
  "normalized": true
}

系统会自动使用OpenAI兼容客户端进行调用。

5.3 参与社区与路线图

UltraMemory 的GitHub仓库活跃度很高。作者 win4r 维护着一个非常详细的路线图（Roadmap），分为P0到P3四个优先级。

v2.0目标 ：向知识图谱演进。计划引入 关系感知的重排序 （记忆A和记忆B如果有关系，则相互加分）和 确定性记忆ID （相同内容生成相同ID，实现写入时去重）。
v3.0哲学 ：“提示 > 代码”。从开发经验中发现，调整提示词对效果的影响可能比写几十行基础设施代码更大。因此v3.0的重点将放在 SmartExtractor 和检索提示词的精细调优上，并通过真实的基准测试（如LoCoMo）进行验证。

如果你在使用中遇到问题，或者有改进的想法，非常鼓励在GitHub提交Issue或Pull Request。社区也提供了丰富的资源：

视频教程 ：B站和YouTube上有详细的安装配置演示。
Claude Code Skill ：安装 UltraMemory-skill 后，你可以直接让Claude Code帮你分析和配置 UltraMemory ，它会理解所有配置项的含义。

5.4 最终建议：从小处着手，持续观察

给AI智能体添加长期记忆是一个“系统工程”，效果不是立竿见影的，而是随着时间积累越来越明显。

从小范围开始 ：先在一个特定的智能体或项目上启用，观察几天，看看它记住了什么，遗漏了什么。
查看记忆库 ：定期使用 openclaw memory-pro list 和 search 命令，检查记忆提取的质量。如果发现大量无意义的记忆，调整 noise-filter 或 extractMinMessages 。
关注检索日志 ：在开发模式下，关注智能体在回复前自动注入了哪些记忆。这些记忆是否相关？如果不相关，思考是检索权重问题，还是记忆本身存储得不好。
迭代配置 ：不要指望一次配置就完美。根据观察到的效果，微调权重、阈值、模型选择。这是一个让智能体逐渐“理解”你和你的工作方式的过程。

记住， UltraMemory 的目标不是创造一个全知全能的数据库，而是打造一个会学习、会遗忘、能在你需要时提供恰到好处提示的“第二大脑”。它的价值在于让AI交互从一次次独立的交易，变成一段持续发展的、有记忆的关系。