mirror of
https://github.com/TencentCloud/TencentDB-Agent-Memory
synced 2026-07-10 12:34:27 +00:00
Update README_CN.md
This commit is contained in:
chrishuan
+64
-79
@@ -1,10 +1,9 @@
|
|||||||
<div align="center">
|
<div align="center">
|
||||||
|
|
||||||
<img src="./assets/images/logo2.png" alt="TencentDB Agent Memory" width="880" />
|
<img src="./assets/images/logo.png" alt="TencentDB Agent Memory" width="880" />
|
||||||
|
|
||||||
### TencentDB Agent Memory
|
### 让 Agent 沉淀经验，让人专注创造。
|
||||||
|
|
||||||
让 Agent 记住固定流程、沉淀历史经验、复用用户偏好，**把人的注意力从重复工作中释放出来，回到创造、判断和生活本身**。
|
|
||||||
|
|
||||||
[](https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb)
|
[](https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb)
|
||||||
[](./LICENSE)
|
[](./LICENSE)
|
||||||
@@ -20,16 +19,16 @@
|
|||||||
|
|
||||||
## ✨ 效果亮点
|
## ✨ 效果亮点
|
||||||
|
|
||||||
> **TencentDB Agent Memory = 短期记忆压缩 + 长期个性化记忆。**
|
> **TencentDB Agent Memory = 符号化短期记忆压缩 + 分层式长期个性化记忆。**
|
||||||
>
|
>
|
||||||
> - **短期记忆压缩**：把长任务上下文变轻，让 Agent 不再背着全部工具日志继续推理。
|
> - **短期记忆压缩**：将厚重的工具日志分层卸载，逐步总结成轻量级 Mermaid 结构符号，大幅降低 Token 消耗。
|
||||||
> - **长期个性化记忆**：把碎片化对话提炼为结构化记忆、场景块和用户画像。
|
> - **长期个性化记忆**：把碎片化对话层层提炼，沉淀出有层次的画像与场景，不再是扁平的向量堆砌。
|
||||||
|
|
||||||
**作为 OpenClaw 插件接入后**：最高节省 **63.59% Token**，通过率相对提升 **41.18%**；PersonaMem 准确率从 **48%** 提升到 **76%**。
|
**作为 OpenClaw 插件接入后**：最高节省 **61.38% Token**，通过率相对提升 **51.52%**；PersonaMem 准确率从 **48%** 提升到 **76%**。
|
||||||
|
|
||||||
| 记忆能力 | Benchmark | Clawpro 成功率 | 加插件后成功率 | 相对变化 | Clawpro Token 消耗 | 加插件后 Token 消耗 | 相对变化 |
|
| 记忆能力 | Benchmark | Clawpro 成功率 | 加插件后成功率 | 相对变化 | Clawpro Token 消耗 | 加插件后 Token 消耗 | 相对变化 |
|
||||||
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
|
| :---- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||||
| **短期记忆** | WideSearch | 8.5% | **12%** | **+41.18%** | 174.31M | **63.46M** | **−63.59%** |
|
| **短期记忆** | WideSearch | 33% | **50%** | **+51.52%** | 221.31M | **85.64M** | **−61.38%** |
|
||||||
| **短期记忆** | SWE-bench | 58.4% | **64.2%** | **+9.93%** | 3474.1 | **2375.4** | **−33.09%** |
|
| **短期记忆** | SWE-bench | 58.4% | **64.2%** | **+9.93%** | 3474.1 | **2375.4** | **−33.09%** |
|
||||||
| **短期记忆** | AA-LCR | 44.0% | **47.5%** | **+7.95%** | 112.0M | **77.3M** | **−31%** |
|
| **短期记忆** | AA-LCR | 44.0% | **47.5%** | **+7.95%** | 112.0M | **77.3M** | **−31%** |
|
||||||
| **长期记忆** | PersonaMem | 48% | **76%** | **+59%** | — | — | — |
|
| **长期记忆** | PersonaMem | 48% | **76%** | **+59%** | — | — | — |
|
||||||
@@ -38,45 +37,75 @@
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
||||||
## 项目简介
|
## 项目简介
|
||||||
|
|
||||||
**Memory 不是为了让 AI 存下所有东西，而是为了让人不必重复所有事情。**
|
**Memory 不是为了让 AI 存下所有东西，而是为了让人不必重复所有事情。**
|
||||||
|
|
||||||
TencentDB Agent Memory 帮助 Agent 学会你的流程、保留任务上下文、复用历史经验，让人把注意力留给判断、创造和真正有价值的工作。
|
在实际使用中，我们往往需要反复告诉 Agent 固定 SOP、项目背景、工具习惯和输出格式。这些信息不应该每次重新解释，但同时也不应该被无脑、扁平地全部塞进上下文。
|
||||||
|
|
||||||
真实工作里，很多内容不应该被用户反复交代：固定 SOP、常用分析口径、项目背景、用户偏好等。因此，我们把这些稳定经验沉淀下来，让 Agent 在合适的时候自动复用。
|
TencentDB Agent Memory 帮助 Agent 学会你的流程、保留任务上下文、复用历史经验。但我们**拒绝暴力的历史堆砌**，也**抛弃不可逆的暴力摘要**。我们将记忆设计为一套极具层次感的系统，以**符号化记忆**解决单次长任务的信息过载，以**记忆分层**解决跨会话的经验沉淀。
|
||||||
|
|
||||||
TencentDB Agent Memory 不是简单的历史记录、不可恢复的摘要，也不是单纯的 RAG。我们把记忆设计成一套分层信息管理系统：数据库负责可检索、可过滤、可召回的事实底座；文件系统负责承载可读、可编辑、可逐步展开的任务画布、场景块和用户画像。短期记忆压缩解决长任务中的过程信息过载，长期个性化记忆解决跨会话的用户理解沉淀。
|
> **让 Agent 记住该记的，让人把注意力留给判断、创造和真正有价值的工作。**
|
||||||
|
|
||||||
> **让 Agent 记住该记的，让人专注于更有价值的创造。**
|
---
|
||||||
|
|
||||||
它由两块能力组成：
|
## 核心技术：拒绝平铺，走向分层与符号化
|
||||||
|
|
||||||
### 短期记忆压缩：Mermaid无限画布 ✖️ 上下文卸载
|
TencentDB Agent Memory 的设计理念围绕两个核心展开：**记忆分层** 与 **符号化记忆**。这不仅让 Agent “记得更多”，更重要的是“想得更清”。
|
||||||
|
|
||||||
长任务里最占上下文的往往不是用户目标，而是工具调用产生的过程信息：搜索结果、网页正文、文件片段、测试日志、报错、diff、中间版本。TencentDB Agent Memory 会把这些完整信息卸载到外部文件，只把摘要、路径和任务状态保留在上下文附近。
|
### 1. 记忆分层：渐进式披露与异构存储
|
||||||
|
|
||||||
```text
|
传统的记忆系统往往将所有数据切片并平铺为向量，召回时如同在一堆毫无关联的便利贴中寻找线索，缺乏宏观视角的指引。
|
||||||
工具结果
|
|
||||||
└─► refs/*.md 保存完整原文
|
|
||||||
└─► offload-*.jsonl 保存工具调用级摘要与 result_ref
|
|
||||||
└─► mmds/*.mmd 保存 Mermaid 任务画布
|
|
||||||
└─► 上下文 只注入当前任务最需要的结构化状态
|
|
||||||
```
|
|
||||||
|
|
||||||
这里的关键不是“删掉历史”，而是“折叠历史”：Agent 平时看任务地图，需要细节时再沿着 `node_id` 和 `result_ref` 下钻到原始证据。
|
我们认为，**不管是长期的知识、短期的任务，还是未来的经验能力，记忆都不应该平铺，生成和召回都必须有层次**。TencentDB Agent Memory 将“分层”作为整个架构的统一设计哲学：
|
||||||
|
|
||||||
### 长期个性化记忆：从信息碎片到用户画像
|
* **短期记忆（上下文卸载/任务）的分层**：底层保留原始、厚重的工具调用结果（`refs/*.md`），中层抽取步骤摘要（`jsonl`），高层则浓缩为一张极度轻量的 Mermaid 任务画布。Agent 在上下文中仅需关注高层结构，遇错时再沿着 `node_id` 下钻到底层查证。
|
||||||
|
* **长期个性化（用户理解）的分层**：打破扁平的历史记录，建立 L0 原始对话 → L1 结构化事实 → L2 场景块 → L3 用户画像 的语义金字塔。平时靠高层画像把握用户偏好，需要考证细节时再检索底层事实。
|
||||||
跨会话记忆面对的是另一个问题：原始对话日志是低密度矿藏，里面有偏好、有事实、有情绪、有长期目标，也有大量噪音。单纯向量检索只能找到“相似片段”，很难挖出用户长期稳定的特质。
|
* **技能生成（Skill与动作沉淀，Roadmap）的分层**：记忆不应仅限于“知道什么”，还应包括“会做什么”。我们正在将分层延伸至动作域：从底层的执行轨迹（Traces）与报错日志中，中层归纳出共性的解决模式，高层最终提炼出可直接挂载复用的 Skill 或标准 SOP 代码。
|
||||||
|
|
||||||
TencentDB Agent Memory 用 L0 → L3 的金字塔管线逐层提纯：
|
|
||||||
|
|
||||||
<p align="center">
|
<p align="center">
|
||||||
<img src="./assets/images/memory-pyramid.png" alt="TencentDB Agent Memory L0 to L3 semantic pyramid" width="860" />
|
<img src="./assets/images/memory-pyramid.png" alt="TencentDB Agent Memory L0 to L3 semantic pyramid" width="860" />
|
||||||
</p>
|
</p>
|
||||||
|
|
||||||
上层画像负责让 Agent “懂你”，下层记忆负责在事实细节上兜底。这样 Agent 既能有宏观判断，也能在需要时查到具体证据。
|
**渐进式披露与异构存储**：为了支撑这种无处不在的分层，我们设计了底层数据库与上层文件系统结合的存储方案。底层（海量事实、日志、轨迹）存入数据库或归档文件，确保稳定与全量检索；高层（画像、场景、画布、Skill）存入业务可读的文件系统（Markdown），确保高信息密度、逻辑清晰与白盒可调。**低层保留证据，高层保留结构。**
|
||||||
|
|
||||||
|
**每一条信息都 100% 可找回、可恢复**：压缩或抽象最大的风险是“丢失证据”。得益于严格的索引映射机制，系统内没有任何一段摘要是“不可逆”的黑盒。无论是短期记忆中被卸载的一段报错日志，还是长期记忆里总结出的一条用户偏好，Agent 或开发者都可以沿着“高层符号（画像/画布） → 中层索引（场景/JSONL） → 底层原文（L0对话/refs）”的链路进行完美溯源与恢复。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
flowchart LR
|
||||||
|
subgraph TraceLink["100% 可找回、可恢复的下钻链路"]
|
||||||
|
direction TB
|
||||||
|
High["高层：符号与结构<br/>(Persona 画像 / Mermaid 画布)"]
|
||||||
|
Mid["中层：摘要与索引<br/>(Scene 场景块 / JSONL 摘要)"]
|
||||||
|
Low["底层：完整事实与证据<br/>(L0 原始对话 / refs 原文)"]
|
||||||
|
|
||||||
|
High == "需要细节 / 发生疑惑" ==> Mid
|
||||||
|
Mid == "凭借 node_id 或引文匹配" ==> Low
|
||||||
|
end
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 符号化记忆：用最少符号表达最多语义（Mermaid 画布）
|
||||||
|
|
||||||
|
长程任务中最消耗 Token 的往往是繁杂的过程日志（如搜索结果、代码、报错）。为此，我们结合 **上下文卸载 (Context Offloading)** 提出了 **符号化记忆**：
|
||||||
|
|
||||||
|
* **Mermaid 符号图谱**：取代冗长的自然语言或扁平的 JSON，我们使用高密度、强拓扑的 Mermaid 语法来描绘任务状态流转，既能被 LLM 精准理解，也方便人类阅览。
|
||||||
|
* **历史折叠与卸载**：完整工具日志被卸载到外部文件系统，上下文仅保留轻量级的 Mermaid 任务地图。
|
||||||
|
* **基于 `node_id` 的溯源**：Agent 看着符号图谱推理，如需核对细节，直接 grep 图谱上的 `node_id` 即可瞬间找回完整原文，既大幅降本又保全了 100% 可追溯性。
|
||||||
|
|
||||||
|
```mermaid
|
||||||
|
graph LR
|
||||||
|
Log["繁杂冗长的过程日志<br/>(几十万 Token)"] -->|"1. 卸载完整原文"| FS[("外部文件系统<br/>(refs/xxx.md)")]
|
||||||
|
Log -->|"2. 提取关系"| MMD["Mermaid 符号图谱<br/>(带 node_id)"]
|
||||||
|
|
||||||
|
MMD -->|"3. 轻量级注入"| Agent(("Agent 上下文<br/>(几百 Token)"))
|
||||||
|
Agent -. "4. 随时按 node_id 下钻恢复原文" .-> FS
|
||||||
|
|
||||||
|
style Log fill:#f1f5f9,stroke:#94a3b8,stroke-dasharray: 5 5
|
||||||
|
style FS fill:#f8fafc,stroke:#cbd5e1
|
||||||
|
style MMD fill:#eff6ff,stroke:#3b82f6,stroke-width:2px
|
||||||
|
style Agent fill:#fffbeb,stroke:#f59e0b,stroke-width:2px
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -104,7 +133,7 @@ openclaw gateway restart
|
|||||||
|
|
||||||
启用后，TencentDB Agent Memory 会自动完成对话录制、记忆提取、场景归纳、用户画像生成和下一轮对话前召回。
|
启用后，TencentDB Agent Memory 会自动完成对话录制、记忆提取、场景归纳、用户画像生成和下一轮对话前召回。
|
||||||
|
|
||||||
### 3. 使用 TCVDB 后端（可选，需版本号≥0.2.0）
|
### 3. 使用 TCVDB 后端（可选）
|
||||||
|
|
||||||
```jsonc
|
```jsonc
|
||||||
{
|
{
|
||||||
@@ -119,8 +148,7 @@ openclaw gateway restart
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### 4. 启用短期记忆压缩（可选，需版本号≥0.3.0）
|
### 4. 启用短期记忆压缩（可选）
|
||||||
|
|
||||||
|
|
||||||
```jsonc
|
```jsonc
|
||||||
{
|
{
|
||||||
@@ -204,36 +232,7 @@ export-tencent-vdb --help
|
|||||||
|
|
||||||
## 🤔 方案特点
|
## 🤔 方案特点
|
||||||
|
|
||||||
### 1. 渐进式披露：短期压缩任务，长期沉淀用户
|
### 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，而是保留了从高层摘要回到底层证据的路径。
|
压缩最大的风险是“省了 Token，也丢了证据”。因此 TencentDB Agent Memory 没有把历史压成一段不可恢复的 summary，而是保留了从高层摘要回到底层证据的路径。
|
||||||
|
|
||||||
@@ -246,7 +245,7 @@ TencentDB Agent Memory 的核心不是“多存一点”，而是**把信息按
|
|||||||
|
|
||||||
上层负责“情商”和方向，下层负责“证据”和精度。短期压缩和长期记忆在这里合成一条闭环：**能折叠，也能展开；能抽象，也能追证。**
|
上层负责“情商”和方向，下层负责“证据”和精度。短期压缩和长期记忆在这里合成一条闭环：**能折叠，也能展开；能抽象，也能追证。**
|
||||||
|
|
||||||
### 4. 白盒可调试：记忆不是黑盒向量
|
### 2. 白盒可调试：记忆不是黑盒向量
|
||||||
|
|
||||||
很多记忆系统的问题是：召回错了，你只能看到一串向量分数，很难判断到底哪里错。TencentDB Agent Memory 把关键中间产物保存在可读文件里：
|
很多记忆系统的问题是：召回错了，你只能看到一串向量分数，很难判断到底哪里错。TencentDB Agent Memory 把关键中间产物保存在可读文件里：
|
||||||
|
|
||||||
@@ -257,21 +256,7 @@ TencentDB Agent Memory 的核心不是“多存一点”，而是**把信息按
|
|||||||
|
|
||||||
这意味着调试不再是翻黑盒数据库，而是沿着“画像 → 场景 → 记忆 → 原文”的链路逐层定位。
|
这意味着调试不再是翻黑盒数据库，而是沿着“画像 → 场景 → 记忆 → 原文”的链路逐层定位。
|
||||||
|
|
||||||
### 5. 异构存储解耦：数据库保事实，文件系统保结构
|
### 3. 工程能力完整：不是 Demo，而是可接入的插件
|
||||||
|
|
||||||
长期记忆和短期压缩看起来是两套功能，底层其实遵循同一条存储原则：**数据库负责可检索的事实，文件系统负责可读可改的结构。**
|
|
||||||
|
|
||||||
| 信息类型 | 存储介质 | 为什么这样放 |
|
|
||||||
| :--- | :--- | :--- |
|
|
||||||
| L0 / L1 长期记忆底座 | SQLite 或 TCVDB | 数据量大、需要语义检索和时序查证 |
|
|
||||||
| L2 / L3 场景与画像 | Markdown 文件 | 需要业务可读、Prompt 可调、渐进式披露 |
|
|
||||||
| Offload 原文 | `refs/*.md` | 原始证据必须完整保留，但不应常驻上下文 |
|
|
||||||
| Offload 摘要 | JSONL | 方便按 `node_id` 检索工具调用历史 |
|
|
||||||
| Offload 任务结构 | Mermaid 文件 | 让 Agent 和人都能看懂任务如何推进 |
|
|
||||||
|
|
||||||
底层像弹药库，负责稳定、完整、可检索；顶层像作战地图，负责灵活、可读、能快速迭代。短期压缩的画布和长期记忆的画像，本质上都是“给 Agent 看得懂的高密度工作面”。
|
|
||||||
|
|
||||||
### 6. 工程能力完整：不是 Demo，而是可接入的插件
|
|
||||||
|
|
||||||
| 能力 | 说明 |
|
| 能力 | 说明 |
|
||||||
| :--- | :--- |
|
| :--- | :--- |
|
||||||
|
|||||||
Reference in New Issue
Block a user