# Installation

> Prerequisites (Node >= 22.16, OpenClaw >= 2026.3.13), npm package install, OpenClaw plugin install and update commands, 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-5a33bbf5540a
- Complete Markdown: https://grok-wiki.com/public/docs/tencentcloud-tencentdb-agent-memory-5a33bbf5540a/llms-full.txt

## Source Files

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

---

---
title: "Installation"
description: "Prerequisites (Node >= 22.16, OpenClaw >= 2026.3.13), npm package install, OpenClaw plugin install and update commands, and postinstall patch behavior."
---

`@tencentdb-agent-memory/memory-tencentdb` installs as an OpenClaw plugin (plugin id `memory-tencentdb`) or as a standalone npm package for Hermes Gateway layouts. Package metadata pins Node `>=22.16.0`, OpenClaw plugin API / gateway `>=2026.3.13`, and a `postinstall` hook that best-effort patches OpenClaw for context-offload message injection.

## Prerequisites

| Requirement | Constraint | Where declared |
| :--- | :--- | :--- |
| Node.js | `>= 22.16.0` | `package.json` `engines.node` |
| OpenClaw (in-process host) | `>= 2026.3.13` | `openclaw.compat.pluginApi` / `minGatewayVersion`, README, `SKILL.md` |
| npm / pnpm | Any current installer that can resolve the package | CONTRIBUTING / Hermes install paths |

Verify before install:

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

If either check fails, upgrade Node or OpenClaw first.

<Note>
`peerDependencies.openclaw` is listed as `>=2026.3.7` and marked optional so pure npm / Hermes installs do not hard-fail. For the OpenClaw plugin path, treat **`>=2026.3.13`** as the supported floor (`pluginApi` and `minGatewayVersion`).
</Note>

Optional peers (not required for basic install):

| Peer | Role |
| :--- | :--- |
| `openclaw` | Host when running as an OpenClaw plugin (optional peer) |
| `node-llama-cpp` | Optional local LLM path (`^3.16.2`) |

## Package identity

| Field | Value |
| :--- | :--- |
| npm name | `@tencentdb-agent-memory/memory-tencentdb` |
| Plugin id | `memory-tencentdb` |
| Command alias | `memory-tdai` |
| Entry (OpenClaw) | `./index.ts` via `package.json` `openclaw.extensions` |
| Main (published) | `./dist/index.mjs` |
| License | MIT |

Published layout includes `dist/`, `bin/`, `src/`, `hermes-plugin/`, `openclaw.plugin.json`, Gateway/control scripts (`scripts/memory-tencentdb-ctl.sh`, `scripts/install_hermes_memory_tencentdb.sh`), and the offload patch/setup scripts.

## Install paths

Choose the host surface you are targeting:

| Path | Use when |
| :--- | :--- |
| OpenClaw plugin install | Primary path: long-term memory hooks inside OpenClaw Gateway |
| npm package only | Hermes attach, tooling bins, or custom Gateway process layout |
| Linked local clone | Development (`openclaw plugins install --link .`) |

Hermes Docker / attach steps are documented on [Hermes setup](/hermes-setup). This page covers package acquisition and the OpenClaw install surface.

### OpenClaw plugin install

<Steps>
  <Step title="Install the plugin">
```bash
openclaw plugins install @tencentdb-agent-memory/memory-tencentdb
```
  </Step>
  <Step title="Restart the gateway">
```bash
openclaw gateway restart
```
  </Step>
  <Step title="Enable the plugin (zero-config minimum)">
Edit `~/.openclaw/openclaw.json`:

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

Defaults use local `SQLite + sqlite-vec`. Full enablement, data-dir signals, and optional offload slot registration are on [Quickstart](/quickstart).
  </Step>
</Steps>

### Update the OpenClaw plugin

Prefer the native OpenClaw updater. Semantic version ranges in ad-hoc package managers can leave the plugin disabled.

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

`SKILL.md` also accepts the short id form:

```bash
openclaw plugins update memory-tencentdb
```

Restart the gateway after update. If you use context offload, re-run the after-tool-call patch after upgrading OpenClaw itself (see below).

### npm package install (non-OpenClaw / Hermes layout)

For a standalone tree under `~/.memory-tencentdb` (Hermes attach pattern):

```bash
mkdir -p ~/.memory-tencentdb
TEMP_DIR=$(mktemp -d)
cd "$TEMP_DIR"
npm init -y --silent
npm install @tencentdb-agent-memory/memory-tencentdb@latest --omit=dev
cp -r node_modules/@tencentdb-agent-memory/memory-tencentdb \
      ~/.memory-tencentdb/tdai-memory-openclaw-plugin
rm -rf "$TEMP_DIR"

cd ~/.memory-tencentdb/tdai-memory-openclaw-plugin
npm install --omit=dev
npm install tsx
```

