# Overview

> What TencentDB Agent Memory exposes, who should use it, host entry points (OpenClaw plugin, Hermes provider, Gateway), and the first docs routes to follow.

- Repository: TencentCloud/TencentDB-Agent-Memory
- GitHub: https://github.com/TencentCloud/TencentDB-Agent-Memory
- Human docs: https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-14fefdd76c97
- Complete Markdown: https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-14fefdd76c97/llms-full.txt

## Source Files

- `package.json`
- `index.ts`
- `openclaw.plugin.json`
- `src/core/tdai-core.ts`
- `src/core/types.ts`
- `README.md`

---

---
title: "Overview"
description: "What TencentDB Agent Memory exposes, who should use it, host entry points (OpenClaw plugin, Hermes provider, Gateway), and the first docs routes to follow."
---

`@tencentdb-agent-memory/memory-tencentdb` (v0.3.6) is a host-neutral four-layer agent memory system. Core algorithms live in `TdaiCore` (`src/core/tdai-core.ts`); hosts attach through `HostAdapter` + `LLMRunnerFactory` and never embed OpenClaw or Hermes APIs inside the memory pipeline. The same core powers in-process OpenClaw registration (`index.ts`), a Node HTTP Gateway sidecar (`src/gateway/server.ts`), and the Hermes Python `memory_tencentdb` provider that talks to that Gateway.

## Package identity

| Field | Value |
| --- | --- |
| npm package | `@tencentdb-agent-memory/memory-tencentdb` |
| OpenClaw plugin id | `memory-tencentdb` |
| CLI / log alias | `memory-tdai` (`commandAliases`, log tag `[memory-tdai]`) |
| Hermes provider dir / key | `memory_tencentdb` (underscore; config alias `memory-tencentdb` / `tdai` also resolve) |
| Node | `>=22.16.0` |
| OpenClaw plugin API | `>=2026.3.13` (`package.json` `openclaw.compat`) |
| License | MIT |

Legacy package name `@tdai/memory-tdai` (plugin id `memory-tdai`) shares the on-disk data root `~/.openclaw/memory-tdai/` with the current package. Migrate via the package-rename flow; do not delete that directory when uninstalling the old plugin.

## What it exposes

Two independent memory tracks share one install:

| Track | Default | Role |
| --- | --- | --- |
| **Layered long-term memory** | On when capture/recall/extraction defaults apply | L0 conversations → L1 atoms → L2 scene blocks → L3 persona; auto-recall before each turn; agent tools for search |
| **Symbolic short-term memory (context offload)** | `offload.enabled: false` | Offloads tool-pair logs, builds L1/L1.5/L2 Mermaid canvas, injects compact symbols with `node_id` drill-down |

### Long-term layers (L0–L3)

| Layer | Producer | Typical storage under data dir |
| --- | --- | --- |
| **L0 Conversation** | Auto-capture on successful turn end | `conversations/*.jsonl` + vector index |
| **L1 Atom** | LLM extraction + optional vector/keyword dedup | `records/*.jsonl` + vector index |
| **L2 Scene** | Pipeline after L1 (Markdown scene blocks) | `scene_blocks/*.md` |
| **L3 Persona** | Triggered every N new L1 memories (default 50) | `persona.md` (+ backups) |

Recall injects dynamic L1 hits as user-prompt `prependContext` and stable persona / scene navigation / tool guidance as `appendSystemContext` (system prompt). Capture records L0 and notifies the L1→L2→L3 pipeline scheduler.

### Agent tools (OpenClaw)

Registered when capture or recall is enabled:

| Tool | Searches | Notes |
| --- | --- | --- |
| `tdai_memory_search` | L1 structured memories | Hybrid / embedding / keyword strategies |
| `tdai_conversation_search` | L0 raw conversations | Use when L1 is insufficient |

Both tools share a **combined limit of 3 calls per turn**.

### Gateway HTTP API (Hermes sidecar)

Node `http` server (default `127.0.0.1:8420`, no Express/Fastify):

| Method | Path | Maps to |
| --- | --- | --- |
| `GET` | `/health` | Liveness (no auth required) |
| `POST` | `/recall` | `TdaiCore.handleBeforeRecall` |
| `POST` | `/capture` | `TdaiCore.handleTurnCommitted` |
| `POST` | `/search/memories` | `TdaiCore.searchMemories` |
| `POST` | `/search/conversations` | `TdaiCore.searchConversations` |
| `POST` | `/session/end` | `TdaiCore.handleSessionEnd` (per-session flush only) |
| `POST` | `/seed` | Batch historical seed (L0→L1) |

