From d9f6291becc9639873038ab71d0b4dab8d5841bd Mon Sep 17 00:00:00 2001 From: chrishuan Date: Mon, 11 May 2026 14:28:14 +0800 Subject: [PATCH] docs: add contributing guidelines and update README_CN --- CONTRIBUTING.md | 133 ++++++++++++++ CONTRIBUTING_CN.md | 133 ++++++++++++++ README_CN.md | 438 +++++++++++++++++++++++++++++---------------- 3 files changed, 545 insertions(+), 159 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 CONTRIBUTING_CN.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..ff9763e --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,133 @@ +# Contributing Guide + +Thank you for your interest in the **TencentDB Agent Memory** project! We welcome all kinds of contributions from the community — whether it's reporting issues, improving documentation, or submitting code. + +## How to Contribute + +- **Report Bugs**: Describe the issue in GitHub Issues and provide steps to reproduce. +- **Request Features**: Describe your use case and proposed solution in Issues. +- **Improve Documentation**: Fix typos, clarify explanations, or add examples. +- **Submit Code**: Fix bugs, implement new features, or optimize performance. + +## Getting Started + +### Prerequisites + +- Node.js >= 22.16.0 +- npm or pnpm +- OpenClaw >= 2026.3.13 + +### Developing from Source + +This project requires no build step. Node.js 22.16+ natively supports TypeScript type stripping, and OpenClaw directly loads `.ts` source files at runtime. + +```bash +# Clone the repository +git clone https://github.com/Tencent/TencentDB-Agent-Memory.git +cd TencentDB-Agent-Memory + +# Install dependencies +npm install + +# Register the current directory as a local plugin in OpenClaw +openclaw plugins install --link . +``` + +`install --link` registers the current directory as a local plugin in OpenClaw. After modifying source code, simply restart the Gateway for changes to take effect. + +### Project Structure + +``` +├── index.ts # Plugin entry point +├── openclaw.plugin.json # OpenClaw plugin manifest +├── src/ +│ ├── config.ts # Configuration management +│ ├── conversation/ # L0 Conversation layer — raw dialogue capture +│ ├── record/ # L1 Record layer — structured information extraction +│ ├── scene/ # L2 Scene layer — scene summarization & aggregation +│ ├── persona/ # L3 Persona layer — user profile construction +│ ├── store/ # Storage layer — SQLite / vector database +│ ├── hooks/ # OpenClaw hooks integration +│ ├── prompts/ # LLM prompt templates +│ ├── tools/ # Tool functions +│ ├── utils/ # General utilities +│ └── report/ # Health check & reporting +├── hermes-plugin/ # Hermes agent plugin adapter +├── scripts/ # Helper scripts (Gateway control, etc.) +├── CHANGELOG.md # Changelog +└── README.md # Project documentation +``` + +## Submitting a Pull Request + +1. **Fork** this repository and create your feature branch from `main`. +2. **Make changes** — keep each commit focused and atomic. +3. **Test** — ensure existing functionality is not affected. +4. **Update documentation** — if changes affect user-facing behavior, update the README or related docs. +5. **Open a PR** — describe the motivation, changes, and link related Issues. + +### Branch Information + +| Branch | Purpose | +|--------|---------| +| `main` | Default branch, PR target | + +## Commit Message Convention + +Use the following format for commit messages: + +``` +(): + + + +Closes #123 +Signed-off-by: Your Name +``` + +### Types + +Aligned with the PR template Change Types: + +| Type | Description | PR Change Type | +|------|-------------|----------------| +| `fix` | Bug fix | Bug fix | +| `feat` | New feature | New feature | +| `docs` | Documentation update | Documentation update | +| `perf` | Performance optimization | Code optimization | +| `refactor` | Code refactoring (no behavior change) | Code optimization | +| `test` | Test related | — | +| `chore` | Build / tooling / dependency changes | — | + +### Scope Examples + +`store`, `hooks`, `persona`, `scene`, `record`, `conversation`, `gateway`, `hermes` + +## Code Style + +- **TypeScript**: Follow the existing code style in the project for consistency. +- **Naming**: Use meaningful variable and function names, prefer English. +- **Comments**: Add comments at critical logic points explaining "why" rather than "what". +- **Import order**: Node.js built-in modules → third-party dependencies → internal project modules. + +## Developer Certificate of Origin (DCO) + +All commits must include a `Signed-off-by` line, indicating your agreement to the [Developer Certificate of Origin](https://developercertificate.org/): + +```bash +git commit -s -m "feat(store): add batch insert support" +``` + +Commits without a valid `Signed-off-by` will not be merged. + +## Security Issues + +If you discover a security vulnerability, please report it via [GitHub Issues](https://github.com/Tencent/TencentDB-Agent-Memory/issues) and we will address it promptly. + +## License + +By submitting a contribution, you agree that your code will be licensed under the [MIT License](./LICENSE). + +--- + +Thank you again for contributing! If you have any questions, feel free to discuss them in Issues. diff --git a/CONTRIBUTING_CN.md b/CONTRIBUTING_CN.md new file mode 100644 index 0000000..58a2839 --- /dev/null +++ b/CONTRIBUTING_CN.md @@ -0,0 +1,133 @@ +# 贡献指南 + +感谢你对 **TencentDB Agent Memory** 项目的关注！我们欢迎来自社区的各种贡献——无论是报告问题、改进文档还是提交代码。 + +## 贡献方式 + +- **报告 Bug**：在 GitHub Issues 中描述问题并提供复现步骤。 +- **请求功能**：在 Issues 中描述使用场景和你期望的解决方案。 +- **改进文档**：修复错别字、完善说明或补充示例。 +- **提交代码**：修复 Bug、实现新功能或优化性能。 + +## 开发入门 + +### 前置条件 + +- Node.js >= 22.16.0 +- npm 或 pnpm +- OpenClaw >= 2026.3.13 + +### 从源码开发 + +本项目无需编译。Node.js 22.16+ 原生支持 TypeScript 类型剥离，OpenClaw 直接加载 `.ts` 源码运行。 + +```bash +# 克隆仓库 +git clone https://github.com/Tencent/TencentDB-Agent-Memory.git +cd TencentDB-Agent-Memory + +# 安装依赖 +npm install + +# 将当前目录作为本地插件注册到 OpenClaw +openclaw plugins install --link . +``` + +`install --link` 会将当前目录作为本地插件注册到 OpenClaw，修改源码后重启 Gateway 即可生效。 + +### 项目结构 + +``` +├── index.ts # 插件入口 +├── openclaw.plugin.json # OpenClaw 插件清单 +├── src/ +│ ├── config.ts # 配置管理 +│ ├── conversation/ # L0 对话层 — 原始对话捕获 +│ ├── record/ # L1 记录层 — 结构化信息提取 +│ ├── scene/ # L2 场景层 — 场景归纳与聚合 +│ ├── persona/ # L3 画像层 — 用户画像构建 +│ ├── store/ # 存储层 — SQLite/向量数据库 +│ ├── hooks/ # OpenClaw 钩子集成 +│ ├── prompts/ # LLM 提示词模板 +│ ├── tools/ # 工具函数 +│ ├── utils/ # 通用工具 +│ └── report/ # 健康检测与报告 +├── hermes-plugin/ # Hermes 智能体插件适配 +├── scripts/ # 辅助脚本（Gateway 控制等） +├── CHANGELOG.md # 变更日志 +└── README.md # 项目说明 +``` + +## 提交 Pull Request + +1. **Fork** 本仓库并基于 `main` 分支创建你的特性分支。 +2. **进行修改** — 保持每个提交专注且原子化。 +3. **测试** — 确保现有功能不受影响。 +4. **更新文档** — 如果更改涉及用户可见行为，请同步更新 README 或相关文档。 +5. **提交 PR** — 描述修改动机、变更内容，并关联相关 Issue。 + +### 分支说明 + +| 分支 | 用途 | +|------|------| +| `main` | 默认分支，PR 提交目标 | + +## 提交信息规范 + +使用以下格式编写 commit message： + +``` +<类型>(<范围>): <简要描述> + +<详细说明（可选）> + +Closes #123 +Signed-off-by: Your Name +``` + +### 类型 + +与 PR 模板中的 Change Type 对应： + +| 类型 | 说明 | 对应 PR Change Type | +|------|------|---------------------| +| `fix` | Bug 修复 | Bug fix | +| `feat` | 新功能 | New feature | +| `docs` | 文档更新 | Documentation update | +| `perf` | 代码优化 | Code optimization | +| `refactor` | 代码重构（不影响功能） | Code optimization | +| `test` | 测试相关 | — | +| `chore` | 构建/工具/依赖变更 | — | + +### 范围示例 + +`store`、`hooks`、`persona`、`scene`、`record`、`conversation`、`gateway`、`hermes` + +## 代码风格 + +- **TypeScript**：使用项目已有的代码风格，保持一致性。 +- **命名**：使用有意义的变量名和函数名，优先使用英文。 +- **注释**：关键逻辑处添加注释，说明"为什么"而非"做了什么"。 +- **导入顺序**：Node.js 内置模块 → 第三方依赖 → 项目内部模块。 + +## 开发者来源证书 (DCO) + +所有提交必须包含 `Signed-off-by` 行，表示你同意 [开发者来源证书](https://developercertificate.org/)： + +```bash +git commit -s -m "feat(store): add batch insert support" +``` + +没有有效 `Signed-off-by` 的提交将不会被合并。 + +## 安全问题 + +如果你发现安全漏洞，请通过 [GitHub Issues](https://github.com/Tencent/TencentDB-Agent-Memory/issues) 报告，我们会尽快处理。 + +## 许可证 + +提交贡献即表示你同意你的代码将在 [MIT License](./LICENSE) 下许可。 + +--- + +再次感谢你的贡献！如有任何问题，欢迎在 Issues 中讨论。 diff --git a/README_CN.md b/README_CN.md index 57adef6..de378f3 100644 --- a/README_CN.md +++ b/README_CN.md @@ -1,201 +1,321 @@ -[English](README.md) +
-

