TencentDB-Agent-Memory/openclaw-plugin/README.md

OpenClaw Adapter for TencentDB Agent Memory

简体中文 · English

This directory is a reference implementation for integrating an Agent framework with TencentDB Agent Memory v2 API. It is an OpenClaw client plugin: it does not run extraction, indexing, scene generation, or persona generation itself. Instead, it connects to an already-running Memory Gateway and uses the TypeScript SDK to capture conversations, recall memories, and expose memory tools to the Agent.

For standalone local usage, the recommended Memory Gateway endpoint is http://127.0.0.1:8420. The default local convention is apiKey = "local" and serviceId = "default". If your Gateway enables TDAI_GATEWAY_API_KEY, use the same value as server.apiKey.

Architecture

OpenClaw runtime
  └─ memory-tencentdb-client plugin
       ├─ hooks/capture.ts             agent_end -> addConversation (L0)
       ├─ hooks/recall.ts              before_prompt_build -> search + prompt injection
       ├─ tools/memory-search.ts       tdai_memory_search -> searchAtomic (L1)
       ├─ tools/conversation-search.ts tdai_conversation_search -> searchConversation (L0)
       └─ tools/read-cos.ts            tdai_read_cos -> read L2/L3 artifacts
            │
            ▼
       @tencentdb-agent-memory/memory-sdk-ts
            │ HTTP v2 API
            ▼
       TencentDB Agent Memory Gateway (:8420 standalone, or remote service)

Quick Start

Recommended: run the installer from the repository root:

bash scripts/install-openclaw-plugin-v2.sh

The script checks/installs the OpenClaw CLI, installs plugin dependencies, builds the plugin, and installs the current openclaw-plugin directory into OpenClaw through openclaw plugins install -l. By default it also updates ~/.openclaw/openclaw.json: it sets plugins.slots.memory = "memory-tencentdb-client", enables the plugin, and writes the standalone defaults for server, recall, and capture. The script auto-detects the OpenClaw version: on 2026.4.24+ it also writes hooks.allowPromptInjection / hooks.allowConversationAccess (required by non-bundled plugins to enable conversation capture); on older versions these fields are omitted, because gateways before 2026.4.24 use a strict zod schema that refuses to start with these fields present.

You can override defaults with environment variables: OPENCLAW_CONFIG_FILE, TDAI_MEMORY_ENDPOINT, TDAI_MEMORY_API_KEY, TDAI_MEMORY_INSTANCE_ID, TDAI_MEMORY_RECALL_MAX_RESULTS, and TDAI_MEMORY_CAPTURE_ENABLED. Set WRITE_OPENCLAW_CONFIG=0 if you only want to install the plugin without modifying OpenClaw config.

For manual installation, follow the steps below.

1. Install OpenClaw

If OpenClaw is not installed yet, install the OpenClaw CLI first:

curl -fsSL https://get.openclaw.dev | bash

Verify that the command is available:

openclaw --version

2. Install dependencies

cd openclaw-plugin
npm install

The plugin depends on @tencentdb-agent-memory/memory-sdk-ts, the TypeScript SDK for the v2 API.

3. Build

npm run build

4. Install the plugin into OpenClaw

For local source development, install the current directory as a linked plugin:

openclaw plugins install -l .

5. Configure the plugin

If you use the agentmemory/openclaw-memory container image, the entrypoint already generates this configuration for you, so you usually do not need to edit it manually.

If you use scripts/install-openclaw-plugin-v2.sh, the script writes this configuration by default as well, and version-gates the hooks.* policy fields automatically. You only need to edit the OpenClaw config yourself when running with WRITE_OPENCLAW_CONFIG=0 or when installing manually.

⚠️ Important — hooks.* is version-gated. The hooks.allowPromptInjection / hooks.allowConversationAccess fields were added to the gateway schema in OpenClaw 2026.4.24. Earlier versions (including 2026.4.23) use a strict zod schema and will refuse to start if these fields are present. Pick the example that matches your installed OpenClaw version. Run openclaw --version to check.

Example A — OpenClaw >= 2026.4.24 (recommended):

{
  "plugins": {
    "slots": {
      "memory": "memory-tencentdb-client"
    },
    "entries": {
      "memory-tencentdb-client": {
        "enabled": true,
        // hooks.* is REQUIRED on >= 2026.4.24 for non-bundled plugins.
        // Without allowConversationAccess=true, L0 capture is silently blocked.
        "hooks": {
          "allowPromptInjection": true,
          "allowConversationAccess": true
        },
        "config": {
          "server": {
            "url": "http://127.0.0.1:8420",
            "apiKey": "local",
            "instanceId": "default"
          },
          "recall": {
            "maxResults": 5,
            "includePersona": true,
            "includeSceneNav": true
          },
          "capture": {
            "enabled": true
          }
        }
      }
    }
  }
}

