openclaw-memory-tencentdb-setup

Purpose

To provide OpenClaw with sustainable local long-term memory capabilities (L0→L1→L2→L3) without relying on an external managed memory service, and to complete a one-time closed loop from installation and configuration to acceptance.

Applicable Scenarios

• The user requests to install or enable in OpenClaw memory-tencentdb
• The user needs to configure parameters such as recall, extraction, profiling, and cleanup
• The user reports "the plugin is installed but there is no memory / no recall / no vector retrieval"

Inapplicable Scenarios

• The user only needs an explanation of the memory concept and does not require actual implementation
• The user wants to integrate with a non-OpenClaw host (first confirm the target framework)

Standard Workflow

1) Environment Precheck

First confirm that the base version meets the requirements:

• OpenClaw: >= 2026.3.13
• Node.js: >= 22.16.0

Execute:

openclaw --version
node -v

If the version does not meet the requirements, upgrade first before continuing.

2) Install the Plugin

Run the installation command:

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

If already installed, run the update:

openclaw plugins update memory-tencentdb

3) Write the Minimal Configuration

Edit ~/.openclaw/openclaw.json, ensuring the following exists:

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

Note: This plugin supports zero-configuration startup; basic capabilities can run without adding other fields.

4) Append Recommended Configuration as Needed (Common in Production)

Add the following groups according to user needs:

• capture: Conversation capture and retention policy
• extraction: L1 extraction and deduplication
• pipeline: L1→L2→L3 scheduling
• recall: Recall count, threshold, and strategy
• persona: Scenario and profile trigger parameters
• embedding: Vector retrieval configuration (remote OpenAI-compatible)

Recommended template:

{
  "memory-tencentdb": {
    "capture": {
      "enabled": true,
      "excludeAgents": [],
      "l0l1RetentionDays": 90,
      "cleanTime": "03:00"
    },
    "extraction": {
      "enabled": true,
      "enableDedup": true,
      "maxMemoriesPerSession": 10,
      "model": "provider/model"
    },
    "pipeline": {
      "everyNConversations": 5,
      "enableWarmup": true,
      "l1IdleTimeoutSeconds": 600,
      "l2DelayAfterL1Seconds": 10,
      "l2MinIntervalSeconds": 900,
      "l2MaxIntervalSeconds": 3600,
      "sessionActiveWindowHours": 24
    },
    "recall": {
      "enabled": true,
      "maxResults": 5,
      "scoreThreshold": 0.3,
      "strategy": "hybrid"
    },
    "persona": {
      "triggerEveryN": 50,
      "maxScenes": 15,
      "backupCount": 3,
      "sceneBackupCount": 10,
      "model": "provider/model"
    },
    "embedding": {
      "enabled": true,
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${EMBEDDING_API_KEY}",
      "model": "text-embedding-3-small",
      "dimensions": 1536,
      "conflictRecallTopK": 5
    }
  }
}

5) Key Configuration Rules (Avoid Hidden Failures)

• embedding.provider = "none" , the vector capability will be disabled, retaining only the keyword path.
• If configuring a remote provider(such as openai / deepseek), the following must also be provided:
  • apiKey
  • baseUrl
  • model
  • dimensions
• If any of the above is missing, the plugin will continue to run but automatically degrade to non-vector mode.
• l0l1RetentionDays：
  • 0 means no cleanup
  • Non- 0 when it is recommended to >=3
  • If set to 1~2, you must explicitly enable allowAggressiveCleanup

6) Restart and Verify It Takes Effect

Execute:

openclaw gateway restart

Check items:

• The Gateway log contains the [memory-tdai] prefix
• The data directory has been created:~/.openclaw/state/memory-tdai/
• At least includes:conversations/、records/、scene_blocks/、vectors.db

7) Functional Smoke Test

Run one minimal conversation loop and verify:

1. Have 2~3 consecutive conversation turns and provide memorable information (preferences, constraints, background).
2. Start a new round of conversation and observe whether recall context injection occurs.
3. Call in the Agent:
   • tdai_memory_search
   • tdai_conversation_search
4. Confirm that the content just generated can be retrieved.

Troubleshooting Quick Reference

• No plugin logs: Check openclaw.json in memory-tencentdb.enabled whether it is true, and confirm that the Gateway has been restarted.
• Records but no recall: Check recall.enabled、scoreThreshold whether it is too high.
• No vector results: Check embedding the quadruple (apiKey/baseUrl/model/dimensions) whether it is complete.
• Overly aggressive cleanup resulted in too little history: check l0l1RetentionDays and allowAggressiveCleanup。
• Configuration changed but behavior unchanged: confirm that what was modified is ~/.openclaw/openclaw.json, and restart the Gateway again.

Security and Compliance Constraints

• Treat apiKey as sensitive information; do not spread it in plaintext in chats, logs, or screenshots.
• Prefer injecting secrets via environment variables; keep only placeholders in configuration examples.
• Only modify the configuration section corresponding to memory-tencentdb , to avoid overwriting the user's other plugin configurations.

Definition of Done

Before ending the task, all of the following must be satisfied:

• The plugin install/update command executed successfully
• openclaw.json already has a valid memory-tencentdb configuration
• The Gateway has been restarted
• [memory-tdai] logs are visible
• The data directory and key files have been generated
• At least 1 retrieval tool call returned results successfully

Delivery Message Template

After completion, you may output to the user:

• Completed the installation and configuration of memory-tencentdb , and restarted the Gateway.
• Verified that the logs and data directory are in effect, and the memory pipeline is available.
• If further optimization is needed, you can continue tuning recall.scoreThreshold、pipeline.everyNConversations、persona.triggerEveryN and embedding model parameters.