# CLI reference

> 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.

- 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

- `package.json`
- `src/cli/README.md`
- `src/cli/commands/seed.ts`
- `scripts/migrate-sqlite-to-tcvdb/cli-entry.ts`
- `scripts/export-tencent-vdb/export-tencent-vdb.ts`
- `scripts/read-local-memory/read-local-memory.ts`
- `scripts/README.memory-tencentdb-ctl.md`
- `bin/migrate-sqlite-to-tcvdb.mjs`

---

---
title: "CLI reference"
description: "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."
---

`@tencentdb-agent-memory/memory-tencentdb` ships three npm `bin` entry points, one OpenClaw CLI namespace (`openclaw memory-tdai`), and a non-bin ops shell script (`scripts/memory-tencentdb-ctl.sh`). Bins load prebuilt JS under `scripts/*/dist/`; the OpenClaw namespace is registered from the plugin via `api.registerCli()` and currently exposes only `seed`.

## Command map

| Surface | How to invoke | Role |
|---|---|---|
| `migrate-sqlite-to-tcvdb` | `npx migrate-sqlite-to-tcvdb …` or `npm run migrate-sqlite-to-tcvdb -- …` | Offline SQLite → Tencent VectorDB (TCVDB) migration |
| `export-tencent-vdb` | `npx export-tencent-vdb …` or `npm run export-tencent-vdb -- …` | Export TCVDB collections to JSONL |
| `read-local-memory` | `npx read-local-memory …` or `npm run read-local-memory -- …` | Inspect local L0–L3 data under a memory data dir |
| `openclaw memory-tdai seed` | OpenClaw CLI after plugin install | Seed historical conversation JSON through L0→L1→L2→L3 |
| `memory-tencentdb-ctl` | `scripts/memory-tencentdb-ctl.sh` (optional PATH symlink) | Gateway lifecycle + `tdai-gateway.json` config |

```text
Package bins (package.json "bin")
  bin/migrate-sqlite-to-tcvdb.mjs  → scripts/migrate-sqlite-to-tcvdb/dist/.../cli-entry.js
  bin/export-tencent-vdb.mjs       → scripts/export-tencent-vdb/dist/export-tencent-vdb.js
  bin/read-local-memory.mjs        → scripts/read-local-memory/dist/read-local-memory.js

OpenClaw plugin CLI
  index.ts → api.registerCli("memory-tdai") → registerMemoryTdaiCli() → seed

Ops script (shipped, not a bin)
  scripts/memory-tencentdb-ctl.sh
```

<Note>
Bin launchers require a prior build (`npm run build` / per-script `build:*`). If the dist file is missing, `export-tencent-vdb` and `read-local-memory` exit with a clear “precompiled artifact missing” message.
</Note>

## Prerequisites

| Tool | Requirement |
|---|---|
| Node | `>=22.16.0` (package `engines`) |
| OpenClaw | Plugin installed for `openclaw memory-tdai`; peer `openclaw >=2026.3.7`, compat `>=2026.3.13` |
| `memory-tencentdb-ctl` | `bash`, `python3`, `node`, `npx`, `lsof` or `ss` |

Build scripts before first bin use from a source checkout:

```bash
npm run build:scripts
# or individually:
npm run build:migrate-sqlite-to-vdb
npm run build:export-tencent-vdb
npm run build:read-local-memory
```

---

## `openclaw memory-tdai seed`

Registered under the `memory-tdai` Commander namespace (`commandAliases: ["memory-tdai"]` in `openclaw.plugin.json`). Description in code: seed historical conversation data into the memory pipeline (L0 → L1); the CLI README documents full L0→L1→L2→L3 execution via the seed runtime.

```bash
openclaw memory-tdai seed --input <file> [options]
```

### Flags

<ParamField body="--input" type="string" required>
Path to input JSON file (Format A object wrapper or Format B top-level array).
</ParamField>

<ParamField body="--output-dir" type="string">
Output directory for pipeline data. Default: `<stateDir>/memory-tdai-seed-<YYYYMMDD-HHmmss>` where `stateDir` is the OpenClaw state root (for example `~/.openclaw`).
</ParamField>

<ParamField body="--session-key" type="string">
Fallback session key when the input lacks one.
</ParamField>

