# Installation

> Prerequisites (Node >= 22.16.0, OpenClaw >= 2026.3.13), openclaw plugins install/update, link-from-source development install, and postinstall patch behavior.

- 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

- `package.json`
- `openclaw.plugin.json`
- `SKILL.md`
- `CONTRIBUTING.md`
- `scripts/openclaw-after-tool-call-messages.patch.sh`
- `index.ts`

---

---
title: "Installation"
description: "Prerequisites (Node >= 22.16.0, OpenClaw >= 2026.3.13), openclaw plugins install/update, link-from-source development install, and postinstall patch behavior."
---

The OpenClaw host installs the published package `@tencentdb-agent-memory/memory-tencentdb` as plugin id `memory-tencentdb`. The package declares Node `engines.node` `>=22.16.0`, OpenClaw plugin compatibility `pluginApi` / `minGatewayVersion` `>=2026.3.13`, entry `openclaw.extensions` → `./index.ts` (built main `./dist/index.mjs`), and a `postinstall` that best-effort runs `scripts/openclaw-after-tool-call-messages.patch.sh` against the host OpenClaw install.

## Prerequisites

| Requirement | Constraint | Source of truth |
|---|---|---|
| Node.js | `>= 22.16.0` | `package.json` → `engines.node` |
| OpenClaw Gateway / plugin API | `>= 2026.3.13` | `package.json` → `openclaw.compat` (`pluginApi`, `minGatewayVersion`) and `openclaw.build` |
| OpenClaw peer (optional) | `openclaw` `>=2026.3.7` (optional peer) | `peerDependencies` / `peerDependenciesMeta` |
| Package manager | npm or pnpm (dev install) | Contributing docs |

Verify versions before installing:

```bash
node -v
openclaw --version
```

If either version is below the table, upgrade first. TypeScript source loading (link-from-source) relies on Node 22.16+ type stripping so OpenClaw can load `.ts` without a local build step.

<Note>
Plugin id is `memory-tencentdb`. Runtime log prefix, data-directory leaf, and CLI namespace remain legacy names: `[memory-tdai]`, `~/.openclaw/memory-tdai/`, and `openclaw memory-tdai …`.
</Note>

## Package identity

| Field | Value |
|---|---|
| npm package | `@tencentdb-agent-memory/memory-tencentdb` |
| Plugin id | `memory-tencentdb` |
| Manifest | `openclaw.plugin.json` (`id`, `name`, `commandAliases`, tools contracts) |
| CLI aliases | `memory-tdai` (`commandAliases` + `registerCli` in `index.ts`) |
| Registered tools | `tdai_memory_search`, `tdai_conversation_search` |
| Default store backend | `sqlite` (`sqlite-vec` + local files) |
| Activation | `activation.onStartup: true` |

Published bins (after install/build): `migrate-sqlite-to-tcvdb`, `export-tencent-vdb`, `read-local-memory`.

## Install on OpenClaw (release)

<Steps>
  <Step title="Install the plugin">
    Use the OpenClaw plugin CLI so the host registers the package and runs lifecycle hooks:

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

    Prefer this over a bare global `npm install` into an unrelated tree; the host plugin registry is what loads `memory-tencentdb` at gateway start.
  </Step>
  <Step title="Restart the gateway">
```bash
openclaw gateway restart
```
  </Step>
  <Step title="Enable (zero-config minimum)">
    Edit `~/.openclaw/openclaw.json` (or the path resolved by `OPENCLAW_CONFIG_PATH` / `OPENCLAW_STATE_DIR`):

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

    With only `enabled: true`, defaults apply: local SQLite backend, capture/extraction/recall on, offload off. Full schema lives under `openclaw.plugin.json` → `configSchema`.
  </Step>
  <Step title="Verify load">
    - Gateway logs contain the `[memory-tdai]` tag (plugin register / config parse).
    - Data root exists at `{stateDir}/memory-tdai` — usually `~/.openclaw/memory-tdai` (`resolveOpenClawStateDir` + `"memory-tdai"` in `index.ts`).
    - Expected subdirs after init: `conversations/`, `records/`, `scene_blocks/`, `.metadata/`, `.backup/` (`initDataDirectories`); vector file `vectors.db` appears once the sqlite store initializes.
  </Step>
