tablestore-mem

tablestore-mem is an OpenClaw memory plugin backed by Alibaba Cloud TableStore memory APIs via [email protected].

It provides:

• Automatic retrieval before each turn through before_prompt_build with hidden system-context injection
• Automatic writeback after each successful run through agent_end
• Slash commands:
  • /tablestore-mem-search
  • /tablestore-mem-add
• CLI commands:
  • openclaw tablestore-mem search
  • openclaw tablestore-mem add
  • openclaw tablestore-mem doctor

Features

• Native OpenClaw memory slot plugin
• Minimal required configuration
• Automatic Beijing instance provisioning and reuse when instance config is omitted
• Shared instance.json reuse across CLI and conversation hooks
• Automatic memory store creation
• Hermes-style scope mapping adapted for OpenClaw
• Cross-agent and cross-run retrieval under the same tenant
• CLI for direct add/search verification
• CLI doctor command for diagnosing connection, memory store, and scoped memory listing

Requirements

• Node.js >=20
• OpenClaw >=2026.3.23
• Valid TableStore access key pair

Installation

Install from a local directory:

cd /root/openclaw/tablestore-mem
npm install
openclaw plugins install /root/openclaw/tablestore-mem
openclaw plugins enable tablestore-mem

For OpenClaw 2026.4.26+, if you want automatic writeback through agent_end, you must explicitly trust this non-bundled plugin to read conversation content:

{
  "plugins": {
    "entries": {
      "tablestore-mem": {
        "hooks": {
          "allowConversationAccess": true
        }
      }
    }
  }
}

This is an OpenClaw security policy flag, not a TableStore plugin business setting.

After publish, install from npm:

npm install -g @tablestore/openclaw-tablestore-memory

Or use it as a package source for your OpenClaw plugin deployment workflow.

Required Configuration

Only these two fields are required:

{
  "accessKeyId": "<your-ak>",
  "accessKeySecret": "<your-sk>"
}

Example OpenClaw config:

{
  "plugins": {
    "slots": {
      "memory": "tablestore-mem"
    },
    "entries": {
      "tablestore-mem": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "accessKeyId": "<your-ak>",
          "accessKeySecret": "<your-sk>"
        }
      }
    }
  }
}

Important:

• accessKeyId and accessKeySecret are still the only required plugin business configuration values.
• plugins.entries.tablestore-mem.hooks.allowConversationAccess=true is a separate OpenClaw trust flag required by OpenClaw 2026.4.26+ if you want the plugin's agent_end writeback hook to run.
• If you omit that flag, CLI commands and automatic retrieval through before_prompt_build still work, but automatic writeback after a conversation turn is blocked by OpenClaw.

Optional Configuration

These fields are optional:

• otsInstanceName: optional instance name override; if unset, the plugin auto-creates one managed instance in cn-beijing and reuses it later
• endpoint: optional endpoint override; if unset, the plugin derives https://<instance>.cn-beijing.ots.aliyuncs.com
• appId: optional override, defaults to openclaw
• tenantId: optional tenant override; if configured, it takes precedence over runtime session user identity
• memoryStoreName: defaults to openclaw_mem
• autoCreateMemoryStore: defaults to true
• writebackEnabled: defaults to true
• includeScores: defaults to true
• searchTopK: defaults to 5
• minQueryLength: defaults to 6
• enableRerank: defaults to true

If openclaw_mem does not exist, the plugin creates it automatically on first use.

If both otsInstanceName and endpoint are omitted, the plugin:

• creates a TableStore VCU instance in cn-beijing on first use through the control-plane CreateVCUInstance API
• waits for the instance status to become ready
• updates the instance ACL through UpdateInstance to enable public data-plane access
• waits for the data endpoint DNS to become resolvable before first data-plane use
• persists the created instanceName and derived endpoint under the local OpenClaw home
• reuses that same instance on later runs

Connection resolution priority:

1. If otsInstanceName is configured, use it.
2. If endpoint is also configured, use that endpoint.
3. If otsInstanceName is configured but endpoint is omitted, derive https://<otsInstanceName>.cn-beijing.ots.aliyuncs.com.
4. If only endpoint is configured and it matches https://<instance>.cn-beijing.ots.aliyuncs.com, parse the instance name from the endpoint and use it.
5. If otsInstanceName is omitted and no usable configured endpoint is available, read the persisted auto-created instance from $OPENCLAW_HOME/plugins/tablestore-mem/instance.json and wait for its endpoint to become usable.
6. If no persisted instance exists, create one in cn-beijing, persist it, wait for readiness, and use it.

