Skip to content

Commit c4ac328

Browse files
Maxwell-Code07Maxwell-Code07
committed
Update README.md
1 parent f7639d9 commit c4ac328

2 files changed

Lines changed: 401 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
[中文](README_CN.md)
2+
3+
<h1 align="center">TencentDB Agent Memory</h1>
4+
5+
<p align="center">AI without memory is just a tool. AI with memory becomes an asset.</p>
6+
7+
<p align="center">
8+
<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>
9+
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2EA043?logo=opensourceinitiative&logoColor=white" alt="MIT License" /></a>
10+
</p>
11+
12+
13+
**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.
14+
15+
## Benchmark
16+
17+
Evaluated on [PersonaMem](https://github.com/jiani-huang/PersonaMem) (UPenn, COLM 2025) — 589 questions, 20 actors.
18+
19+
| Category | OpenClaw Native Memory | TencentDB Agent Memory |
20+
| :--- | :---: | :---: |
21+
| Recall Update Reason | 70.97% | **88.89%** |
22+
| Preference Evolution | 66.67% | **83.45%** |
23+
| Personalized Recommendation | 46.67% | **76.36%** |
24+
| Scenario Generalization | 31.58% | **78.95%** |
25+
| Recall User Facts | 29.63% | **79.07%** |
26+
| Recall Facts | 25.00% | **76.47%** |
27+
| Creative Suggestion | 24.00% | **45.16%** |
28+
| **Overall** | **47.85%** | **76.10%** |
29+
30+
## Highlights
31+
32+
- **OpenClaw native plugin** — package name `@tencentdb-agent-memory/memory-tencentdb`, one command to install
33+
- **4-layer memory pipeline**: L0 Raw Dialogue → L1 Structured Memory → L2 Scenario Synthesis → L3 User Profile
34+
- **Hybrid recall**: supports `keyword`, `embedding`, and `hybrid` strategies
35+
- **Two retrieval tools**: `tdai_memory_search` (structured memory) and `tdai_conversation_search` (raw conversations)
36+
- **Local-first storage**: JSONL + SQLite, data is directly inspectable on disk
37+
- **Operational features**: deduplication, checkpoint, backup, scheduled cleanup, metrics logging
38+
- **MIT License**
39+
40+
## Quick Start
41+
42+
### Requirements
43+
44+
- Node.js `>= 22.16.0`
45+
- OpenClaw `>= 2026.3.13`
46+
47+
### Install
48+
49+
```bash
50+
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
51+
```
52+
53+
Once installed, the plugin hooks into the OpenClaw conversation lifecycle and automatically handles conversation capture, memory recall, and L1/L2/L3 processing.
54+
55+
### Development from Source
56+
57+
No build step required. Node.js 22.16+ natively supports TypeScript type stripping, and OpenClaw loads `.ts` source files directly.
58+
59+
```bash
60+
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
61+
cd TencentDB-Agent-Memory
62+
npm install
63+
openclaw plugins install --link .
64+
```
65+
66+
`install --link` registers the current directory as a local plugin in OpenClaw. Source changes take effect after restarting the Gateway.
67+
68+
### Optional: Enable Embedding Recall
69+
70+
To use vector retrieval or hybrid recall, add an embedding configuration. Currently supports remote embedding services compatible with the OpenAI API.
71+
72+
```jsonc
73+
{
74+
"plugins": {
75+
"entries": {
76+
"memory-tencentdb": {
77+
"enabled": true,
78+
"config": {
79+
"embedding": { // Embedding model config (not LLM model)
80+
"enabled": true, // Enable vector search
81+
"provider": "openai", // Only OpenAI-compatible API is supported
82+
"baseUrl": "https://xxx", // API Base URL
83+
"apiKey": "xxx", // API Key
84+
"model": "text-embedding-3-large", // Model name
85+
"dimensions": 1024 // Vector dimensions (must match the chosen model)
86+
}
87+
}
88+
}
89+
}
90+
}
91+
}
92+
```
93+
94+
95+
## Architecture
96+
97+
```text
98+
┌─────────────────┐
99+
│ L3 Profile │ Preferences & behavioral patterns
100+
├─────────────────┤
101+
│ L2 Scenarios │ Cross-session task / scenario blocks
102+
├─────────────────┤
103+
│ L1 Structured │ Facts, constraints, preferences, decisions
104+
├─────────────────┤
105+
│ L0 Dialogue │ Complete conversation records
106+
└─────────────────┘
107+
```
108+
109+
Each layer serves a different purpose:
110+
111+
- **L0** preserves raw conversations for replay and precise retrieval
112+
- **L1** extracts high-value information for direct recall
113+
- **L2** organizes scattered memories into scenario blocks across sessions
114+
- **L3** maintains a user profile for long-term preference modeling
115+
116+
## Lifecycle
117+
118+
| Stage | Trigger | Action |
119+
|---|---|---|
120+
| Recall | `before_prompt_build` | Recall relevant memory and inject into context |
121+
| L0 | `agent_end` | Write raw conversation logs |
122+
| L1 | Scheduled | Extract structured memory, deduplicate, persist |
123+
| L2 | After L1 | Update scenario blocks |
124+
| L3 | Threshold reached | Generate or refresh user profile |
125+
| Shutdown | `gateway_stop` | Clean up resources |
126+
127+
The plugin also registers two tools for the Agent to call directly:
128+
129+
- `tdai_memory_search`: queries L1 structured memory. Useful for questions like "what does the user prefer" or "what constraints were confirmed earlier".
130+
- `tdai_conversation_search`: queries L0 raw conversations. Useful when exact original wording is needed.
131+
132+
## Retrieval
133+
134+
Three recall strategies:
135+
136+
| Strategy | Implementation |
137+
|---|---|
138+
| `keyword` | FTS5 full-text search with jieba for Chinese tokenization |
139+
| `embedding` | sqlite-vec vector similarity search |
140+
| `hybrid` | Merged keyword and vector results |
141+
142+
All backed by SQLite.
143+
144+
## Configuration
145+
146+
Grouped by capability:
147+
148+
| Config Group | Purpose |
149+
|---|---|
150+
| `capture` | L0 conversation capture, exclusion rules, retention |
151+
| `extraction` | L1 extraction, deduplication, per-run limit |
152+
| `persona` | L2/L3 trigger frequency, scenario limit, backup count |
153+
| `pipeline` | L1/L2/L3 scheduling |
154+
| `recall` | Auto-recall toggle, result count, threshold, strategy |
155+
| `embedding` | Vector retrieval service configuration |
156+
| `report` | Metrics logging |
157+
158+
Minimum configuration is just installing the plugin. Add `embedding` and scheduling parameters for better recall quality.
159+
160+
## Data Directory
161+
162+
```text
163+
<pluginDataDir>/
164+
├── conversations/ # L0 raw conversations
165+
├── records/ # L1 structured memory
166+
├── scene_blocks/ # L2 scenario blocks
167+
├── .metadata/ # checkpoints, indexes, metadata
168+
└── .backup/ # backups
169+
```
170+
171+
## Scope
172+
173+
This repository is the core OpenClaw plugin implementation.
174+
175+
**Includes**: plugin entry and lifecycle hooks, 4-layer memory pipeline, retrieval tools and auto-recall, JSONL + SQLite local storage, checkpoint / backup / cleanup / logging.
176+
177+
### Code Structure
178+
179+
```text
180+
TencentDB-Agent-Memory/
181+
├── index.ts # Plugin registration, tool registration, lifecycle hooks
182+
├── openclaw.plugin.json
183+
├── package.json
184+
├── CHANGELOG.md
185+
└── src/
186+
├── hooks/ # Auto-recall and auto-capture
187+
├── conversation/ # L0 conversation management
188+
├── record/ # L1 extraction and persistence
189+
├── scene/ # L2 scenario synthesis
190+
├── persona/ # L3 user profile
191+
├── store/ # SQLite / FTS / vector retrieval
192+
├── tools/ # Retrieval tool registration
193+
├── prompts/ # Prompt templates
194+
├── report/ # Metrics reporting
195+
└── utils/
196+
```
197+
198+
## License
199+
200+
MIT. See [LICENSE](LICENSE).

0 commit comments

Comments
 (0)