OpenClaw Memory (Milvus) Plugin

Milvus-backed memory with hybrid search (vector + BM25) for OpenClaw.

Features

• Hybrid Search: Combines vector similarity search with BM25 keyword search
• Milvus Backend: Uses Milvus vector database for scalable storage and search
• Multi-Agent Isolation: Each agent gets its own Milvus collection
• Multiple Embedding Providers: Supports OpenAI, Gemini, Voyage, Mistral, Ollama
• MMR Re-ranking: Maximal Marginal Relevance for diverse results
• Temporal Decay: Boosts recent memories, decays old ones
• File Watching: Automatic sync. when memory files change
• CLI Commands: openclaw milvus-mem status|search|sync

Installation

npm install @chunliu/memory-milvus

Configuration

Required Settings

Milvus Configuration

| Setting | Type | Default | Description | |---------|------|---------|------------| | milvus.address | string | localhost:19530 | Milvus server address | | milvus.prefix | string | openclaw-memory | Collection prefix | | milvus.username | string | - | Milvus username (if required) | | milvus.password | string | - | Milvus password (if required) |

Embedding Configuration

| Setting | Type | Default | Description | |---------|------|---------|------------| | embedding.provider | string | ollama | Embedding provider (ollama/openai/gemini/mistral/voyage/custom) | | embedding.model | string | qwen3-embed:latest | Embedding model name | | embedding.apiKey | string | - | API key for OpenAI-compatible providers | | embedding.baseUrl | string | http://localhost:11434/v1 | Base URL for OpenAI-compatible providers |

Note:

• Only milvus and embedding settings need to be in openclaw.json
• Other settings (search, sync, watch, cache) use built-in defaults
• See Advanced Configuration for more details

Using OpenAI

{
  plugins: {
    slots: {
      memory: "memory-milvus"
    },
    entries: {
      "memory-milvus": {
        enabled: true,
        config: {
          milvus: {
            address: "localhost:19530",
            prefix: "openclaw-memory"
          },
          embedding: {
            provider: "openai",
            model: "text-embedding-3-small",
            apiKey: "your-api-key"
          }
        }
      }
    }
  }
}

Using Ollama (Local)

{
  plugins: {
    slots: {
      memory: "memory-milvus"
    },
    entries: {
      "memory-milvus": {
        enabled: true,
        config: {
          milvus: {
            address: "localhost:19530",
            prefix: "openclaw-memory"
          },
          embedding: {
            provider: "ollama",
            model: "qwen3-embed:latest",
            baseUrl: "http://localhost:11434/v1"
          }
        }
      }
    }
  }
}

Using BytePlus Milvus

{
  plugins: {
    slots: {
      memory: "memory-milvus"
    },
    entries: {
      "memory-milvus": {
        enabled: true,
        config: {
          milvus: {
            address: "http://your-milvus-server:19530",
            username: "your-username",
            password: "your-password",
            prefix: "openclaw"
          },
          embedding: {
            provider: "ollama",
            model: "qwen3-embed:latest",
            baseUrl: "http://localhost:11434/v1"
          }
        }
      }
    }
  }
}

Advanced Configuration

Search Configuration

| Setting | Type | Default | Description | |---------|------|---------|------------| | search.maxResults | number | 5 | Maximum number of search results | | search.minScore | number | 0.5 | Minimum similarity score (0-1) | | search.hybrid.enabled | boolean | true | Enable vector + BM25 hybrid search | | search.hybrid.vectorWeight | number | 0.7 | Vector search weight (0-1) | | search.hybrid.textWeight | number | 0.3 | BM25 search weight (0-1) | | search.mmr.enabled | boolean | false | Enable MMR re-ranking for diversity | | search.mmr.lambda | number | 0.7 | MMR lambda (higher = more diverse) | | search.temporalDecay.enabled | boolean | false | Boost recent memories, decay old ones | | search.temporalDecay.halfLifeDays | number | 30 | Half-life for decay (days) |

Sync Configuration

| Setting | Type | Default | Description | |---------|------|---------|------------| | sync.onSearch | boolean | true | Sync memory files before search | | sync.onSessionStart | boolean | true | Sync memory files when session starts | | sync.watch | boolean | true | Enable file watching |

Watch Configuration

| Setting | Type | Default | Description | |---------|------|---------|------------| | watch.enabled | boolean | true | Enable file watching | | watch.workspacePath | string | "" | Agent workspace path (empty = auto-detect) | | watch.debounceMs | number | 500 | Debounce delay in milliseconds | | watch.patterns | array of strings | ["MEMORY.md", "memory/*.md"] | File patterns to watch (glob) |

Cache Configuration

| Setting | Type | Default | Description | |---------|------|---------|------------| | cache.enabled | boolean | true | Cache embeddings to reduce API calls | | cache.maxEntries | number | 50000 | Maximum cache entries |

Note:

• All settings in this section use built-in defaults
• You only need to configure settings that differ from defaults

CLI Commands

Status

openclaw milvus-mem status
openclaw milvus-mem status --agent-id <agent-id>

Shows:

• Agent ID
• Collection name
• Total chunks
• Embedding provider and model

Options:

• --agent-id <agent-id>: Agent ID to check (optional, default: current agent)

Search

openclaw milvus-mem search <query> --agent-id <agent-id>
openclaw milvus-mem search <query> --agent-id <agent-id> --limit 10 --min-score 0.6

Searches memory files using Milvus vector search.

Options:

• --agent-id <agent-id>: Agent ID to search in (required)
• --limit <number>: Maximum number of results (default: 5)
• --min-score <number>: Minimum similarity score (0-1, default: 0.0)

Sync

openclaw milvus-mem sync --agent-id <agent-id>
openclaw milvus-mem sync --agent-id <agent-id> --force

Manually syncs memory files to Milvus.

Options:

• --agent-id <agent-id>: Agent ID to sync (required)
• --force: Force full re-sync

Architecture

┌─────────────────────────────────────┐
│         OpenClaw Memory API         │
│  (memory_search, memory_get)        │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│      Milvus Memory Manager         │
│  - Agent-specific collections       │
│  - Hybrid Search                   │
│  - File Sync                       │
│  - File Watching                   │
└──────────────┬──────────────────────┘
               │
┌──────────────┴──────────────────────┐
│         Milvus Server               │
│  - Collection per agent             │
│  - Vector Search (HNSW)            │
│  - BM25 Search                      │
│  - Hybrid Search API                │
└─────────────────────────────────────┘

Multi-Agent Isolation

Each OpenClaw agent gets its own Milvus collection:

• Collection Naming: {prefix}-{agentId}
• Example: openclaw-memory-agent1, openclaw-memory-agent2
• Isolation: Complete data separation between agents
• Security: Agents cannot access each other's memory
• Customizable Prefix: Configure via milvus.prefix in config

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT