# Overview

> What TencentDB Agent Memory exposes, host integration surfaces (OpenClaw plugin and Hermes Gateway), runtime assumptions, 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-5a33bbf5540a
- Complete Markdown: https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/llms-full.txt

## Source Files

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

---

---
title: "Overview"
description: "What TencentDB Agent Memory exposes, host integration surfaces (OpenClaw plugin and Hermes Gateway), runtime assumptions, and the first docs routes to follow."
---

`@tencentdb-agent-memory/memory-tencentdb` (v0.3.6) is a four-layer agent memory package for OpenClaw and Hermes. It exposes long-term memory (L0 conversation → L1 atoms → L2 scenes → L3 persona), optional symbolic short-term context offload, hybrid recall tools, a host-neutral `TdaiCore` facade, and a Node.js HTTP Gateway for non-OpenClaw hosts. Default storage is local `sqlite` + `sqlite-vec` + FTS5; optional `tcvdb` targets Tencent VectorDB. LLM and embedding calls use OpenAI-compatible endpoints you supply (BYOK).

## What the package exposes

| Surface | Identifiers | Role |
| :--- | :--- | :--- |
| OpenClaw plugin | id `memory-tencentdb`, CLI namespace `memory-tdai` | In-process capture, recall, tools, optional offload |
| Agent tools (OpenClaw) | `tdai_memory_search`, `tdai_conversation_search` | L1 memory and L0 conversation search |
| Agent tools (Hermes) | `memory_tencentdb_memory_search`, `memory_tencentdb_conversation_search` | Same capabilities over Gateway HTTP |
| Core facade | `TdaiCore` | Host-neutral recall, capture, search, session end, pipeline |
| Host adapters | `OpenClawHostAdapter`, `StandaloneHostAdapter` | OpenClaw plugin API vs standalone/Gateway runtime |
| Gateway HTTP | `TdaiGateway` on `127.0.0.1:8420` by default | Hermes sidecar: `/health`, `/recall`, `/capture`, `/search/*`, `/session/end`, `/seed` |
| Package bins | `migrate-sqlite-to-tcvdb`, `export-tencent-vdb`, `read-local-memory` | Offline migrate, export, inspect |
| Ops scripts | `scripts/memory-tencentdb-ctl.sh`, `scripts/install_hermes_memory_tencentdb.sh` | Gateway lifecycle and Hermes install |
| Hermes provider | `hermes-plugin/memory/memory_tencentdb/` | Python client + supervisor; provider key `memory_tencentdb` |

Plugin metadata lives in `openclaw.plugin.json` (`activation.onStartup: true`, config schema for capture/pipeline/recall/embedding/offload/tcvdb). Package entry is `index.ts` → built `dist/index.mjs`; engines require **Node `>=22.16.0`**. OpenClaw compat in `package.json` pins `pluginApi` / `minGatewayVersion` to `>=2026.3.13` (README badge matches; peerDependency allows `openclaw >=2026.3.7`).

## Host integration surfaces

### OpenClaw (in-process)

`index.ts` is a thin shell: parse plugin config, construct `OpenClawHostAdapter` + `TdaiCore`, register tools/hooks/CLI. Core logic stays in `src/core/tdai-core.ts`.

| Host event | Core method | Behavior |
| :--- | :--- | :--- |
| `before_prompt_build` | `handleBeforeRecall` | Auto-recall L1 (+ persona context) into the prompt |
| `agent_end` (success) | `handleTurnCommitted` | L0 capture and pipeline scheduling |
| Tool execute | `searchMemories` / `searchConversations` | Agent-driven search |
| `gateway_stop` / process exit | `destroy` | Full teardown (not session-scoped) |

Zero-config enable path:

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

```bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
openclaw gateway restart
```

Data directory resolves under the OpenClaw state dir as `memory-tdai` (typically `~/.openclaw/memory-tdai/`). On enable, the plugin auto-captures turns, runs L1→L2→L3 extraction when configured, and injects recall before the next turn.

Context offload is **separate** and default-off (`offload.enabled: false`). Enabling it requires `plugins.slots.contextEngine: "memory-tencentdb"`, the after-tool-call messages patch (`postinstall` / `scripts/openclaw-after-tool-call-messages.patch.sh`), and `offload.enabled: true`.

### Hermes (Gateway sidecar)

Hermes does not load TypeScript in-process. The Python provider `memory_tencentdb` starts or discovers the Node Gateway and maps lifecycle hooks to HTTP:

