mirror of
https://github.com/TencentCloud/TencentDB-Agent-Memory
synced 2026-07-10 12:34:27 +00:00
docs: update README/README_CN and add assets/images
This commit is contained in:
chrishuan
@@ -1,200 +1,334 @@
|
||||
[中文](README_CN.md)
|
||||
<div align="center">
|
||||
|
||||
<h1 align="center">TencentDB Agent Memory</h1>
|
||||
<img src="./assets/images/logo.png" alt="TencentDB Agent Memory" width="880" />
|
||||
|
||||
<p align="center">AI without memory is just a tool. AI with memory becomes an asset.</p>
|
||||
### TencentDB Agent Memory
|
||||
|
||||
让 Agent 记住固定流程、沉淀历史经验、复用用户偏好，**把人的注意力从重复工作中释放出来，回到创造、判断和生活本身**。
|
||||
|
||||
[](https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb)
|
||||
[](./LICENSE)
|
||||
[](https://nodejs.org/)
|
||||
[](https://github.com/openclaw/openclaw)
|
||||
|
||||
|
||||
[效果亮点](#效果亮点) · [项目简介](#项目简介) · [特点](#特点) · [快速开始](#快速开始)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ✨ 效果亮点
|
||||
|
||||
> **TencentDB Agent Memory = 短期记忆压缩 + 长期个性化记忆。**
|
||||
>
|
||||
> - **短期记忆压缩**：把长任务上下文变轻，让 Agent 不再背着全部工具日志继续推理。
|
||||
> - **长期个性化记忆**：把碎片化对话提炼为结构化记忆、场景块和用户画像。
|
||||
|
||||
**作为 OpenClaw 插件接入后**：最高节省 **63.59% Token**，通过率相对提升 **41.18%**；PersonaMem 准确率从 **48%** 提升到 **76%**。
|
||||
|
||||
| 记忆能力 | Benchmark | Clawpro 成功率 | 加插件后成功率 | 相对变化 | Clawpro Token 消耗 | 加插件后 Token 消耗 | 相对变化 |
|
||||
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **短期记忆** | WideSearch | 8.5% | **12%** | **+41.18%** | 174.31M | **63.46M** | **−63.59%** |
|
||||
| **短期记忆** | 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%** |
|
||||
| **长期记忆** | PersonaMem | 48% | **76%** | **+59%** | — | — | — |
|
||||
|
||||
> 超长 Session 评测不是单题清空上下文，而是把多个任务拼接到同一个 Session 中连续执行。例如 SWE-bench 每个 Session 连续执行 50 个任务，用来模拟真实长程 Agent 的上下文累积压力。
|
||||
|
||||
---
|
||||
|
||||
## 项目简介
|
||||
|
||||
**Memory 不是为了让 AI 存下所有东西，而是为了让人不必重复所有事情。**
|
||||
|
||||
TencentDB Agent Memory 帮助 Agent 学会你的流程、保留任务上下文、复用历史经验，让人把注意力留给判断、创造和真正有价值的工作。
|
||||
|
||||
真实工作里，很多内容不应该被用户反复交代：固定 SOP、常用分析口径、项目背景、用户偏好等。因此，我们把这些稳定经验沉淀下来，让 Agent 在合适的时候自动复用。
|
||||
|
||||
TencentDB Agent Memory 不是简单的历史记录、不可恢复的摘要，也不是单纯的 RAG。我们把记忆设计成一套分层信息管理系统：数据库负责可检索、可过滤、可召回的事实底座；文件系统负责承载可读、可编辑、可逐步展开的任务画布、场景块和用户画像。短期记忆压缩解决长任务中的过程信息过载，长期个性化记忆解决跨会话的用户理解沉淀。
|
||||
|
||||
> **让 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 的金字塔管线逐层提纯：
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.npmjs.com/package/@tencentdb-agent-memory/memory-tencentdb"><img src="https://img.shields.io/badge/OpenClaw-Plugin-6C63FF?logo=npm&logoColor=white" alt="OpenClaw Plugin" /></a>
|
||||
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA043?logo=opensourceinitiative&logoColor=white" alt="MIT License" /></a>
|
||||
<img src="./assets/images/memory-pyramid.png" alt="TencentDB Agent Memory L0 to L3 semantic pyramid" width="860" />
|
||||
</p>
|
||||
|
||||
上层画像负责让 Agent “懂你”，下层记忆负责在事实细节上兜底。这样 Agent 既能有宏观判断，也能在需要时查到具体证据。
|
||||
|
||||
**TencentDB Agent Memory is an Agent memory system built by the Tencent Cloud Database team**, adding persistent long-term memory to OpenClaw. Through a 4-layer progressive memory pyramid, it automatically handles memory capture, layered distillation, on-demand recall and injection — turning an Agent from "chat-only" into a long-term, cross-session AI assistant that continuously learns and understands its users.
|
||||
---
|
||||
|
||||
## Benchmark
|
||||
## 快速开始
|
||||
|
||||
Evaluated on [PersonaMem](https://github.com/jiani-huang/PersonaMem) (UPenn, COLM 2025) — 589 questions, 20 actors.
|
||||
|
||||
| Category | OpenClaw Native Memory | TencentDB Agent Memory |
|
||||
| :--- | :---: | :---: |
|
||||
| Recall Update Reason | 70.97% | **88.89%** |
|
||||
| Preference Evolution | 66.67% | **83.45%** |
|
||||
| Personalized Recommendation | 46.67% | **76.36%** |
|
||||
| Scenario Generalization | 31.58% | **78.95%** |
|
||||
| Recall User Facts | 29.63% | **79.07%** |
|
||||
| Recall Facts | 25.00% | **76.47%** |
|
||||
| Creative Suggestion | 24.00% | **45.16%** |
|
||||
| **Overall** | **47.85%** | **76.10%** |
|
||||
|
||||
## Highlights
|
||||
|
||||
- **OpenClaw native plugin** — package name `@tencentdb-agent-memory/memory-tencentdb`, one command to install
|
||||
- **4-layer memory pipeline**: L0 Raw Dialogue → L1 Structured Memory → L2 Scenario Synthesis → L3 User Profile
|
||||
- **Hybrid recall**: supports `keyword`, `embedding`, and `hybrid` strategies
|
||||
- **Two retrieval tools**: `tdai_memory_search` (structured memory) and `tdai_conversation_search` (raw conversations)
|
||||
- **Local-first storage**: JSONL + SQLite, data is directly inspectable on disk
|
||||
- **Operational features**: deduplication, checkpoint, backup, scheduled cleanup, metrics logging
|
||||
- **MIT License**
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Requirements
|
||||
|
||||
- Node.js `>= 22.16.0`
|
||||
- OpenClaw `>= 2026.3.13`
|
||||
|
||||
### Install
|
||||
### 1. 安装插件
|
||||
|
||||
```bash
|
||||
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
|
||||
openclaw gateway restart
|
||||
```
|
||||
|
||||
Once installed, the plugin hooks into the OpenClaw conversation lifecycle and automatically handles conversation capture, memory recall, and L1/L2/L3 processing.
|
||||
### 2. 零配置启用
|
||||
|
||||
### Development from Source
|
||||
默认使用本地 `SQLite + sqlite-vec` 后端。
|
||||
|
||||
No build step required. Node.js 22.16+ natively supports TypeScript type stripping, and OpenClaw loads `.ts` source files directly.
|
||||
|
||||
```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` registers the current directory as a local plugin in OpenClaw. Source changes take effect after restarting the Gateway.
|
||||
启用后，TencentDB Agent Memory 会自动完成对话录制、记忆提取、场景归纳、用户画像生成和下一轮对话前召回。
|
||||
|
||||
### Optional: Enable Embedding Recall
|
||||
|
||||
To use vector retrieval or hybrid recall, add an embedding configuration. Currently supports remote embedding services compatible with the OpenAI API.
|
||||
### 3. 使用 TCVDB 后端（可选）
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"memory-tencentdb": {
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"embedding": { // Embedding model config (not LLM model)
|
||||
"enabled": true, // Enable vector search
|
||||
"provider": "openai", // Only OpenAI-compatible API is supported
|
||||
"baseUrl": "https://xxx", // API Base URL
|
||||
"apiKey": "xxx", // API Key
|
||||
"model": "text-embedding-3-large", // Model name
|
||||
"dimensions": 1024 // Vector dimensions (must match the chosen model)
|
||||
}
|
||||
}
|
||||
}
|
||||
"storeBackend": "tcvdb",
|
||||
"tcvdb": {
|
||||
"url": "http://your-vdb-instance:8100",
|
||||
"apiKey": "your-api-key",
|
||||
"database": "my_memory_db"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 启用短期记忆压缩（可选）
|
||||
|
||||
## Architecture
|
||||
|
||||
```text
|
||||
┌─────────────────┐
|
||||
│ L3 Profile │ Preferences & behavioral patterns
|
||||
├─────────────────┤
|
||||
│ L2 Scenarios │ Cross-session task / scenario blocks
|
||||
├─────────────────┤
|
||||
│ L1 Structured │ Facts, constraints, preferences, decisions
|
||||
├─────────────────┤
|
||||
│ L0 Dialogue │ Complete conversation records
|
||||
└─────────────────┘
|
||||
```jsonc
|
||||
{
|
||||
"memory-tencentdb": {
|
||||
"offload": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Each layer serves a different purpose:
|
||||
### 5. 常用命令
|
||||
|
||||
- **L0** preserves raw conversations for replay and precise retrieval
|
||||
- **L1** extracts high-value information for direct recall
|
||||
- **L2** organizes scattered memories into scenario blocks across sessions
|
||||
- **L3** maintains a user profile for long-term preference modeling
|
||||
```bash
|
||||
# 导入历史对话，完整执行 L0 → L3 管线
|
||||
openclaw memory-tdai seed --input conversations.json
|
||||
|
||||
## Lifecycle
|
||||
# SQLite 数据迁移到 TCVDB
|
||||
migrate-sqlite-to-tcvdb --help
|
||||
|
||||
| Stage | Trigger | Action |
|
||||
|---|---|---|
|
||||
| Recall | `before_prompt_build` | Recall relevant memory and inject into context |
|
||||
| L0 | `agent_end` | Write raw conversation logs |
|
||||
| L1 | Scheduled | Extract structured memory, deduplicate, persist |
|
||||
| L2 | After L1 | Update scenario blocks |
|
||||
| L3 | Threshold reached | Generate or refresh user profile |
|
||||
| Shutdown | `gateway_stop` | Clean up resources |
|
||||
|
||||
The plugin also registers two tools for the Agent to call directly:
|
||||
|
||||
- `tdai_memory_search`: queries L1 structured memory. Useful for questions like "what does the user prefer" or "what constraints were confirmed earlier".
|
||||
- `tdai_conversation_search`: queries L0 raw conversations. Useful when exact original wording is needed.
|
||||
|
||||
## Retrieval
|
||||
|
||||
Three recall strategies:
|
||||
|
||||
| Strategy | Implementation |
|
||||
|---|---|
|
||||
| `keyword` | FTS5 full-text search with jieba for Chinese tokenization |
|
||||
| `embedding` | sqlite-vec vector similarity search |
|
||||
| `hybrid` | Merged keyword and vector results |
|
||||
|
||||
All backed by SQLite.
|
||||
|
||||
## Configuration
|
||||
|
||||
Grouped by capability:
|
||||
|
||||
| Config Group | Purpose |
|
||||
|---|---|
|
||||
| `capture` | L0 conversation capture, exclusion rules, retention |
|
||||
| `extraction` | L1 extraction, deduplication, per-run limit |
|
||||
| `persona` | L2/L3 trigger frequency, scenario limit, backup count |
|
||||
| `pipeline` | L1/L2/L3 scheduling |
|
||||
| `recall` | Auto-recall toggle, result count, threshold, strategy |
|
||||
| `embedding` | Vector retrieval service configuration |
|
||||
| `report` | Metrics logging |
|
||||
|
||||
Minimum configuration is just installing the plugin. Add `embedding` and scheduling parameters for better recall quality.
|
||||
|
||||
## Data Directory
|
||||
|
||||
```text
|
||||
<pluginDataDir>/
|
||||
├── conversations/ # L0 raw conversations
|
||||
├── records/ # L1 structured memory
|
||||
├── scene_blocks/ # L2 scenario blocks
|
||||
├── .metadata/ # checkpoints, indexes, metadata
|
||||
└── .backup/ # backups
|
||||
# 导出腾讯云向量数据库数据
|
||||
export-tencent-vdb --help
|
||||
```
|
||||
|
||||
## Scope
|
||||
完整配置见 [`CONFIGURATION.md`](./CONFIGURATION.md)，CLI 输入格式见 [`src/cli/README.md`](./src/cli/README.md)。
|
||||
|
||||
This repository is the core OpenClaw plugin implementation.
|
||||
---
|
||||
|
||||
**Includes**: plugin entry and lifecycle hooks, 4-layer memory pipeline, retrieval tools and auto-recall, JSONL + SQLite local storage, checkpoint / backup / cleanup / logging.
|
||||
## 🔧 可调参数
|
||||
|
||||
### Code Structure
|
||||
**所有字段均有合理默认值，零配置即可跑。** 如果要调优，可以按使用深度逐层展开。
|
||||
|
||||
```text
|
||||
TencentDB-Agent-Memory/
|
||||
├── index.ts # Plugin registration, tool registration, lifecycle hooks
|
||||
├── openclaw.plugin.json
|
||||
├── package.json
|
||||
├── CHANGELOG.md
|
||||
└── src/
|
||||
├── hooks/ # Auto-recall and auto-capture
|
||||
├── conversation/ # L0 conversation management
|
||||
├── record/ # L1 extraction and persistence
|
||||
├── scene/ # L2 scenario synthesis
|
||||
├── persona/ # L3 user profile
|
||||
├── store/ # SQLite / FTS / vector retrieval
|
||||
├── tools/ # Retrieval tool registration
|
||||
├── prompts/ # Prompt templates
|
||||
├── report/ # Metrics reporting
|
||||
└── utils/
|
||||
```
|
||||
<details>
|
||||
<summary><b>🟢 Level 1 · 日常调参</b>（覆盖 90% 使用场景）</summary>
|
||||
|
||||
## License
|
||||
| 字段 | 默认 | 说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| `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. See [LICENSE](LICENSE).
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🟡 Level 2 · 进阶调优</b>（长任务 / 长 Session 场景）</summary>
|
||||
|
||||
| 字段 | 默认 | 说明 |
|
||||
| :--- | :--- | :--- |
|
||||
| `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` |
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>🔴 Level 3 · 完整参数表</b>（运维 / 自定义模型 / 远程 embedding）</summary>
|
||||
|
||||
完整字段、类型、约束见 [`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.*` — 指标上报
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
## 🤔 方案特点
|
||||
|
||||
### 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 |
|
||||
|
||||
---
|
||||
## 社区与贡献
|
||||
|
||||
我们欢迎一切形式的贡献——Bug 反馈、功能建议、文档勘误、Benchmark 复现、生态集成，或者一个 Pull Request 都可以。Agent 记忆这件事远未有定论，希望和大家一起把它做出来。
|
||||
|
||||
- 🐞 **发现 Bug 或有疑问？** 欢迎到 [GitHub Issues](https://github.com/<org>/<repo>/issues) 提交，我们会在 24 小时内响应。
|
||||
- 💡 **有想法想交流？** 欢迎在 [GitHub Discussions](https://github.com/<org>/<repo>/discussions) 发起讨论。
|
||||
- 🛠️ **想贡献代码？** 请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
||||
- 💬 **想加入交流群？** 扫码加入 **Agent Memory 微信社群**，与早期开发者直接对话。
|
||||
<img width="200" height="146" alt="766450d8a7b30aa7e67121b4981f1810" src="https://github.com/user-attachments/assets/7cbbb57a-ec81-4f92-b0bd-7f3c5d760c1e" />
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
|
||||
- [x] 长期个性化记忆（L0 → L3）
|
||||
- [x] 短期记忆压缩（Context Offload + Mermaid 画布）
|
||||
- [x] 本地 SQLite 后端与腾讯云向量数据库 TCVDB 后端
|
||||
- [x] OpenClaw 插件与 Hermes Gateway 适配
|
||||
- [ ] 短期记忆压缩正式产品化上线
|
||||
- [ ] 记忆可迁移：跨 Agent / 跨框架 / 跨设备的导入导出与热迁移
|
||||
- [ ] 更多 Agent 框架适配
|
||||
- [ ] 可视化调试与记忆观测面板
|
||||
|
||||
---
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="68%">
|
||||
<b>如果 TencentDB Agent Memory 对你有所帮助，欢迎为项目点亮 ⭐ 支持。</b><br />
|
||||
如果有任何建议，欢迎提出issue讨论。
|
||||
</td>
|
||||
<td width="32%" align="right">
|
||||
<img src="./assets/images/star-helper.png" alt="Star TencentDB Agent Memory" width="260" />
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
[MIT](./LICENSE) © TencentDB Agent Memory Team
|
||||
+28
-15
@@ -1,10 +1,10 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="./logo.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)
|
||||
[](./LICENSE)
|
||||
@@ -27,26 +27,28 @@
|
||||
|
||||
**作为 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%** |
|
||||
| 记忆能力 | Benchmark | Clawpro 成功率 | 加插件后成功率 | 相对变化 | Clawpro Token 消耗 | 加插件后 Token 消耗 | 相对变化 |
|
||||
| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
|
||||
| **短期记忆** | WideSearch | 8.5% | **12%** | **+41.18%** | 174.31M | **63.46M** | **−63.59%** |
|
||||
| **短期记忆** | 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%** |
|
||||
| **长期记忆** | PersonaMem | 48% | **76%** | **+59%** | — | — | — |
|
||||
|
||||
> 超长 Session 评测不是单题清空上下文，而是把多个任务拼接到同一个 Session 中连续执行。例如 SWE-bench 每个 Session 连续执行 50 个任务，用来模拟真实长程 Agent 的上下文累积压力。
|
||||
|
||||
---
|
||||
|
||||
## 简单介绍
|
||||
## 项目简介
|
||||
|
||||
**TencentDB Agent Memory 不是把历史暴力堆进上下文，也不是把一切压成不可恢复的摘要。**
|
||||
**Memory 不是为了让 AI 存下所有东西，而是为了让人不必重复所有事情。**
|
||||
|
||||
我们把记忆设计成一套分层信息管理系统：低层保留原始证据，高层保留语义结构；当前需要的进入上下文，暂时不用的外部化保存，需要时再沿着索引找回。
|
||||
TencentDB Agent Memory 帮助 Agent 学会你的流程、保留任务上下文、复用历史经验，让人把注意力留给判断、创造和真正有价值的工作。
|
||||
|
||||
数据库负责事实检索，文件系统负责任务画布、场景块和用户画像。短期记忆压缩解决长任务中的过程信息过载，长期个性化记忆解决跨会话的用户理解沉淀。
|
||||
真实工作里，很多内容不应该被用户反复交代：固定 SOP、常用分析口径、项目背景、用户偏好等。因此，我们把这些稳定经验沉淀下来，让 Agent 在合适的时候自动复用。
|
||||
|
||||
> **让 Agent 少背负，但不丢失；少重复，但能追溯。**
|
||||
TencentDB Agent Memory 不是简单的历史记录、不可恢复的摘要，也不是单纯的 RAG。我们把记忆设计成一套分层信息管理系统：数据库负责可检索、可过滤、可召回的事实底座；文件系统负责承载可读、可编辑、可逐步展开的任务画布、场景块和用户画像。短期记忆压缩解决长任务中的过程信息过载，长期个性化记忆解决跨会话的用户理解沉淀。
|
||||
|
||||
> **让 Agent 记住该记的，让人专注于更有价值的创造。**
|
||||
|
||||
它由两块能力组成：
|
||||
|
||||
@@ -71,7 +73,7 @@
|
||||
TencentDB Agent Memory 用 L0 → L3 的金字塔管线逐层提纯：
|
||||
|
||||
<p align="center">
|
||||
<img src="./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>
|
||||
|
||||
上层画像负责让 Agent “懂你”，下层记忆负责在事实细节上兜底。这样 Agent 既能有宏观判断，也能在需要时查到具体证据。
|
||||
@@ -291,6 +293,17 @@ TencentDB Agent Memory 的核心不是“多存一点”，而是**把信息按
|
||||
| [`CHANGELOG.md`](./CHANGELOG.md) | 版本变更记录 |
|
||||
| [`openclaw.plugin.json`](./openclaw.plugin.json) | OpenClaw 插件声明与配置 Schema |
|
||||
|
||||
---
|
||||
## 社区与贡献
|
||||
|
||||
我们欢迎一切形式的贡献——Bug 反馈、功能建议、文档勘误、Benchmark 复现、生态集成，或者一个 Pull Request 都可以。Agent 记忆这件事远未有定论，希望和大家一起把它做出来。
|
||||
|
||||
- 🐞 **发现 Bug 或有疑问？** 欢迎到 [GitHub Issues](https://github.com/<org>/<repo>/issues) 提交，我们会在 24 小时内响应。
|
||||
- 💡 **有想法想交流？** 欢迎在 [GitHub Discussions](https://github.com/<org>/<repo>/discussions) 发起讨论。
|
||||
- 🛠️ **想贡献代码？** 请先阅读 [CONTRIBUTING.md](./CONTRIBUTING.md)。
|
||||
- 💬 **想加入交流群？** 扫码加入 **Agent Memory 微信社群**，与早期开发者直接对话。
|
||||
<img width="200" height="146" alt="766450d8a7b30aa7e67121b4981f1810" src="https://github.com/user-attachments/assets/7cbbb57a-ec81-4f92-b0bd-7f3c5d760c1e" />
|
||||
|
||||
---
|
||||
|
||||
## Roadmap
|
||||
@@ -313,7 +326,7 @@ TencentDB Agent Memory 的核心不是“多存一点”，而是**把信息按
|
||||
如果有任何建议，欢迎提出issue讨论。
|
||||
</td>
|
||||
<td width="32%" align="right">
|
||||
<img src="./star-helper.png" alt="Star TencentDB Agent Memory" width="260" />
|
||||
<img src="./assets/images/star-helper.png" alt="Star TencentDB Agent Memory" width="260" />
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 174 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 611 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 201 KiB |
Reference in New Issue
Block a user