semantic-vector-store
语义向量库插件，为 OpenClaw 星型记忆架构提供向量存储与语义搜索能力。
🎯 功能
- 向量化记忆：将记忆文本转换为语义向量（嵌入）
- 向量存储：持久化存储向量，支持高效检索
- 语义搜索：基于余弦相似度的向量搜索
- 增量索引：支持动态添加新记忆，无需全量重建
- 可插拔后端：支持 SQLite + FAISS、Pinecone、Weaviate 等后端
📦 安装
# 从 ClawHub 安装
clawhub install semantic-vector-store
# 或从本地目录安装
clawhub install ./skills/semantic-vector-store⚙️ 配置
环境变量：
SEMANTIC_VECTOR_DB_PATH：向量数据库路径（默认：~/.config/cortexgraph/semantic_vectors.db）EMBEDDING_MODEL：嵌入模型名称（默认：all-MiniLM-L6-v2）VECTOR_DIMENSION：向量维度（默认：384）SIMILARITY_THRESHOLD：相似度阈值（默认：0.5）
🚀 快速开始
from semantic_vector_store import SemanticVectorStore
# 初始化
store = SemanticVectorStore()
# 添加记忆向量
mem_id = "mem_001"
text = "今天学习了 Python 异步编程"
vector = store.embed(text)
store.add_vector(mem_id, vector, metadata={"source": "memory.md"})
# 语义搜索
query = "编程学习"
results = store.search(query, top_k=5)
for result in results:
print(f"记忆 ID: {result['memory_id']}, 相似度: {result['score']:.3f}")🔌 适配器接口
SemanticVectorAdapter
提供星型架构的标准适配器接口：
from integration.adapter.semantic_vector_adapter import SemanticVectorAdapter
adapter = SemanticVectorAdapter()
# 获取健康状态
health = adapter.health_check()
print(f"健康状态: {health['status']}")
# 向量化记忆
vectors = adapter.embed_memory("今天完成了重要工作")
print(f"生成向量维度: {len(vectors)}")
# 语义搜索
results = adapter.search("工作", limit=10)主要方法
| 方法 | 说明 |
|---|---|
embed(text: str) -> List[float] | 将文本转换为向量 |
add_vector(memory_id: str, vector: List[float], metadata: dict) | 添加向量到存储 |
search(query: str, top_k: int = 10) -> List[dict] | 语义搜索 |
get_stats() -> dict | 获取统计信息 |
health_check() -> dict | 健康检查 |
🏗️ 架构设计
核心组件
- 嵌入器（Embedder）
- 支持多种嵌入模型（Sentence Transformers、OpenAI、本地模型） - 模型缓存与热加载
- 向量存储（VectorStore）
- SQLite + FAISS 混合存储 - 支持增量索引与批量导入 - 自动向量归一化
- 查询引擎（QueryEngine）
- 余弦相似度计算 - 混合搜索（语义 + 关键词） - 结果排序与去重
数据模型
CREATE TABLE semantic_vectors (
memory_id TEXT PRIMARY KEY,
vector BLOB, -- FAISS 索引 ID 或原始向量
metadata TEXT, -- JSON 元数据
created_at TIMESTAMP,
updated_at TIMESTAMP
);🔄 集成点
与 Memory Sync Enhanced 集成
语义向量库通过适配器与 MSE 集成：
# 在 MSE 中使用语义向量库
from integration.adapter.semantic_vector_adapter import SemanticVectorAdapter
class MemorySyncEnhanced:
def __init__(self):
self.vector_adapter = SemanticVectorAdapter()
def semantic_search(self, query: str):
return self.vector_adapter.search(query)与 Unified Memory 集成
统一记忆系统可同时查询语义向量和共现图：
from unified_memory import UnifiedMemory
memory = UnifiedMemory()
results = memory.search("查询", use_semantic=True, use_cooccurrence=True)📊 性能指标
| 指标 | 目标值 |
|---|---|
| 向量化延迟 | < 100ms（短文本） |
| 搜索延迟 | < 50ms（10K 向量） |
| 存储容量 | > 1M 向量 |
| 准确率 | > 0.85（MRR） |
🔧 维护
数据库维护
# 重建索引
python3 -m semantic_vector_store.reindex
# 备份向量
python3 -m semantic_vector_store.backup --output vectors.bin
# 查看统计
python3 -m semantic_vector_store.stats监控指标
- 向量存储使用率
- 查询延迟（P50, P95, P99）
- 缓存命中率
- 嵌入模型加载状态
📝 版本历史
- v0.1.0（当前）：MVP 版本，基础向量存储与搜索
- v0.2.0（计划）：支持 FAISS 索引，性能优化
- v0.3.0（计划）：多模型支持，混合搜索
🤝 贡献
欢迎提交 Issue 和 Pull Request。请遵循 OpenClaw 技能开发规范。
📄 许可证
MIT