TencentDB Agent Memory Documentation

Pages

1. OverviewWhat TencentDB Agent Memory exposes, host integration surfaces (OpenClaw plugin and Hermes Gateway), runtime assumptions, and the first docs routes to follow.
2. InstallationPrerequisites (Node >= 22.16, OpenClaw >= 2026.3.13), npm package install, OpenClaw plugin install and update commands, and postinstall patch behavior.
3. QuickstartZero-config OpenClaw enable path: plugins install, openclaw.json memory-tencentdb.enabled, gateway restart, data-dir success signals, and optional offload slot registration.
4. Hermes setupInstall and run memory_tencentdb with Hermes: Docker greenfield image, attach to existing Hermes, provider directory naming, Gateway auto-discovery, and health verification.
5. Memory layersRepo-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.
6. Context offloadSymbolic 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.
7. Storage backendssqlite (SQLite + sqlite-vec + FTS5) vs tcvdb store backends, BM25 sparse encoding, hybrid RRF retrieval, embedding service roles, and factory selection constraints.
8. TdaiCore and host adaptersHost-neutral TdaiCore facade, OpenClawHostAdapter vs StandaloneHostAdapter, LLM runner boundaries, and how in-process OpenClaw hooks map to Gateway HTTP handlers.
9. Configure OpenClawEnable the plugin in ~/.openclaw/openclaw.json, daily and advanced tuning groups (capture, pipeline, recall, persona), timezone, and verification after gateway restart.
10. Enable context offloadTurn on offload.enabled, register plugins.slots.contextEngine, apply the after-tool-call messages patch, tune compression ratios, and confirm Mermaid injection paths.
11. Configure embeddingOpenAI-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.
12. Use Tencent VectorDBSwitch storeBackend to tcvdb, required tcvdb.url / apiKey / database fields, BM25 language, server-side embedding model, and CA PEM path for HTTPS instances.
13. Seed historical conversationsImport 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.
14. Secure the GatewayOptional TDAI_GATEWAY_API_KEY Bearer auth, TDAI_CORS_ORIGINS allow-list, non-loopback host warnings, and Hermes client MEMORY_TENCENTDB_GATEWAY_API_KEY alignment.
15. Plugin configuration referenceFull memory-tencentdb config schema: field types, defaults, enums, validation rules (retention, embedding, llm, offload, tcvdb, bm25, report), and parseConfig behavior.
16. Agent toolstdai_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.
17. Gateway HTTP APITdaiGateway routes: GET /health, POST /recall, /capture, /search/memories, /search/conversations, /session/end, /seed — request and response fields, auth exceptions, and error envelope.
18. CLI referencePackage bin commands and OpenClaw memory-tdai namespace: migrate-sqlite-to-tcvdb, export-tencent-vdb, read-local-memory, seed flags, and memory-tencentdb-ctl subcommands.
19. Environment variablesGateway, 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.
20. Migrate SQLite to TCVDBOffline migrate-sqlite-to-tcvdb workflow: dry-run, layer selection (l0/l1/profile), TCVDB connection flags, config rewrite, manifest updates, and rollback-safe verification.
21. Gateway lifecycleOperate 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.
22. Inspect local memoryQuery 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).
23. TroubleshootingSource-backed failure modes: plugin disabled, no recall, embedding 400/matryoshka, retention cleanup, offload patch missing, Gateway circuit breaker, auth 401, and log/probe checklist.
24. ContributingLocal development with openclaw plugins install --link, build and test scripts, project layout, CI expectations, and contribution workflow from CONTRIBUTING.md.