# Inspect local memory

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

- 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

- `scripts/read-local-memory/read-local-memory.ts`
- `scripts/export-tencent-vdb/export-tencent-vdb.ts`
- `scripts/export-diagnostic.sh`
- `SKILL-DIAGNOSTIC-EXPORT.md`
- `src/utils/pipeline-factory.ts`
- `src/utils/manifest.ts`
- `bin/read-local-memory.mjs`

---

---
title: "Inspect local memory"
description: "Query 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)."
---

The package ships three inspection surfaces: the `read-local-memory` CLI (read-only L0–L3 query over a local data directory), `export-tencent-vdb` (HTTP export of Tencent VectorDB collections), and `scripts/export-diagnostic.sh` (full OpenClaw + memory-tdai field dump with redacted config). Runtime data always lives under a directory named **`memory-tdai`** (historical path; the plugin package is `memory-tencentdb`).

## Data directory locations

| Host | Default data dir | Override |
|------|------------------|----------|
| OpenClaw plugin | `<stateDir>/memory-tdai` (usually `~/.openclaw/memory-tdai`) | `OPENCLAW_STATE_DIR` / host `resolveStateDir()` |
| Standalone Gateway / Hermes | `~/.memory-tencentdb/memory-tdai` | `TDAI_DATA_DIR`, `MEMORY_TENCENTDB_ROOT` |
| Legacy Gateway | `~/memory-tdai` if present and the new path does not exist | migrate or set env overrides |

`initDataDirectories()` creates `conversations/`, `records/`, `scene_blocks/`, `.metadata/`, and `.backup/` under the plugin data dir on startup.

## On-disk layout

```text
<memory-tdai data dir>/
├── conversations/          # L0 raw dialogue (daily JSONL shards)
├── records/                # L1 structured atoms (daily JSONL shards)
├── scene_blocks/           # L2 scene Markdown (*.md + META header)
├── persona.md              # L3 user persona
├── vectors.db              # SQLite: l0_conversations, l1_records, vectors, FTS
├── .metadata/
│   ├── manifest.json           # store binding (sqlite | tcvdb) + optional seed info
│   ├── recall_checkpoint.json  # capture/pipeline cursors and counters
│   └── scene_index.json        # L2 scene index
└── .backup/                # rolling backups before destructive LLM writes
```

| Path | Layer | Role |
|------|-------|------|
| `conversations/` | L0 | Append-only JSONL message capture |
| `records/` | L1 | Extracted memory atoms (JSONL) |
| `scene_blocks/*.md` | L2 | Scene profiles with `-----META-START-----` / `-----META-END-----` headers (`created`, `updated`, `summary`, `heat`) |
| `persona.md` | L3 | Aggregated persona body |
| `vectors.db` | L0/L1 index | Primary source for `read-local-memory` L0/L1 queries (`l0_conversations`, `l1_records`) |
| `.metadata/manifest.json` | ops | Store type (`sqlite` path or `tcvdb` url/database); written once |
| `.metadata/recall_checkpoint.json` | ops | Pipeline/runner progress |
| `.metadata/scene_index.json` | L2 | Scene index cache |

<Note>
JSONL under `conversations/` and `records/` is the file-layer write path. For inspection of indexed L0/L1 rows (filters, sort, pagination), use `vectors.db` via `read-local-memory`. L2 and L3 remain filesystem Markdown.
</Note>

## Query with `read-local-memory`

Package bin: `read-local-memory` → `bin/read-local-memory.mjs` → compiled `scripts/read-local-memory/dist/read-local-memory.js`.

Build once if the dist artifact is missing:

```bash
npm run build:read-local-memory
```

### Invocation

```bash
# After install of @tencentdb-agent-memory/memory-tencentdb
read-local-memory -d ~/.openclaw/memory-tdai

# From repo / package scripts
npm run read-local-memory -- -d ~/.openclaw/memory-tdai -L L0 --since 7d
npx tsx scripts/read-local-memory/read-local-memory.ts -d ./path/to/memory-tdai
```

### Flags

<ParamField body="data-dir" type="string" required>
Local `memory-tdai` directory (`-d`). Overview and L0/L1 modes expect `vectors.db` under this path.
</ParamField>

<ParamField body="level" type="L0 | L1 | L2 | L3">
`-L`. Omit for multi-layer overview (counts, role/type distributions, scene heat, persona size).
</ParamField>

<ParamField body="since" type="string">
Start time: ISO string or relative `Nd` / `Nh` / `Nm` / `Ns` (for example `7d`, `24h`).
</ParamField>

<ParamField body="until" type="string">
End time (same formats as `since`).
</ParamField>

<ParamField body="limit" type="number">
Page size (`-l`). Default `50`.
</ParamField>

<ParamField body="offset" type="number">
Pagination offset. Default `0`.
</ParamField>

<ParamField body="sort" type="asc | desc">
Time sort. Default `desc`. L0 sorts on `timestamp` (epoch ms); L1 on `updated_time` (ISO text).
</ParamField>

