# TencentDB Agent Memory Documentation

> Technical reference for the @tencentdb-agent-memory/memory-tencentdb four-layer agent memory system: OpenClaw plugin, Hermes Gateway HTTP API, L0–L3 pipeline, context offload, storage backends, CLIs, and operations.

This is a Grok-Wiki source-grounded repository documentation set. Use the complete Markdown link when an agent needs the full repo context.

## Context Links

- [Complete Markdown docs](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/llms-full.txt)
- [Complete Markdown alias](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a.md)
- [Human interactive docs](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a)
- [GitHub repository](https://github.com/TencentCloud/TencentDB-Agent-Memory)

## Repository

- Repository: TencentCloud/TencentDB-Agent-Memory

- Generated: 2026-08-04T19:25:39.445Z
- Updated: 2026-08-04T19:43:12.716Z
- Runtime: Grok CLI
- Format: Documentation
- Pages: 24

## Pages

- [Overview](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/01-overview.md): What TencentDB Agent Memory exposes, host integration surfaces (OpenClaw plugin and Hermes Gateway), runtime assumptions, and the first docs routes to follow.
- [Installation](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/02-installation.md): Prerequisites (Node >= 22.16, OpenClaw >= 2026.3.13), npm package install, OpenClaw plugin install and update commands, and postinstall patch behavior.
- [Quickstart](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/03-quickstart.md): Zero-config OpenClaw enable path: plugins install, openclaw.json memory-tencentdb.enabled, gateway restart, data-dir success signals, and optional offload slot registration.
- [Hermes setup](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/04-hermes-setup.md): Install and run memory_tencentdb with Hermes: Docker greenfield image, attach to existing Hermes, provider directory naming, Gateway auto-discovery, and health verification.
- [Memory layers](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/05-memory-layers.md): Repo-specific L0 conversation, L1 atom, L2 scene, and L3 persona model: what each layer stores, how the pipeline schedules L1→L2→L3, and drill-down paths between layers.
- [Context offload](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/06-context-offload.md): Symbolic short-term memory: tool-result offload to refs, L1/L1.5/L2 pipelines, Mermaid canvas injection, mild vs aggressive compression ratios, and node_id recovery.
- [Storage backends](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/07-storage-backends.md): sqlite (SQLite + sqlite-vec + FTS5) vs tcvdb store backends, BM25 sparse encoding, hybrid RRF retrieval, embedding service roles, and factory selection constraints.
- [TdaiCore and host adapters](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/08-tdaicore-and-host-adapters.md): Host-neutral TdaiCore facade, OpenClawHostAdapter vs StandaloneHostAdapter, LLM runner boundaries, and how in-process OpenClaw hooks map to Gateway HTTP handlers.
- [Configure OpenClaw](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/09-configure-openclaw.md): Enable the plugin in ~/.openclaw/openclaw.json, daily and advanced tuning groups (capture, pipeline, recall, persona), timezone, and verification after gateway restart.
- [Enable context offload](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/10-enable-context-offload.md): Turn on offload.enabled, register plugins.slots.contextEngine, apply the after-tool-call messages patch, tune compression ratios, and confirm Mermaid injection paths.
- [Configure embedding](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/11-configure-embedding.md): OpenAI-compatible embedding providers, required fields (baseUrl, apiKey, model, dimensions), sendDimensions for BGE-M3-style backends, timeouts, and graceful keyword-only degradation when provider is none.
- [Use Tencent VectorDB](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/12-use-tencent-vectordb.md): Switch storeBackend to tcvdb, required tcvdb.url / apiKey / database fields, BM25 language, server-side embedding model, and CA PEM path for HTTPS instances.
- [Seed historical conversations](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/13-seed-historical-conversations.md): Import conversation JSON via openclaw memory-tdai seed or POST /seed: input formats A/B, flags, config overrides, output directory layout, and L0→L1→L2→L3 execution path.
- [Secure the Gateway](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/14-secure-the-gateway.md): Optional TDAI_GATEWAY_API_KEY Bearer auth, TDAI_CORS_ORIGINS allow-list, non-loopback host warnings, and Hermes client MEMORY_TENCENTDB_GATEWAY_API_KEY alignment.
- [Plugin configuration reference](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/15-plugin-configuration-reference.md): Full memory-tencentdb config schema: field types, defaults, enums, validation rules (retention, embedding, llm, offload, tcvdb, bm25, report), and parseConfig behavior.
- [Agent tools](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/16-agent-tools.md): tdai_memory_search and tdai_conversation_search (OpenClaw) plus Hermes memory_tencentdb_* tool schemas: parameters, hybrid/embedding/keyword strategies, combined 3-call-per-turn limit, and response shapes.
- [Gateway HTTP API](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/17-gateway-http-api.md): TdaiGateway routes: GET /health, POST /recall, /capture, /search/memories, /search/conversations, /session/end, /seed — request and response fields, auth exceptions, and error envelope.
- [CLI reference](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/18-cli-reference.md): Package bin commands and OpenClaw memory-tdai namespace: migrate-sqlite-to-tcvdb, export-tencent-vdb, read-local-memory, seed flags, and memory-tencentdb-ctl subcommands.
- [Environment variables](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/19-environment-variables.md): Gateway, LLM, Hermes supervisor, install root, and data-dir env keys: TDAI_*, MEMORY_TENCENTDB_*, MODEL_*, resolution order for tdai-gateway.json, and client vs server API-key names.
- [Migrate SQLite to TCVDB](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/20-migrate-sqlite-to-tcvdb.md): Offline migrate-sqlite-to-tcvdb workflow: dry-run, layer selection (l0/l1/profile), TCVDB connection flags, config rewrite, manifest updates, and rollback-safe verification.
- [Gateway lifecycle](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/21-gateway-lifecycle.md): Operate the Node Gateway with memory-tencentdb-ctl: standalone vs hermes modes, start/stop/status/health/logs, config llm/embedding/vdb writes, and path layout under ~/.memory-tencentdb.
- [Inspect local memory](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/22-inspect-local-memory.md): Query L0–L3 artifacts with read-local-memory, export TCVDB collections with export-tencent-vdb, diagnostic export script, and on-disk layout (conversations, records, scene_blocks, persona, vectors.db).
- [Troubleshooting](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/23-troubleshooting.md): Source-backed failure modes: plugin disabled, no recall, embedding 400/matryoshka, retention cleanup, offload patch missing, Gateway circuit breaker, auth 401, and log/probe checklist.
- [Contributing](https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/pages/24-contributing.md): Local development with openclaw plugins install --link, build and test scripts, project layout, CI expectations, and contribution workflow from CONTRIBUTING.md.

## Source Files

- `.github/workflows/pr-ci.yml`
- `bin/migrate-sqlite-to-tcvdb.mjs`
- `bin/read-local-memory.mjs`
- `CHANGELOG.md`
- `CONTRIBUTING.md`
- `docker/opensource/Dockerfile.hermes`
- `docker/opensource/README-hermes.md`
- `hermes-plugin/memory/memory_tencentdb/__init__.py`
- `hermes-plugin/memory/memory_tencentdb/client.py`
- `hermes-plugin/memory/memory_tencentdb/plugin.yaml`
- `hermes-plugin/memory/memory_tencentdb/README.md`
- `hermes-plugin/memory/memory_tencentdb/supervisor.py`
- `hermes-plugin/memory/memory_tencentdb/tests/test_memory_tencentdb_recovery.py`
- `index.ts`
- `LICENSE`
- `openclaw.plugin.json`
- `package.json`
- `README.md`
- `scripts/bugfix-20260423/BUGFIX-20260423-SOP.md`
- `scripts/export-diagnostic.sh`
- `scripts/export-tencent-vdb/export-tencent-vdb.ts`
- `scripts/install_hermes_memory_tencentdb.sh`
- `scripts/memory-tencentdb-ctl.sh`
- `scripts/migrate-sqlite-to-tcvdb/cli-entry.ts`
- `scripts/migrate-sqlite-to-tcvdb/config-write.ts`
- `scripts/migrate-sqlite-to-tcvdb/manifest-write.ts`
- `scripts/migrate-sqlite-to-tcvdb/README.md`
- `scripts/migrate-sqlite-to-tcvdb/sqlite-to-tcvdb.ts`
- `scripts/openclaw-after-tool-call-messages.patch.sh`
- `scripts/read-local-memory/read-local-memory.ts`
- `scripts/README.memory-tencentdb-ctl.md`
- `scripts/setup-offload.sh`
- `SKILL-DIAGNOSTIC-EXPORT.md`
- `SKILL-MIGRATION.md`
- `SKILL.md`
- `src/adapters/index.ts`
- `src/adapters/openclaw/host-adapter.ts`
- `src/adapters/standalone/host-adapter.ts`
- `src/adapters/standalone/llm-runner.ts`
- `src/cli/commands/seed.ts`
- `src/cli/index.ts`
- `src/cli/README.md`
- `src/config.ts`
- `src/core/conversation/l0-recorder.ts`
- `src/core/persona/persona-generator.ts`
- `src/core/record/l1-extractor.ts`
- `src/core/report/reporter.ts`
- `src/core/scene/scene-extractor.ts`
- `src/core/seed/input.ts`
- `src/core/seed/seed-runtime.ts`
- `src/core/seed/types.ts`
- `src/core/store/bm25-local.ts`
- `src/core/store/embedding.ts`
- `src/core/store/factory.ts`
- `src/core/store/search-utils.ts`
- `src/core/store/sqlite.ts`
- `src/core/store/tcvdb-client.ts`
- `src/core/store/tcvdb.ts`
- `src/core/store/types.ts`
- `src/core/tdai-core.ts`
- `src/core/tools/conversation-search.ts`
- `src/core/tools/memory-search.ts`
- `src/core/types.ts`
- `src/gateway/config.ts`
- `src/gateway/server.ts`
- `src/gateway/types.ts`
- `src/offload/hooks/after-tool-call.ts`
- `src/offload/hooks/llm-input-l3.ts`
- `src/offload/index.ts`
- `src/offload/pipelines/l2-mermaid.ts`
- `src/offload/storage.ts`
- `src/offload/types.ts`
- `src/utils/ensure-hook-policy.ts`
- `src/utils/env.ts`
- `src/utils/manifest.ts`
- `src/utils/memory-cleaner.ts`
- `src/utils/no-think-fetch.ts`
- `src/utils/pipeline-factory.ts`
- `tsdown.config.ts`
- `vitest.config.ts`