# Quickstart

> Zero-config enable in openclaw.json, gateway restart, success signals ([memory-tdai] logs, data dir layout), and first smoke checks with tdai tools.

- 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-14fefdd76c97
- Complete Markdown: https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-14fefdd76c97/llms-full.txt

## Source Files

- `SKILL.md`
- `openclaw.plugin.json`
- `index.ts`
- `src/config.ts`
- `src/utils/pipeline-factory.ts`
- `README.md`

---

---
title: "Quickstart"
description: "Zero-config enable in openclaw.json, gateway restart, success signals ([memory-tdai] logs, data dir layout), and first smoke checks with tdai tools."
---

Zero-config OpenClaw enablement for `@tencentdb-agent-memory/memory-tencentdb` is: set plugin `enabled: true` in `~/.openclaw/openclaw.json`, restart the gateway, then confirm runtime via `[memory-tdai]` log lines and the on-disk tree under `~/.openclaw/memory-tdai/`. `parseConfig({})` supplies full defaults — capture, extraction, recall, and the L1→L2→L3 pipeline start without any embedding or offload keys.

## Prerequisites

| Requirement | Constraint |
| :--- | :--- |
| Node.js | `>= 22.16.0` |
| OpenClaw | `>= 2026.3.13` |
| Plugin package | `@tencentdb-agent-memory/memory-tencentdb` (plugin id `memory-tencentdb`) |
| Install | `openclaw plugins install @tencentdb-agent-memory/memory-tencentdb` (see [Installation](/installation)) |

```bash
openclaw --version
node -v
openclaw plugins list | grep -i memory
```

<Note>
CLI command alias remains `memory-tdai` (`openclaw.plugin.json` `commandAliases`). Log prefix is always `[memory-tdai]` even though the package id is `memory-tencentdb`.
</Note>

## Zero-config enable

Plugin config is empty-object safe: every field has a default. Minimal host enablement only needs the plugin entry switched on.

### 1. Write minimal `openclaw.json`

Edit `~/.openclaw/openclaw.json`. Prefer the OpenClaw `plugins.entries` shape used by migration tooling; the short form in the README is equivalent when OpenClaw maps it to the same entry.

<Tabs>
  <Tab title="plugins.entries (recommended)">
```json
{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "enabled": true
      }
    }
  }
}
```
  </Tab>
  <Tab title="Short form (README / SKILL)">
```json
{
  "memory-tencentdb": {
    "enabled": true
  }
}
```
  </Tab>
</Tabs>

With only `enabled: true`, the plugin receives an empty (or default) `pluginConfig` and `parseConfig` resolves:

| Surface | Default | Effect on first run |
| :--- | :--- | :--- |
| `storeBackend` | `sqlite` | Local `vectors.db` + FTS5 under the plugin data dir |
| `capture.enabled` | `true` | L0 JSONL on successful `agent_end` |
| `extraction.enabled` | `true` | Background L1 extraction |
| `recall.enabled` | `true` | Auto-recall on `before_prompt_build` |
| `recall.strategy` | `hybrid` | FTS + embedding when available; FTS-only when embedding is off |
| `embedding.provider` | `none` | Vector search disabled until a remote quadruplet is set |
| `offload.enabled` | `false` | Short-term context offload stays off |
| `pipeline.everyNConversations` | `5` | L1 batch cadence (warmup starts at 1) |

<Info>
Optional tuning (`capture`, `extraction`, `pipeline`, `recall`, `persona`, `embedding`, …) lives in the plugin config object passed to `api.pluginConfig` / `parseConfig` — not required for first light-up. Full schema: [Configuration reference](/configuration-reference).
</Info>

### 2. Restart the gateway

```bash
openclaw gateway restart
```

`register()` runs on full gateway start (not only `cli-metadata` mode). Restart is required after enable or config changes.

### 3. Confirm success signals

#### Gateway logs (`[memory-tdai]`)

Watch OpenClaw gateway logs for the plugin tag. Expected patterns after a healthy start and a short conversation:

| Phase | Example / signal | Meaning |
| :--- | :--- | :--- |
| Register | `[memory-tdai] Registering plugin ...` | Entry into full register path |
| Config | `[memory-tdai] Config parsed: capture=true, recall=true(...), extraction=true(...)` | Defaults applied |
| Data dir | `[memory-tdai] Data dir: <state>/memory-tdai (all subdirectories initialized)` | `initDataDirectories` ran |
| Complete | `[memory-tdai] Plugin registration complete (v3.1 — TdaiCore)` | Tools/hooks/CLI wired |
| Recall (turn) | `[memory-tdai] [before_prompt_build] Recall complete (...ms), ...` | Auto-recall path ran |
| Capture (turn) | `[memory-tdai] [agent_end] Auto-capture complete (...ms), l0Recorded=..., schedulerNotified=...` | L0 write + pipeline notify |
| Tools | `[memory-tdai] [tool] tdai_memory_search called/completed` | Agent tool used |

