semantic-vector-store#

语义向量库插件，为 OpenClaw 星型记忆架构提供向量存储与语义搜索能力。

🎯 功能#

• 向量化记忆：将记忆文本转换为语义向量（嵌入）
• 向量存储：持久化存储向量，支持高效检索
• 语义搜索：基于余弦相似度的向量搜索
• 增量索引：支持动态添加新记忆，无需全量重建
• 可插拔后端：支持 SQLite + FAISS、Pinecone、Weaviate 等后端

📦 安装#

bash

# 从 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）

🚀 快速开始#

python

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#

提供星型架构的标准适配器接口：

python

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健康检查

🏗️ 架构设计#

核心组件#

1. 嵌入器（Embedder）
   • 支持多种嵌入模型（Sentence Transformers、OpenAI、本地模型）
   • 模型缓存与热加载
2. 向量存储（VectorStore）
   • SQLite + FAISS 混合存储
   • 支持增量索引与批量导入
   • 自动向量归一化
3. 查询引擎（QueryEngine）
   • 余弦相似度计算
   • 混合搜索（语义 + 关键词）
   • 结果排序与去重

数据模型#

sql

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 集成：

python

# 在 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 集成#

统一记忆系统可同时查询语义向量和共现图：

python

from unified_memory import UnifiedMemory

memory = UnifiedMemory()
results = memory.search("查询", use_semantic=True, use_cooccurrence=True)

📊 性能指标#

指标目标值向量化延迟< 100ms（短文本）搜索延迟< 50ms（10K 向量）存储容量> 1M 向量准确率> 0.85（MRR）

🔧 维护#

数据库维护#

bash

# 重建索引
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