TencentDB Agent Memory

+TencentDB Agent Memory -

没有记忆的AI，只是工具；有记忆的AI，才是资产。

+### TencentDB Agent Memory + +面向生产级 Agent 的自进化记忆基础设施 —— **短期压缩 × 长期沉淀**。 + +[![npm](https://img.shields.io/npm/v/@tencentdb-agent-memory/memory-tencentdb?color=blue)](https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE) +[![Node](https://img.shields.io/badge/node-%3E=22.16-brightgreen)](https://nodejs.org/) +[![OpenClaw](https://img.shields.io/badge/OpenClaw-%3E=2026.3.13-orange)](https://github.com/openclaw/openclaw) +![Hermes](https://img.shields.io/badge/Hermes-Gateway-7B61FF) + +[效果亮点](#效果亮点) · [项目简介](#项目简介) · [特点](#特点) · [快速开始](#快速开始) + +
+ +--- + +## ✨ 效果亮点 + +> **TencentDB Agent Memory = 短期记忆压缩 + 长期个性化记忆。** +> +> - **短期记忆压缩**：把长任务上下文变轻，让 Agent 不再背着全部工具日志继续推理。 +> - **长期个性化记忆**：把碎片化对话提炼为结构化记忆、场景块和用户画像。 + +**作为 OpenClaw 插件接入后**：最高节省 **63.59% Token**，通过率相对提升 **41.18%**；PersonaMem 准确率从 **48%** 提升到 **76%**。 + +| 记忆能力 | 场景 / Benchmark | 提升效果 | +| :--- | :--- | :--- | +| **短期记忆压缩** | WideSearch 200 题网页搜索 | Token 最高节省 **63.59%**，通过率相对提升 **41.18%** | +| **短期记忆压缩** | SWE-bench 500 题代码修复 | 完成率 **58.4% → 64.2%**，相对提升 **9.93%**，Token 节省 **33.09%** | +| **短期记忆压缩** | AA-LCR 800 题长文分析 | 准确率 **44.0% → 47.5%**，总 Token 节省 **31%** | +| **长期个性化记忆** | PersonaMem：6000+ 消息 / 589 题 | 准确率 **48% → 76%**，相对提升 **59%** | + +> 超长 Session 评测不是单题清空上下文，而是把多个任务拼接到同一个 Session 中连续执行。例如 SWE-bench 每个 Session 连续执行 50 个任务，用来模拟真实长程 Agent 的上下文累积压力。 + +--- + +## 简单介绍 + +**TencentDB Agent Memory 不是把历史暴力堆进上下文，也不是把一切压成不可恢复的摘要。** + +我们把记忆设计成一套分层信息管理系统：低层保留原始证据，高层保留语义结构；当前需要的进入上下文，暂时不用的外部化保存，需要时再沿着索引找回。 + +数据库负责事实检索，文件系统负责任务画布、场景块和用户画像。短期记忆压缩解决长任务中的过程信息过载，长期个性化记忆解决跨会话的用户理解沉淀。 + +> **让 Agent 少背负，但不丢失；少重复，但能追溯。** + +它由两块能力组成： + +### 短期记忆压缩：Mermaid无限画布 ✖️ 上下文卸载 + +长任务里最占上下文的往往不是用户目标，而是工具调用产生的过程信息：搜索结果、网页正文、文件片段、测试日志、报错、diff、中间版本。TencentDB Agent Memory 会把这些完整信息卸载到外部文件，只把摘要、路径和任务状态保留在上下文附近。 + +```text +工具结果 + └─► refs/*.md 保存完整原文 + └─► offload-*.jsonl 保存工具调用级摘要与 result_ref + └─► mmds/*.mmd 保存 Mermaid 任务画布 + └─► 上下文 只注入当前任务最需要的结构化状态 +``` + +这里的关键不是“删掉历史”，而是“折叠历史”：Agent 平时看任务地图，需要细节时再沿着 `node_id` 和 `result_ref` 下钻到原始证据。 + +### 长期个性化记忆：从信息碎片到用户画像 + +跨会话记忆面对的是另一个问题：原始对话日志是低密度矿藏，里面有偏好、有事实、有情绪、有长期目标，也有大量噪音。单纯向量检索只能找到“相似片段”，很难挖出用户长期稳定的特质。 + +TencentDB Agent Memory 用 L0 → L3 的金字塔管线逐层提纯：

