Qdrant Memory System

基于自建 Qdrant 向量数据库的永久记忆系统，为 AI 助手提供跨会话持久记忆能力。

架构

Client Machine (MacBook Pro)          Server Machine (Mac Mini)
┌──────────────────┐   SSH Tunnel   ┌──────────────────────┐
│ Claude Code       │──(6333端口)──→│  Qdrant 服务          │
│ ├ MCP Server (V1) │               │  ├ claude-memory      │
│ └ MCP Server (V2) │               │  │  (512维, bge-zh)   │
└──────────────────┘               │  └ openclaw_memories  │
                                    │     (384维, MiniLM)   │
                                    │                      │
                                    │  OpenClaw Gateway     │
                                    │  ├ Plugin V1          │
                                    │  └ Plugin V2 (当前)    │
                                    └──────────────────────┘

组件总览

目录	语言	版本	用途
mcp-server/	Python	V1	Claude Code MCP 记忆服务
mcp-server-v2/	Python	V2	Claude Code MCP 记忆服务（增强版）
openclaw-plugin/	Node.js	V1	OpenClaw 语义记忆插件
openclaw-plugin-v2/	Node.js	V2	OpenClaw 语义记忆插件（增强版）

---

V1 vs V2 对比

特性	V1	V2
存储	纯记录，所有记忆平等对待	自动 importance 分级（high/medium/low）
搜索	纯向量余弦相似度	向量相似度 × importance 加权，重要记忆优先
关键词搜索	无	新增 keyword_search，支持精确匹配
统计	无	新增 memory_stats，查看分类/重要性分布
噪音过滤	无，什么都存	自动过滤 image_key、媒体附件、飞书图片等噪音
去重	简单相似度检查	0.95 阈值去重，防止重复存储
Payload 索引	无	自动创建 text(multilingual)、category、importance_level 索引
V1 兼容	—	完全兼容，无 importance 的旧记录视为 medium
工具数量	4个 (store/search/delete/list)	5个 (+keyword_search, +memory_stats)

---

V2 核心改进

1. Importance 自动分级

根据分类自动判定重要性等级和加权系数：

高重要性 (high, ×1.3):
  architecture — 架构决策
  solution    — 问题解决方案
  project     — 项目信息
  preference  — 用户偏好
  decision    — 关键决定
  summary     — 总结摘要

中重要性 (medium, ×1.0):
  fact        — 事实信息
  entity      — 实体信息
  other       — 其他

低重要性 (low, ×0.7):
  conversation — 日常对话记录

2. 加权搜索排序

最终得分 = 向量相似度 × importance 权重

例：
  架构决策，相似度 0.78 → 0.78 × 1.3 = 1.01 ★ 排在前面
  日常对话，相似度 0.85 → 0.85 × 0.7 = 0.60 · 排在后面

即使对话记录的向量匹配度更高，架构决策等重要记忆仍然优先展示。

3. 关键词搜索（新增）

V1 只有语义搜索，搜「OpenClaw」可能返回语义相近但不含该词的结果。

V2 新增 keyword_search：

• 基于 Qdrant payload text index（multilingual tokenizer）
• 精确匹配关键词，适合搜项目名、工具名、特定术语
• 可选按分类过滤

搜索策略：先用 search_memory（语义），不理想再用 keyword_search（精确），两种互补。

4. 噪音过滤

自动过滤以下无意义内容：

{"image_key":...}     — 飞书图片 JSON
img_v3_xxxx           — 飞书图片 key
[media attached:...]  — 媒体附件标记
/Users/...media/...   — 本地媒体路径
系统心跳/健康检查消息
PII（手机号、邮箱，可配置）

5. Payload 索引

启动时自动创建（幂等）：

• text — multilingual 全文索引，支持中英文关键词搜索
• category — keyword 索引，加速分类过滤
• importance_level — keyword 索引，加速重要性过滤

6. 统计面板（新增）

memory_stats 查看记忆库状态：

总记忆数: 329

按分类:
  conversation: 185
  solution: 45
  architecture: 32
  ...

按重要性:
  high: 127
  medium: 17
  low: 185

---

安装

MCP Server V2（Claude Code）

cd mcp-server-v2
pip install -r requirements.txt
python server_v2.py

OpenClaw Plugin V2

cd openclaw-plugin-v2
npm install
# 在 openclaw.json 中配置插件路径和 Qdrant 连接

MCP Server V1（旧版）

cd mcp-server
pip install -r requirements.txt
python server.py

OpenClaw Plugin V1（旧版）

cd openclaw-plugin
npm install

详见 openclaw-plugin/README.md

前置依赖

• Qdrant 向量数据库（本地部署）
• Python 3.10+（MCP Server）
• Node.js 18+（OpenClaw Plugin）

迁移工具

从 Pinecone 迁移到自建 Qdrant

cd mcp-server
export PINECONE_API_KEY="your-api-key"
python migrate_from_pinecone.py

V1 → V2 importance 字段回填

cd mcp-server-v2
python backfill_importance.py

为已有 V1 记录补充 importance_level 字段，根据 category 自动映射。

License

MIT