How to Equip Your OpenClaw Agent with Local Memory in 10 Minutes

How to Equip Your OpenClaw Agent with Local Memory in 10 Minutes

I'm Zhou Xiaoma.

Have you ever experienced this: every time you start a new Agent session, you have to re-explain the project background, output formats, and team SOPs from scratch. The Agent doesn't remember your preferences from last week or the endpoint address you confirmed yesterday. You're forced to repeatedly input the same context, burning through tokens rapidly while draining your energy.

The issue isn't that Agents aren't smart enough; it's that most Agent frameworks natively rely on memory mechanisms that are flat and short-lived. They either stuff a few conversation rounds into the context window and get pushed out, or dump fragmented chats into a vector database, making retrieval hit-or-miss.

Today, I'll guide you through a trending open-source solution: TencentDB-Agent-Memory (5,791 ⭐). It is a completely local, zero external API dependency memory plugin for Agents. Once installed, your Agent will automatically learn your workflows, remember your preferences, and even compress hundreds of thousands of tokens of tool logs from long-running tasks into a lightweight Mermaid flowchart—reducing token consumption by up to 61% in official tests.

By the end of this guide, you will have hands-on local long-term memory capabilities integrated into your OpenClaw Agent, from installation to real-world application in under 10 minutes. Let's dive in.

Prerequisites

Before we begin, verify two things:

1. Node.js >= 22.16: The project relies on newer Node.js features and will not run on older versions.
2. OpenClaw Installed: This tutorial uses OpenClaw as the host Agent framework. If you are using Hermes, the README also provides complete Docker and source-code integration guides.

If you haven't installed OpenClaw yet, please install it according to the official documentation. This guide assumes you already have a working OpenClaw environment.

Step 1: Install the Plugin

Open your terminal and run a single command:

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

Why restart the gateway? The plugin requires the OpenClaw gateway process to reload to take effect. The official documentation strictly advises using this native command for installation and upgrades. Do not install directly via npm, as semantic versioning ranges might unexpectedly disable the plugin.

The plugin itself is only a few dozen MB. Once installed, you'll see a memory-tencentdb module added to OpenClaw, which serves as the carrier for all subsequent memory features.

Step 2: Zero-Configuration Enablement (SQLite by Default)

This step is so simple it barely requires explanation. Edit your OpenClaw configuration file:

// ~/.openclaw/openclaw.json
{
  "memory-tencentdb": {
    "enabled": true
  }
}

That's it. Save the file and either restart the gateway or start a new conversation.

Why does it work out of the box? The plugin comes with SQLite + sqlite-vec built-in as a local storage backend. You don't need to deploy a vector database or apply for any API keys. All data is stored in your local file system. Memory extraction, scenario aggregation, persona generation, and recall injection are all handled automatically.

Once enabled, the Agent automatically performs the following after each conversation:

• Captures L0 raw dialogues.
• Extracts L1 atomic memories (facts, preferences) every 5 rounds.
• Aggregates them into L2 scenario blocks once enough data accumulates.
• Periodically generates an L3 user persona (persona.md).

In subsequent conversations, the Agent automatically recalls and injects relevant memories into the context based on the current topic.

Step 3: Enable Short-Term Context Compression (Optional)

If you frequently run long tasks with your Agent (e.g., search + coding + debugging, generating thousands of tool logs), it is highly recommended to enable the short-term compression feature. It offloads verbose tool logs to external files and retains only a lightweight Mermaid task diagram in the Agent's context window.

3.1 Modify Configuration

{
  "memory-tencentdb": {
    "enabled": true,
    "config": {
      "offload": {
        "enabled": true
      }
    }
  }
}

3.2 Register the context-engine Slot

{
  "plugins": {
    "slots": {
      "contextEngine": "memory-tencentdb"
    }
  }
}

This step routes OpenClaw's context offloading requests to our plugin.

3.3 Apply the Runtime Patch

bash scripts/openclaw-after-tool-call-messages.patch.sh

This patch only needs to be run once for each OpenClaw installation. Remember to re-run it after upgrading OpenClaw. It hooks into the after-tool-call message event, ensuring verbose logs from tool executions are properly offloaded and restored.

Verification: Is Your Agent Actually "Remembering"?

You've installed the plugin, but how do you confirm it's actually working? Let's run a quick test.

Scenario Simulation: You tell the Agent your project preferences, wait a while (or restart the gateway), and then open a new conversation to see if it remembers.

## First Conversation
You: Our backend service is deployed at dev.example.com, the API prefix is /api/v2,
    responses always use {"code": 0, "data": {...}}.
    Also, I prefer 2-space indentation for code.

## Agent replies normally...

## After a few conversation rounds (triggering L1 auto-extraction), or after restarting the gateway

## Second Conversation
You: Can you check the API endpoint I mentioned earlier?
Agent (after internally recalling L1 memory):
    According to your records, the backend service is deployed at dev.example.com
    with the API prefix /api/v2... What would you like me to do now?

If the Agent answers accurately, the entire memory pipeline is functioning correctly. You can also directly inspect the ~/.openclaw/memory-tdai/ directory. It contains raw dialogues, extracted atomic memories, scenario blocks, and persona files organized by layer—all readable Markdown. This is a white-box solution, not a black box.

Understanding this layered architecture is crucial:

• Short-term: Mermaid canvas (high-level overview) → JSONL (step summaries) → refs/*.md (raw logs), drilling down on demand.
• Long-term: L0 raw dialogues → L1 atomic facts → L2 scenario blocks → L3 user persona, moving from abstract to concrete.

This design ensures the Agent doesn't stuff everything into the context window. It only drills down to the source via node_id when details are needed, saving tokens without sacrificing auditability.

Troubleshooting / Common Pitfalls

Q1: The plugin stops working after upgrading OpenClaw. What should I do?
Do not use npm update to upgrade the plugin. Always use the native command openclaw plugins update @tencentdb-agent-memory/memory-tencentdb, otherwise semantic version ranges might disable the plugin.

Q2: The patch script throws a permission denied error?
Ensure the script has execution permissions: chmod +x scripts/openclaw-after-tool-call-messages.patch.sh

Q3: Memory recall isn't accurate enough?
The default retrieval strategy is hybrid (BM25 + vector hybrid search), which covers most scenarios. If results are unsatisfactory, try changing retrieval.strategy to keyword for pure keyword recall. Additionally, recall.maxResults defaults to 5; you can increase it for long-document scenarios.

Q4: I don't want to store data locally; can I connect to a remote vector database?
Yes. Level 3 configuration in the README details how to connect to Tencent Cloud Vector Database (TCVDB). Embeddings can also be configured to use remote OpenAI-compatible endpoints.

Summary

We've successfully installed and configured TencentDB Agent Memory step-by-step: from a single openclaw plugins install command to zero-configuration local memory enablement, short-term context compression, and real-world verification. The entire process takes less than 10 minutes and requires absolutely zero external API dependencies.

Its core value can be summarized in one sentence: Let Agents remember what they should, so humans can focus on judgment and creation.

Next steps you can explore:

• Adjust pipeline.everyNConversations and persona.triggerEveryN to control memory extraction frequency.
• Use a remote LLM to run the L1/L2/L3 extraction pipeline (configure llm.* fields).
• Explore the files under ~/.openclaw/memory-tdai/ to understand how memories gradually abstract from raw conversations into user personas.

Feel free to leave a comment if you have questions, or head over to the GitHub Repository to raise an issue. The community is highly responsive.