腾讯云开源Agent记忆系统：解决AI长期记忆难题的实践指南

📅 2026/7/11 14:31:59 👁️ 阅读次数 📝 编程学习

这次我们来看一个解决AI Agent长期记忆问题的开源项目——TencentDB Agent Memory。这个由腾讯云开源的Agent记忆系统，重点不是概念有多复杂，而是能不能在实际应用中真正解决"AI记不住事"的痛点。

如果你关心本地部署、零外部API依赖、长对话上下文管理，特别是希望Agent能记住你的工作习惯和项目背景，这篇文章值得直接收藏。项目采用4层渐进式流水线设计，支持符号化短期记忆和分层长期记忆，在OpenClaw集成测试中能将token使用量降低61.38%，任务通过率提升51.52%。

本文会带你完成从环境准备到功能验证的全流程，重点演示如何在OpenClaw和Hermes两大主流Agent框架中集成记忆能力，以及如何通过配置调优适应不同场景需求。

1. 核心能力速览

能力项	具体说明
项目类型	AI Agent记忆增强插件
开源团队	TencentCloud腾讯云
核心功能	符号化短期记忆 + 分层长期记忆
存储后端	本地SQLite + sqlite-vec（零外部API依赖）
集成框架	OpenClaw插件、Hermes Agent适配器
记忆分层	L0对话→L1原子事实→L2场景块→L3用户画像
检索策略	BM25 + 向量 + RRF混合检索
启动方式	插件自动加载、Docker一键部署、手动集成
API支持	提供Gateway HTTP接口（端口8420）
适合场景	长对话Agent、个性化助手、工作流记忆

2. 适用场景与使用边界

TencentDB Agent Memory最适合需要长期记忆的AI Agent应用场景。比如你有一个开发助手Agent，每次都要重新解释项目背景、代码规范、工具使用方式，这个插件能让Agent记住这些重复信息，显著提升交互效率。

典型适用场景：

个性化对话助手：记住用户偏好、常用指令、对话风格
开发工作流Agent：记忆项目结构、编码规范、调试历史
客服机器人：保留用户问题历史、解决方案模式
研究助手：积累领域知识、研究方法论

使用边界提醒：

记忆系统基于对话历史构建，需要足够的交互数据才能有效工作
隐私敏感场景需谨慎配置记忆保留策略
商业使用需确保符合数据保护法规要求
记忆准确性依赖LLM的提取和推理能力

3. 环境准备与前置条件

在开始部署前，需要确保基础环境就绪。TencentDB Agent Memory对硬件要求相对宽松，主要依赖在于软件框架。

操作系统要求：

Linux（Ubuntu 18.04+、CentOS 7+）
macOS 10.15+
Windows 10/11（WSL2推荐）

基础依赖：

Node.js 16+（Gateway服务）
Python 3.8+（部分工具脚本）
SQLite 3.35+（向量扩展支持）

框架依赖（二选一）：

OpenClaw 最新版本（插件模式）
Hermes Agent 环境（Gateway模式）

存储空间：

基础安装：100-200MB
记忆数据：根据使用量动态增长，建议预留1GB+

端口检查：

Hermes Gateway默认使用8420端口
确保端口未被占用或可配置其他端口

4. OpenClaw集成部署

OpenClaw是目前最成熟的集成方案，安装配置最为简单。下面以OpenClaw插件模式为例，展示完整的部署流程。

4.1 插件安装

# 安装记忆插件 openclaw plugins install @tencentdb-agent-memory/memory-tencentdb # 重启Gateway服务 openclaw gateway restart

如果已安装旧版本需要升级：

# 使用原生命令升级，避免语义版本范围导致的插件禁用 openclaw plugins update @tencentdb-agent-memory/memory-tencentdb

4.2 零配置启用

安装完成后，在OpenClaw配置文件中启用插件：

// ~/.openclaw/openclaw.json { "memory-tencentdb": { "enabled": true } }

启用后，TencentDB Agent Memory会自动处理对话捕获、记忆提取、场景聚合、用户画像生成，并在下一轮对话前进行记忆召回。

4.3 短期记忆压缩配置（可选）

对于需要处理长上下文的场景，可以启用短期记忆压缩功能：

{ "memory-tencentdb": { "config": { "offload": { "enabled": true } } } }

配置短期压缩的完整步骤：

在插件配置中注册上下文引擎槽位：