Example B — OpenClaw < 2026.4.24 (e.g. 2026.4.23): omit the hooks block entirely.

{
  "plugins": {
    "slots": {
      "memory": "memory-tencentdb-client"
    },
    "entries": {
      "memory-tencentdb-client": {
        "enabled": true,
        // ⚠️ DO NOT add a "hooks" block here. The strict schema in 2026.4.23 and
        // earlier rejects allowPromptInjection / allowConversationAccess and the
        // gateway will fail to start. Upgrade OpenClaw to use those fields.
        "config": {
          "server": {
            "url": "http://127.0.0.1:8420",
            "apiKey": "local",
            "instanceId": "default"
          },
          "recall": {
            "maxResults": 5,
            "includePersona": true,
            "includeSceneNav": true
          },
          "capture": {
            "enabled": true
          }
        }
      }
    }
  }
}

If the Gateway is protected by TDAI_GATEWAY_API_KEY, set server.apiKey to that value. server.instanceId is sent as x-tdai-service-id; standalone mode uses default.

hooks.allowPromptInjection allows before_prompt_build to inject recalled context. hooks.allowConversationAccess allows agent_end to read the raw conversation and write L0. Version compatibility:

• OpenClaw >= 2026.4.24 — these fields are recognised by the gateway schema. allowConversationAccess must be set to true for non-bundled plugins (otherwise conversation hooks are silently blocked and L0 capture stops working). allowPromptInjection defaults to allowed when unset; we still write true to lock the intent.
• OpenClaw < 2026.4.24 (including 4.23 and earlier) — the gateway uses a strict zod schema that rejects these fields. Do not include the hooks.* block at all, otherwise the gateway will fail to start. The installer script auto-detects the version and skips the block on older hosts.

6. Enable the plugin in OpenClaw

The plugin manifest ID is memory-tencentdb-client. The container image already wires it as the memory slot. If you install it manually, make sure OpenClaw loads the plugin and selects it for the memory slot. After changing the config, restart the Gateway:

openclaw gateway restart

Adapter Responsibilities

Area	Implementation	Description
Capture	src/hooks/capture.ts	Writes completed turns to L0 through addConversation()
Recall	src/hooks/recall.ts	Searches memories before prompt construction and injects concise context
L1 tool	src/tools/memory-search.ts	Lets the Agent actively search structured memories
L0 tool	src/tools/conversation-search.ts	Lets the Agent search raw conversation history
L2/L3 read tool	src/tools/read-cos.ts	Lets the Agent read scene/core artifacts when needed

Configuration

Field	Default	Description
server.url	http://127.0.0.1:8420	Memory Gateway URL
server.apiKey	""	Bearer token sent by the SDK. Use local for default standalone mode.
server.instanceId	default	Memory space ID, sent as x-tdai-service-id
recall.maxResults	5	Max L1 memories injected per turn
recall.includePersona	true	Whether to include L3 core/profile context
recall.includeSceneNav	true	Whether to include L2 scene navigation
capture.enabled	true	Whether to auto-capture completed turns
hooks.allowPromptInjection	true	Allows prompt-build context injection. Defaults to enabled when unset; we write true explicitly to lock the intent. Only write this field on OpenClaw >= 2026.4.24 — older gateways reject it with a strict schema.
hooks.allowConversationAccess	true	Allows agent_end / llm_input / llm_output to read raw conversation content for L0 writes. Required (true) for non-bundled plugins — without it, conversation hooks are silently blocked at registration and L0 capture stops working. Only write this field on OpenClaw >= 2026.4.24 — older gateways reject it with a strict schema.

Files

openclaw-plugin/
├── openclaw.plugin.json       # plugin manifest
├── package.json               # dependencies and build script
├── index.ts                   # OpenClaw entrypoint
├── src/hooks/capture.ts       # L0 capture hook
├── src/hooks/recall.ts        # recall hook
├── src/tools/                 # Agent-callable tools
└── src/format.ts              # prompt formatting helpers

Using This as an Adapter Template

When adapting another Agent framework, copy the same pattern:

1. Capture completed user/assistant turns and call addConversation().
2. Before the next prompt, call searchAtomic(), readCore(), and optionally listScenarios().
3. Inject only concise, labeled memory context into the Agent prompt.
4. Expose active tools for L1 search, L0 conversation search, and L2 scene read.
5. Keep the adapter stateless; the Memory Gateway owns storage and asynchronous L1/L2/L3 processing.

Notes

This plugin is a client-side adapter only. It should not start a Memory Gateway subprocess and should not implement memory extraction logic locally. For the standalone Gateway startup and SDK examples, see the root README.