<ParamField body="filter" type="string">
`-f`. Comma-separated column predicates. Operators: `=`, `!=`, `>=`, `<=`, `>`, `<`. CamelCase or snake_case column names. Whitelisted columns only (parameterized SQL).
</ParamField>

<ParamField body="format" type="table | json | jsonl">
Default `table`.
</ParamField>

<ParamField body="file" type="string">
L2 only: return full body of one scene file by basename (for example `work.md`).
</ParamField>

### L0 / L1 filter columns

| Level | Filterable columns |
|-------|--------------------|
| 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` |

### Behavior by layer

| Mode | Source | Notes |
|------|--------|-------|
| Overview (no `-L`) | `vectors.db` + L2 dir + `persona.md` | Requires `vectors.db`; exits with error if missing |
| L0 | table `l0_conversations` | Time filter on epoch `timestamp`; maps to camelCase fields (`id`, `sessionKey`, `content`, …) |
| L1 | table `l1_records` | Time filter on `updated_time`; parses `metadata_json` |
| L2 | `scene_blocks/*.md` | No SQLite. List mode omits body in JSON (meta only). `--file` returns full body |
| L3 | `persona.md` | Missing file returns empty content (not an error) |

Missing `vectors.db` with `-L L0` or `-L L1` returns empty data (fresh install). Missing L2 directory or L3 file is treated as “not generated yet.”

### Examples

```bash
# Layer overview
read-local-memory -d ~/.openclaw/memory-tdai

# Recent L0 dialogue
read-local-memory -d ~/.openclaw/memory-tdai -L L0 --since 7d

# L1 persona-type atoms
read-local-memory -d ~/.openclaw/memory-tdai -L L1 -f 'type=persona'

# Paginated L0 page 2 (20 per page)
read-local-memory -d ~/.openclaw/memory-tdai -L L0 -l 20 --offset 20

# Machine-readable export
read-local-memory -d ~/.openclaw/memory-tdai -L L1 --format json

# Single L2 scene body
read-local-memory -d ~/.openclaw/memory-tdai -L L2 --file work.md
```

<RequestExample>
```bash
read-local-memory -d ~/.openclaw/memory-tdai -L L0 --since 7d --format json
```
</RequestExample>

<ResponseExample>
```json
{
  "level": "L0",
  "total": 128,
  "offset": 0,
  "limit": 50,
  "sort": "desc",
  "filter": null,
  "data": [
    {
      "id": "…",
      "sessionKey": "agent:main:main",
      "sessionId": "…",
      "role": "user",
      "content": "…",
      "recordedAt": "…",
      "timestamp": 1710000000000
    }
  ]
}
```
</ResponseExample>

SQLite is opened with `PRAGMA query_only = ON` (read-only inspection).

## Export TCVDB with `export-tencent-vdb`

Package bin: `export-tencent-vdb` → `bin/export-tencent-vdb.mjs`. Connects only to **Tencent VectorDB** over HTTP (built-in `fetch`; Node ≥ 18). Connection parameters are CLI flags only (no `.env` file).

```bash
npm run build:export-tencent-vdb   # if dist missing
export-tencent-vdb \
  --url "http://your-vdb-host:8100" \
  --username root \
  --api-key "$TCVDB_API_KEY" \
  --database mydb
```

### Connection parameters (required)

<ParamField body="url" type="string" required>
VDB HTTP base URL (trailing slash stripped).
</ParamField>

<ParamField body="username" type="string" required>
Auth account (for example `root`). Sent as `Authorization: Bearer account=…&api_key=…`.
</ParamField>

<ParamField body="api-key" type="string" required>
API key.
</ParamField>

<ParamField body="database" type="string" required>
Database name.
</ParamField>

### Export options

| Flag | Default | Purpose |
|------|---------|---------|
| `--timeout` | `30000` | Per-request timeout (ms) |
| `-o` / `--output` | `./vdb-export-YYYY-MM-DD` | Output directory |
| `-c` / `--collection` | all collections | Exact collection name |
| `-f` / `--filter` | none | Server-side document filter (VDB filter expression) |
| `-l` / `--limit` | all | Max documents |
| `--offset` | `0` | Start offset (page size 100) |
| `--include-vectors` | off | Include dense `vector` field (skipped by default) |
| `--probe` | off | Connectivity check + collection list; no export |
| `-h` / `--help` | | Help text |

`sparse_vector` (BM25) is always exported. Dense `vector` is omitted unless `--include-vectors` is set.

### Output layout

```text
<outputDir>/
├── <collection>.jsonl    # one JSON document per line
├── schemas.json          # /collection/describe per collection
└── export-meta.json      # exportedAt, url, database, filter, counts
```

### Probe first

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

Success prints collection names and document counts, then exits. Export uses `/collection/list`, `/collection/describe`, and paged `/document/query` with `readConsistency: "strongConsistency"`.

## Diagnostic field export

For support / debugging of OpenClaw + memory-tencentdb:

```bash
bash scripts/export-diagnostic.sh
# optional output base (default: ~/Downloads)
bash scripts/export-diagnostic.sh /tmp
```

### State dir resolution

1. `OPENCLAW_STATE_DIR` if set  
2. else `~/.openclaw` if it exists  
3. else `~/.clawdbot`  
4. else exit with error  

### Archive contents

Output: `<base>/openclaw-diagnostic-<timestamp>.tar.gz` (and an unpacked sibling directory).

| Entry | Contents | Privacy |
|-------|----------|---------|
| `env-info.txt` | OS, Node, OpenClaw version, tree listing, `du` for `memory-tdai` | Low |
| `logs/` | Gateway logs from `<stateDir>/logs/`; last 3 rolling `/tmp/openclaw/openclaw-*.log` files (tail 5000 lines each) | Low–medium |
| `memory-tdai/` | Full L0–L3 tree, `.metadata/`, `vectors.db`, optional `.backup/` | **High** (conversation text) |
| `openclaw-config-redacted.json` | Redacted `openclaw.json` | Low |
| `plugins-info.txt` | Extension package names/versions | Low |

### Config redaction rules

| Match | Replacement |
|-------|-------------|
| Keys matching `apiKey` / `token` / `password` / `secret` / `credential` (string values) | `***REDACTED(Nchars)***` |
| SecretRef objects (`source` / `provider` / `id`) | `id` redacted |
| Top-level `models`, `secrets`, `channels`, `env` | Whole section placeholder |
| `gateway.auth` token/password | Redacted |
| Remaining fields (including `plugins`) | Kept for diagnosis |

The archive is **local only** — nothing is uploaded. Review memory contents before sharing.

### Manual fallback

If the script cannot run, copy `logs/`, `memory-tdai/`, and a carefully redacted config into a temp dir and `tar -czf` yourself. Never send raw API keys.

## Inspection workflows

<Steps>
  <Step title="Confirm the data directory">
    ```bash
    ls -la "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/memory-tdai/"
    # Gateway / Hermes default
    ls -la "${TDAI_DATA_DIR:-$HOME/.memory-tencentdb/memory-tdai}/"
    ```
    Expect `conversations/`, `records/`, `scene_blocks/`, and optionally `vectors.db` / `persona.md`.
  </Step>
  <Step title="Overview and layer drill-down">
    ```bash
    read-local-memory -d ~/.openclaw/memory-tdai
    read-local-memory -d ~/.openclaw/memory-tdai -L L1 -f 'priority>=80' --format json
    read-local-memory -d ~/.openclaw/memory-tdai -L L2
    read-local-memory -d ~/.openclaw/memory-tdai -L L3
    ```
  </Step>
  <Step title="Check pipeline progress">
    Inspect `.metadata/recall_checkpoint.json` for capture cursors, L1/L2 session state, and persona request flags. Inspect `.metadata/manifest.json` for store backend (`sqlite` vs `tcvdb`).
  </Step>
  <Step title="TCVDB backend">
    If `manifest.store.type` is `tcvdb` (or config uses `storeBackend: tcvdb`), probe and export collections with `export-tencent-vdb` using the same url/database credentials as the runtime.
  </Step>
  <Step title="Bundle for support">
    ```bash
    bash scripts/export-diagnostic.sh
    ```
    Verify the printed `.tar.gz` path and size; confirm memory data may leave the machine before sending.
  </Step>
</Steps>

## Troubleshooting signals

| Symptom | Check |
|---------|--------|
| `SQLite 数据库不存在` on overview | No `vectors.db` yet — capture/index never ran, or wrong `-d` |
| Empty L0/L1 with `-L` | Fresh install or filters too tight; try overview without filters |
| L2 “尚未生成场景数据” | Pipeline has not produced scenes; check logs for `[pipeline]` |
| L3 “画像文件尚未生成” | Persona trigger/generator not completed; see checkpoint `last_persona_*` |
| `export-tencent-vdb` list failure | Wrong url/api-key/database; use `--probe` |
| Diagnostic script “未找到 OpenClaw 工作目录” | Set `OPENCLAW_STATE_DIR` or ensure `~/.openclaw` exists |
| Log search for runtime issues | `[memory-tdai]`, `[recall]`, `[pipeline]` (log tag remains `memory-tdai`) |

## Related pages

<CardGroup>
  <Card title="Memory layers" href="/memory-layers">
    What L0–L3 store and how L1→L2→L3 is scheduled.
  </Card>
  <Card title="Storage backends" href="/storage-backends">
    sqlite vs tcvdb, hybrid retrieval, and store factory rules.
  </Card>
  <Card title="CLI reference" href="/cli-reference">
    Full package bins and `openclaw memory-tdai` commands.
  </Card>
  <Card title="Use Tencent VectorDB" href="/use-tcvdb">
    Runtime `storeBackend: tcvdb` connection fields.
  </Card>
  <Card title="Migrate SQLite to TCVDB" href="/migrate-to-tcvdb">
    Offline migrate-sqlite-to-tcvdb workflow.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Plugin disabled, no recall, embedding errors, and probe checklist.
  </Card>
</CardGroup>