When OPENCLAW_HOME is not set, OpenClaw home defaults to ~/.openclaw, so the auto-created instance state is stored at:

~/.openclaw/plugins/tablestore-mem/instance.json

Environment variable overrides:

• TABLESTORE_MEMORY_APP_ID
• TABLESTORE_MEMORY_TENANT_ID

Scope Design

The plugin follows the Hermes-style scope design, adapted for OpenClaw.

appId

• Source priority:
  1. plugin config appId or app_id
  2. TABLESTORE_MEMORY_APP_ID
• Default: openclaw

tenantId

• Source priority:
  1. plugin config tenantId or tenant_id
  2. TABLESTORE_MEMORY_TENANT_ID
  3. current OpenClaw session user_id, userId, or OpenAI-compatible user
• Default: __default__

agentId

• Source: OpenClaw runtime context
  • agent_identity
  • agentIdentity
  • agentId
  • derived from sessionKey if needed
• Default: openclaw

runId

• Source priority:
  1. gateway_session_key or gatewaySessionKey
  2. session_title or sessionTitle
  3. current sessionId
• Default: __default__

Read vs Write Scope

Writes preserve runtime agent/run identity. tenantId uses the configured tenant when set; otherwise it falls back to the current session user identity:

{
  "appId": "<configured-app-or-openclaw>",
  "tenantId": "<configured-tenant-or-current-user>",
  "agentId": "<runtime-agent>",
  "runId": "<runtime-session-identity>"
}

Reads intentionally search across all agents and runs under the same effective tenant:

{
  "appId": "<configured-app-or-openclaw>",
  "tenantId": "<configured-tenant-or-current-user>",
  "agentId": "*",
  "runId": "*"
}

This allows a memory written by one OpenClaw agent to be recalled by another agent under the same user scope.

CLI Usage

Add one memory:

openclaw tablestore-mem add "Alice likes jasmine tea" --uid alice

Search memory:

openclaw tablestore-mem search "what does Alice like" --uid alice

Show help:

openclaw tablestore-mem --help
openclaw tablestore-mem add --help
openclaw tablestore-mem doctor --help
openclaw tablestore-mem search --help

Without --uid, the CLI uses the default/global tenant scope and is mainly useful for maintenance or debugging.

The CLI uses the same connection resolution and instance.json reuse flow as the automatic OpenClaw hooks.

Doctor:

openclaw tablestore-mem doctor --uid alice

Doctor checks:

• resolved endpoint and otsInstanceName
• memory store existence and metadata through GetMemoryStore
• scoped memory listing through ListMemories
• a small sample of returned memories for quick inspection

On the first AK/SK-only run, doctor may take longer because it can create a new instance and wait for the endpoint DNS to become ready.

Doctor returns structured JSON so users can share the output for troubleshooting.

Slash Commands

Inside an OpenClaw session:

/tablestore-mem-add Alice likes jasmine tea
/tablestore-mem-search jasmine tea

Slash command search intentionally returns visible text because it is an explicit user command. Automatic retrieval uses hidden system context and is not printed into the visible session transcript.

OpenClaw Hook Trust

OpenClaw 2026.4.26+ treats some typed hooks as conversation-sensitive for non-bundled plugins.

For this plugin:

• before_prompt_build does not require allowConversationAccess
• agent_end does require allowConversationAccess

That means:

• retrieval can still work without the flag
• writeback will be blocked without the flag

Recommended config:

{
  "plugins": {
    "entries": {
      "tablestore-mem": {
        "enabled": true,
        "hooks": {
          "allowConversationAccess": true
        },
        "config": {
          "accessKeyId": "<your-ak>",
          "accessKeySecret": "<your-sk>"
        }
      }
    }
  }
}

How to verify:

openclaw plugins inspect tablestore-mem --json

Expected result when writeback is enabled:

• typedHooks contains both before_prompt_build and agent_end
• policy.allowConversationAccess is true
• diagnostics does not contain a warning about agent_end being blocked