<ParamField body="--config" type="string">
JSON config override file, two-level deep-merged on top of the current plugin config from `openclaw.json`.
</ParamField>

<ParamField body="--strict-round-role" type="boolean">
Require each conversation round to include both `user` and `assistant` messages. Default: `false`.
</ParamField>

<ParamField body="--yes" type="boolean">
Skip interactive confirmations (for example timestamp auto-fill). Default: `false`.
</ParamField>

### Behavior notes

- Missing timestamps: without `--yes`, prompts to fill with current time; with `--yes`, auto-fills.
- Existing non-empty `--output-dir`: exits with error. Checkpoint resume is **not** implemented; a directory with `.metadata/checkpoint.json` fails with a “use a new output directory” message.
- Progress is printed per round; a seed summary box reports sessions, rounds, messages, L0 count, and duration.

### Input shapes (summary)

| Format | Shape |
|---|---|
| A | `{ "sessions": [ { "sessionKey", "sessionId?", "conversations": message[][] } ] }` |
| B | Top-level array of the same session objects |

Message fields: `role` (`user` \| `assistant`), `content`, optional `timestamp` (epoch ms or ISO string).

### Config override merge

`--config` merges plain objects one level deep (sibling keys under each top-level group are shallow-merged; other values replace). Useful for aggressive pipeline timing or a dedicated TCVDB database during seed.

### Output layout

```text
<output-dir>/
├── conversations/     # L0 JSONL
├── records/           # L1 JSONL
├── scene_blocks/      # L2
├── vectors.db         # SQLite backend only
├── .metadata/
│   ├── manifest.json
│   └── checkpoint.json
└── .backup/
```

<RequestExample>
```bash title="Seed examples"
openclaw memory-tdai seed --input conversations.json
openclaw memory-tdai seed --input data.json --output-dir ./seed-output --strict-round-role
openclaw memory-tdai seed --input data.json --config ./seed-config.json --yes
```
</RequestExample>

For full formats and pipeline behavior, see [Seed historical conversations](/seed-history).

---

## `migrate-sqlite-to-tcvdb`

Offline migration of local SQLite (`vectors.db`) L0/L1/profile data into Tencent VectorDB, with optional rewrite of `openclaw.json` plugin config and data-dir `manifest.json`.

```bash
migrate-sqlite-to-tcvdb [options]
# or
npm run migrate-sqlite-to-tcvdb -- [options]
```

Stdout prints the migration summary as pretty-printed JSON. Logs go to stderr with tag `[memory-tdai][migrate]`.

### Required options

| Flag | Description |
|---|---|
| `--plugin-data-dir <path>` | Plugin data directory (for example `~/.openclaw/memory-tdai`) |
| `--openclaw-config-path <path>` | Path to `openclaw.json` |
| `--tcvdb-url <url>` | TCVDB HTTP base URL |
| `--tcvdb-username <name>` | TCVDB username |
| `--tcvdb-database <name>` | Target database name |
| `--tcvdb-embedding-model <name>` | Server-side embedding model |
| `--tcvdb-api-key <key>` **or** `--tcvdb-api-key-env <var>` | API key (mutually exclusive) |

### Optional options

| Flag | Default | Description |
|---|---|---|
| `--sqlite-path <path>` | `<plugin-data-dir>/vectors.db` | Source SQLite path |
| `--plugin-id <id>` | `memory-tencentdb` | Plugin ID written into config |
| `--layers <list>` | `l0,l1,l2,l3` | Comma-separated layers |
| `--tcvdb-alias <name>` | `""` | Optional alias |
| `--tcvdb-timeout-ms <ms>` | `10000` | Request timeout |
| `--tcvdb-ca-pem <path>` | — | CA PEM for HTTPS |
| `--bm25-language <zh\|en>` | `zh` | BM25 tokenization language |
| `--summary-json-path <path>` | — | Write summary JSON to file |
| `--job-id <id>` | — | Job id for tracking |

### Boolean flags (`node:util` allowNegative)

Defaults are all **true** for safety options unless noted:

