openclaw-memory-qdrant

OpenClaw local semantic memory plugin with zero-configuration semantic search powered by Qdrant and Transformers.js.

📦 ClawHub: https://clawhub.ai/skills/memory-qdrant

Features

• 🧠 Local semantic search: Generate embeddings locally with Transformers.js
• 💾 In-memory mode: Zero configuration, no external service required
• 🔄 Automatic capture: Record important information through lifecycle hooks
• 🎯 Smart recall: Retrieve relevant memories based on conversation context

Installation

Via ClawHub (Recommended)

clawhub install memory-qdrant

Manual installation

mkdir -p ~/.openclaw/extensions
cd ~/.openclaw/extensions
git clone https://github.com/zuiho/openclaw-memory-qdrant.git memory-qdrant
cd memory-qdrant
npm install

If you keep the plugin somewhere else, add that directory to plugins.load.paths in ~/.openclaw/openclaw.json.

Requirements

First-run setup:

1. Node.js version: Requires Node.js >= 18.17

   node --version  # Check your version

2. Build tools (for native dependencies):

• Windows: Visual Studio Build Tools

     npm install --global windows-build-tools

• macOS: Xcode Command Line Tools

     xcode-select --install

• Linux: build-essential

     sudo apt-get install build-essential  # Debian/Ubuntu
     sudo yum groupinstall "Development Tools"  # RHEL/CentOS

3. Network access:

• npmjs.com must be reachable during installation to download dependencies
• The embedding model is downloaded from huggingface.co on first run (about 25 MB)
• If you configure an external Qdrant server, it must be reachable

4. Native dependencies:

• sharp: image processing library (may require compilation)
• onnxruntime: ML inference engine (may require compilation)
• undici: HTTP client (pulled in through @qdrant/js-client-rest)

Recommended installation flow

# Use npm ci for reproducible installs (recommended for production)
npm ci

# Or install in stages (useful for debugging)
npm install --ignore-scripts  # Skip post-install scripts
npm rebuild                   # Rebuild native modules afterward

Troubleshooting

Issue: Native module compilation failed

• Make sure the required build tools for your platform are installed
• Try clearing the npm cache: npm cache clean --force
• Remove node_modules and reinstall: rm -rf node_modules && npm install

Issue: sharp loads the wrong CPU architecture binary on macOS

• This usually means the plugin dependencies were installed under one Node/runtime architecture, but the OpenClaw gateway is running under another
• Check the runtime used by the gateway in ~/Library/LaunchAgents/ai.openclaw.gateway.plist
• Rebuild sharp with that exact Node/npm pair. Example using OpenClaw's bundled Node runtime:

PATH="$HOME/.openclaw/tools/node-v22.22.0/bin:$PATH" \
  "$HOME/.openclaw/tools/node-v22.22.0/bin/npm" rebuild sharp --foreground-scripts --verbose

• On Apple Silicon, the expected binary is usually node_modules/sharp/build/Release/sharp-darwin-arm64v8.node

Issue: Model download failed

• Check your network connection and firewall settings
• Make sure huggingface.co is reachable
• Model files are cached under ~/.cache/huggingface/

Issue: Node version is incompatible

• Upgrade to Node.js 18.17 or newer
• Use nvm to manage multiple Node versions: nvm install 18 && nvm use 18

Configuration

Enable the plugin in your OpenClaw config:

{
  "plugins": {
    "slots": {
      "memory": "memory-qdrant"
    },
    "entries": {
      "memory-qdrant": {
        "enabled": true,
        "config": {
          "autoCapture": false,
          "autoRecall": true,
          "captureMaxChars": 500
        }
      }
    }
  }
}

Configuration options

Plugin-specific options belong under plugins.entries.memory-qdrant.config.

In OpenClaw 2026.4.10, the memory slot must also be set to memory-qdrant. If plugins.slots.memory is left at the default bundled value (memory-core), this plugin will be discovered but not activated.

• qdrantUrl (optional): External Qdrant server URL. Leave empty to use in-memory mode
• autoCapture (default false): Automatically record conversation content. Review privacy implications before enabling
• autoRecall (default true): Automatically inject relevant memories into the conversation
• captureMaxChars (default 500): Maximum characters per stored memory
• maxMemorySize (default 1000): Maximum number of memories in in-memory mode
• Only applies when qdrantUrl is not configured
• Oldest memories are deleted automatically when the limit is reached (LRU eviction)
• Range: 100 to 1000000
• Set to 999999 for unlimited storage (old memories are not auto-deleted)
• ⚠️ Unlimited mode can exhaust memory; use cautiously
• External Qdrant mode is not affected by this limit

Privacy and Security

Data storage

• In-memory mode (default): Data exists only while the process is running and is cleared on restart
• Qdrant mode: If qdrantUrl is configured, data is sent to that server
• ⚠️ Only use trusted Qdrant servers
• A local Qdrant instance or a dedicated service account is recommended

Network access

• First run: Transformers.js downloads the model from Hugging Face (about 25 MB)
• Runtime: In-memory mode makes no network requests; Qdrant mode connects to the configured server

Automatic capture

• autoCapture is disabled by default and must be enabled manually
• When enabled, conversation content may be stored automatically, including sensitive data
• Recommended for personal environments only, not shared or production environments

Recommendations

1. Test in an isolated environment before first use 2. Review index.js to understand the data handling flow 3. Pin dependency versions in sensitive environments with npm ci 4. Periodically inspect stored memories

Usage

The plugin provides three tools:

memory_store

Save important information to long-term memory:

memory_store({
  text: "The user prefers using Opus for complex tasks",
  category: "preference",
  importance: 0.8
})

memory_search

Search for relevant memories:

memory_search({
  query: "workflow",
  limit: 5
})

memory_forget

Delete a specific memory:

memory_forget({
  memoryId: "uuid-here"
})
// Or delete via search
memory_forget({
  query: "content to delete"
})

Technical Details

Architecture

• Vector database: Qdrant (in-memory mode)
• Embedding model: Xenova/all-MiniLM-L6-v2 (local execution)
• Module system: ES6 modules

Key implementation detail

The plugin exports tools through a factory function pattern to stay compatible with the OpenClaw tool system:

export default {
  name: 'memory-qdrant',
  version: '1.0.0',
  tools: [
    () => ({
      name: 'memory_search',
      description: '...',
      parameters: { ... },
      execute: async (params) => { ... }
    })
  ]
}

FAQ

Q: Why use a factory function?

A: OpenClaw calls tool.execute(). Exporting a plain object can lead to tool.execute is not a function. The factory pattern guarantees a fresh tool instance on each call.

Q: Why use ES6 modules?

A: The OpenClaw plugin loader expects ES6 module format. Set "type": "module" in package.json.

Q: Where is the data stored?

A: In-memory mode keeps data only for the current process lifetime. A restart requires re-indexing. Persistent storage may be added in a future version.

Development

# Install dependencies
npm install

# Test (requires an OpenClaw environment)
openclaw gateway restart

If the gateway says the plugin is discovered but disabled, verify that both the plugin entry and memory slot are set:

{
  "plugins": {
    "slots": {
      "memory": "memory-qdrant"
    },
    "entries": {
      "memory-qdrant": {
        "enabled": true
      }
    }
  }
}

License

MIT

Acknowledgements

• Qdrant - Vector database
• Transformers.js - Local ML inference
• OpenClaw - AI assistant framework