</Steps>

### Update

Always update through OpenClaw’s plugin commands. That path avoids disabling the plugin when a semantic version range is rewritten by a generic package manager:

```bash
openclaw plugins update @tencentdb-agent-memory/memory-tencentdb
# equivalent short form used in setup skill:
openclaw plugins update memory-tencentdb
openclaw gateway restart
```

After OpenClaw itself is upgraded, re-run the after-tool-call patch (below) if you use context offload.

### Uninstall / rename path

Uninstalling removes plugin config entries from `openclaw.json` but does **not** delete `~/.openclaw/memory-tdai/`. Migrating from the old package `@tdai/memory-tdai` is a separate procedure; see [Migrate from memory-tdai package](/package-rename).

## Link-from-source (development)

No `npm run build` is required for day-to-day plugin development: Node 22.16+ strips types, and OpenClaw loads the extension path `./index.ts` from the package `openclaw.extensions` field.

```bash
git clone https://github.com/TencentCloud/TencentDB-Agent-Memory.git
cd TencentDB-Agent-Memory
npm install
openclaw plugins install --link .
openclaw gateway restart
```

| Step | Behavior |
|---|---|
| `npm install` | Installs dependencies; runs `postinstall` patch against the host OpenClaw install (best-effort). |
| `openclaw plugins install --link .` | Registers the current working tree as the live plugin. |
| Edit source | Restart gateway; linked tree is reloaded without reinstall. |
| `npm test` | `vitest run` (see contributing). |
| Packaging / bins | `npm run build` produces `dist/index.mjs` and script bins when publishing or using migrate/export CLIs. |

`package.json` `files` includes `src/`, `index.ts`, patch/setup scripts, `hermes-plugin/`, and `openclaw.plugin.json` for publish layouts.

## Postinstall patch behavior

### What runs

```json
"postinstall": "bash scripts/openclaw-after-tool-call-messages.patch.sh 2>/dev/null || true"
```

| Property | Behavior |
|---|---|
| Trigger | Every successful `npm install` of this package (including OpenClaw plugin install and local `npm install`). |
| Failure policy | stderr discarded; `|| true` so **install never fails** if OpenClaw is missing or patch strategies miss. |
| Manual re-run | `bash scripts/openclaw-after-tool-call-messages.patch.sh` or pass an explicit OpenClaw root: `bash scripts/openclaw-after-tool-call-messages.patch.sh /path/to/openclaw` |
| Debug | `DEBUG=1 bash scripts/openclaw-after-tool-call-messages.patch.sh` |

### Why it exists

Context offload needs the host `after_tool_call` hook event to include session messages. The script injects:

```js
messages: ctx.params.session?.messages
```

into OpenClaw’s compiled `dist/**/*.js` hookEvent construction after `durationMs`, so offload hooks can read the full tool history.

Long-term memory (L0–L3 capture/recall) does **not** require this patch. Offload does for correct tool-pair recovery.

### How the script finds OpenClaw

1. Optional CLI argument: explicit install directory.
2. Otherwise Node resolution: `which openclaw` → realpath / pnpm shim parse → walk up for `package.json` with `"name": "openclaw"`.
3. Fallback search under common global roots (`~/.local/share/pnpm`, `~/.local/node/lib/node_modules`, `/usr/local/lib/node_modules`, `/usr/lib/node_modules`).

Requires `$OPENCLAW_DIR/dist` to exist. Detected version is read from that package’s `package.json`.

### Patch strategies (first success wins, per file)

Candidates: all `dist/**/*.js` containing `after_tool_call` and an `after_tool_call`…`durationMs` context.

| Strategy | Target shape |
|---|---|
| 1 | `durationMs` then `};` then `hookRunnerAfter` / `runAfterToolCall` |
| 2 | Legacy `dispatch-*.js` with line-only `durationMs` |
| 3 | `durationMs` → `};` near `after_tool_call` without hookRunner anchor |
| 4 | Loose `hookEvent` / `hook_event` + `durationMs` fallback; restores `.pre-offload-patch.bak` if verify fails |