| Hermes call | Gateway route |
| :--- | :--- |
| `prefetch(query)` | `POST /recall` |
| `sync_turn(user, assistant)` | `POST /capture` (background, back-pressured) |
| `on_session_end` / shutdown | `POST /session/end` |
| Tool schemas | Client-side; execute via `/search/memories` and `/search/conversations` |

Provider directory name **must** be `memory_tencentdb` (underscore). Config aliases include `memory-tencentdb` and legacy `tdai`. Default Gateway listen address is `http://127.0.0.1:8420`. Auth is optional: set `TDAI_GATEWAY_API_KEY` on the server and `MEMORY_TENCENTDB_GATEWAY_API_KEY` (or fallback `TDAI_GATEWAY_API_KEY`) on the Hermes client.

```mermaid
flowchart TB
  subgraph Hosts["Host runtimes"]
    OC["OpenClaw plugin<br/>index.ts"]
    HM["Hermes MemoryTencentdbProvider<br/>hermes-plugin/memory/memory_tencentdb"]
  end

  subgraph Core["Host-neutral core"]
    OCA["OpenClawHostAdapter"]
    SHA["StandaloneHostAdapter"]
    TC["TdaiCore"]
    OCA --> TC
    SHA --> TC
  end

  subgraph Stores["Storage"]
    SQL[("sqlite + sqlite-vec + FTS5")]
    VDB[("tcvdb")]
    FS["JSONL / Markdown<br/>conversations, records,<br/>scene_blocks, persona"]
  end

  subgraph Ext["External BYOK services"]
    LLM["OpenAI-compatible LLM"]
    EMB["OpenAI-compatible embeddings<br/>or TCVDB server-side embed"]
  end

  OC --> OCA
  HM -->|"HTTP TdaiGateway<br/>:8420"| SHA
  TC --> SQL
  TC --> VDB
  TC --> FS
  TC --> LLM
  TC --> EMB
```

## Memory model (summary)

Two complementary systems share the package:

| System | Layers / artifacts | Default |
| :--- | :--- | :--- |
| Long-term layered memory | **L0** conversations (JSONL + search) → **L1** episodic atoms → **L2** scene blocks (Markdown) → **L3** persona (`persona.md`) | Capture/extraction/recall on; pipeline schedules L1 then delayed L2/L3 |
| Symbolic short-term (offload) | Tool results → `refs/*.md` → L1/L1.5/L2 pipelines → Mermaid canvas with `node_id` recovery | Off by default |

Drill-down is intentional: persona/scenes for direction; atoms/conversations for evidence; Mermaid `node_id` for raw offloaded tool payloads. Heterogeneous storage: lower layers favor DB/JSONL retrieval; upper layers favor readable Markdown.

## Runtime assumptions

| Requirement | Value |
| :--- | :--- |
| Node.js | `>= 22.16.0` |
| OpenClaw (plugin path) | `>= 2026.3.13` recommended (plugin API / gateway compat) |
| Default store | `storeBackend: "sqlite"` (no remote DB required) |
| Embedding | `embedding.provider` default `"none"` → keyword/hybrid degrades without vectors |
| LLM for L1/L2/L3 | OpenClaw host model by default; optional `llm.enabled` standalone OpenAI-compatible API |
| Hermes path | Node Gateway process + LLM credentials (`TDAI_LLM_*` or `tdai-gateway.json`) |
| Gateway auth | Disabled by default; `GET /health` always unauthenticated |
| Gateway host | Default loopback; non-loopback without API key logs a loud warning |
| License | MIT |

<Warning>
Do not expose the Gateway on a non-loopback interface without `TDAI_GATEWAY_API_KEY`. Auth and CORS are opt-in so existing local sidecars keep working.
</Warning>

## Storage and data layout

`initDataDirectories` creates under the plugin/Gateway data dir:

```text
<dataDir>/
  conversations/   # L0
  records/         # L1
  scene_blocks/    # L2
  .metadata/
  .backup/
  # plus vectors.db / persona artifacts depending on backend and pipeline
```

| Host | Typical data root |
| :--- | :--- |
| OpenClaw | `<openclaw-state-dir>/memory-tdai` (often `~/.openclaw/memory-tdai`) |
| Gateway / Hermes | `$TDAI_DATA_DIR` default `~/.memory-tencentdb/memory-tdai` |
| Offload (optional) | `~/.openclaw/context-offload` unless `offload.dataDir` is set |

