docs: sync README, SKILL, and image updates from GitHub

2026-07-10 12:34:27 +00:00 · 2026-05-13 15:02:10 +08:00
parent d377b09fbc
commit f7794f198e
9 changed files with 180 additions and 168 deletions
@@ -1,17 +1,24 @@
 <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" />
-### Help your Agent accumulate experience, so people can focus on creation.
+### Agents remember,Humans innovate.
 [![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)
+[![Hermes](https://img.shields.io/badge/Hermes-Gateway-7B61FF)](https://hermes-agent.nousresearch.com/docs/)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/kDtHb5RW2)
-[Highlights](#-highlights) · [Overview](#overview) · [Core Technology](#core-technology-reject-flat-storage-embrace-layering-and-symbolization) · [Quick Start](#quick-start)
+[Highlights](#-highlights) · [Overview](#overview) · [Core Technology](#core-technology-reject-flat-storage-embrace-layering-and-symbolization) · [Features](#-features) · [Quick Start](#quick-start)
 <div align="center">
 [**English**](./README.md) · [简体中文](./README_CN.md)
 </div>
 </div>
@@ -19,12 +26,12 @@
 ## ✨ Highlights
-> **TencentDB Agent Memory = Symbolic short-term memory + Layered long-term memory.**
+> **TencentDB Agent Memory = symbolic short-term memory + layered long-term memory.**
 >
-> - **Symbolic short-term memory**: offload heavy tool logs layer by layer and progressively condense them into lightweight Mermaid structural symbols, drastically reducing token consumption while improving task success rate.
+> - **Symbolic short-term memory** offloads heavy tool logs and condenses them into compact Mermaid symbols, cutting token usage and improving task success.
-> - **Layered long-term memory**: refine fragmented conversations layer by layer into structured personas and scenes — no more flat vector piles.
+> - **Layered long-term memory** distills fragmented conversations into structured personas and scenes, instead of flat vector piles.
-**Plugged into OpenClaw**, it saves up to **61.38% tokens**, lifts pass rate by **+51.52%** (relative), and pushes PersonaMem accuracy from **48%** to **76%**.
+When integrated with OpenClaw, it cuts token usage by up to **61.38%**, improves pass rate by **51.52%** (relative), and raises PersonaMem accuracy from **48%** to **76%**.
 | Memory Capability | Benchmark | Openclaw Success | With Plugin | Relative Δ | Openclaw Tokens | With Plugin Tokens | Relative Δ |
 | :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: |
@@ -33,17 +40,17 @@
 | **Short-term** | AA-LCR | 44.0% | **47.5%** | **+7.95%** | 112.0M | **77.3M** | **−30.98%** |
 | **Long-term** | PersonaMem | 48% | **76%** | **+59%** | — | — | — |
-> These are long-session evaluations, not single-turn isolated runs. Multiple tasks are concatenated into the same session and executed back-to-back. For example, each SWE-bench session runs 50 tasks consecutively to simulate the context-accumulation pressure faced by a real long-horizon Agent.
+> These results are measured over continuous long-horizon sessions, not isolated turns. For example, SWE-bench runs 50 consecutive tasks per session to simulate the context-accumulation pressure of real-world long-horizon agents.
 ---
 ## Overview
-**Memory is not about letting AI store everything — it is about freeing humans from repeating everything.**
+**Memory is not about hoarding everything in the AI — it is about sparing humans from having to repeat themselves.**
-In real work, we often have to repeatedly tell the Agent about fixed SOPs, project backgrounds, tool habits, and output formats. This information should not need to be re-explained every time, yet it also should not be mindlessly and flatly crammed into the context.
+In practice, we constantly re-explain the same SOPs, project background, tool conventions, and output formats to the Agent. Such information should not require repetition, nor should it be indiscriminately dumped into the context.
-TencentDB Agent Memory helps the Agent learn your workflows, retain task context, and reuse past experience. But we **reject brute-force history piling** and **abandon irreversible brute-force summarization**. We design memory as a deeply layered system: **symbolic memory** to solve information overload within a single long task, and **memory layering** to solve cross-session experience accumulation.
+TencentDB Agent Memory helps the Agent learn your workflows, retain task context, and reuse past experience. We reject both brute-force history accumulation and irreversible lossy summarization. Instead, we design memory as a layered system: **symbolic memory** for in-task information overload, and **memory layering** for cross-session experience.
 > **Let the Agent remember what should be remembered, so people can focus on judgment, creation, and work that truly matters.**
@@ -51,73 +58,64 @@ TencentDB Agent Memory helps the Agent learn your workflows, retain task context
 ## Core Technology: Reject Flat Storage, Embrace Layering and Symbolization
-The design philosophy of TencentDB Agent Memory revolves around two cores: **memory layering** and **symbolic memory**. This not only lets the Agent "remember more" but, more importantly, "think more clearly".
+Our architecture rests on two pillars: **memory layering** and **symbolic memory**. Together they ensure Agents do not merely "remember more", but "reason better".
-### 1. Memory Layering: Progressive Disclosure and Heterogeneous Storage
+### 1. Memory Layering: Progressive Disclosure with Heterogeneous Storage
-Traditional memory systems often slice all data into flat vectors. Recall then feels like searching for clues among a pile of unrelated sticky notes, lacking the guidance of a macro perspective.
+Traditional memory systems shred data into fragments and dump them into a flat vector store. Recall degenerates into a blind search across disconnected fragments, with no macro-level guidance.
-We believe that **whether it is long-term knowledge, short-term tasks, or future experiential capabilities, memory should never be flat — both generation and recall must have layers**. TencentDB Agent Memory adopts "layering" as the unified design philosophy across the entire architecture:
+Whether it is long-term knowledge, short-term tasks, or future skill capabilities, memory should never be flat — both its formation and its recall must be hierarchical. TencentDB Agent Memory adopts **layering** as its unified architectural paradigm:
-*   **Short-term memory (context offload / task) layering**: the bottom layer retains the raw, heavy tool-call results (`refs/*.md`); the middle layer extracts step summaries (`jsonl`); the top layer condenses everything into an extremely lightweight Mermaid task canvas. The Agent only needs to focus on the top-layer structure in the context, drilling down to the bottom layer via `node_id` when errors occur.
+*   **Short-term context layering.** The bottom layer archives raw tool outputs (`refs/*.md`); the middle layer extracts step-level summaries (`jsonl`); the top layer condenses state into a lightweight Mermaid canvas. The Agent only needs to attend to the top-layer structure in context, and drills down to the lower layers via `node_id` when an error occurs.
-*   **Long-term personalization (user understanding) layering**: break away from flat history logs and build a semantic pyramid: L0 raw conversations → L1 structured facts → L2 scene blocks → L3 user persona. Rely on the top-layer persona to grasp user preferences day-to-day; search the bottom-layer facts when details need verification.
+*   **Long-term personalization layering.** In place of flat logs, we build a semantic pyramid: **L0 Conversation** (raw dialogue) → **L1 Atom** (atomic facts) → **L2 Scenario** (scene blocks) → **L3 Persona** (user profile). The Persona layer carries day-to-day preferences; the system drills down to Atoms only when details matter.
-*   **Skill generation (skill and action accumulation, Roadmap) layering**: memory should not be limited to "knowing what" but also include "knowing how". We are extending layering into the action domain: from bottom-layer execution traces and error logs, the middle layer generalizes common solution patterns, and the top layer ultimately distills reusable Skills or standardized SOP code.
+*   **Skill generation layering.** Layering also applies to actions. The middle layer derives common solution patterns (**Scenario**) from bottom-layer execution traces (**Conversation**), and the top layer distills reusable Skills or standard SOPs (**Persona**).
 <p align="center">
  <img src="./assets/images/memory-pyramid-en.jpg" alt="TencentDB Agent Memory L0 to L3 semantic pyramid" width="860" />
 </p>
-**Progressive disclosure and heterogeneous storage**: to support this pervasive layering, we designed a storage approach combining a bottom-layer database with a top-layer file system. The bottom layer (massive facts, logs, traces) is stored in databases or archive files, ensuring stability and full-text retrieval; the top layer (personas, scenes, canvases, Skills) is stored in business-readable file systems (Markdown), ensuring high information density, clear logic, and white-box tunability. **Lower layers preserve evidence; upper layers preserve structure.**
+**Heterogeneous storage and progressive disclosure.** A dual-layer storage strategy underpins this architecture. The bottom layer (facts, logs, traces) is persisted in databases for robust full-text retrieval; the top layer (personas, scenes, canvases) is stored as human-readable Markdown files for high information density and white-box inspection. **Lower layers preserve evidence; upper layers preserve structure.**
-**Every piece of information is 100% retrievable and recoverable**: the biggest risk of compression or abstraction is "losing the evidence". Thanks to strict index mapping, no summary in the system is an "irreversible" black box. Whether it is an error log offloaded from short-term memory or a user preference distilled from long-term memory, the Agent or developer can perfectly trace and recover it along the chain: "top-layer symbol (persona / canvas) → middle-layer index (scene / JSONL) → bottom-layer raw text (L0 conversation / refs)".
+**Full traceability and lossless recovery.** Compression often sacrifices traceability. TencentDB Agent Memory avoids irreversible compression by maintaining a deterministic path from high-level abstractions back to ground-truth evidence. Whether it is an offloaded error log or a distilled user preference, the system guarantees a complete drill-down path: "top-layer symbol (Persona / canvas) → mid-layer index (Scenario / jsonl) → bottom-layer raw text (L0 Conversation / refs)".
-```mermaid
+<div align="center">
-flowchart LR
+  <img src="assets/images/flowchart1.png" alt="Retrievable and Recoverable Drill-Down Chain" />
-  subgraph TraceLink["100% Retrievable and Recoverable Drill-Down Chain"]
+</div>
    direction TB
    High["Top layer: Symbols & Structure<br/>(Persona / Mermaid Canvas)"] 
    Mid["Middle layer: Summaries & Indexes<br/>(Scene Blocks / JSONL Summaries)"]
    Low["Bottom layer: Complete Facts & Evidence<br/>(L0 Raw Conversations / refs Raw Text)"]
    High == "Need details / Encountered doubt" ==> Mid
    Mid == "Via node_id or citation matching" ==> Low
  end
 ```
-### 2. Symbolic Memory: Express Maximum Semantics with Minimum Symbols (Mermaid Canvas)
+### 2. Symbolic Memory: Maximum Semantics in Minimum Symbols (Mermaid Canvas)
-In long tasks, the biggest token consumers are often verbose process logs (e.g., search results, code, error messages). To address this, we combine **Context Offloading** to propose **Symbolic Memory**:
+In long tasks, the largest token consumers are verbose intermediate logs (search results, code, error traces). To address this, we combine **context offloading** with **symbolic memory**:
-*   **Mermaid symbol graph**: replacing verbose natural language or flat JSON, we use high-density, strongly-topological Mermaid syntax to depict task state transitions, precisely understandable by LLMs and easy for humans to read.
+*   **Mermaid symbol graph.** Instead of verbose prose or flat JSON, we encode task state transitions in high-density Mermaid syntax — precise enough for LLMs to parse, concise enough for humans to read.
-*   **History folding and offloading**: complete tool logs are offloaded to the external file system; the context retains only a lightweight Mermaid task map.
+*   **History offloading.** Full tool logs are offloaded to external files; only a lightweight Mermaid task map remains in context.
-*   **`node_id`-based tracing**: the Agent reasons by looking at the symbol graph; when it needs to verify details, it simply greps the `node_id` on the graph to instantly retrieve the full original text — drastically reducing costs while preserving 100% traceability.
+*   **`node_id` tracing.** The Agent reasons over the symbol graph; to verify a detail, it greps for the `node_id` and instantly retrieves the full raw text — cutting token cost while preserving full traceability.
 ```mermaid
 graph LR
-    Log["Verbose process logs<br/>(hundreds of thousands of tokens)"] -->|"1. Offload full text"| FS[("External file system<br/>(refs/xxx.md)")]
+    Log["Verbose Logs<br/>(hundreds of thousands of tokens)"] -->|"1. Offload full text"| FS[("External FS<br/>(refs/*.md)")]
-    Log -->|"2. Extract relationships"| MMD["Mermaid symbol graph<br/>(with node_id)"]
+    Log -->|"2. Extract relations"| MMD["Mermaid Canvas<br/>(with node_id)"]
-    MMD -->|"3. Lightweight injection"| Agent(("Agent context<br/>(a few hundred tokens)"))
+    MMD -->|"3. Light injection"| Agent(("Agent Context<br/>(a few hundred tokens)"))
-    Agent -. "4. Drill down to recover full text via node_id anytime" .-> FS
+    Agent -. "4. Recall via node_id" .-> FS
-    style Log fill:#f1f5f9,stroke:#94a3b8,stroke-dasharray: 5 5
+    style Log fill:#f1f5f9,stroke:#94a3b8,stroke-dasharray: 5 5,color:#475569
-    style FS fill:#f8fafc,stroke:#cbd5e1
+    style FS fill:#f8fafc,stroke:#cbd5e1,stroke-width:2px,color:#334155
-    style MMD fill:#eff6ff,stroke:#3b82f6,stroke-width:2px
+    style MMD fill:#eff6ff,stroke:#3b82f6,stroke-width:2px,color:#1e3a8a
-    style Agent fill:#fffbeb,stroke:#f59e0b,stroke-width:2px
+    style Agent fill:#fffbeb,stroke:#f59e0b,stroke-width:2px,color:#92400e
 ```
 ---
 ## Quick Start
-
+### 1. Openclaw
-### 1. Install the plugin
+### 1.1 Install the plugin
 ```bash
 openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
 openclaw gateway restart
 ```
-### 2. Zero-config to enable
+### 1.2 Zero-config to enable
 Defaults to a local `SQLite + sqlite-vec` backend.
@@ -132,22 +130,7 @@ Defaults to a local `SQLite + sqlite-vec` backend.
 Once enabled, TencentDB Agent Memory automatically handles conversation capture, memory extraction, scene aggregation, persona generation, and recall before the next turn.
-### 3. Use the TCVDB backend (optional, requires version ≥ 0.2.0)
+### 1.3 Enable short-term compression (optional, requires version ≥ 0.3.4)
 ```jsonc
 {
  "memory-tencentdb": {
    "storeBackend": "tcvdb",
    "tcvdb": {
      "url": "http://your-vdb-instance:8100",
      "apiKey": "your-api-key",
      "database": "my_memory_db"
    }
  }
 }
 ```
 ### 4. Enable short-term compression (optional, requires version ≥ 0.3.0)
 ```jsonc
 {
@@ -159,21 +142,46 @@ Once enabled, TencentDB Agent Memory automatically handles conversation capture,
 }
 ```
-### 5. Hermes Gateway Quick Start (Docker, requires version ≥ 0.3.0)
+#### Step 1 — Register the slot in your plugin config
-In addition to OpenClaw, this plugin also supports the [Hermes](https://github.com/hermes-ai/hermes) Agent. Start a memory-enabled Hermes with a single command:
+Add the `slots` field so OpenClaw routes context-offload requests to this plugin:
 ```jsonc
 {
  "plugins": {
    "slots": {
      "contextEngine": "openclaw-context-offload"
    }
  }
 }
 ```
 #### Step 2 — Apply the runtime patch
 For the best results, run the patch script below. It hooks `after-tool-call` messages so they can be offloaded and recovered correctly:
 ```bash
-docker run -d \
+bash scripts/openclaw-after-tool-call-messages.patch.sh
-  --name hermes-memory \
+```
-  --restart unless-stopped \
+
-  -p 8420:8420 \
+> 💡 The patch only needs to be applied once per OpenClaw installation. After upgrading OpenClaw, re-run the script to re-apply.
-  -e MODEL_API_KEY="your-api-key" \
+
-  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \
+
-  -e MODEL_NAME="deepseek-v3.2" \
+### 2. Hermes (Docker, requires version ≥ 0.3.4)
-  -e MODEL_PROVIDER="custom" \
+
-  -v hermes_data:/opt/data \
+In addition to OpenClaw, this plugin also supports the [Hermes](https://github.com/NousResearch/hermes-agent) Agent. Start a memory-enabled Hermes with a single command:
-  agentmemory/hermes-memory:latest
+
 ```bash
 docker run -d \                                                              # Run container in detached (background) mode
  --name hermes-memory \                                                     # Container name for easy docker exec / logs / stop
  --restart unless-stopped \                                                 # Auto-restart on crash or host reboot, unless manually stopped
  -p 8420:8420 \                                                             # Map host port 8420 -> container port 8420 (Hermes Gateway)
  -e MODEL_API_KEY="your-api-key" \                                          # LLM API key (required) — replace with your own credential
  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \               # LLM endpoint, defaults to Tencent Cloud LKE Auto Platform
  -e MODEL_NAME="deepseek-v3.2" \                                            # Model identifier, defaults to DeepSeek-V3.2
  -e MODEL_PROVIDER="custom" \                                               # Provider type: "custom" for OpenAI-compatible endpoints
  -v hermes_data:/opt/data \                                                 # Persist memory data to a named volume (survives container restarts)
  agentmemory/hermes-memory:latest                                           # Official image, supports linux/amd64 and linux/arm64
 ```
 The image supports `linux/amd64` and `linux/arm64`. It ships with Tencent Cloud DeepSeek-V3.2 defaults — to use a different model, pass `MODEL_BASE_URL`, `MODEL_NAME`, and `MODEL_PROVIDER` accordingly.
@@ -181,8 +189,8 @@ The image supports `linux/amd64` and `linux/arm64`. It ships with Tencent Cloud
 Verify:
 ```bash
-curl http://localhost:8420/health          # Check Gateway health
+curl http://localhost:8420/health          # Check Gateway health endpoint, expect HTTP 200 + {"status":"ok"}
-docker exec -it hermes-memory hermes       # Enter Hermes conversation
+docker exec -it hermes-memory hermes       # Enter interactive Hermes REPL inside the running container
 ```
 ---
@@ -196,7 +204,7 @@ docker exec -it hermes-memory hermes       # Enter Hermes conversation
 | Field | Default | Description |
 | :--- | :--- | :--- |
-| `storeBackend` | `"sqlite"` | Storage backend: `sqlite` / `tcvdb` |
+| `storeBackend` | `"sqlite"` | Storage backend: `sqlite` |
 | `recall.strategy` | `"hybrid"` | Recall strategy: `keyword` / `embedding` / `hybrid` (RRF fusion, recommended) |
 | `recall.maxResults` | `5` | Number of items returned per recall |
 | `pipeline.everyNConversations` | `5` | Trigger an L1 memory extraction every N turns |
@@ -231,7 +239,6 @@ docker exec -it hermes-memory hermes       # Enter Hermes conversation
 For all fields, types, and constraints see [`openclaw.plugin.json`](./openclaw.plugin.json) and [`CONFIGURATION.md`](./CONFIGURATION.md).
 - `embedding.*` — remote embedding service (OpenAI-compatible API)
 - `tcvdb.*` — full Tencent Cloud Vector Database parameters (incl. HTTPS / self-signed CA)
 - `llm.*` — standalone LLM mode (bypass OpenClaw's built-in model and run L1/L2/L3 with a designated API)
 - `offload.backendUrl / backendApiKey` — offload the L1/L1.5/L2/L4 flow to a backend service
 - `report.*` — metrics reporting
@@ -240,42 +247,43 @@ For all fields, types, and constraints see [`openclaw.plugin.json`](./openclaw.p
 ---
-## 🤔 Design Highlights
+## 🤔 Features
-### 1. Macro persona + micro facts: one drill-down mechanism to reduce hallucination
+### 1. Macro Personas + Micro Facts: A Unified Drill-Down Mechanism
-The biggest risk of compression is "saving tokens but losing the receipts". So TencentDB Agent Memory does not collapse history into an irreversible summary — it keeps a clear path from high-level abstraction back to ground-truth evidence.
+The biggest risk in compression is saving tokens at the cost of losing the evidence. TencentDB Agent Memory therefore does not collapse history into an irreversible summary — it preserves a clear path from high-level abstraction back to ground-truth evidence.
 | Question type | First look at | Drill down to |
 | :--- | :--- | :--- |
-| Daily preferences, voice, long-term goals | L3 Persona / L2 Scene | Hit L1 / L0 when facts are needed |
+| Daily preferences, voice, long-term goals | L3 Persona / L2 Scenario | L1 Atom / L0 Conversation when facts are needed |
-| Specific facts, dates, project details | L1 Memory / L0 Conversation | Widen the time range or use semantic recall when hits are sparse |
+| Specific facts, dates, project details | L1 Atom / L0 Conversation | Widen the time range, or fall back to semantic recall when results are sparse |
-| Continuing a long-running task | Active MMD task canvas | Check the JSONL when the summary is thin, then read `refs/*.md` for raw text |
+| Continuing a long-running task | Active Mermaid task canvas | Check the JSONL when the summary lacks detail, then `refs/*.md` for raw text |
-| Resuming a historical task | Metadata task entry | Open the MMD → find `node_id` → trace `result_ref` |
+| Resuming a historical task | Metadata task entry | Open the Mermaid canvas → locate the `node_id` → trace `result_ref` |
-The upper layer carries "judgment" and direction; the lower layer carries "evidence" and precision. Short-term compression and long-term memory close into one loop: **foldable and unfoldable; abstract yet auditable.**
+The upper layers carry judgment and direction; the lower layers carry evidence and precision. Short-term compression and long-term memory form a single closed loop: **collapsible and expandable, abstract yet auditable.**
-### 2. White-box debuggable: memory is not a black-box vector
+### 2. White-Box Debuggability: Memory Is Not a Black Box
-Many memory systems break here: when recall is wrong, all you see is a list of vector scores, and you cannot tell where things went sideways. TencentDB Agent Memory keeps the key intermediates as readable files:
+Most memory systems fall short here: when recall is wrong, all you see is a list of vector scores, with no way to tell where things went wrong. TencentDB Agent Memory keeps the key intermediates as readable files:
- L2 scene blocks are Markdown — open and inspect directly.
+- L2 Scenario blocks are plain Markdown — open them and inspect.
- L3 personas live in `persona.md` and trace back to the scenes that produced them.
+- L3 Persona lives in `persona.md` and traces back to the Scenarios that produced it.
- Short-term task canvases are Mermaid — readable to humans and to Agents.
+- Short-term task canvases are Mermaid — readable by both humans and Agents.
 - Raw payloads, summaries, and nodes are linked by `result_ref` and `node_id`.
-Debugging is no longer rummaging through a black-box database — it is walking the chain "persona → scene → memory → raw text" until the issue surfaces.
+Debugging no longer means probing an opaque database — it becomes a deterministic walk along the chain "Persona → Scenario → Atom → Conversation" until the root cause surfaces.
-### 3. Production-ready engineering: a real plugin, not a demo
+**All of these layered memory artifacts live under `~/.openclaw/memory-tdai/` — feel free to open the directory and inspect each layer for yourself.**
 ### 3. Production-Ready Engineering: Not a Demo
 | Capability | Description |
 | :--- | :--- |
-| OpenClaw plugin | Capture, extract, and recall memory automatically once installed |
+| OpenClaw plugin | Automatically captures, extracts, and recalls memory once installed |
-| Hermes Gateway adapter | `TdaiCore + HostAdapter` decoupled from the host framework |
+| Hermes Gateway adapter | `TdaiCore + HostAdapter`, decoupled from the host framework |
-| Dual backends | Local `SQLite + sqlite-vec`, or remote `TCVDB` |
+| Local backend | `SQLite + sqlite-vec`, ready to use out of the box |
-| Hybrid retrieval | BM25 + vector + RRF — both keyword and semantic recall |
+| Hybrid retrieval | BM25 + vector + RRF — supports both keyword and semantic recall |
 | Agent tools | `tdai_memory_search` / `tdai_conversation_search` |
 | Data migration | Historical import, SQLite → TCVDB migration, VDB export |
 ---
@@ -283,7 +291,6 @@ Debugging is no longer rummaging through a black-box database — it is walking
 | Document | Contents |
 | :--- | :--- |
 | [`CONFIGURATION.md`](./CONFIGURATION.md) | Full configuration reference, field descriptions, and advanced parameters |
 | [`scripts/README.memory-tencentdb-ctl.md`](./scripts/README.memory-tencentdb-ctl.md) | Operations & management tooling |
 | [`CHANGELOG.md`](./CHANGELOG.md) | Release notes and version history |
 | [`openclaw.plugin.json`](./openclaw.plugin.json) | OpenClaw plugin manifest and configuration schema |
@@ -307,9 +314,8 @@ We welcome every kind of contribution — bug reports, feature ideas, doc fixes,
 - [x] Short-term context compression (Context Offload + Mermaid canvas)
 - [x] Local SQLite backend and Tencent Cloud Vector Database (TCVDB) backend
 - [x] OpenClaw plugin and Hermes Gateway integration
 - [ ] Short-term compression GA release
 - [ ] Portable memory: cross-Agent / cross-framework / cross-device import, export, and live migration
- [ ] More Agent framework adapters
+- [ ] Automatic Skill generation
 - [ ] Visual debugging and memory observability dashboard
 ---
@@ -1,6 +1,6 @@
 <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" />
 ### 让 Agent 沉淀经验，让人专注创造。
@@ -9,14 +9,21 @@
 [![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)
+[![Hermes](https://img.shields.io/badge/Hermes-Gateway-7B61FF)](https://hermes-agent.nousresearch.com/docs/)
 [![Discord](https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white)](https://discord.gg/kDtHb5RW2)
-[效果亮点](#效果亮点) · [项目简介](#项目简介) · [特点](#特点) · [快速开始](#快速开始)
+[效果亮点](#-效果亮点) · [项目简介](#项目简介) · [核心技术](#核心技术拒绝平铺走向分层与符号化) · [方案特点](#-方案特点) · [快速开始](#快速开始)
 <div align="center">
 [English](./README.md) · [**简体中文**](./README_CN.md)
 </div>
 ---
 </div>
 ## ✨ 效果亮点
 > **TencentDB Agent Memory = 符号化短期记忆 + 分层式长期记忆。**
@@ -61,7 +68,7 @@ TencentDB Agent Memory 的设计理念围绕两个核心展开：**记忆分层*
 我们认为，**不管是长期的知识、短期的任务，还是未来的经验能力，记忆都不应该平铺，生成和召回都必须有层次**。TencentDB Agent Memory 将“分层”作为整个架构的统一设计哲学：
 *   **短期记忆（上下文卸载/任务）的分层**：底层保留原始、厚重的工具调用结果（`refs/*.md`），中层抽取步骤摘要（`jsonl`），高层则浓缩为一张极度轻量的 Mermaid 任务画布。Agent 在上下文中仅需关注高层结构，遇错时再沿着 `node_id` 下钻到底层查证。
-*   **长期个性化（用户理解）的分层**：打破扁平的历史记录，建立 L0 原始对话 → L1 结构化事实 → L2 场景块 → L3 用户画像 的语义金字塔。平时靠高层画像把握用户偏好，需要考证细节时再检索底层事实。
+*   **长期个性化（用户理解）的分层**：打破扁平的历史记录，建立 **L0 Conversation**（原始对话） → **L1 Atom**（结构化事实） → **L2 Scenario**（场景块） → **L3 Persona**（用户画像）的语义金字塔。平时靠高层 Persona 把握用户偏好，需要考证细节时再检索底层 Atom。
 *   **技能生成（Skill与动作沉淀，Roadmap）的分层**：记忆不应仅限于“知道什么”，还应包括“会做什么”。我们正在将分层延伸至动作域：从底层的执行轨迹（Traces）与报错日志中，中层归纳出共性的解决模式，高层最终提炼出可直接挂载复用的 Skill 或标准 SOP 代码。
 <p align="center">
@@ -70,20 +77,11 @@ TencentDB Agent Memory 的设计理念围绕两个核心展开：**记忆分层*
 **渐进式披露与异构存储**：为了支撑这种无处不在的分层，我们设计了底层数据库与上层文件系统结合的存储方案。底层（海量事实、日志、轨迹）存入数据库或归档文件，确保稳定与全量检索；高层（画像、场景、画布、Skill）存入业务可读的文件系统（Markdown），确保高信息密度、逻辑清晰与白盒可调。**低层保留证据，高层保留结构。**
-**每一条信息都 100% 可找回、可恢复**：压缩或抽象最大的风险是“丢失证据”。得益于严格的索引映射机制，系统内没有任何一段摘要是“不可逆”的黑盒。无论是短期记忆中被卸载的一段报错日志，还是长期记忆里总结出的一条用户偏好，Agent 或开发者都可以沿着“高层符号（画像/画布） → 中层索引（场景/JSONL） → 底层原文（L0对话/refs）”的链路进行完美溯源与恢复。
+**每一条信息都 100% 可找回、可恢复**：压缩或抽象最大的风险是“丢失证据”。得益于严格的索引映射机制，系统内没有任何一段摘要是“不可逆”的黑盒。无论是短期记忆中被卸载的一段报错日志，还是长期记忆里总结出的一条用户偏好，Agent 或开发者都可以沿着“高层符号（Persona / 画布） → 中层索引（Scenario / JSONL） → 底层原文（L0 Conversation / refs）”的链路进行完美溯源与恢复。
-```mermaid
+<div align="center">
-flowchart LR
+  <img src="assets/images/flowchart1.cn.png" alt="Retrievable and Recoverable Drill-Down Chain" />
-  subgraph TraceLink["100% 可找回、可恢复的下钻链路"]
+</div>
    direction TB
    High["高层：符号与结构<br/>(Persona 画像 / Mermaid 画布)"] 
    Mid["中层：摘要与索引<br/>(Scene 场景块 / JSONL 摘要)"]
    Low["底层：完整事实与证据<br/>(L0 原始对话 / refs 原文)"]
    High == "需要细节 / 发生疑惑" ==> Mid
    Mid == "凭借 node_id 或引文匹配" ==> Low
  end
 ```
 ### 2. 符号化记忆：用最少符号表达最多语义（Mermaid 画布）
@@ -106,19 +104,18 @@ graph LR
    style MMD fill:#eff6ff,stroke:#3b82f6,stroke-width:2px
    style Agent fill:#fffbeb,stroke:#f59e0b,stroke-width:2px
 ```
 ---
 ## 快速开始
-
+### 1. Openclaw
-### 1. 安装插件
+### 1.1 安装插件
 ```bash
 openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
 openclaw gateway restart
 ```
-### 2. 零配置启用
+### 1.2 零配置启用
 默认使用本地 `SQLite + sqlite-vec` 后端。
@@ -133,22 +130,8 @@ openclaw gateway restart
 启用后，TencentDB Agent Memory 会自动完成对话录制、记忆提取、场景归纳、用户画像生成和下一轮对话前召回。
 ### 3. 使用 TCVDB 后端（可选，需版本号 ≥ 0.2.0）
-```jsonc
+### 1.3 启用短期记忆压缩（可选，要求版本 ≥ 0.3.4）
 {
  "memory-tencentdb": {
    "storeBackend": "tcvdb",
    "tcvdb": {
      "url": "http://your-vdb-instance:8100",
      "apiKey": "your-api-key",
      "database": "my_memory_db"
    }
  }
 }
 ```
 ### 4. 启用短期记忆压缩（可选，需版本号 ≥ 0.3.0）
 ```jsonc
 {
@@ -160,21 +143,46 @@ openclaw gateway restart
 }
 ```
-### 5. Hermes Gateway 快速启动（Docker，需版本号 ≥ 0.3.0）
+#### 步骤 1 —— 在插件配置中注册 slot
-除 OpenClaw 外，本插件也支持 [Hermes](https://github.com/hermes-ai/hermes) Agent。一行命令即可启动带记忆能力的 Hermes：
+在 `slots` 字段中声明 `contextEngine`，让 OpenClaw 把上下文卸载请求路由到本插件：
 ```jsonc
 {
  "plugins": {
    "slots": {
      "contextEngine": "openclaw-context-offload"
    }
  }
 }
 ```
 #### 步骤 2 —— 执行 patch 脚本
 为保证最佳效果，请执行以下 patch 脚本。该脚本会注入 `after-tool-call` 消息钩子，让工具调用结果能被正确卸载与回溯：
 ```bash
-docker run -d \
+bash scripts/openclaw-after-tool-call-messages.patch.sh
-  --name hermes-memory \
+```
-  --restart unless-stopped \
+
-  -p 8420:8420 \
+> 💡 patch 每次 OpenClaw 安装只需执行一次。升级 OpenClaw 后建议重新执行以确保钩子生效。
-  -e MODEL_API_KEY="your-api-key" \
+
-  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \
+
-  -e MODEL_NAME="deepseek-v3.2" \
+### 2. Hermes（Docker，需版本号 ≥ 0.3.4）
-  -e MODEL_PROVIDER="custom" \
+
-  -v hermes_data:/opt/data \
+除 OpenClaw 外，本插件同样支持 [Hermes](https://github.com/NousResearch/hermes-agent) Agent。通过一条命令即可启动一个带记忆能力的 Hermes：
-  agentmemory/hermes-memory:latest
+
 ```bash
 docker run -d \                                                              # 以后台（detached）模式运行容器
  --name hermes-memory \                                                     # 容器命名，方便后续 docker exec / logs / stop
  --restart unless-stopped \                                                 # 崩溃或宿主机重启时自动拉起，除非手动停止
  -p 8420:8420 \                                                             # 宿主机端口 8420 映射到容器端口 8420（Hermes Gateway）
  -e MODEL_API_KEY="your-api-key" \                                          # 大模型 API Key（必填）—— 替换为你自己的凭证
  -e MODEL_BASE_URL="https://api.lkeap.cloud.tencent.com/v1" \               # 大模型接入地址，默认指向腾讯云大模型知识引擎
  -e MODEL_NAME="deepseek-v3.2" \                                            # 模型名称，默认使用 DeepSeek-V3.2
  -e MODEL_PROVIDER="custom" \                                               # 服务商类型："custom" 适用于所有 OpenAI 兼容接口
  -v hermes_data:/opt/data \                                                 # 将记忆数据持久化到命名卷（容器重启后数据不丢）
  agentmemory/hermes-memory:latest                                           # 官方镜像，支持 linux/amd64 与 linux/arm64
 ```
 镜像支持 `linux/amd64` 和 `linux/arm64`。内置腾讯云 DeepSeek-V3.2 默认配置，如需自定义模型可额外传入 `MODEL_BASE_URL`、`MODEL_NAME`、`MODEL_PROVIDER`。
@@ -197,7 +205,7 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 | 字段 | 默认 | 说明 |
 | :--- | :--- | :--- |
-| `storeBackend` | `"sqlite"` | 存储后端：`sqlite` / `tcvdb` |
+| `storeBackend` | `"sqlite"` | 存储后端：`sqlite` |
 | `recall.strategy` | `"hybrid"` | 召回策略：`keyword` / `embedding` / `hybrid`（RRF 融合，推荐） |
 | `recall.maxResults` | `5` | 每次召回条数 |
 | `pipeline.everyNConversations` | `5` | 每 N 轮对话触发一次 L1 记忆提取 |
@@ -232,7 +240,6 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 完整字段、类型、约束见 [`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.*` — 指标上报
@@ -249,8 +256,8 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 | 问题类型 | 优先使用 | 继续下钻 |
 | :--- | :--- | :--- |
-| 日常偏好、表达风格、长期目标 | L3 Persona / L2 Scene | 需要事实时查 L1 / L0 |
+| 日常偏好、表达风格、长期目标 | L3 Persona / L2 Scenario | 需要事实时查 L1 Atom / L0 Conversation |
-| 具体事实、时间、项目细节 | L1 Memory / L0 Conversation | 命中不足时扩大时间范围或语义检索 |
+| 具体事实、时间、项目细节 | L1 Atom / L0 Conversation | 命中不足时扩大时间范围或语义检索 |
 | 当前长任务继续执行 | Active MMD 任务画布 | 摘要不够时查 JSONL，再读 `refs/*.md` 原文 |
 | 历史任务恢复 | Metadata 任务入口 | 打开 MMD → 找 node_id → 追 result_ref |
@@ -260,12 +267,14 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 很多记忆系统的问题是：召回错了，你只能看到一串向量分数，很难判断到底哪里错。TencentDB Agent Memory 把关键中间产物保存在可读文件里：
- L2 场景块是 Markdown，可以直接打开检查。
+- L2 Scenario 块是 Markdown，可以直接打开检查。
- L3 用户画像是 `persona.md`，可以追溯到对应场景。
+- L3 Persona 存放在 `persona.md`，可以追溯到对应的 Scenario。
 - 短期任务画布是 Mermaid，既能给人看，也能给 Agent 读。
 - 原文、摘要、节点之间有 `result_ref` 和 `node_id` 关联。
-这意味着调试不再是翻黑盒数据库，而是沿着“画像 → 场景 → 记忆 → 原文”的链路逐层定位。
+这意味着调试不再是翻黑盒数据库，而是沿着“Persona → Scenario → Atom → Conversation”的链路逐层定位。
 **这些分层记忆产物都存放在 `~/.openclaw/memory-tdai/` 下，可以直接打开目录逐层查看。**
 ### 3. 工程能力完整：不是 Demo，而是可接入的插件
@@ -273,10 +282,9 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 | :--- | :--- |
 | OpenClaw 插件 | 安装后即可自动捕获、提取、召回记忆 |
 | Hermes Gateway 适配 | `TdaiCore + HostAdapter` 解耦宿主框架 |
-| 双后端 | 本地 `SQLite + sqlite-vec`，或远端 `TCVDB` |
+| 本地后端 | `SQLite + sqlite-vec`，开箱即用 |
 | 混合检索 | BM25 + 向量 + RRF，兼顾关键词和语义召回 |
 | Agent 工具 | `tdai_memory_search` / `tdai_conversation_search` |
 | 数据迁移 | 支持历史导入、SQLite → TCVDB 迁移、VDB 导出 |
 ---
@@ -284,7 +292,6 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 | 文档 | 内容 |
 | :--- | :--- |
 | [`CONFIGURATION.md`](./CONFIGURATION.md) | 完整配置参考、字段说明与高级参数 |
 | [`scripts/README.memory-tencentdb-ctl.md`](./scripts/README.memory-tencentdb-ctl.md) | 运维管理工具说明 |
 | [`CHANGELOG.md`](./CHANGELOG.md) | 版本变更记录 |
 | [`openclaw.plugin.json`](./openclaw.plugin.json) | OpenClaw 插件声明与配置 Schema |
@@ -306,11 +313,10 @@ docker exec -it hermes-memory hermes       # 进入 Hermes 对话
 - [x] 长期个性化记忆（L0 → L3）
 - [x] 短期记忆压缩（Context Offload + Mermaid 画布）
- [x] 本地 SQLite 后端与腾讯云向量数据库 TCVDB 后端
+- [x] 可用本地 SQLite 后端与腾讯云向量数据库 TCVDB 后端
 - [x] OpenClaw 插件与 Hermes Gateway 适配
 - [ ] 短期记忆压缩正式产品化上线
 - [ ] 记忆可迁移：跨 Agent / 跨框架 / 跨设备的导入导出与热迁移
- [ ] 更多 Agent 框架适配
+- [ ] Skill自动生成
 - [ ] 可视化调试与记忆观测面板
 ---
@@ -153,7 +153,7 @@ openclaw gateway restart
 检查项：
 - Gateway 日志中出现 `[memory-tdai]` 前缀
- 数据目录已创建：`~/.openclaw/state/memory-tdai/`
+- 数据目录已创建：`~/.openclaw/memory-tdai/`
 - 至少包含：`conversations/`、`records/`、`scene_blocks/`、`vectors.db`
 ### 7) 功能冒烟测试
@@ -198,4 +198,4 @@ openclaw gateway restart
 - 已完成 `memory-tencentdb` 安装与配置，并重启 Gateway。
 - 已验证日志与数据目录生效，记忆链路可用。
- 如需下一步优化，可继续调优 `recall.scoreThreshold`、`pipeline.everyNConversations`、`persona.triggerEveryN` 与 `embedding` 模型参数。
+- 如需下一步优化，可继续调优 `recall.scoreThreshold`、`pipeline.everyNConversations`、`persona.triggerEveryN` 与 `embedding` 模型参数。
@@ -1,4 +1,4 @@
-# memory-tencentdb-ctl.sh — memory_tencentdb (TDAI) 运维脚本
+# memory-tencentdb-ctl.sh — memory_tencentdb运维脚本
 > 配合 [`install_hermes_memory_tencentdb.sh`](./install_hermes_memory_tencentdb.sh) 使用。
 > 先跑安装脚本部署好插件 + Node 依赖，之后日常的启停 / 配置全部通过 `memory-tencentdb-ctl.sh` 完成。