# Migrate from memory-tdai package

> Rename path from @tdai/memory-tdai to @tencentdb-agent-memory/memory-tencentdb: backup openclaw.json, uninstall old plugin, preserve ~/.openclaw/memory-tdai data, reinstall and verify.

- 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-MIGRATION.md`
- `package.json`
- `openclaw.plugin.json`
- `index.ts`
- `CHANGELOG.md`

---

---
title: "Migrate from memory-tdai package"
description: "Rename path from @tdai/memory-tdai to @tencentdb-agent-memory/memory-tencentdb: backup openclaw.json, uninstall old plugin, preserve ~/.openclaw/memory-tdai data, reinstall and verify."
---

Package rename migration for OpenClaw installs: replace npm package `@tdai/memory-tdai` (plugin id `memory-tdai`) with `@tencentdb-agent-memory/memory-tencentdb` (plugin id `memory-tencentdb`). Runtime data stays under `<openclawStateDir>/memory-tdai` (default `~/.openclaw/memory-tdai`). Uninstall removes the plugin config entry and **does not** delete that data directory. Log tag, CLI namespace, and tool names remain `memory-tdai` / `tdai_*` for compatibility.

## What changes and what stays

| Surface | Old | New / unchanged |
|---|---|---|
| npm package | `@tdai/memory-tdai` | `@tencentdb-agent-memory/memory-tencentdb` |
| Plugin id | `memory-tdai` | `memory-tencentdb` |
| `openclaw.json` entry key | `plugins.entries.memory-tdai` | `plugins.entries.memory-tencentdb` |
| Data directory | `~/.openclaw/memory-tdai/` | **Unchanged** (hard-coded basename `memory-tdai` under OpenClaw state dir) |
| Log prefix | `[memory-tdai]` | **Unchanged** |
| CLI namespace | `openclaw memory-tdai …` | **Unchanged** (`commandAliases: ["memory-tdai"]`) |
| Agent tools | `tdai_memory_search`, `tdai_conversation_search` | **Unchanged** |
| Context Engine slot | must match plugin id | `plugins.slots.contextEngine: "memory-tencentdb"` |
| Current package version (repo) | — | `0.3.6` in `package.json` |

```text
  Uninstall old plugin                    Install new package
  ─────────────────────                   ──────────────────
  openclaw plugins uninstall              openclaw plugins install
    memory-tdai                             @tencentdb-agent-memory/
                                            memory-tencentdb
           │                                         │
           │ removes plugins.entries.memory-tdai     │
           │                                         ▼
           │                              plugins.entries.memory-tencentdb
           │                                         │
           ▼                                         ▼
  ~/.openclaw/memory-tdai/  ────────────────────► same paths
    conversations/  records/  scene_blocks/
    vectors.db  persona.md  (.metadata / .backup)