{ "plugins": { "slots": { "contextEngine": "memory-tencentdb" } } }

应用运行时补丁（提升工具调用消息的处理效果）：

bash scripts/openclaw-after-tool-call-messages.patch.sh

这个补丁只需要在每次OpenClaw安装后应用一次，升级后重新运行即可。

5. Hermes Agent集成部署

对于使用Hermes Agent的用户，TencentDB Agent Memory提供了Docker一键部署和现有环境集成两种方案。

5.1 Docker全新部署（推荐新手）

Docker方案将所有依赖打包，适合快速验证和生产部署：

# 进入Docker构建目录 cd docker/opensource # 构建镜像 docker build -f Dockerfile.hermes -t hermes-memory . # 运行容器（替换your-api-key为实际API密钥） docker run -d \ --name hermes-memory \ --restart unless-stopped \ -p 8420:8420 \ -e MODEL_API_KEY="your-api-key" \ -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \ -e MODEL_NAME="deepseek-v3.2" \ -e MODEL_PROVIDER="custom" \ -v hermes_data:/opt/data \ hermes-memory

环境变量说明：

MODEL_API_KEY: LLM API密钥（必需）
MODEL_BASE_URL: LLM端点，默认腾讯云LKE
MODEL_NAME: 模型名称，默认DeepSeek-V3.2
MODEL_PROVIDER: 提供商类型，custom适用于任何OpenAI兼容端点

5.2 现有Hermes环境集成

如果已有Hermes Agent环境，只需添加记忆能力：

# 1. 创建统一目录并下载插件 mkdir -p ~/.memory-tencentdb TEMP_DIR=$(mktemp -d) cd "$TEMP_DIR" npm init -y --silent npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb \ ~/.memory-tencentdb/tdai-memory-openclaw-plugin rm -rf "$TEMP_DIR" # 2. 安装Gateway依赖 cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin npm install --omit=dev npm install tsx # 3. 链接到Hermes插件目录 rm -rf ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb ln -sf ~/.memory-tencentdb/tdai-memory-openclaw-plugin/hermes-plugin/memory/memory_tencentdb \ ~/.hermes/hermes-agent/plugins/memory/memory_tencentdb

关键命名注意：目录名必须是memory_tencentdb（下划线），Hermes使用这个作为provider key。

5.3 Hermes配置调整

编辑Hermes配置文件声明记忆provider：

# ~/.hermes/config.yaml memory: provider: memory_tencentdb

配置Gateway环境变量：

# ~/.hermes/.env MEMORY_TENCENTDB_GATEWAY_CMD="sh -c 'cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin && exec npx tsx src/gateway/server.ts'" MEMORY_TENCENTDB_GATEWAY_HOST="127.0.0.1" MEMORY_TENCENTDB_GATEWAY_PORT="8420" TDAI_LLM_API_KEY="sk-your-api-key-here" TDAI_LLM_BASE_URL="https://api.openai.com/v1" TDAI_LLM_MODEL="gpt-4o"

或者使用配置文件方式：

{ "llm": { "baseUrl": "https://your-api-endpoint/v1", "apiKey": "your-api-key", "model": "your-model-name" } }

6. 功能测试与效果验证

部署完成后，需要通过实际对话测试记忆功能是否正常工作。

6.1 服务健康检查

首先验证Gateway服务状态：

curl http://127.0.0.1:8420/health

正常响应应为：{"status":"ok"}或{"status":"degraded"}

6.2 基础记忆测试

进行多轮对话测试记忆保持能力：

第一轮对话（建立记忆）：

用户："我喜欢用Markdown格式写文档，特别是表格要用三线表"
Agent："好的，已记录您偏好Markdown和三线表"

第二轮对话（间隔其他话题后）：

用户："帮我写个项目文档"
Agent："我会用Markdown格式为您编写，表格采用三线表样式"

如果Agent能正确回忆之前的偏好，说明长期记忆正常工作。

6.3 短期记忆压缩测试

对于启用短期压缩的场景，测试长任务中的上下文管理：

# 模拟长任务执行 # 观察context窗口的token使用量变化 # 验证Mermaid符号图是否能正确替代详细日志

6.4 记忆检索测试

通过工具调用测试记忆检索功能：

# 在Agent工具中调用记忆搜索 result = tdai_memory_search(query="用户文档偏好", session_key="current_session")

7. 配置参数调优指南

TencentDB Agent Memory提供了丰富的配置参数，适应不同使用场景。

