# Configure OpenClaw

> Enable the plugin in ~/.openclaw/openclaw.json, daily and advanced tuning groups (capture, pipeline, recall, persona), timezone, and verification after gateway restart.

- 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

- `src/config.ts`
- `openclaw.plugin.json`
- `README.md`
- `SKILL.md`
- `index.ts`
- `src/utils/ensure-hook-policy.ts`

---

---
title: "Configure OpenClaw"
description: "Enable the plugin in ~/.openclaw/openclaw.json, daily and advanced tuning groups (capture, pipeline, recall, persona), timezone, and verification after gateway restart."
---

OpenClaw loads `@tencentdb-agent-memory/memory-tencentdb` (plugin id `memory-tencentdb`, CLI alias `memory-tdai`) from `~/.openclaw/openclaw.json`. On gateway start, `register()` calls `parseConfig(api.pluginConfig)` and wires capture, extraction, pipeline, recall, persona, and optional embedding under `{stateDir}/memory-tdai` (default `~/.openclaw/memory-tdai`).

<Note>
Install the package first (`openclaw plugins install @tencentdb-agent-memory/memory-tencentdb`). Prerequisites: Node `>= 22.16`, OpenClaw `>= 2026.3.13`. See [Installation](/installation) and [Quickstart](/quickstart) for the zero-config path.
</Note>

## Prerequisites

| Requirement | Check |
| :--- | :--- |
| Plugin installed | `openclaw plugins install @tencentdb-agent-memory/memory-tencentdb` |
| OpenClaw / Node | `openclaw --version`, `node -v` |
| Config file | `~/.openclaw/openclaw.json`, or path from `OPENCLAW_CONFIG_PATH` / `$OPENCLAW_STATE_DIR/openclaw.json` |

## Enable the plugin

Minimal enable (all other fields use defaults from `parseConfig`):

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

OpenClaw may also store the entry under the plugins registry. The migration writer and hook-policy patch use this shape:

```jsonc
{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          // tuning groups go here — see below
        }
      }
    }
  }
}
```

Runtime reads **plugin config** as `api.pluginConfig` and passes it to `parseConfig`. Host `enabled` is an OpenClaw entry flag (outside `parseConfig`). Tuning groups (`capture`, `pipeline`, …) live in the plugin config object.

<Warning>
Config changes apply only after a gateway restart:

```bash
openclaw gateway restart
```
</Warning>

## Config model

`parseConfig({})` is valid. Groups and defaults are defined in `src/config.ts` and exposed in `openclaw.plugin.json`.

```text
openclaw.json
└── memory-tencentdb (or plugins.entries.memory-tencentdb)
    ├── enabled                 # host enable flag
    ├── hooks.allowConversationAccess  # capture hook gate (OpenClaw ≥ 2026.4.24)
    └── config / plugin fields  # parseConfig input
        ├── timezone
        ├── storeBackend          # "sqlite" | "tcvdb"
        ├── capture / extraction / persona / pipeline / recall
        ├── embedding / tcvdb / bm25 / llm / report / offload
        └── memoryCleanup       # derived from capture.l0l1RetentionDays + cleanTime
```

## Daily tuning

Use these for most production setups.

### Timezone

<ParamField body="timezone" type="string" default="system">
User/LLM-facing timestamps and local day boundaries. Accepts `"system"` (process TZ), IANA names (`Asia/Shanghai`, `Europe/Berlin`, `UTC`), or UTC offsets (`+08:00`, `-05:30`). Invalid values fall back to system TZ with a warning. Storage instants (SQLite/TCVDB) stay UTC.
</ParamField>

```json
{
  "memory-tencentdb": {
    "enabled": true,
    "timezone": "Asia/Shanghai"
  }
}
```

### Capture (L0)

| Field | Default | Description |
| :--- | :--- | :--- |
| `capture.enabled` | `true` | Register `agent_end` auto-capture |
| `capture.excludeAgents` | `[]` | Glob patterns; matched agents skip capture, recall, and pipeline |
| `capture.l0l1RetentionDays` | `0` | L0/L1 local TTL days; `0` = no cleanup |
| `capture.allowAggressiveCleanup` | `false` | Allow retention of 1–2 days |
| `capture.cleanTime` | `"03:00"` | Daily cleanup clock (`HH:mm`); invalid values fall back to `03:00` |

Retention rules:

- `l0l1RetentionDays <= 0` → cleanup disabled  
- `>= 3` → accepted  
- `1` or `2` → accepted only if `allowAggressiveCleanup: true`; otherwise treated as disabled  

### Extraction (L1)