```

<Warning>
Uninstalling `memory-tdai` **deletes** its `openclaw.json` configuration segment (including `embedding.apiKey`, models, retention). Always backup before uninstall. The on-disk memory tree is not removed by uninstall.
</Warning>

## When to use this migration

**Use when:**

- `openclaw plugins list` shows `memory-tdai` / `@tdai/memory-tdai` loaded
- `openclaw plugins install @tdai/memory-tdai` fails with 404 / not found
- You were told the old package name is retired

**Do not use when:**

- No memory plugin is installed yet — use a fresh install of `@tencentdb-agent-memory/memory-tencentdb` instead
- You only need SQLite → Tencent VectorDB data migration (separate tool `migrate-sqlite-to-tcvdb`)

### Prerequisites

| Requirement | Constraint |
|---|---|
| Node.js | `>= 22.16.0` (`package.json` `engines`) |
| OpenClaw plugin API / gateway | `>= 2026.3.13` (`package.json` `openclaw.compat`) |
| Peer OpenClaw (optional peer) | `>= 2026.3.7` |

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

## Identity map (config and runtime)

| Identifier | Value | Notes |
|---|---|---|
| New package name | `@tencentdb-agent-memory/memory-tencentdb` | npm / `openclaw plugins install` |
| New plugin id | `memory-tencentdb` | `openclaw.plugin.json` `"id"`; config key under `plugins.entries` |
| Old plugin id | `memory-tdai` | Uninstall target; old config key |
| CLI alias | `memory-tdai` | Still registered; seed commands stay `openclaw memory-tdai seed …` |
| Log tag | `[memory-tdai]` | Expected after successful migration |
| Data basename | `memory-tdai` | `path.join(openclawStateDir, "memory-tdai")` |
| State dir resolution | `runtime.state.resolveStateDir()` → `OPENCLAW_STATE_DIR` → `~/.openclaw` | |

Minimal enable shape after migration (flat form also used in README):

```json
{
  "memory-tencentdb": {
    "enabled": true
  }
}
```

OpenClaw host config used by uninstall/restore workflow is typically nested as:

```json
{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "enabled": true,
        "config": { }
      }
    }
  }
}
```

Restore whatever structure you backed up under the **new** plugin id key. Preserve nested `config` fields (`embedding`, `extraction`, `persona`, `capture`, `pipeline`, `recall`, `offload`, `storeBackend`, `tcvdb`, …) exactly.

## Migration procedure

<Steps>
<Step title="Confirm old plugin is installed">
```bash
openclaw plugins list | grep -i memory
```

Expect `memory-tdai` or `@tdai/memory-tdai` loaded. If nothing matches, skip this page and install `@tencentdb-agent-memory/memory-tencentdb` as a new install.
</Step>

<Step title="Backup plugin config (required)">
Uninstall removes the old entry. Extract and save it:

```bash
cat ~/.openclaw/openclaw.json | python3 -c "
import sys, json
cfg = json.load(sys.stdin)
plugins = cfg.get('plugins', {}).get('entries', {})
old_cfg = plugins.get('memory-tdai', {})
if old_cfg:
    print(json.dumps(old_cfg, indent=2, ensure_ascii=False))
    with open('/tmp/memory-tdai-config-backup.json', 'w') as f:
        json.dump(old_cfg, f, indent=2, ensure_ascii=False)
    print('\nConfig backed up to /tmp/memory-tdai-config-backup.json')
else:
    print('No memory-tdai entry found (may already use defaults only)')