7.1 日常调优参数（覆盖90%场景）

{ "memory-tencentdb": { "config": { "timezone": "system", "storeBackend": "sqlite", "recall": { "strategy": "hybrid", "maxResults": 5, "maxCharsPerMemory": 0, "maxTotalRecallChars": 0 }, "pipeline": { "everyNConversations": 5 }, "extraction": { "maxMemoriesPerSession": 20 }, "persona": { "triggerEveryN": 50 }, "offload": { "enabled": false } } } }

7.2 长任务场景优化

对于长对话或复杂任务场景，调整高级参数：

{ "pipeline": { "enableWarmup": true, "l1IdleTimeoutSeconds": 600, "l2MinIntervalSeconds": 900 }, "recall": { "timeoutMs": 5000 }, "offload": { "mildOffloadRatio": 0.5, "aggressiveCompressRatio": 0.85, "mmdMaxTokenRatio": 0.2 } }

7.3 自定义嵌入模型配置

如果需要使用自托管嵌入模型：

{ "embedding": { "enabled": true, "provider": "openai", "baseUrl": "http://your-host:your-port/v1", "apiKey": "<KEY>", "model": "bge-m3", "dimensions": 1024, "sendDimensions": false } }

注意：某些自托管模型（如BGE-M3）不支持Matryoshka表示，需要设置sendDimensions: false。

8. 接口API与批量任务

TencentDB Agent Memory通过Gateway提供完整的HTTP API，支持批量记忆操作。

8.1 核心API端点

健康检查：

GET http://localhost:8420/health

记忆搜索：

POST http://localhost:8420/search Content-Type: application/json { "query": "搜索关键词", "session_key": "会话标识", "max_results": 5 }

对话回忆：

POST http://localhost:8420/recall Content-Type: application/json { "query": "回忆查询", "session_key": "会话标识" }

8.2 Python客户端示例

import requests class MemoryClient: def __init__(self, base_url="http://localhost:8420", api_key=None): self.base_url = base_url self.headers = {} if api_key: self.headers["Authorization"] = f"Bearer {api_key}" def search_memory(self, query, session_key, max_results=5): payload = { "query": query, "session_key": session_key, "max_results": max_results } response = requests.post( f"{self.base_url}/search", json=payload, headers=self.headers, timeout=10 ) return response.json() def recall_context(self, query, session_key): payload = { "query": query, "session_key": session_key } response = requests.post( f"{self.base_url}/recall", json=payload, headers=self.headers, timeout=10 ) return response.json() # 使用示例 client = MemoryClient() results = client.search_memory("文档格式偏好", "user-session-123")

8.3 批量记忆处理

对于需要批量处理历史对话的场景：

def batch_process_conversations(conversation_files, session_key): memories = [] for file_path in conversation_files: with open(file_path, 'r', encoding='utf-8') as f: conversation = json.load(f) # 提取关键信息构建记忆 memory_entry = extract_memory_from_conversation(conversation) memories.append(memory_entry) # 批量存储记忆 return store_batch_memories(memories, session_key)

9. 安全配置与访问控制

Gateway服务提供了可选的安全增强配置，适合生产环境部署。

9.1 API密钥认证

启用Bearer Token认证：

# 设置网关API密钥 export TDAI_GATEWAY_API_KEY="your-secret-key-here" # 客户端调用时携带认证头 curl -H "Authorization: Bearer your-secret-key-here" \ -H "Content-Type: application/json" \ -d '{"query":"test","session_key":"session1"}' \ http://localhost:8420/search

9.2 CORS配置

控制跨域访问权限：

# 允许特定域名访问 export TDAI_CORS_ORIGINS="https://example.com,https://app.example.com" # 或本地开发时允许所有来源（仅开发环境） export TDAI_CORS_ORIGINS="*"

9.3 Hermes插件端配置

确保插件与安全网关协同工作：

# 设置插件端的API密钥（与网关相同） export MEMORY_TENCENTDB_GATEWAY_API_KEY="your-secret-key-here" # 或者使用统一环境变量名 export TDAI_GATEWAY_API_KEY="your-secret-key-here"

10. 性能观察与资源占用

在实际使用中需要关注系统的资源使用情况，特别是长时间运行时的表现。

10.1 内存与存储占用观察

SQLite数据库增长：

初始安装：50-100MB
每万条记忆：增加10-20MB
建议定期归档旧会话数据