Expected result when the trust flag is missing:

• before_prompt_build is still present
• agent_end is missing
• diagnostics contains a warning like: typed hook "agent_end" blocked because non-bundled plugins must set plugins.entries.tablestore-mem.hooks.allowConversationAccess=true

Runtime Behavior

Before prompt build:

• extracts the latest user prompt
• ensures the TableStore instance is resolved or auto-created
• waits for a newly auto-created instance to become ready before the first data-plane call
• ensures the memory store exists, creating openclaw_mem by default when missing
• searches TableStore memory using tenant-wide read scope
• calls SearchMemories with enableRerank=true by default
• injects matched memories into hidden system context
• does not print retrieved memories into the visible session transcript
• logs retrieval count and scope at debug level

After agent end:

• ensures the TableStore instance is resolved or auto-created
• reuses the same persisted instance.json state as CLI and retrieval hooks
• ensures the memory store exists, creating openclaw_mem by default when missing
• collects user/assistant messages from the completed turn
• writes them into TableStore using runtime write scope
• calls AddMemories with sync=false by default

OpenClaw 2026.4.26+ note:

• this agent_end path only runs when plugins.entries.tablestore-mem.hooks.allowConversationAccess=true
• if that trust flag is missing, OpenClaw blocks agent_end before the plugin can see conversation messages

The plugin does not call ListMemories as a fallback. Search results are exactly the results returned by SearchMemories; server-side scope filtering is trusted.

Verification

Plugin inspection:

openclaw plugins inspect tablestore-mem

Expected shape:

• Typed hooks: before_prompt_build, agent_end
• Commands: tablestore-mem-search, tablestore-mem-add
• CLI doctor: tablestore-mem doctor
• CLI commands: tablestore-mem

Syntax check:

npm run check

Package dry run:

npm run pack:check

Packaged-plugin cold-start smoke test:

npm run smoke:pack

This check is the new release gate for “fresh install but unusable” failures. It:

• runs npm pack
• installs the packed tarball into a brand new OpenClaw profile
• verifies the plugin loads from the packed artifact
• writes the minimal AK/SK config directly into that fresh profile
• verifies hooks, slash commands, and openclaw tablestore-mem CLI registration
• verifies doctor, add, and search subcommand help can start successfully

Optional live OpenClaw smoke test against a real TableStore environment:

TABLESTORE_MEM_LIVE_ACCESS_KEY_ID="<ak>" \
TABLESTORE_MEM_LIVE_ACCESS_KEY_SECRET="<sk>" \
npm run smoke:live

Optional live overrides:

• TABLESTORE_MEM_LIVE_ENDPOINT
• TABLESTORE_MEM_LIVE_OTS_INSTANCE_NAME
• TABLESTORE_MEM_LIVE_TENANT_ID

When TABLESTORE_MEM_LIVE_ENDPOINT and TABLESTORE_MEM_LIVE_OTS_INSTANCE_NAME are both omitted, npm run smoke:live exercises the AK/SK-only managed-instance path and verifies that a newly created instance.json is persisted and reused on the second doctor run.

Publishing

Pre-publish checklist:

1. Update version in package.json
2. Run npm install
3. Run npm run release:check
4. If you rely on the managed AK/SK-only path, run one live smoke: TABLESTORE_MEM_LIVE_ACCESS_KEY_ID=... TABLESTORE_MEM_LIVE_ACCESS_KEY_SECRET=... npm run smoke:live
5. If you want additional business validation, verify one real doctor, one real add, one real search

npm run release:check runs:

• npm run check
• npm run test
• npm run pack:check
• npm run smoke:pack

This means npm publish now fails before publish if the packed tarball cannot be installed into a clean OpenClaw profile or if the plugin fails to register its hooks and CLI after minimal configuration.

Publish:

npm publish

The package is configured for public publish under:

@tablestore/openclaw-tablestore-memory

Note:

• npm package names cannot use tablestore/openclaw-tablestore-memory directly
• the valid npm scoped package name is @tablestore/openclaw-tablestore-memory

Notes

• The plugin uses the TableStore Node SDK directly.
• It does not depend on message:preprocessed.
• It does not register model-callable memory tools.
• Retrieval uses SearchMemories results directly and does not perform ListMemories fallback.