# Quickstart
> Zero-config OpenClaw enable path: plugins install, openclaw.json memory-tencentdb.enabled, gateway restart, data-dir success signals, and optional offload slot registration.
- 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`
- `SKILL.md`
- `index.ts`
- `src/config.ts`
- `src/utils/pipeline-factory.ts`
- `openclaw.plugin.json`
---
---
title: "Quickstart"
description: "Zero-config OpenClaw enable path: plugins install, openclaw.json memory-tencentdb.enabled, gateway restart, data-dir success signals, and optional offload slot registration."
---
The OpenClaw path for `@tencentdb-agent-memory/memory-tencentdb` is install → set `memory-tencentdb.enabled` → restart the gateway. With no further plugin fields, the runtime uses a local `sqlite` store, turns on L0 capture / L1 extraction / auto-recall, keeps `embedding.provider` at `none` (keyword path only), and leaves context offload off until you opt in.
## Prerequisites
| Requirement | Constraint |
| :--- | :--- |
| Node.js | `>= 22.16.0` (`package.json` `engines`) |
| OpenClaw | Plugin API / gateway `>= 2026.3.13` (`openclaw.compat` / peer guidance) |
| Host config | Writable `~/.openclaw/openclaw.json` (or your `OPENCLAW_STATE_DIR` root) |
```bash
node -v
openclaw --version
```
Upgrade the host before installing the plugin if either check fails.
## Zero-config enable path
```bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
```
Prefer OpenClaw’s native update command for upgrades so the plugin is not disabled by semantic version ranges:
```bash
openclaw plugins update @tencentdb-agent-memory/memory-tencentdb
```
`postinstall` best-effort runs `scripts/openclaw-after-tool-call-messages.patch.sh` (failures are ignored). That patch is required for full context-offload behavior; long-term memory works without it.
Edit `~/.openclaw/openclaw.json` so the plugin is on:
```json
{
"memory-tencentdb": {
"enabled": true
}
}
```
Empty functional config is valid: `parseConfig({})` applies defaults. Host-level `enabled` is separate from nested feature toggles such as `capture.enabled` / `recall.enabled` / `offload.enabled`.
```bash
openclaw gateway restart
```
`register()` runs on gateway start (and on later reloads). It parses plugin config, creates `…/memory-tdai` data dirs, wires `TdaiCore` + `OpenClawHostAdapter`, registers tools/hooks, and optionally registers offload when `offload.enabled` is true.
Check logs and the data directory (next section). Then run 2–3 chat turns with memorable facts and, in a later turn, call `tdai_memory_search` / `tdai_conversation_search`.
## What runs with defaults
| Surface | Default | Behavior |
| :--- | :--- | :--- |
| `storeBackend` | `sqlite` | Local SQLite + sqlite-vec under the plugin data dir |
| `capture.enabled` | `true` | L0 conversation JSONL on `agent_end` |
| `extraction.enabled` | `true` | Background L1 atom extraction |
| `recall.enabled` | `true` | Auto-recall before prompt build (`hybrid`, `maxResults=5`, `scoreThreshold=0.3`) |
| `pipeline.everyNConversations` | `5` | L1 batch every N turns; warm-up starts at 1 and doubles to N |
| `pipeline.l1IdleTimeoutSeconds` | `600` | Idle L1 trigger |
| `embedding.provider` | `none` | No remote vectors; keyword / hybrid degrades without embeddings |
| `offload.enabled` | `false` | Context offload not registered |
| `llm.enabled` | `false` | L1/L2/L3 use the OpenClaw host model |
Plugin id: `memory-tencentdb`. Log tag: `[memory-tdai]`. CLI namespace: `memory-tdai` (via `commandAliases` / `openclaw memory-tdai …`).
## Data directory layout
State root:
```text
{OPENCLAW_STATE_DIR || ~/.openclaw}/memory-tdai/
```
Resolution order: host `runtime.state.resolveStateDir()` → env `OPENCLAW_STATE_DIR` → `~/.openclaw`.
On registration, `initDataDirectories` creates:
:::files
memory-tdai/
├── conversations/ # L0 JSONL
├── records/ # L1 JSONL
├── scene_blocks/ # L2 scene markdown
├── .metadata/ # instance_id, manifest, checkpoints
└── .backup/ # rolling backups
:::
After store init (sqlite backend), expect `vectors.db` in the same directory. `persona.md` appears after L3 persona generation, not at first install.
**Startup log markers** (debug/info, depending on host log level):
- `[memory-tdai] Registering plugin ...`
- `[memory-tdai] Data dir: …/memory-tdai (all subdirectories initialized)`
- `[memory-tdai] Plugin registration complete (v3.1 — TdaiCore). …`
Incomplete remote embedding config logs `[memory-tdai] [EMBEDDING CONFIG ERROR] …` and continues without vectors.
## Smoke test
1. Chat 2–3 turns with concrete preferences or constraints.
2. Start a new turn and watch for auto-recall injection (when memories exist and scores clear the threshold).
3. From the agent, call:
| Tool | Role |
| :--- | :--- |
| `tdai_memory_search` | Search L1 long-term memories |
| `tdai_conversation_search` | Search L0 conversation text |
Combined limit: **3 calls per turn** across both tools.
4. Confirm hits for content just captured (keyword path works without embedding).
## Optional: enable context offload
Offload is independent of long-term memory. Requires plugin **≥ 0.3.4** for the documented OpenClaw short-term path.
### 1 — Config
```json
{
"memory-tencentdb": {
"enabled": true,
"config": {
"offload": {
"enabled": true
}
}
}
}
```
Equivalent under the full OpenClaw tree: `plugins.entries.memory-tencentdb.config.offload.enabled = true` (what `scripts/setup-offload.sh` writes).
Default offload data dir: `~/.openclaw/context-offload` (override with `offload.dataDir`).
### 2 — Register the context-engine slot
```json
{
"plugins": {
"slots": {
"contextEngine": "memory-tencentdb"
}
}
}
```
Without this slot, OpenClaw does not route context-engine traffic to the plugin.
### 3 — Apply the after-tool-call messages patch
```bash
# From the installed package directory, or a clone that contains scripts/
bash scripts/openclaw-after-tool-call-messages.patch.sh
```
Idempotent per OpenClaw install. Re-run after upgrading OpenClaw. Injects `session.messages` into `after_tool_call` so offload can see tool history.
### 4 — Restart and verify
```bash
openclaw gateway restart
```
Expect offload registration logs when enabled: `Offload enabled, registering offload module...` / `Offload module registered successfully`.
For a scripted enable path with backend URL and user id, use `scripts/setup-offload.sh --enable …` (also sets `agents.defaults.compaction.mode` to `safeguard`). Full tuning: [Enable context offload](/enable-context-offload).
## Common failures
| Symptom | Check |
| :--- | :--- |
| No `[memory-tdai]` logs | `memory-tencentdb.enabled` is true; gateway restarted after edit |
| Config ignored | File is `~/.openclaw/openclaw.json` (or state dir override); nested fields under plugin `config` for entries-style layouts |
| Capture but no recall | `recall.enabled`, `scoreThreshold` not too high; enough L1 records exist |
| No vector hits | Default `embedding.provider=none` is keyword-only; configure embedding four-tuple when needed |
| Offload inactive | `offload.enabled`, `plugins.slots.contextEngine`, patch applied, gateway restart |
| Behavior stuck after edits | Restart gateway again; avoid overwriting unrelated plugin entries |
## Next
Daily and advanced tuning: capture, pipeline, recall, persona, timezone.
Slot registration, patch, compression ratios, Mermaid injection.
OpenAI-compatible providers, dimensions, sendDimensions, keyword-only degradation.
Docker or attach path when the host is Hermes instead of OpenClaw.
Prerequisites, npm/package install details, postinstall patch behavior.
Disabled plugin, no recall, embedding 400, offload patch, auth.