| Field | Default | Description |
| :--- | :--- | :--- |
| `extraction.enabled` | `true` | Background L1 extraction |
| `extraction.enableDedup` | `true` | Smart dedup / conflict detection |
| `extraction.maxMemoriesPerSession` | `20` | Cap per L1 pass |
| `extraction.model` | *(host default)* | Optional `provider/model` |

### Pipeline (L1→L2→L3 schedule)

| Field | Default | Description |
| :--- | :--- | :--- |
| `pipeline.everyNConversations` | `5` | L1 every N conversation rounds |
| `pipeline.enableWarmup` | `true` | New sessions: 1→2→4→…→`everyN` |
| `pipeline.l1IdleTimeoutSeconds` | `600` | Idle seconds before L1 |
| `pipeline.l2DelayAfterL1Seconds` | `10` | Delay after L1 before L2 |
| `pipeline.l2MinIntervalSeconds` | `900` | Min gap between L2 runs (per session) |
| `pipeline.l2MaxIntervalSeconds` | `3600` | Max L2 poll interval for active sessions |
| `pipeline.sessionActiveWindowHours` | `24` | Stop L2 polling after this idle window |

### Recall

| Field | Default | Description |
| :--- | :--- | :--- |
| `recall.enabled` | `true` | `before_prompt_build` auto-recall |
| `recall.maxResults` | `5` | Max injected memories |
| `recall.maxCharsPerMemory` | `0` | Per-memory char cap; `0` = unlimited |
| `recall.maxTotalRecallChars` | `0` | Total L1 inject budget; `0` = unlimited |
| `recall.scoreThreshold` | `0.3` | Minimum score |
| `recall.strategy` | `"hybrid"` | `embedding` \| `keyword` \| `hybrid` (invalid → `hybrid`) |
| `recall.timeoutMs` | `5000` | On timeout, skip inject and log a warning |

### Persona (L2/L3)

| Field | Default | Description |
| :--- | :--- | :--- |
| `persona.triggerEveryN` | `50` | Persona generation every N new memories |
| `persona.maxScenes` | `15` | Max scene blocks |
| `persona.backupCount` | `3` | Persona backup count |
| `persona.sceneBackupCount` | `10` | Scene backup count |
| `persona.model` | *(host default)* | Optional `provider/model` |

### Recommended daily template

```json
{
  "memory-tencentdb": {
    "enabled": true,
    "timezone": "system",
    "capture": {
      "enabled": true,
      "excludeAgents": [],
      "l0l1RetentionDays": 90,
      "cleanTime": "03:00"
    },
    "extraction": {
      "enabled": true,
      "enableDedup": true,
      "maxMemoriesPerSession": 20
    },
    "pipeline": {
      "everyNConversations": 5,
      "enableWarmup": true,
      "l1IdleTimeoutSeconds": 600,
      "l2DelayAfterL1Seconds": 10,
      "l2MinIntervalSeconds": 900,
      "l2MaxIntervalSeconds": 3600,
      "sessionActiveWindowHours": 24
    },
    "recall": {
      "enabled": true,
      "maxResults": 5,
      "scoreThreshold": 0.3,
      "strategy": "hybrid",
      "timeoutMs": 5000
    },
    "persona": {
      "triggerEveryN": 50,
      "maxScenes": 15,
      "backupCount": 3,
      "sceneBackupCount": 10
    }
  }
}
```

## Advanced tuning (summary)

These groups are optional for day-to-day use; full field types and validation live in [Plugin configuration reference](/plugin-config-reference).

| Group | Role | Defaults (high level) |
| :--- | :--- | :--- |
| `storeBackend` | `sqlite` (default) or `tcvdb` | Local SQLite + sqlite-vec unless TCVDB is configured |
| `embedding` | Vector search (OpenAI-compatible remote) | `provider: "none"` → keyword-only; incomplete remote config disables vectors without crashing |
| `llm` | Standalone OpenAI-compatible LLM for L1/L2/L3 | `enabled: false` (uses host LLM) |
| `offload` | Context offload / short-term compression | `enabled: false` — see [Enable context offload](/enable-context-offload) |
| `bm25` | Sparse encoding (mainly TCVDB hybrid) | `enabled: true`, `language: "zh"` |
| `report` | Structured metric logs | `enabled: false`, `type: "local"` |

<Info>
Default embedding is off (`provider: "none"`). Hybrid recall then degrades to keyword paths. To enable vectors, set `apiKey`, `baseUrl`, `model`, and `dimensions` together. See [Configure embedding](/configure-embedding).
</Info>

## Hook policy auto-patch