Automated variant: `scripts/install_hermes_memory_tencentdb.sh` (requires Hermes already installed, Node `>= 22`). Path defaults:

| Env | Default |
| :--- | :--- |
| `MEMORY_TENCENTDB_ROOT` | `~/.memory-tencentdb` |
| `TDAI_INSTALL_DIR` | `$MEMORY_TENCENTDB_ROOT/tdai-memory-openclaw-plugin` |
| `TDAI_DATA_DIR` | `$MEMORY_TENCENTDB_ROOT/memory-tdai` |

### Development link install

From a repository clone:

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

OpenClaw loads `.ts` sources at runtime on Node 22.16+ (type stripping). After edits, restart the gateway. Contribution workflow details: [Contributing](/contributing).

## postinstall patch behavior

`package.json` defines:

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

| Behavior | Detail |
| :--- | :--- |
| When it runs | After every npm/pnpm install of this package |
| Failure mode | Errors are swallowed (`2>/dev/null \|\| true`) so install succeeds without OpenClaw |
| Script | `scripts/openclaw-after-tool-call-messages.patch.sh` |
| Purpose | Inject `messages: ctx.params.session?.messages` into OpenClaw `after_tool_call` hook events so context-offload can read full tool-call history |

### What the patch does

1. Resolves the OpenClaw package root via `which openclaw`, pnpm shims, or common global module paths (nvm / npm / yarn / volta layouts).
2. Scans `$OPENCLAW_DIR/dist/**/*.js` for `after_tool_call` + `durationMs`.
3. Inserts session messages into the hook event object (four match strategies; first success wins).
4. Skips files already patched (idempotent).
5. Writes first-time backups as `*.pre-offload-patch.bak`.
6. Exits `0` if at least one file was patched or already skipped; exits `1` only when nothing matched.

Manual invocation (required after OpenClaw upgrades, or when postinstall could not find OpenClaw):

```bash
# Auto-detect OpenClaw install
bash scripts/openclaw-after-tool-call-messages.patch.sh

# Or pass the package root explicitly
bash scripts/openclaw-after-tool-call-messages.patch.sh /path/to/openclaw

# Debug matching
DEBUG=1 bash scripts/openclaw-after-tool-call-messages.patch.sh
```

Restart OpenClaw after a successful patch.

<Warning>
The patch is only required for **context offload** correctness (tool-result history on `after_tool_call`). Core L0→L3 long-term memory does not depend on it. Apply once per OpenClaw install; re-apply after upgrading OpenClaw.
</Warning>

Related enablement: set `offload.enabled`, register `plugins.slots.contextEngine: "memory-tencentdb"`, and optionally use `scripts/setup-offload.sh` — see [Enable context offload](/enable-context-offload).

## Install verification (OpenClaw)

After install + enable + `openclaw gateway restart`:

| Signal | Expected |
| :--- | :--- |
| Gateway logs | Lines with `[memory-tdai]` prefix |
| Data directory | `~/.openclaw/state/memory-tdai/` |
| Layout | At least `conversations/`, `records/`, `scene_blocks/`, `vectors.db` |
| Tools | `tdai_memory_search`, `tdai_conversation_search` available to the agent |

## Common install failures

| Symptom | Check |
| :--- | :--- |
| Plugin silent / no logs | `memory-tencentdb.enabled` is `true` in `~/.openclaw/openclaw.json`; gateway restarted |
| Plugin disabled after upgrade | Prefer `openclaw plugins update …` over range-based package upgrades |
| Offload cannot see tool history | Re-run `openclaw-after-tool-call-messages.patch.sh` after OpenClaw upgrade |
| `postinstall` did nothing | Expected when OpenClaw is not on PATH; run the patch script manually with an explicit path |
| Node too old | Upgrade to Node `>= 22.16.0` |
| OpenClaw too old | Upgrade to `>= 2026.3.13` for plugin API / gateway compatibility |

Broader runtime failures (recall, embedding, gateway auth): [Troubleshooting](/troubleshooting).

## Next

<CardGroup>
  <Card title="Quickstart" href="/quickstart">
    Enable the plugin, restart the gateway, and confirm data-dir success signals.
  </Card>
  <Card title="Hermes setup" href="/hermes-setup">
    Docker greenfield image or attach to an existing Hermes install.
  </Card>
  <Card title="Enable context offload" href="/enable-context-offload">
    Offload flags, contextEngine slot, and after-tool-call patch confirmation.
  </Card>
  <Card title="Configure OpenClaw" href="/configure-openclaw">
    Daily and advanced tuning groups after a working install.
  </Card>
  <Card title="Contributing" href="/contributing">
    Linked local install, build, and contribution workflow.
  </Card>
</CardGroup>