```bash
# Adjust log path to your OpenClaw install
grep '\[memory-tdai\]' ~/.openclaw/logs/* 2>/dev/null | tail -n 50
```

<Warning>
If there are **no** `[memory-tdai]` lines after restart, the host is not loading the plugin. Check `plugins.entries.memory-tencentdb.enabled` (or the short-form key), that the package is installed, then restart again. See [Troubleshooting](/troubleshooting).
</Warning>

#### Data directory layout

State root resolution order (`resolveOpenClawStateDir`):

1. Host `runtime.state.resolveStateDir()` when present  
2. `OPENCLAW_STATE_DIR`  
3. Fallback `~/.openclaw`

Plugin data dir:

```text
<path.join(stateDir, "memory-tdai")>
# default: ~/.openclaw/memory-tdai
```

On register, `initDataDirectories` creates:

:::files
~/.openclaw/memory-tdai/
├── conversations/     # L0 conversation JSONL
├── records/           # L1 atom records
├── scene_blocks/      # L2 scene Markdown
├── .metadata/         # checkpoints, instance_id
└── .backup/           # backup snapshots
:::

After store init (sqlite default), also expect:

| Path | When it appears | Role |
| :--- | :--- | :--- |
| `vectors.db` | SQLite store creation | FTS5 (+ vec0 when embedding dimensions &gt; 0) |
| `persona.md` | After L3 persona generation | L3 profile (not created on empty first boot) |
| `scene_blocks/*.md` | After L2 extraction | Scene blocks |

```bash
ls -la ~/.openclaw/memory-tdai/
# conversations/  records/  scene_blocks/  .metadata/  .backup/
# vectors.db may appear after core store init
```

<Check>
Shared data path name is intentionally still `memory-tdai` for compatibility with the former package. Uninstalling/reinstalling plugins does not wipe this tree.
</Check>

## Default runtime behavior (what “on” means)

```text
OpenClaw gateway
  └── memory-tencentdb register()
        ├── parseConfig → defaults
        ├── initDataDirectories(~/.openclaw/memory-tdai)
        ├── TdaiCore + OpenClawHostAdapter
        ├── tools: tdai_memory_search, tdai_conversation_search
        ├── hooks: before_prompt_build (recall), agent_end (capture)
        └── offload: only if offload.enabled
```

| Capability | Zero-config | Notes |
| :--- | :---: | :--- |
| L0 auto-capture | Yes | Skips failed turns (`agent_end` without `success`) |
| L1 / L2 / L3 pipeline | Yes | Uses host LLM unless `llm.enabled` |
| Auto-recall inject | Yes | Empty early on; grows as L0/L1 accumulate |
| Hybrid vector search | No | Needs remote `embedding` quadruplet |
| Context offload | No | Separate enable + slot + patch — [Enable context offload](/enable-offload) |

## First smoke checks

<Steps>
  <Step title="Conversation loop (L0 capture)">
    Hold 2–3 successful agent turns that include memorable facts (preferences, constraints, project names). After each success, expect:

    ```text
    [memory-tdai] [agent_end] Auto-capture complete (...ms), l0Recorded=<n>, schedulerNotified=...
    ```

    Verify L0 files:

    ```bash
    ls -la ~/.openclaw/memory-tdai/conversations/
    wc -l ~/.openclaw/memory-tdai/conversations/*.jsonl 2>/dev/null
    ```
  </Step>

  <Step title="Recall path (next turn)">
    Start a **new** turn that should need prior context. Logs should show `before_prompt_build` recall completion. Early sessions may inject little or no L1 until the pipeline extracts atoms; persona injection appears only after L3 has written `persona.md`.
  </Step>

  <Step title="Agent tools">
    In the agent session, invoke:

    | Tool | Purpose | Required param |
    | :--- | :--- | :--- |
    | `tdai_memory_search` | Search structured L1 memories | `query` |
    | `tdai_conversation_search` | Search raw L0 dialogue | `query` |

    Shared limit (tool descriptions): **combined 3 calls per turn** across both tools.

    Example tool parameters for L1 search:

    ```json
    {
      "query": "preferred timezone or coding style",
      "limit": 5
    }
    ```

    Optional filters on `tdai_memory_search`: `type` (`persona` | `episodic` | `instruction`), `scene`.

    Success signals:

    - Tool returns text results (or an empty ranked set with strategy name), not a hard registration error
    - Gateway debug: `[memory-tdai] [tool] tdai_memory_search completed (...ms): total=..., strategy=...`
    - Or L0: `[memory-tdai][tdai_conversation_search] RESULT (strategy=...)`

    <Tip>
    With default `embedding.provider = "none"`, search degrades to FTS/keyword paths. That is expected for zero-config. Configure remote embedding only when you need dense retrieval — [Configure storage backends](/configure-storage).
    </Tip>
  </Step>

  <Step title="Optional CLI presence check">
    Plugin CLI namespace:

    ```bash
    openclaw memory-tdai --help
    ```

    Seed of historical chats is a separate workflow: [Seed historical conversations](/seed-conversations).
  </Step>