| Flag | Default | Description |
|---|---|---|
| `--dry-run` | `false` | Preflight only; no writes |
| `--yes` | `false` | Skip interactive confirmation |
| `--no-apply-config` | apply = true | Do not update `openclaw.json` |
| `--no-config-backup` | backup = true | Skip config backup before write |
| `--no-rewrite-manifest` | rewrite = true | Do not update `manifest.json` |
| `--no-fail-if-target-nonempty` | fail if nonempty = true | Allow non-empty target |
| `--no-verify-counts` | verify = true | Skip post-migration count checks |
| `--no-bm25-enabled` | bm25 = true | Disable BM25 sparse vectors |

### Layer semantics

| Layer token | Migrated content |
|---|---|
| `l0` | L0 conversation rows from SQLite |
| `l1` | L1 memory records from SQLite |
| `l2` or `l3` | Local profiles via `listLocalProfiles` / `syncProfiles` (either token enables profile migration) |

Empty source (missing data dir or `vectors.db`, or zero counts) skips data migration and still can apply config/manifest depending on flags.

### Example

```bash
export TCVDB_API_KEY='...'

migrate-sqlite-to-tcvdb \
  --plugin-data-dir ~/.openclaw/memory-tdai \
  --openclaw-config-path ~/.openclaw/openclaw.json \
  --tcvdb-url http://127.0.0.1:80 \
  --tcvdb-username root \
  --tcvdb-api-key-env TCVDB_API_KEY \
  --tcvdb-database agent_memory_prod \
  --tcvdb-embedding-model bge-large-zh \
  --dry-run

migrate-sqlite-to-tcvdb \
  --plugin-data-dir ~/.openclaw/memory-tdai \
  --openclaw-config-path ~/.openclaw/openclaw.json \
  --tcvdb-url http://127.0.0.1:80 \
  --tcvdb-username root \
  --tcvdb-api-key-env TCVDB_API_KEY \
  --tcvdb-database agent_memory_prod \
  --tcvdb-embedding-model bge-large-zh \
  --layers l0,l1 \
  --yes
```

Workflow depth: [Migrate SQLite to TCVDB](/migrate-to-tcvdb).

---

## `export-tencent-vdb`

Connects to a Tencent VectorDB instance over HTTP and exports collection documents. Connection parameters are CLI-only (no `.env`).

```bash
export-tencent-vdb \
  --url <addr> --username <user> --api-key <key> --database <name> [options]
```

### Connection (required)

| Flag | Description |
|---|---|
| `--url` | VDB HTTP address (for example `http://host:8100`) |
| `--username` | Auth username (often `root`) |
| `--api-key` | Auth key |
| `--database` | Database name |

Auth header form: `Bearer account=<username>&api_key=<apiKey>`.

### Options

| Flag | Default | Description |
|---|---|---|
| `--timeout <ms>` | `30000` | Per-request timeout |
| `-o, --output <dir>` | `./vdb-export-YYYY-MM-DD` | Output directory |
| `-c, --collection <name>` | all | Exact collection name filter |
| `-f, --filter <expr>` | — | VDB filter expression |
| `-l, --limit <n>` | all | Max documents (`>= 1`) |
| `--offset <n>` | `0` | Start offset (`>= 0`) |
| `--include-vectors` | off | Include dense `vector` fields (default strips them) |
| `--probe` | off | Connectivity check + list collections, no export |
| `-h, --help` | — | Help |

`sparse_vector` is always exported. Page size is 100 documents.

### Output layout

```text
<outputDir>/
├── <collection>.jsonl
├── schemas.json
└── export-meta.json
```

```bash
export-tencent-vdb \
  --url "http://gz-vdb-xxx:8100" --username root --api-key "xxx" --database mydb \
  --probe

export-tencent-vdb \
  --url "http://gz-vdb-xxx:8100" --username root --api-key "xxx" --database mydb \
  -c mydb_l0_conversations -o /tmp/backup
```

---

## `read-local-memory`

Read-only inspection of a local memory data directory. L0/L1 come from `vectors.db` (`node:sqlite`, `PRAGMA query_only = ON`). L2 is `scene_blocks/*.md`; L3 is `persona.md`.

```bash
read-local-memory -d <data-dir> [options]
```

### Options