"
```

Record these if present (restore failures usually start here):

| Config path | Why it matters |
|---|---|
| `embedding` (`provider`, `baseUrl`, `apiKey`, `model`, `dimensions`, `proxyUrl`, `sendDimensions`) | Incomplete quadruplet degrades vector search |
| `extraction.model` / `persona.model` | L1/L2/L3 model routing |
| `capture.excludeAgents` | Agent capture filter |
| `capture.l0l1RetentionDays` / `allowAggressiveCleanup` | Cleanup aggressiveness |
| `offload` + `plugins.slots.contextEngine` | Offload enable + slot id |
| `storeBackend` / `tcvdb` / `bm25` | Backend choice and remote VDB credentials |

<Warning>
`/tmp/memory-tdai-config-backup.json` may contain plaintext `apiKey` values. Restrict access; delete after a successful migration.
</Warning>
</Step>

<Step title="Inventory the data directory">
```bash
ls -la ~/.openclaw/memory-tdai/
```

Typical layout after use:

```text
~/.openclaw/memory-tdai/
├── conversations/     # L0 JSONL
├── records/           # L1 atoms
├── scene_blocks/      # L2 scenes
├── vectors.db         # sqlite-vec store (if storeBackend=sqlite)
├── persona.md         # L3 persona
├── .metadata/
└── .backup/
```

Capture pre-migration counts:

```bash
echo "=== pre-migration stats ==="
wc -l ~/.openclaw/memory-tdai/conversations/*.jsonl 2>/dev/null || echo "no conversations"
wc -l ~/.openclaw/memory-tdai/records/*.jsonl 2>/dev/null || echo "no records"
ls ~/.openclaw/memory-tdai/scene_blocks/*.md 2>/dev/null | wc -l | xargs -I{} echo "scene blocks: {}"
wc -c ~/.openclaw/memory-tdai/persona.md 2>/dev/null || echo "no persona"
```

If `OPENCLAW_STATE_DIR` is set, the data root is `$OPENCLAW_STATE_DIR/memory-tdai` instead of `~/.openclaw/memory-tdai`.
</Step>

<Step title="Uninstall the old plugin">
```bash
openclaw plugins uninstall memory-tdai
```

Verify:

| Check | Expected |
|---|---|
| `plugins.entries.memory-tdai` | Gone |
| `~/.openclaw/memory-tdai/` | Still present |

```bash
ls ~/.openclaw/memory-tdai/ && echo "data dir intact" || echo "data dir missing"
```
</Step>

<Step title="Install the new package">
```bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
```

For later updates, prefer:

```bash
openclaw plugins update @tencentdb-agent-memory/memory-tencentdb
```

Native OpenClaw install/update avoids disabling the plugin from loose semantic version ranges. Package `postinstall` runs `scripts/openclaw-after-tool-call-messages.patch.sh` (best-effort; failures are ignored).
</Step>

<Step title="Restore config under memory-tencentdb">
Write the backup to the **new** plugin id:

```bash
python3 -c "
import json, os

backup_path = '/tmp/memory-tdai-config-backup.json'
if os.path.exists(backup_path):
    with open(backup_path) as f:
        old_cfg = json.load(f)
    print('Restoring backup:')
    print(json.dumps(old_cfg, indent=2, ensure_ascii=False))
else:
    old_cfg = {'enabled': True}
    print('No backup found; writing minimal enabled config')

config_path = os.path.expanduser('~/.openclaw/openclaw.json')
with open(config_path) as f:
    cfg = json.load(f)

cfg.setdefault('plugins', {}).setdefault('entries', {})['memory-tencentdb'] = old_cfg

with open(config_path, 'w') as f:
    json.dump(cfg, f, indent=2, ensure_ascii=False)

print('Wrote plugins.entries.memory-tencentdb')
"
```

If the backup is missing, at least:

```json
{
  "plugins": {
    "entries": {
      "memory-tencentdb": {
        "enabled": true
      }
    }
  }
}
```

If you use context offload, ensure the slot points at the new id (not an old engine id):

```json
{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}
```

`registerContextEngine` / `setup-offload.sh` use `CONTEXT_ENGINE_ID=memory-tencentdb` so `openclaw doctor --fix` does not reset the slot against a mismatched plugin name.
</Step>

<Step title="Restart Gateway and verify">
```bash
openclaw gateway restart
```

| Signal | How to check | Pass criteria |
|---|---|---|
| Plugin loaded | `openclaw plugins list \| grep -i memory` | `memory-tencentdb` present |
| Runtime log tag | Gateway logs | Lines with `[memory-tdai]` (legacy tag is normal) |
| Data preserved | `wc -l` / `ls` under data dir | Matches pre-migration stats |
| Config present | `openclaw.json` | `plugins.entries.memory-tencentdb` (or flat `memory-tencentdb`) with `enabled: true` and restored nested settings |

```bash
echo "=== post-migration verify ==="
openclaw plugins list | grep -i memory
wc -l ~/.openclaw/memory-tdai/conversations/*.jsonl 2>/dev/null
wc -l ~/.openclaw/memory-tdai/records/*.jsonl 2>/dev/null
```
</Step>

<Step title="Smoke-test the memory path">
1. Send a turn that contains durable personal facts (preference, constraint, background).
2. Confirm Gateway logs show `[before_prompt_build]` / `[agent_end]` activity under `[memory-tdai]`.
3. Optionally call tools `tdai_memory_search` and `tdai_conversation_search`.
4. If embedding was configured, confirm no `[EMBEDDING CONFIG ERROR]` / incomplete-config degrade messages.
</Step>

<Step title="Clean sensitive backup">
```bash
rm -f /tmp/memory-tdai-config-backup.json
```
</Step>
</Steps>

## Compatible surfaces that keep old names

These intentionally retain `memory-tdai` branding so scripts and data stay stable:

| Surface | Identifier | Source behavior |
|---|---|---|
| On-disk plugin data | `…/memory-tdai` | `path.join(openclawStateDir, "memory-tdai")` |
| Log tag | `[memory-tdai]` | `const TAG = "[memory-tdai]"` in plugin entry |
| CLI | `openclaw memory-tdai seed …` | `commandAliases: ["memory-tdai"]` + CLI registration |
| Tools | `tdai_memory_search`, `tdai_conversation_search` | `openclaw.plugin.json` `contracts.tools` |
| SQLite migrate default data path | `--plugin-data-dir ~/.openclaw/memory-tdai` | migrate tool docs; `--plugin-id` default is already `memory-tencentdb` |
| Hermes / standalone data (non-OpenClaw) | `$MEMORY_TENCENTDB_ROOT/memory-tdai` (default `~/.memory-tencentdb/memory-tdai`) | Gateway config defaults; separate from OpenClaw plugin data |

<Note>
Seeing `[memory-tdai]` in logs after installing `memory-tencentdb` is expected, not a failed rename. Plugin **id** and **npm name** changed; log tag and data basename did not.
</Note>

## Rollback

If post-migration behavior is wrong and the old package is still reachable on npm:

```bash
openclaw plugins uninstall memory-tencentdb
openclaw plugins install @tdai/memory-tdai
# Restore /tmp/memory-tdai-config-backup.json under plugins.entries.memory-tdai
openclaw gateway restart
```

If the old package 404s, keep the new package installed, re-apply config from backup, and fix config keys rather than reinstalling the old id. Data under `memory-tdai/` remains the source of truth either way.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---|---|---|
| No plugin logs after restart | `memory-tencentdb.enabled` not true / wrong config key | Ensure `plugins.entries.memory-tencentdb` (or documented enable shape) has `enabled: true`; restart gateway |
| Install of old package 404 | Package renamed | Install `@tencentdb-agent-memory/memory-tencentdb` only |
| Install of new package fails | Registry / network | Check npm registry and connectivity |
| History missing after migrate | Config not restored; recall disabled; wrong data dir | Diff backup vs live config; confirm data path still has files; check `recall.enabled` |
| Embedding errors / keyword-only | Lost `apiKey` / `baseUrl` / `model` / `dimensions` | Restore full `embedding` block from backup |
| Empty data directory | Unexpected delete (rare) or wrong `OPENCLAW_STATE_DIR` | Locate actual state dir; do not recreate empty tree over a moved path |
| Offload / context engine inactive | Slot still points at old engine id | Set `plugins.slots.contextEngine` to `"memory-tencentdb"`; re-run after-tool-call patch if needed |
| `migrate-sqlite-to-tcvdb` writes wrong plugin id | Explicit old `--plugin-id` | Default is `memory-tencentdb`; pass that id when rewriting `openclaw.json` |

## Security notes

- Treat backup JSON as secret material (`embedding.apiKey`, `tcvdb.apiKey`, `llm.apiKey`, offload backend keys).
- Prefer not to paste full configs into chat; redact keys in support exports.
- Limit edits to the memory plugin entry and related slots; do not rewrite unrelated `plugins.entries`.
- Delete `/tmp/memory-tdai-config-backup.json` after verification.

## Definition of done

Migration is complete only when all of the following hold:

- [ ] `@tdai/memory-tdai` / plugin id `memory-tdai` uninstalled  
- [ ] `@tencentdb-agent-memory/memory-tencentdb` installed and listed as loaded  
- [ ] `openclaw.json` has full `memory-tencentdb` config (custom embedding and other overrides restored)  
- [ ] Gateway restarted  
- [ ] Logs show `[memory-tdai]`  
- [ ] `~/.openclaw/memory-tdai/` (or `$OPENCLAW_STATE_DIR/memory-tdai`) counts match pre-migration inventory  
- [ ] At least one conversation turn proves capture/recall path  
- [ ] Sensitive backup file removed  

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Fresh install, update, link-from-source, and postinstall patch behavior for the current package.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    Zero-config enable, gateway restart, log and data-dir success signals.
  </Card>
  <Card title="Data directories" href="/data-directories">
    Layout of `memory-tdai`, context-offload, and Hermes `MEMORY_TENCENTDB_ROOT` trees.
  </Card>
  <Card title="Migrate SQLite to Tencent VectorDB" href="/migrate-sqlite-tcvdb">
    Backend migration tool; uses data dir `memory-tdai` and default plugin id `memory-tencentdb`.
  </Card>
  <Card title="Enable context offload" href="/enable-offload">
    `offload.enabled`, `plugins.slots.contextEngine: memory-tencentdb`, and after-tool-call patch.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Full plugin config schema restored during migration (embedding, capture, pipeline, offload, …).
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Silent plugin, missing recall, embedding degrade, and recovery probes.
  </Card>
</CardGroup>