</Steps>

### Smoke checklist

| Check | Pass criteria |
| :--- | :--- |
| Plugin entry | `memory-tencentdb` / package listed and enabled |
| Restart | Gateway restarted after config write |
| Logs | Any `[memory-tdai]` registration or turn logs |
| Data dir | `~/.openclaw/memory-tdai/{conversations,records,scene_blocks}` exist |
| Capture | `l0Recorded` &gt; 0 after successful turns, or growing JSONL under `conversations/` |
| Tools | At least one `tdai_*` call returns without tool-missing failure |

## Optional next configuration (not required for smoke)

### Recommended production groups

```json
{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "enabled": true,
        "config": {
          "capture": {
            "enabled": true,
            "excludeAgents": [],
            "l0l1RetentionDays": 90,
            "cleanTime": "03:00"
          },
          "extraction": {
            "enabled": true,
            "enableDedup": true,
            "maxMemoriesPerSession": 10
          },
          "pipeline": {
            "everyNConversations": 5,
            "enableWarmup": true,
            "l1IdleTimeoutSeconds": 600
          },
          "recall": {
            "enabled": true,
            "maxResults": 5,
            "scoreThreshold": 0.3,
            "strategy": "hybrid"
          },
          "embedding": {
            "enabled": true,
            "provider": "openai",
            "baseUrl": "https://api.openai.com/v1",
            "apiKey": "${EMBEDDING_API_KEY}",
            "model": "text-embedding-3-small",
            "dimensions": 1536
          }
        }
      }
    }
  }
}
```

Embedding rules:

- `provider = "none"` (default): no vectors; keyword/FTS only  
- Remote provider requires **all four**: `apiKey`, `baseUrl`, `model`, `dimensions`  
- Incomplete remote config logs `[memory-tdai] [EMBEDDING CONFIG ERROR] ...` and **degrades** without stopping the plugin  

Retention: `l0l1RetentionDays = 0` means no cleanup; non-zero values should be `>= 3` unless `allowAggressiveCleanup` is true.

### Short-term offload (separate switch)

Offload defaults to **off** and does not affect long-term memory. Enabling needs `offload.enabled`, `plugins.slots.contextEngine = "memory-tencentdb"`, and the after-tool-call patch — full procedure on [Enable context offload](/enable-offload).

## Quick failure probes

| Symptom | Probe |
| :--- | :--- |
| Silent plugin (no `[memory-tdai]` logs) | `enabled: true`? package installed? gateway restarted? |
| Capture never runs | Only successful turns capture; failed `agent_end` is skipped |
| No recall content | Wait for L1; check `recall.enabled` / high `scoreThreshold` |
| Tools missing | Tools register when `recall.enabled \|\| capture.enabled` (both true by default) |
| Vector empty / degrade | Incomplete embedding quadruplet → non-vector mode |
| Config change ignored | Confirm `~/.openclaw/openclaw.json` path, then `openclaw gateway restart` |

Broader matrix: [Troubleshooting](/troubleshooting).

## Definition of done

Treat first enable as complete when **all** hold:

1. Plugin install/update succeeded  
2. `openclaw.json` has `memory-tencentdb` enabled  
3. Gateway restarted  
4. `[memory-tdai]` logs visible  
5. `~/.openclaw/memory-tdai/` subdirs created  
6. At least one successful capture **or** tool search against local data  

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Prerequisites, plugins install/update, link-from-source, postinstall patch.
  </Card>
  <Card title="Memory layers" href="/memory-layers">
    L0 conversation → L1 atom → L2 scene → L3 persona producers and storage.
  </Card>
  <Card title="Agent tools" href="/agent-tools">
    `tdai_memory_search` / `tdai_conversation_search` parameters, strategies, RRF.
  </Card>
  <Card title="Data directories" href="/data-directories">
    Full on-disk trees for OpenClaw, offload, and Hermes roots.
  </Card>
  <Card title="Configure storage" href="/configure-storage">
    sqlite vs tcvdb, embedding quadruplets, BM25 language, store health.
  </Card>
  <Card title="Enable context offload" href="/enable-offload">
    Turn on short-term Mermaid offload after memory is healthy.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Silent plugin, no recall, embedding degrade, cleanup, offload slot issues.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Full schema: defaults, constraints, degrade rules.
  </Card>
</CardGroup>