Factory selection (`createStoreBundle`): `sqlite` uses local vectors and client-side embeddings when configured; `tcvdb` requires `tcvdb.url`, `tcvdb.apiKey`, and `tcvdb.database`, uses server-side embedding (`NoopEmbeddingService` client-side), and optional BM25 sparse encoding (`bm25.language` default `"zh"`).

## Gateway routes (inventory)

| Method | Path | Auth when key set | Purpose |
| :--- | :--- | :--- | :--- |
| `GET` | `/health` | No | Status, version, uptime, store readiness |
| `POST` | `/recall` | Yes | Prefetch memory context |
| `POST` | `/capture` | Yes | Commit a user/assistant turn |
| `POST` | `/search/memories` | Yes | L1 search |
| `POST` | `/search/conversations` | Yes | L0 search |
| `POST` | `/session/end` | Yes | Flush one session (not full process destroy) |
| `POST` | `/seed` | Yes | Batch historical import |

Error envelope: `{ "error": "<message>" }`. Health returns `status: "ok" | "degraded"` based on vector store presence.

## Configuration entry points

| Context | Where |
| :--- | :--- |
| OpenClaw plugin | `~/.openclaw/openclaw.json` → `memory-tencentdb` / nested `config` |
| Schema + defaults | `openclaw.plugin.json` → `configSchema` |
| Gateway file | `TDAI_GATEWAY_CONFIG`, `./tdai-gateway.{yaml,json}`, or `<dataDir>/tdai-gateway.{yaml,json}` |
| Gateway env | `TDAI_GATEWAY_PORT` (8420), `TDAI_GATEWAY_API_KEY`, `TDAI_CORS_ORIGINS`, `TDAI_DATA_DIR`, `TDAI_LLM_*` |
| Hermes client | `MEMORY_TENCENTDB_GATEWAY_*`, `memory.provider: memory_tencentdb` in `~/.hermes/config.yaml` |

Daily tuning defaults that matter on day one: `recall.strategy: "hybrid"`, `recall.maxResults: 5`, `pipeline.everyNConversations: 5`, `pipeline.enableWarmup: true`, `persona.triggerEveryN: 50`, `storeBackend: "sqlite"`, `offload.enabled: false`.

## CLI and package scripts

| Command | Role |
| :--- | :--- |
| `openclaw plugins install/update @tencentdb-agent-memory/memory-tencentdb` | Install / upgrade plugin |
| `openclaw memory-tdai …` | Plugin CLI (seed and related) |
| `migrate-sqlite-to-tcvdb` | Offline SQLite → TCVDB |
| `export-tencent-vdb` | Export TCVDB collections |
| `read-local-memory` | Inspect local L0–L3 artifacts |
| `memory-tencentdb-ctl` (script) | start/stop/status/health/logs for Gateway |
| `npm test` / `npm run build` | Vitest + tsdown |

`postinstall` best-effort applies the OpenClaw after-tool-call messages patch for offload correctness (`|| true` so install never fails hard).

## Choose a path

<CardGroup>
  <Card title="Quickstart (OpenClaw)" href="/quickstart">
    Install plugin, enable `memory-tencentdb`, restart gateway, confirm data-dir activity.
  </Card>
  <Card title="Installation" href="/installation">
    Node/OpenClaw prerequisites, npm package install, update commands, postinstall patch.
  </Card>
  <Card title="Hermes setup" href="/hermes-setup">
    Docker greenfield image, attach to existing Hermes, provider directory naming, health checks.
  </Card>
  <Card title="Memory layers" href="/memory-layers">
    L0–L3 model, pipeline schedule, drill-down paths.
  </Card>
</CardGroup>

## Next

<CardGroup>
  <Card title="TdaiCore and host adapters" href="/tdai-core-adapters">
    Facade methods, OpenClaw vs Standalone adapters, hook-to-HTTP mapping.
  </Card>
  <Card title="Context offload" href="/context-offload">
    Symbolic short-term memory, Mermaid injection, compression ratios.
  </Card>
  <Card title="Storage backends" href="/storage-backends">
    sqlite vs tcvdb, BM25, hybrid RRF, embedding roles.
  </Card>
  <Card title="Gateway HTTP API" href="/gateway-http-api">
    Request/response fields, auth exceptions, error envelope.
  </Card>
  <Card title="Plugin configuration reference" href="/plugin-config-reference">
    Full schema, defaults, validation, parseConfig behavior.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Disabled plugin, empty recall, embedding 400, Gateway auth, offload patch gaps.
  </Card>
</CardGroup>