| Flag | Default | Description |
|---|---|---|
| `-d, --data-dir <path>` | required | Memory data dir (must resolve; overview needs `vectors.db`) |
| `-L, --level <L0\|L1\|L2\|L3>` | all (overview) | Single layer query |
| `--since <time>` | — | ISO or relative (`7d`, `24h`, `30m`, `60s`) |
| `--until <time>` | — | Same formats as `--since` |
| `-l, --limit <n>` | `50` | Page size (`>= 1`) |
| `--offset <n>` | `0` | Offset (`>= 0`) |
| `--sort <asc\|desc>` | `desc` | Sort direction |
| `-f, --filter <expr>` | — | Column filters, comma-separated (`type=persona`, `priority>=80`) |
| `--format <table\|json\|jsonl>` | `table` | Output format |
| `--file <name>` | — | L2 single-file detail (full body) |
| `-h, --help` | — | Help |

### Filter columns

| Level | Allowed columns (snake or camel aliases) |
|---|---|
| L0 | `record_id`, `session_key`, `session_id`, `role`, `message_text`, `recorded_at`, `timestamp` |
| L1 | `record_id`, `content`, `type`, `priority`, `scene_name`, `session_key`, `session_id`, `timestamp_str`, `timestamp_start`, `timestamp_end`, `created_time`, `updated_time`, `metadata_json` |

Time filters: L0 uses integer epoch `timestamp`; L1 uses ISO `updated_time`.

### Missing data behavior

| Situation | Behavior |
|---|---|
| No `vectors.db`, level L0/L1 | Empty result (JSON/table), exit 0 |
| No `vectors.db`, overview | Error exit |
| Missing `scene_blocks/` or `persona.md` | Empty / “not generated yet”, exit 0 |

```bash
read-local-memory -d ~/.openclaw/memory-tdai
read-local-memory -d ~/.openclaw/memory-tdai -L L0 --since 7d
read-local-memory -d ~/.openclaw/memory-tdai -L L1 -f 'type=persona' --format json
read-local-memory -d ~/.openclaw/memory-tdai -L L2 --file my-scene.md
```

Deeper layout notes: [Inspect local memory](/inspect-local-memory).

---

## `memory-tencentdb-ctl`

Bash ops controller for the standalone/Hermes Node Gateway. Published under `scripts/` but **not** registered as an npm `bin` (explicit PATH install is intentional).

```bash
# One-shot from install
"$(npm root)/@tencentdb-agent-memory/memory-tencentdb/scripts/memory-tencentdb-ctl.sh" --help

# Optional symlink
sudo ln -sf "$SCRIPT" /usr/local/bin/memory-tencentdb-ctl
```

### Modes

| Mode | Activation | Behavior |
|---|---|---|
| `standalone` (default) | no flag | Start/stop Gateway; write `$TDAI_DATA_DIR/tdai-gateway.json`; logs under `$TDAI_DATA_DIR/logs/` |
| `hermes` | `--hermes` or `MEMORY_TENCENTDB_MODE=hermes` | Same + LLM env under `$HERMES_HOME/env.d/`; logs under `$HERMES_HOME/logs/memory_tencentdb/`; enables `enable-hermes-memory` |

Default paths (overridable):

| Variable | Default |
|---|---|
| `MEMORY_TENCENTDB_ROOT` | `~/.memory-tencentdb` |
| `TDAI_INSTALL_DIR` | `$MEMORY_TENCENTDB_ROOT/tdai-memory-openclaw-plugin` |
| `TDAI_DATA_DIR` | `$MEMORY_TENCENTDB_ROOT/memory-tdai` |
| Gateway listen | `127.0.0.1:8420` (`MEMORY_TENCENTDB_GATEWAY_HOST` / `_PORT`) |

### Subcommands

| Command | Description |
|---|---|
| `start` | Background spawn; no-op if port already in use; waits for `/health` |
| `stop` | SIGTERM then SIGKILL after 5s |
| `restart` | stop + start |
| `status` | Mode, port, data/log paths, process state |
| `health` | GET `/health` via `python3` (no curl required) |
| `logs [out\|err\|all] [N=200]` | Tail logs |
| `config llm …` | Write `$.llm` (and hermes env file when `--hermes`) |
| `config embedding …` | Write `$.memory.embedding` |
| `config vdb …` | Write `$.memory.tcvdb` and usually `storeBackend=tcvdb` |
| `config vdb-off …` | Set `storeBackend=sqlite`; optional `--purge-creds` |
| `config show` | Print config with secrets redacted |
| `enable-hermes-memory` | Set Hermes `memory.provider` to `memory_tencentdb` (**hermes mode only**) |