Idempotent: already-patched files are skipped. First backup per file: `*.pre-offload-patch.bak`.

Exit codes: `0` if any file patched or skipped as already patched; `1` if nothing matched.

### When to re-apply

- After upgrading OpenClaw (dist files are replaced).
- After a fresh OpenClaw install on a new machine path.
- If offload is enabled but tool pairs never land — verify injection with the patch script or `setup-offload.sh` (which hard-requires a successful patch).

Offload enablement (slot + `offload.enabled`) is documented under [Enable context offload](/enable-offload). One-shot helper: `scripts/setup-offload.sh --enable …` runs the same patch, then writes `plugins.slots.contextEngine` and offload config.

## Install surfaces outside OpenClaw

| Host | Install surface | Docs |
|---|---|---|
| Hermes Agent | Docker image, `scripts/install_hermes_memory_tencentdb.sh`, or copy/symlink `hermes-plugin/memory/memory_tencentdb` + Node Gateway sidecar | [Install on Hermes](/install-hermes) |
| Standalone Gateway | Package tree under `~/.memory-tencentdb/…` + `src/gateway/server.ts` | [Gateway control](/gateway-control), [Gateway HTTP API](/gateway-http-api) |

This page covers the OpenClaw plugin path only.

## Install graph

```text
  Node >= 22.16.0          OpenClaw >= 2026.3.13
           \                      /
            v                    v
   openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
            |
            +--> npm lifecycle: postinstall
            |         |
            |         v
            |   openclaw-after-tool-call-messages.patch.sh
            |         (best-effort; injects messages into after_tool_call)
            |
            v
   openclaw.plugin.json id=memory-tencentdb
   openclaw.extensions -> ./index.ts  (or dist/index.mjs when built)
            |
            v
   openclaw gateway restart
            |
            +--> register() in index.ts  log tag [memory-tdai]
            +--> pluginDataDir = {stateDir}/memory-tdai
            +--> tools: tdai_memory_search, tdai_conversation_search
```

## Troubleshooting install

| Symptom | Check |
|---|---|
| Plugin silent after install | `memory-tencentdb.enabled` is true; gateway restarted; `openclaw plugins list` shows the plugin loaded. |
| `npm install` succeeded but no patch | Expected when OpenClaw is not on PATH / not resolvable; run the patch script with an explicit path. Install exit is still 0. |
| Offload broken after OpenClaw upgrade | Re-run `scripts/openclaw-after-tool-call-messages.patch.sh`; confirm `plugins.slots.contextEngine` is `"memory-tencentdb"`. |
| Old package 404 / `@tdai/memory-tdai` | Use the rename migration; data under `~/.openclaw/memory-tdai/` is preserved. |
| Node too old | Engines require `>=22.16.0` (type stripping + runtime assumptions). |
| Looking for Hermes Docker / `install_hermes_memory_tencentdb.sh` | Wrong page — use [Install on Hermes](/install-hermes). |

## Next

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    Zero-config enable, gateway restart, `[memory-tdai]` success signals, and first `tdai_*` smoke checks.
  </Card>
  <Card title="Enable context offload" href="/enable-offload">
    Turn on `offload.enabled`, register `plugins.slots.contextEngine`, and confirm Mermaid injection after the postinstall patch.
  </Card>
  <Card title="Install on Hermes" href="/install-hermes">
    Hermes MemoryProvider paths, Gateway sidecar, and provider keys.
  </Card>
  <Card title="Migrate from memory-tdai package" href="/package-rename">
    Move from `@tdai/memory-tdai` to `@tencentdb-agent-memory/memory-tencentdb` without losing data.
  </Card>
  <Card title="Contributing" href="/contributing">
    Link install, vitest, build targets, and PR conventions.
  </Card>
  <Card title="Troubleshooting" href="/troubleshooting">
    Silent plugin, missing recall, offload slot/patch gaps, and recovery probes.
  </Card>
</CardGroup>