Optional `TDAI_GATEWAY_API_KEY` enforces `Authorization: Bearer` on all routes except `GET /health`.

### CLI and package bins

| Surface | Purpose |
| --- | --- |
| `openclaw memory-tdai seed` | Seed historical conversations into the memory tree |
| `migrate-sqlite-to-tcvdb` | SQLite → Tencent VectorDB migration |
| `export-tencent-vdb` | Export Tencent VectorDB content |
| `read-local-memory` | Inspect local memory files |
| `scripts/memory-tencentdb-ctl.sh` | Gateway start/stop/status/health/logs/config |
| `scripts/install_hermes_memory_tencentdb.sh` | Hermes provider + Gateway install |
| `scripts/export-diagnostic.sh` | Redacted diagnostic package |

`postinstall` runs `scripts/openclaw-after-tool-call-messages.patch.sh` (non-fatal on failure) so offload can see `after-tool-call` messages when OpenClaw is present.

## Who should use it

| Audience | Fit |
| --- | --- |
| **OpenClaw operators** | Want automatic capture, layered recall, and optional token-saving offload inside the gateway process |
| **Hermes operators** | Want the same memory core via a supervised Gateway + `memory_tencentdb` MemoryProvider |
| **Integrators / hosts** | Need host-neutral `TdaiCore` APIs behind their own `HostAdapter` |
| **Maintainers** | Operate storage backends, seed history, migrate sqlite→tcvdb, or export diagnostics |

Not required: a single cloud vendor for LLM or embeddings. Extraction and embedding accept OpenAI-compatible endpoints; `storeBackend` is local `sqlite` (default) or remote `tcvdb`. Independent `llm` config can override the host model for L1/L2/L3.

## Host entry points

```mermaid
flowchart TB
  subgraph hosts [Host surfaces]
    OC[OpenClaw plugin<br/>index.ts register]
    HM[Hermes MemoryProvider<br/>memory_tencentdb]
    GW[TdaiGateway<br/>src/gateway/server.ts]
  end

  subgraph adapters [Host adapters]
    OCA[OpenClawHostAdapter]
    SA[StandaloneHostAdapter]
  end

  subgraph core [Host-neutral core]
    TC[TdaiCore]
    PIPE[L0→L1→L2→L3 pipeline]
    STORE[(sqlite-vec / tcvdb)]
  end

  subgraph offload [Optional short-term]
    OFF[registerOffload<br/>contextEngine slot]
  end

  OC --> OCA --> TC
  HM -->|HTTP 127.0.0.1:8420| GW
  GW --> SA --> TC
  TC --> PIPE
  TC --> STORE
  OC --> OFF
```

### OpenClaw plugin

1. Install: `openclaw plugins install @tencentdb-agent-memory/memory-tencentdb`
2. Enable in `~/.openclaw/openclaw.json` (plugin id `memory-tencentdb`)
3. Restart gateway; look for `[memory-tdai]` logs and data under `~/.openclaw/memory-tdai/`

`index.ts` is a thin shell: parses config, builds `OpenClawHostAdapter` + `TdaiCore`, registers tools, hooks `before_prompt_build` (recall) and `agent_end` (capture), and optionally `registerOffload`. Runtime data path is `path.join(openclawStateDir, "memory-tdai")` (directory name kept for compatibility).

Zero-config enable:

```jsonc
// ~/.openclaw/openclaw.json
{
  "memory-tencentdb": {
    "enabled": true
  }
}
```

Optional offload (requires `plugins.slots.contextEngine: "memory-tencentdb"` and the after-tool-call patch for best results):

```jsonc
{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  },
  "memory-tencentdb": {
    "config": {
      "offload": {
        "enabled": true
      }
    }
  }
}
```

### Hermes provider

Python package under `hermes-plugin/memory/memory_tencentdb/`:

- **Hooks:** `on_memory_write`, `on_session_end`
- **Lifecycle map:** `prefetch` → `POST /recall`, `sync_turn` → `POST /capture` (background, max 4 in-flight), session end → `POST /session/end`
- **Reliability:** circuit breaker (5 failures → 60s pause), supervised Gateway start, auto-discovery of `src/gateway/server.ts`
- **Install paths:** Docker greenfield (`docker/opensource/Dockerfile.hermes`), `install_hermes_memory_tencentdb.sh`, or symlink/copy into Hermes `plugins/memory/memory_tencentdb`

