Kv Embed Store

Key-embedding value store with memory integration — fuzzy-search by embedding similarity with multi-alias dedup and optional memory indexing.

shaojun0@shaojun0

Install

openclaw skills install @shaojun0/kv-embed-store

KV Embed Store

Embedding-based key-value store. Multiple key aliases map to one entry. Built-in dedup prevents duplicates. Optional memory index for memory_search discovery.

Usage Modes

Plugin Mode (recommended)

Install as an OpenClaw plugin for native tool access:

bash

openclaw plugins install clawhub:openclaw-plugin-kv-embed-store

Registers: kv_put, kv_search, kv_get, kv_list, kv_remove, kv_merge, kv_dedup, kv_refresh_index.

Standalone Mode

bash

python3 scripts/kv_store.py put "my-project" '{"repo":"github.com/example/project","port":3000}'
python3 scripts/kv_store.py search "project reference" -k 5

Plugin Configuration

In openclaw.json under plugins.entries.kv-embed-store.config:

Key	Default	Description
`storePath`	`data/kv_store.json`	Path to the store JSON file
`memoryIndex`	`false`	Generate memory index with aliases and value previews
`apiKey`	—	Embedding API key (or `KV_EMBED_API_KEY` env)
`baseUrl`	`https://api.siliconflow.cn/v1`	Embedding API base URL (or `KV_EMBED_BASE_URL` env)
`model`	`BAAI/bge-m3`	Embedding model (or `KV_EMBED_MODEL` env)

json5

{
  plugins: {
    entries: {
      "kv-embed-store": {
        enabled: true,
        config: {
          storePath: "~/.openclaw/workspace/data/kv-store.json",
          apiKey: "sk-xxx",
          baseUrl: "https://api.siliconflow.cn/v1",
          model: "BAAI/bge-m3"
        }
      }
    }
  }
}

Provider Examples

bash

# SiliconFlow (default)
export KV_EMBED_API_KEY=***
export KV_EMBED_BASE_URL=https://api.siliconflow.cn/v1
export KV_EMBED_MODEL=BAAI/bge-m3

# OpenRouter
export KV_EMBED_API_KEY=***
export KV_EMBED_BASE_URL=https://openrouter.ai/api/v1
export KV_EMBED_MODEL=openai/text-embedding-3-small

# OpenAI
export KV_EMBED_API_KEY=***
export KV_EMBED_BASE_URL=https://api.openai.com/v1
export KV_EMBED_MODEL=text-embedding-3-small

Requirements

Plugin: Node >= 22, openclaw >=2026.5.17
Standalone: Python 3, numpy, requests
API: Any OpenAI-compatible embeddings provider (SiliconFlow, OpenRouter, OpenAI, etc.)

Put Behavior (anti-duplicate)

When kv_put is called:

Embed the key text via the configured embedding provider
Search existing keys by cosine similarity
cos > 0.95: auto-merge — add key as alias, update value
cos 0.85-0.95: return candidates, let caller decide
cos < 0.85: create new entry
force=true skips dedup

Data Format

Store file is human-readable JSON:

json

{
  "entries": {
    "e1": {
      "aliases": ["my-project", "project-reference"],
      "data": {"repo": "github.com/example/project", "port": 3000},
      "created_at": "2026-07-06T15:30:00",
      "updated_at": "2026-07-06T15:35:00"
    }
  },
  "embeddings": {
    "my-project": [0.1, 0.2, ...],
    "project-reference": [0.15, 0.22, ...]
  }
}

Tips

Use short, distinctive key texts for best embedding results
Group related values under one entry with multiple aliases
Run kv_dedup --apply periodically to clean up accidental duplicates
Enable memoryIndex to make entries discoverable via memory_search
Use the standalone Python CLI for ad-hoc queries without installing the plugin