### Global options

| Flag | Description |
|---|---|
| `--hermes` / `--standalone` | Select mode |
| `--dry-run` | Print planned writes; do not persist |
| `-h, --help` | Usage |

### Config write examples

```bash
memory-tencentdb-ctl config llm \
  --api-key "sk-..." --base-url "https://api.openai.com/v1" --model "gpt-4o" --restart

memory-tencentdb-ctl config embedding \
  --provider openai --api-key "sk-..." --base-url "https://api.openai.com/v1" \
  --model "text-embedding-3-small" --dimensions 1536 --restart

memory-tencentdb-ctl config embedding --provider none --restart

memory-tencentdb-ctl config vdb \
  --url "http://xxx:8100" --username root --api-key "..." --database "openclaw_memory" \
  --alias "primary" --embedding-model "bge-large-zh" --ca-pem "/etc/ssl/vdb-ca.pem" --restart

memory-tencentdb-ctl config vdb --url "..." --api-key "..." --database "..." --no-set-backend
memory-tencentdb-ctl config vdb-off --restart
memory-tencentdb-ctl config vdb-off --purge-creds --restart
memory-tencentdb-ctl config show
```

`config llm` JSON path: `$.llm.{baseUrl, apiKey, model}`.  
`config embedding` path: `$.memory.embedding.{provider, baseUrl, apiKey, model, dimensions, enabled, proxyUrl?}`.  
`config vdb` path: `$.memory.tcvdb.{url, username, apiKey, database, alias?, caPemPath?, embeddingModel?}` and typically `$.memory.storeBackend = "tcvdb"`.

### Exit codes

| Code | Meaning |
|---|---|
| `0` | Success |
| `1` | Bad args / validation (for example hermes-only command in standalone) |
| `2` | Write failure (disk/permissions) |
| `127` | Missing dependency (`python3` / `node` / `npx`) |

Ops guide: [Gateway lifecycle](/gateway-ops).

---

## Related npm scripts

| `package.json` script | Action |
|---|---|
| `build:scripts` | Compile migrate + export + read-local-memory |
| `migrate-sqlite-to-tcvdb` | `node ./bin/migrate-sqlite-to-tcvdb.mjs` |
| `export-tencent-vdb` | `node ./bin/export-tencent-vdb.mjs` |
| `read-local-memory` | `node ./bin/read-local-memory.mjs` |

Pass flags after `--` when using `npm run`:

```bash
npm run read-local-memory -- -d ~/.openclaw/memory-tdai -L L1 --format json
```

---

## Failure signals

| Symptom | Likely cause |
|---|---|
| Bin: “precompiled artifact missing” | Run the matching `npm run build:*` script |
| Seed: “Resume from checkpoint is not implemented” | Pick a fresh `--output-dir` |
| Seed: output dir not empty | Clean or choose another directory |
| Migrate: missing required option / both API key flags | Supply required flags; use only one of `--tcvdb-api-key` / `--tcvdb-api-key-env` |
| Export: list collection HTTP/code error | Wrong URL/credentials/database |
| `read-local-memory` overview exits 1 | `vectors.db` absent under `--data-dir` |
| `ctl enable-hermes-memory` fails | Not in hermes mode |
| `ctl` exit 127 | Install `node`/`npx`/`python3` |

---

## Related pages

<CardGroup>
  <Card title="Seed historical conversations" href="/seed-history">
    Input formats A/B, config overrides, and L0→L1→L2→L3 seed path.
  </Card>
  <Card title="Migrate SQLite to TCVDB" href="/migrate-to-tcvdb">
    Dry-run, layer selection, config rewrite, and verification.
  </Card>
  <Card title="Gateway lifecycle" href="/gateway-ops">
    standalone vs hermes modes, start/stop, and path layout.
  </Card>
  <Card title="Inspect local memory" href="/inspect-local-memory">
    On-disk layout and diagnostic export workflows.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    `TDAI_*`, `MEMORY_TENCENTDB_*`, and gateway config resolution.
  </Card>
  <Card title="Gateway HTTP API" href="/gateway-http-api">
    `/health`, `/seed`, and other Gateway routes used by ctl health checks.
  </Card>
</CardGroup>