OpenClaw HY Memory Plugin

由腾讯混元团队研发的 OpenClaw 插件，专注于为 AI Agent 提供智能长期记忆能力。

Features

• 5 Memory Tools — memory_search, memory_add, memory_get, memory_update, memory_delete
• Auto-Recall — Automatically injects relevant memories before each agent turn
• Auto-Capture — Stores key facts from conversations after each agent turn
• Auto-Start Server — Manages a local Python HY Memory server automatically
• CLI Commands — openclaw hy-memory status, search, add, list, delete, reset, init

Quick Start

1. Install the plugin

# 公开 npm（npmjs.org）
openclaw plugin install openclaw-hy-memory --dangerously-force-unsafe-install

# 腾讯内部 npm
# openclaw plugin install @tencent/openclaw-hy-memory --dangerously-force-unsafe-install

为什么必须加 --dangerously-force-unsafe-install？

Hy-Memory 以 Python 子进程的方式随插件启动来提供服务。OpenClaw 出于安全考虑默认拒绝安装会启动外部进程的插件，因此需要显式加上该参数以确认你知晓并允许此行为。

Windows

插件会自动使用 ~/.hy-memory/.venv（若你已有旧版 ~/.openclaw/hy-memory-venv 会继续沿用，避免重复安装）。请确保系统已安装 Python 3.8+ 且 python 在 PATH 中。一般无需改 pythonPath；若使用自定义解释器，填完整路径，例如 D:\Python311\python.exe。

2. Run the setup wizard

openclaw hy-memory init

This will guide you through configuring:

• LLM Provider — OpenAI, DeepSeek, Moonshot, Hunyuan, or Ollama (local)
• Embedding Provider — OpenAI, Aliyun Bailian, or Ollama
• Vector Store — Qdrant, ChromaDB (embedded), or FAISS

3. Restart the gateway

openclaw gateway restart

4. Verify services

openclaw hy-memory status

确认 VDB、Embed、LLM 三项服务均为 ok 状态。

Manual Configuration

Add to ~/.openclaw/openclaw.json:

{
  "plugins": {
    "slots": { "memory": "openclaw-hy-memory" },
    "entries": {
      "openclaw-hy-memory": {
        "enabled": true,
        "hooks": { "allowConversationAccess": true },
        "config": {
          "userId": "your-username",
          "autoRecall": true,
          "autoCapture": true,
          "memoryWriteTurnWindow": 5,
          "topK": 10,
          "llm": {
            "provider": "openai",
            "model": "gpt-4.1-nano",
            "apiKey": "sk-your-key"
          },
          "embedder": {
            "provider": "openai",
            "model": "text-embedding-3-small",
            "apiKey": "sk-your-key"
          },
          "vectorStore": {
            "provider": "chroma"
          }
        }
      }
    }
  }
}

Ultra mode (manual config only)

Not part of openclaw hy-memory init. Set mode in openclaw.json and restart the gateway:

{
  "config": {
    "mode": "ultra",
    "logLevel": "DEBUG"
  }
}

Ultra uses embedded Kuzu under ~/.hy_memory/data/kuzu_db/ (no Neo4j). Requires hy-memory core package (includes kuzu).

Configuration Options

| Option | Default | Description | |--------|---------|-------------| | serverUrl | http://127.0.0.1:19527 | HY Memory server URL | | userId | OS username | User ID for scoping memories | | agentId | default_agent | Agent ID | | mode | pro | lite / pro / ultra. ultra enables System 2 + embedded Kuzu graph (local, no extra service) | | autoRecall | false | Inject memories before each turn | | autoCapture | false | Store conversation after each turn | | memoryWriteTurnWindow | 5 | Agent turns between each auto-capture write | | topK | 10 | Max search results | | searchThreshold | 0.3 | Min similarity score | | autoStartServer | true | Auto-start Python server | | serverPort | 19527 | Python server port | | llm | — | LLM config (see below) | | embedder | — | Embedding config (see below) | | vectorStore | ChromaDB | Vector store config |

LLM Config

{
  "provider": "openai",
  "model": "deepseek-chat",
  "apiKey": "sk-...",
  "baseUrl": "https://api.deepseek.com"
}

Any OpenAI-compatible API works — just set baseUrl accordingly.

CLI Commands

openclaw hy-memory status              # Check server connectivity
openclaw hy-memory search "query"      # Search memories
openclaw hy-memory add "text"          # Add a memory
openclaw hy-memory list                # List all memories
openclaw hy-memory delete <id>         # Delete a memory
openclaw hy-memory reset --yes         # Delete all memories
openclaw hy-memory init                # Setup wizard

Development

cd plugins/openclaw/
npm install
npm run build

License

MIT