- OpenClaw Plugin - MIT License + TencentDB Agent Memory L0 to L3 semantic pyramid

+上层画像负责让 Agent “懂你”，下层记忆负责在事实细节上兜底。这样 Agent 既能有宏观判断，也能在需要时查到具体证据。 -**TencentDB Agent Memory是腾讯云数据库团队自研的 Agent 记忆系统**，为 OpenClaw 补上长期连续的记忆。通过四层渐进式记忆金字塔架构，自动完成记忆写入、分层提炼、按需召回与注入，让 Agent 从“只能聊天对话”进化为“持续学习、更懂你、跨会话不断线的长期可依赖 AI 助理”。 - -## 评测 - -基于 [PersonaMem](https://github.com/jiani-huang/PersonaMem)（UPenn，COLM 2025）评测集，589 道题，20 个角色。 - -| 题型 | OpenClaw 原生记忆 | TencentDB Agent Memory | -| :----------- | :---------------: | :---------: | -| 召回更新原因 | 70.97% | **88.89%** | -| 偏好演变跟踪 | 66.67% | **83.45%** | -| 个性化推荐 | 46.67% | **76.36%** | -| 场景泛化 | 31.58% | **78.95%** | -| 召回用户事实 | 29.63% | **79.07%** | -| 召回事实 | 25.00% | **76.47%** | -| 创意建议 | 24.00% | **45.16%** | -| **总计** | **47.85%** | **76.10%** | - -## 主要特点 - -- **OpenClaw 原生插件**，包名 `@tencentdb-agent-memory/memory-tencentdb`，一行命令即可安装 -- **四层记忆链路**：L0 原始对话 → L1 结构化记忆 → L2 场景归纳 → L3 用户画像 -- **混合召回**：支持 `keyword`、`embedding`、`hybrid` 三种策略 -- **两类检索工具**：`tdai_memory_search`（查结构化记忆）和 `tdai_conversation_search`（查原始对话） -- **本地优先存储**：JSONL + SQLite，数据在本地可直接查看和排查 -- **工程化能力**：去重、checkpoint、备份、定时清理、指标日志 -- **MIT 许可证** +--- ## 快速开始 -### 环境要求 - -- Node.js `>= 22.16.0` -- OpenClaw `>= 2026.3.13` - -### 安装 +### 1. 安装插件 ```bash openclaw plugins install @tencentdb-agent-memory/memory-tencentdb +openclaw gateway restart ``` -安装完成后，插件接入 OpenClaw 对话生命周期，自动执行对话捕获、记忆召回和 L1/L2/L3 后续处理。 +### 2. 零配置启用 -### 从源码开发 +默认使用本地 `SQLite + sqlite-vec` 后端。 -本项目无需编译。Node.js 22.16+ 原生支持 TypeScript 类型剥离，OpenClaw 直接加载 `.ts` 源码运行。 - -```bash -git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git -cd TencentDB-Agent-Memory -npm install -openclaw plugins install --link . +```jsonc +// ~/.openclaw/openclaw.json +{ + "memory-tencentdb": { + "enabled": true + } +} ``` -`install --link` 会将当前目录作为本地插件注册到 OpenClaw，修改源码后重启 Gateway 即可生效。 +启用后，TencentDB Agent Memory 会自动完成对话录制、记忆提取、场景归纳、用户画像生成和下一轮对话前召回。 -### 可选：开启 embedding 召回 - -如果需要向量检索或混合召回，补充 embedding 配置即可。当前支持兼容 OpenAI API 的远程 embedding 服务。 +### 3. 使用 TCVDB 后端（可选） ```jsonc { - "plugins": { - "entries": { - "memory-tencentdb": { - "enabled": true, - "config": { - "embedding": { // 需配置自定义Embedding模型信息，非LLM模型 - "enabled": true, // 是否启用向量搜索 - "provider": "openai", // 暂只支持OpenAI兼容的协议 - "baseUrl": "https://xxx", // API Base URL - "apiKey": "xxx", // API Key - "model": "text-embedding-3-large", // 模型名称 - "dimensions": 1024 // 向量维度（需与所选模型匹配） - } - } - } + "memory-tencentdb": { + "storeBackend": "tcvdb", + "tcvdb": { + "url": "http://your-vdb-instance:8100", + "apiKey": "your-api-key", + "database": "my_memory_db" } } } - ``` +### 4. 启用短期记忆压缩（可选） -## 架构 - -```text - ┌─────────────────┐ - │ L3 用户画像 │ 偏好与行为模式 - ├─────────────────┤ - │ L2 场景归纳 │ 跨会话的任务 / 场景块 - ├─────────────────┤ - │ L1 结构化记忆 │ 事实、约束、偏好、决策 - ├─────────────────┤ - │ L0 原始对话 │ 完整对话记录 - └─────────────────┘ +```jsonc +{ + "memory-tencentdb": { + "offload": { + "enabled": true + } + } +} ``` -各层各有侧重： +### 5. 常用命令 -- **L0** 保留原始对话，用于回溯和精确检索 -- **L1** 抽取高价值信息，直接用于召回 -- **L2** 将零散记忆整理成场景块，跨会话聚合 -- **L3** 维护用户画像，用于长期偏好建模 +```bash +# 导入历史对话，完整执行 L0 → L3 管线 +openclaw memory-tdai seed --input conversations.json -## 生命周期 +# SQLite 数据迁移到 TCVDB +migrate-sqlite-to-tcvdb --help -| 阶段 | 触发时机 | 动作 | -|---|---|---| -| Recall | `before_prompt_build` | 召回相关记忆，注入上下文 | -| L0 | `agent_end` | 写入原始对话 | -| L1 | 调度触发 | 提取结构化记忆，去重，持久化 | -| L2 | L1 完成后 | 更新场景块 | -| L3 | 达到阈值 | 生成或刷新用户画像 | -| Shutdown | `gateway_stop` | 清理资源 | - -插件还注册了两个 tool 供 Agent 主动调用： - -- `tdai_memory_search`：查 L1 结构化记忆。适合"用户偏好什么""之前确认过哪些约束"类问题。 -- `tdai_conversation_search`：查 L0 原始对话。适合需要原始措辞的场景。 - -## 检索实现 - -三种召回策略： - -| 策略 | 实现 | -|---|---| -| `keyword` | FTS5 全文检索，中文分词基于 jieba | -| `embedding` | sqlite-vec 向量相似度检索 | -| `hybrid` | 融合关键词与向量结果 | - -底层存储统一用 SQLite。 - -## 配置 - -按能力分组： - -| 配置组 | 作用 | -|---|---| -| `capture` | L0 对话捕获、排除规则、保留时间 | -| `extraction` | L1 提取、去重、单次上限 | -| `persona` | L2/L3 触发频率、场景上限、备份数量 | -| `pipeline` | L1/L2/L3 调度节奏 | -| `recall` | 自动召回开关、结果数、阈值、策略 | -| `embedding` | 向量检索服务配置 | -| `report` | 指标日志 | - -最小配置只需要安装插件。如果需要更好的召回效果，再加 `embedding` 和调度参数。 - -## 数据目录 - -```text -/ -├── conversations/ # L0 原始对话 -├── records/ # L1 结构化记忆 -├── scene_blocks/ # L2 场景块 -├── .metadata/ # checkpoint、索引、元数据 -└── .backup/ # 备份 +# 导出腾讯云向量数据库数据 +export-tencent-vdb --help ``` -## 仓库范围 +完整配置见 [`CONFIGURATION.md`](./CONFIGURATION.md)，CLI 输入格式见 [`src/cli/README.md`](./src/cli/README.md)。 -当前仓库是 OpenClaw 插件的核心实现。 +--- -**包含**：插件入口与生命周期钩子、四层记忆链路、检索工具与自动召回、JSONL + SQLite 本地存储、checkpoint / 备份 / 清理 / 日志。 +## 🔧 可调参数 -### 代码结构 +**所有字段均有合理默认值，零配置即可跑。** 如果要调优，可以按使用深度逐层展开。 -```text -TencentDB-Agent-Memory/ -├── index.ts # 插件注册、工具注册、生命周期接入 -├── openclaw.plugin.json -├── package.json -├── CHANGELOG.md -└── src/ - ├── hooks/ # 自动召回与自动捕获 - ├── conversation/ # L0 对话管理 - ├── record/ # L1 提取与持久化 - ├── scene/ # L2 场景归纳 - ├── persona/ # L3 用户画像 - ├── store/ # SQLite / FTS / 向量检索 - ├── tools/ # 检索工具注册 - ├── prompts/ # prompt 模板 - ├── report/ # 指标上报 - └── utils/ -``` +
+🟢 Level 1 · 日常调参（覆盖 90% 使用场景） -## 许可证 +| 字段 | 默认 | 说明 | +| :--- | :--- | :--- | +| `storeBackend` | `"sqlite"` | 存储后端：`sqlite` / `tcvdb` | +| `recall.strategy` | `"hybrid"` | 召回策略：`keyword` / `embedding` / `hybrid`（RRF 融合，推荐） | +| `recall.maxResults` | `5` | 每次召回条数 | +| `pipeline.everyNConversations` | `5` | 每 N 轮对话触发一次 L1 记忆提取 | +| `extraction.maxMemoriesPerSession` | `20` | 单次 L1 最多提取多少条 | +| `persona.triggerEveryN` | `50` | 每 N 条新记忆触发用户画像生成 | +| `offload.enabled` | `false` | 是否启用短期记忆压缩 | -MIT。详见 [LICENSE](LICENSE)。 \ No newline at end of file +
+ +
+🟡 Level 2 · 进阶调优（长任务 / 长 Session 场景） + +| 字段 | 默认 | 说明 | +| :--- | :--- | :--- | +| `pipeline.enableWarmup` | `true` | Warm-up：新 session 从 1 轮起触发，每次翻倍至 N（1→2→4→…） | +| `pipeline.l1IdleTimeoutSeconds` | `600` | 用户停止对话多久后触发 L1 | +| `pipeline.l2MinIntervalSeconds` | `900` | 同 session 两次 L2 之间的最小间隔 | +| `recall.timeoutMs` | `5000` | 召回超时阈值，超时跳过注入不阻塞对话 | +| `extraction.enableDedup` | `true` | L1 向量去重 / 冲突检测 | +| `capture.excludeAgents` | `[]` | Glob 模式排除特定 Agent（如 `bench-judge-*`） | +| `capture.l0l1RetentionDays` | `0` | L0/L1 本地文件保留天数，`0` = 永不清理 | +| `offload.mildOffloadRatio` | `0.5` | 温和压缩触发比例（占 context window） | +| `offload.aggressiveCompressRatio` | `0.85` | 激进压缩触发比例 | +| `offload.mmdMaxTokenRatio` | `0.2` | MMD 注入 token 预算比例 | +| `bm25.language` | `"zh"` | 分词语言：`zh`（jieba） / `en` | + +
+ +
+🔴 Level 3 · 完整参数表（运维 / 自定义模型 / 远程 embedding） + +完整字段、类型、约束见 [`openclaw.plugin.json`](./openclaw.plugin.json) 与 [`CONFIGURATION.md`](./CONFIGURATION.md)。 + +- `embedding.*` — 远程 embedding 服务（OpenAI 兼容 API） +- `tcvdb.*` — 腾讯云向量数据库完整参数（含 HTTPS / 自签 CA） +- `llm.*` — 独立 LLM 模式（绕过 OpenClaw 内置模型，用指定 API 跑 L1/L2/L3） +- `offload.backendUrl / backendApiKey` — 将 L1/L1.5/L2/L4 offload 流程卸载到后端服务 +- `report.*` — 指标上报 + +
+ +--- + +## 🤔 方案特点 + +### 1. 渐进式披露：短期压缩任务，长期沉淀用户 + +TencentDB Agent Memory 的核心不是“多存一点”，而是**把信息按密度和用途分层**： + +- **短期记忆压缩**解决“当前任务太长”的问题：把原始工具结果卸载到外部，把任务结构折叠成 Mermaid 画布。 +- **长期个性化记忆**解决“下次见面不认识你”的问题：把原始对话逐层提纯成结构化记忆、场景块和用户画像。 + +两者共享同一条工程逻辑：**低层保留证据，高层保留结构；平时看高层，需要时下钻到底层。** + +| 方向 | 低层：保真 | 中层：组织 | 高层：压缩 / 抽象 | 目标 | +| :--- | :--- | :--- | :--- | :--- | +| 短期记忆压缩 | `refs/*.md` 原始工具结果 | `offload-*.jsonl` 工具摘要 | `mmds/*.mmd` Mermaid 任务画布 / metadata | 长任务继续做，不被上下文拖垮 | +| 长期个性化记忆 | L0 原始对话 | L1 结构化记忆 / L2 场景块 | L3 用户画像 `persona.md` | 下次再见面，Agent 更懂用户 | + +这让 Agent 可以像人一样工作：先看目录，再看章节，最后才翻原始资料。上下文窗口不再是一张越堆越满的桌子，而是一张可以折叠和展开的工作台。 + +### 2. 长期个性化记忆：L0 → L3 语义金字塔 + +长期记忆不是“把聊天记录存起来”这么简单。真正有价值的是从对话碎片中挖出稳定偏好、隐含目标和场景化经验。 + +| 层级 | 产物 | 信息变化 | +| :--- | :--- | :--- | +| L0 | 原始对话 | 保留事实底座，但噪音最大、密度最低 | +| L1 | 结构化原子记忆 | 从对话中提取干净事实，适合语义 + 时序检索 | +| L2 | 场景块 | 将相关记忆聚合成场景，理解“在某类情境下用户如何行动” | +| L3 | 用户画像 | 提炼长期偏好、稳定特质和决策风格，作为高密度上下文注入 | + +这套结构类似 DIKW 金字塔：从 Data 到 Information，再到 Knowledge，最后变成 Wisdom。它让 Agent 不只是回忆“用户说过什么”，而是理解“用户可能需要什么”。 + +### 3. 宏观画像 + 微观事实：同一套下钻机制降低幻觉 + +压缩最大的风险是“省了 Token，也丢了证据”。因此 TencentDB Agent Memory 没有把历史压成一段不可恢复的 summary，而是保留了从高层摘要回到底层证据的路径。 + +| 问题类型 | 优先使用 | 继续下钻 | +| :--- | :--- | :--- | +| 日常偏好、表达风格、长期目标 | L3 Persona / L2 Scene | 需要事实时查 L1 / L0 | +| 具体事实、时间、项目细节 | L1 Memory / L0 Conversation | 命中不足时扩大时间范围或语义检索 | +| 当前长任务继续执行 | Active MMD 任务画布 | 摘要不够时查 JSONL，再读 `refs/*.md` 原文 | +| 历史任务恢复 | Metadata 任务入口 | 打开 MMD → 找 node_id → 追 result_ref | + +上层负责“情商”和方向，下层负责“证据”和精度。短期压缩和长期记忆在这里合成一条闭环：**能折叠，也能展开；能抽象，也能追证。** + +### 4. 白盒可调试：记忆不是黑盒向量 + +很多记忆系统的问题是：召回错了，你只能看到一串向量分数，很难判断到底哪里错。TencentDB Agent Memory 把关键中间产物保存在可读文件里： + +- L2 场景块是 Markdown，可以直接打开检查。 +- L3 用户画像是 `persona.md`，可以追溯到对应场景。 +- 短期任务画布是 Mermaid，既能给人看，也能给 Agent 读。 +- 原文、摘要、节点之间有 `result_ref` 和 `node_id` 关联。 + +这意味着调试不再是翻黑盒数据库，而是沿着“画像 → 场景 → 记忆 → 原文”的链路逐层定位。 + +### 5. 异构存储解耦：数据库保事实，文件系统保结构 + +长期记忆和短期压缩看起来是两套功能，底层其实遵循同一条存储原则：**数据库负责可检索的事实，文件系统负责可读可改的结构。** + +| 信息类型 | 存储介质 | 为什么这样放 | +| :--- | :--- | :--- | +| L0 / L1 长期记忆底座 | SQLite 或 TCVDB | 数据量大、需要语义检索和时序查证 | +| L2 / L3 场景与画像 | Markdown 文件 | 需要业务可读、Prompt 可调、渐进式披露 | +| Offload 原文 | `refs/*.md` | 原始证据必须完整保留，但不应常驻上下文 | +| Offload 摘要 | JSONL | 方便按 `node_id` 检索工具调用历史 | +| Offload 任务结构 | Mermaid 文件 | 让 Agent 和人都能看懂任务如何推进 | + +底层像弹药库，负责稳定、完整、可检索；顶层像作战地图，负责灵活、可读、能快速迭代。短期压缩的画布和长期记忆的画像，本质上都是“给 Agent 看得懂的高密度工作面”。 + +### 6. 工程能力完整：不是 Demo，而是可接入的插件 + +| 能力 | 说明 | +| :--- | :--- | +| OpenClaw 插件 | 安装后即可自动捕获、提取、召回记忆 | +| Hermes Gateway 适配 | `TdaiCore + HostAdapter` 解耦宿主框架 | +| 双后端 | 本地 `SQLite + sqlite-vec`，或远端 `TCVDB` | +| 混合检索 | BM25 + 向量 + RRF，兼顾关键词和语义召回 | +| Agent 工具 | `tdai_memory_search` / `tdai_conversation_search` | +| 数据迁移 | 支持历史导入、SQLite → TCVDB 迁移、VDB 导出 | + +--- + +## 文档 + +| 文档 | 内容 | +| :--- | :--- | +| [`CONFIGURATION.md`](./CONFIGURATION.md) | 完整配置参考、字段说明与高级参数 | +| [`src/cli/README.md`](./src/cli/README.md) | `openclaw memory-tdai seed` 历史对话导入说明 | +| [`scripts/README.memory-tencentdb-ctl.md`](./scripts/README.memory-tencentdb-ctl.md) | 运维管理工具说明 | +| [`CHANGELOG.md`](./CHANGELOG.md) | 版本变更记录 | +| [`openclaw.plugin.json`](./openclaw.plugin.json) | OpenClaw 插件声明与配置 Schema | + +--- + +## Roadmap + +- [x] 长期个性化记忆（L0 → L3） +- [x] 短期记忆压缩（Context Offload + Mermaid 画布） +- [x] 本地 SQLite 后端与腾讯云向量数据库 TCVDB 后端 +- [x] OpenClaw 插件与 Hermes Gateway 适配 +- [ ] 短期记忆压缩正式产品化上线 +- [ ] 记忆可迁移：跨 Agent / 跨框架 / 跨设备的导入导出与热迁移 +- [ ] 更多 Agent 框架适配 +- [ ] 可视化调试与记忆观测面板 + +--- + + + + + + +
+ 如果 TencentDB Agent Memory 对你有所帮助，欢迎为项目点亮 ⭐ 支持。
+ 如果有任何建议，欢迎提出issue讨论。 + 		+ Star TencentDB Agent Memory +
+ +[MIT](./LICENSE) © TencentDB Agent Memory Team