Provider key in `config.yaml` must use the directory name:

```yaml
memory:
  provider: memory_tencentdb
```

Default roots: `$MEMORY_TENCENTDB_ROOT` → `~/.memory-tencentdb` (install + data); Gateway port `8420`.

### Standalone Gateway

`TdaiGateway` constructs `StandaloneHostAdapter` (`hostType: "standalone"`, platform `"gateway"`) and one process-wide `TdaiCore`. Use for Hermes sidecar, manual ops (`memory-tencentdb-ctl`), or any HTTP client that implements the same endpoints. `handleSessionEnd` flushes **one** session only; process teardown uses `destroy()`.

## Storage and LLM boundaries

| Concern | Default | Notes |
| --- | --- | --- |
| `storeBackend` | `sqlite` | Local `vectors.db` + sqlite-vec + FTS5 |
| `storeBackend: tcvdb` | opt-in | Requires `tcvdb.url`, `apiKey`, `database` |
| Embedding | `provider: none` disables remote vectors | OpenAI-compatible quadruplet or ZeroEntropy path when set |
| Extraction LLM (OpenClaw) | Host embedded agent | Optional `llm.enabled` → standalone OpenAI-compatible runner |
| Extraction LLM (Gateway/Hermes) | `StandaloneLLMRunner` | `TDAI_LLM_*` env or `tdai-gateway.json` / yaml |

On store init failure, core degrades: pipeline can continue with JSONL fallback; recall/dedup quality drops. Logs tag degraded store paths under `[memory-tdai]`.

## On-disk layout (defaults)

```text
# OpenClaw long-term
~/.openclaw/memory-tdai/
  conversations/   # L0
  records/         # L1
  scene_blocks/    # L2
  .metadata/ .backup/
  vectors.db       # when sqlite backend
  persona.md       # L3

# OpenClaw short-term (when offload enabled)
~/.openclaw/context-offload/

# Hermes / standalone
~/.memory-tencentdb/
  tdai-memory-openclaw-plugin/   # package checkout
  memory-tdai/                   # TDAI_DATA_DIR default
```

## `TdaiCore` capability surface

Host-neutral methods every adapter path uses:

| Method | Host mapping |
| --- | --- |
| `initialize()` / `destroy()` | Process start / `gateway_stop` |
| `handleBeforeRecall(userText, sessionKey)` | OpenClaw `before_prompt_build`, Hermes `prefetch` |
| `handleTurnCommitted(CompletedTurn)` | OpenClaw `agent_end`, Hermes `sync_turn` |
| `searchMemories` / `searchConversations` | Tools + Gateway search routes |
| `handleSessionEnd(sessionKey)` | Hermes/Gateway session end (not full destroy) |

Interfaces: `RuntimeContext`, `HostAdapter`, `LLMRunner` / `LLMRunnerFactory` in `src/core/types.ts`. Implementations: `OpenClawHostAdapter`, `StandaloneHostAdapter`.

## First path by goal

| Goal | Start here |
| --- | --- |
| Install OpenClaw plugin | [Installation](/installation) → [Quickstart](/quickstart) |
| Understand L0–L3 | [Memory layers](/memory-layers) |
| Enable short-term compression | [Enable context offload](/enable-offload) → [Context offload](/context-offload) |
| Run on Hermes | [Install on Hermes](/install-hermes) → [Gateway HTTP API](/gateway-http-api) |
| Choose sqlite vs tcvdb | [Configure storage backends](/configure-storage) |
| Seed history or migrate package | [Seed historical conversations](/seed-conversations), [Package rename](/package-rename) |
| Operate Gateway / debug | [Gateway control](/gateway-control), [Troubleshooting](/troubleshooting) |

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Node and OpenClaw prerequisites, plugins install/update, link-from-source, postinstall patch.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    Zero-config enable, gateway restart, success logs, first tdai tool smoke checks.
  </Card>
  <Card title="Memory layers" href="/memory-layers">
    L0–L3 producers, storage shapes, pipeline triggers, drill-down paths.
  </Card>
  <Card title="Host adapters" href="/host-adapters">
    TdaiCore boundary: RuntimeContext, HostAdapter, OpenClaw vs standalone/Gateway.
  </Card>
  <Card title="Install on Hermes" href="/install-hermes">
    Docker, install script, provider symlink, Gateway supervision, config.yaml keys.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Full schema: capture, extraction, persona, pipeline, recall, embedding, tcvdb, offload.
  </Card>
</CardGroup>