进程内存占用：

Gateway服务：100-200MB
向量检索时：临时增加50-100MB
长时间运行：注意内存泄漏检查

10.2 检索性能指标

响应时间期望：

简单关键词检索：<100ms
向量相似度检索：200-500ms
混合检索：300-800ms
超时阈值：默认5000ms

并发处理能力：

单实例支持10-20并发检索
高频场景建议增加Gateway实例

10.3 监控与日志

启用详细日志观察系统行为：

# 查看Gateway日志 tail -f ~/.memory-tencentdb/tdai-memory-openclaw-plugin/logs/gateway.log # 监控检索性能 grep "search_time" ~/.memory-tencentdb/tdai-memory-openclaw-plugin/logs/gateway.log

11. 常见问题与排查方法

在实际部署和使用过程中可能会遇到各种问题，下面是常见问题的解决方案。

11.1 安装与启动问题

问题1：插件安装失败

症状：openclaw plugins install 命令执行失败 排查：检查网络连接、npm源配置、权限设置 解决：使用国内npm镜像源，确保有写权限

问题2：Gateway启动失败

症状：端口8420被占用或服务无法启动 排查：检查端口占用 netstat -tulpn | grep 8420 解决：杀死占用进程或修改配置使用其他端口

问题3：Hermes无法识别provider

症状：Hermes报错找不到memory_tencentdb provider 排查：检查符号链接是否正确，目录命名是否使用下划线 解决：确保目录名为memory_tencentdb而非memory-tencentdb

11.2 功能异常问题

问题4：记忆不生效

症状：对话历史没有被正确记忆和回忆 排查：检查配置文件是否正确启用，查看Gateway日志 解决：验证session_key一致性，检查记忆提取触发条件

问题5：检索结果不准确

症状：回忆的内容与查询不相关 排查：检查检索策略配置，验证嵌入模型是否正常 解决：调整hybrid检索参数，检查查询预处理逻辑

问题6：性能下降

症状：响应时间变慢，内存占用持续增长 排查：检查数据库使用量，观察检索日志 解决：清理旧会话数据，优化数据库索引

11.3 配置调优问题

问题7：记忆提取过于频繁

症状：系统资源消耗大，影响主任务性能 排查：检查pipeline.everyNConversations设置 解决：调整触发频率，启用空闲超时检测

问题8：上下文压缩过度

症状：重要细节丢失，Agent决策质量下降 排查：检查offload压缩比率设置 解决：调整mildOffloadRatio，增加MMD token预算

12. 最佳实践与使用建议

基于实际部署经验，总结以下最佳实践帮助提升使用效果。

12.1 会话管理策略

会话生命周期：

短期任务：使用同一session_key，充分利用短期记忆
长期项目：定期归档会话，建立项目级记忆库
用户个性化：维护稳定的用户标识，积累长期偏好

记忆清理策略：

设置合理的保留策略，避免存储无限增长
重要记忆手动标记保护，防止自动清理
定期审查记忆质量，清理低价值条目

12.2 性能优化建议

数据库优化：

定期执行VACUUM优化数据库空间
为常用查询字段建立索引
监控数据库文件大小，及时归档

检索效率提升：

根据查询模式选择合适检索策略（关键词/向量/混合）
设置合理的maxResults限制，避免返回过多结果
使用查询预处理，提升检索准确性

12.3 安全与隐私保护

数据保护：

生产环境务必启用API密钥认证
敏感信息在记忆提取前进行脱敏处理
定期审计记忆内容，确保符合隐私政策

访问控制：

Gateway服务避免绑定到0.0.0.0除非必要
使用防火墙限制访问来源IP
记录访问日志，监控异常行为

12.4 故障恢复与备份

数据备份：

定期备份~/.openclaw/memory-tdai/目录
重要记忆导出为可读格式存档
建立恢复演练流程，确保备份可用

监控告警：

监控服务健康状态，设置自动重启
监控存储空间使用，避免磁盘写满
设置性能阈值告警，及时发现异常

TencentDB Agent Memory为AI Agent提供了真正可用的长期记忆能力，通过分层设计和符号化压缩，在保持完整追溯能力的同时显著提升效率。无论是开发智能助手还是构建专业工作流Agent，这个项目都值得深入尝试。建议从OpenClaw插件入手快速验证核心功能，再根据实际需求逐步深入定制化配置。

编程学习技术分享实战经验

资讯详情