On OpenClaw **≥ 2026.4.24**, non-bundled plugins need `plugins.entries.memory-tencentdb.hooks.allowConversationAccess: true` or `agent_end` capture is silently blocked.

On gateway start, when the host version is parseable and ≥ `2026.4.24`, the plugin:

1. Tries SDK `mutateConfigFile` (may restart the gateway automatically).
2. Falls back to writing `openclaw.json` and logging a restart requirement.
3. Skips auto-write if the config uses `$include` (manual edit required).

Manual verification:

```bash
python3 -m json.tool ~/.openclaw/openclaw.json | grep -A2 allowConversationAccess
```

Expected:

```text
"allowConversationAccess": true
```

under `plugins.entries.memory-tencentdb.hooks`.

## Restart and verification

<Steps>
  <Step title="Apply config">
    Edit `~/.openclaw/openclaw.json` (or `OPENCLAW_CONFIG_PATH`). Only change the `memory-tencentdb` entry / plugin config.
  </Step>
  <Step title="Restart gateway">
    ```bash
    openclaw gateway restart
    ```
  </Step>
  <Step title="Confirm plugin logs">
    Gateway logs should include `[memory-tdai]` lines. On successful parse you get a config summary such as `capture=…`, `recall=…`, `pipeline=(everyN=…)`, `persona(…)`, `memoryCleanup(…)`.
  </Step>
  <Step title="Confirm data directory">
    Default data root:

    ```text
    ~/.openclaw/memory-tdai/
    ├── conversations/
    ├── records/
    ├── scene_blocks/
    ├── .metadata/
    ├── .backup/
    ├── persona.md          # after L3 runs
    └── vectors.db          # after store init (sqlite backend)
    ```

    Override state root with `OPENCLAW_STATE_DIR`; the plugin still appends `memory-tdai`.
  </Step>
  <Step title="Smoke the memory path">
    1. Hold a 2–3 turn conversation with memorable preferences or constraints.  
    2. Start a new turn and check for auto-recall injection.  
    3. Call tools `tdai_memory_search` and `tdai_conversation_search`.  
  </Step>
</Steps>

### Success signals

| Signal | Expected |
| :--- | :--- |
| Log tag | `[memory-tdai]` present after restart |
| Config parse | Debug log lists capture/recall/pipeline/persona flags |
| Data dir | `~/.openclaw/memory-tdai/{conversations,records,scene_blocks}` created at register |
| Hook policy (new hosts) | `allowConversationAccess: true` in openclaw.json |
| Tools | `tdai_memory_search`, `tdai_conversation_search` available when capture or recall is enabled |

### Failure modes

| Symptom | Likely cause |
| :--- | :--- |
| No `[memory-tdai]` logs | Plugin not enabled or gateway not restarted |
| Capture never runs | Missing `allowConversationAccess` on OpenClaw ≥ 2026.4.24 |
| Capture/recall skipped for empty session | Empty `sessionKey` — plugin refuses unstable fallback keys |
| Records but no recall | `recall.enabled: false` or `scoreThreshold` too high |
| No vector hits | `embedding.provider` is `none` or remote four-tuple incomplete (`configError` logged) |
| Config ignored | Edited wrong file; confirm `OPENCLAW_CONFIG_PATH` / `OPENCLAW_STATE_DIR` |
| History thinned | `l0l1RetentionDays` + cleaner schedule (`cleanTime`) |

## Security notes

- Treat `embedding.apiKey`, `llm.apiKey`, `tcvdb.apiKey`, and offload backend keys as secrets; prefer env injection and placeholders in shared configs.
- Limit edits to the `memory-tencentdb` plugin entry so other OpenClaw plugins are not overwritten.
- `capture.excludeAgents` is the supported way to keep bench/judge agents out of the memory pipeline.

## Next

<CardGroup>
  <Card title="Plugin configuration reference" href="/plugin-config-reference">
    Full schema: types, defaults, enums, and parseConfig validation rules.
  </Card>
  <Card title="Configure embedding" href="/configure-embedding">
    OpenAI-compatible providers, dimensions, sendDimensions, and keyword-only degradation.
  </Card>
  <Card title="Enable context offload" href="/enable-context-offload">
    offload.enabled, contextEngine slot, after-tool-call patch, compression ratios.
  </Card>
  <Card title="Use Tencent VectorDB" href="/use-tcvdb">
    storeBackend tcvdb, required connection fields, BM25 language, CA PEM.
  </Card>
  <Card title="Agent tools" href="/agent-tools">
    tdai_memory_search and tdai_conversation_search parameters and limits.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Disabled plugin, no recall, embedding 400, retention, and hook policy failures.
  </Card>
</CardGroup>