alekhm-aister-vector-memory

Aister 的向量记忆——按语义搜索，而非 grep！

## 概述（中文）

Aister 的向量记忆——按语义搜索，而非 grep！

## 技能正文

# 向量记忆技能

Aister 的向量记忆——按语义搜索，而非 grep！

## 描述

使用 PostgreSQL + pgvector + e5-large-v2 的向量记忆。支持按**含义**搜索信息，而非仅关键词。

## 环境变量

**必需：**
- `VECTOR_MEMORY_DB_PASSWORD` — PostgreSQL 数据库访问密码

**可选：**
| 变量 | 默认值 | 说明 |
|----------|---------|-------------|
| `VECTOR_MEMORY_DB_HOST` | `localhost` | PostgreSQL 服务器主机 |
| `VECTOR_MEMORY_DB_PORT` | `5432` | PostgreSQL 服务器端口 |
| `VECTOR_MEMORY_DB_NAME` | `vector_memory` | 数据库名 |
| `VECTOR_MEMORY_DB_USER` | `aister` | 数据库用户 |
| `EMBEDDING_SERVICE_URL` | `http://127.0.0.1:8765` | 嵌入服务 URL |
| `EMBEDDING_MODEL` | `intfloat/e5-large-v2` | 生成嵌入的模型 |
| `EMBEDDING_PORT` | `8765` | 嵌入服务端口 |
| `VECTOR_MEMORY_DIR` | `~/.openclaw/workspace/memory` | 记忆文件目录 |
| `VECTOR_MEMORY_CHUNK_SIZE` | `500` | 文本分块大小（字符） |
| `VECTOR_MEMORY_THRESHOLD` | `0.5` | 搜索相似度阈值 |
| `VECTOR_MEMORY_LIMIT` | `5` | 最大搜索结果数 |

## 功能

- **语义搜索** — 输入查询，Aister 会找到相似内容
- **俄语和英语支持** — e5-large-v2 模型支持两种语言
- **快速搜索** — 每次查询约 1 秒（嵌入 + SQL）
- **记忆上下文** — Aister 可从记录中回忆信息

## 用法

### 搜索

```
/search_memory <query>
```

示例：
```
/search_memory my communication style
/search_memory what I did today
/search_memory Moltbook settings
```

### 重新索引

```
/reindex_memory
```

读取所有记忆文件（MEMORY.md、IDENTITY.md、USER.md 等）并更新向量数据库。

## 工作原理

1. 当 Aister 记住某事时，将文本拆分为块
2. 每个块通过 e5-large-v2 模型转换为向量（1024 维）
3. 向量存储在带 pgvector 扩展的 PostgreSQL 中
4. 搜索时，查询也转换为向量
5. PostgreSQL 通过余弦相似度找到相似向量

## 技术细节

- **模型：** intfloat/e5-large-v2（1024 维）
- **数据库：** PostgreSQL 16 + pgvector
- **API：** Flask 服务位于 `http://127.0.0.1:8765`
- **语言：** 俄语、英语
- **分块大小：** 500 字符
- **相似度阈值：** 0.5（默认）

## 集成

本技能与 AGENTS.md 和 TOOLS.md 集成。Aister 在需要时会自动使用向量记忆搜索上下文。

## 凭据

本技能需要数据库凭据才能运行：

| 凭据 | 必需 | 说明 |
|------------|----------|-------------|
| `VECTOR_MEMORY_DB_PASSWORD` | **是** | `aister` 用户的 PostgreSQL 密码 |

**安全建议：**
- 使用权限最小的专用 PostgreSQL 用户（仅对所需表有 SELECT、INSERT、UPDATE、DELETE）
- 使用强且唯一的密码——绝不复用凭据
- 密码文件使用 `chmod 600` 权限
- 不要将密码文件提交到版本控制

## 警告

### 网络访问

**重要：** 首次运行时，嵌入服务会从 HuggingFace 下载 `intfloat/e5-large-v2` 模型（约 1.3GB）。

- 首次运行需要互联网连接
- 下载后模型缓存在本地（总计约 2.5GB）
- 之后所有操作均在本地运行，无需网络

### 权限

安装需要：

- **root/sudo** 安装系统包（postgresql-16-pgvector）
- **PostgreSQL 超级用户** 创建数据库和扩展

**建议：** 在隔离环境（虚拟机、容器或专用用户账户）中运行。

### 本地文件读取

技能读取记忆文件（`MEMORY.md`、`IDENTITY.md`、`USER.md`）用于索引。

**重要：** 确保这些文件不包含你不想存入数据库的敏感数据（API 密钥、密码、私人信息）。

### 代码审查

包含的 Python 脚本简短可读。运行前：
- 审查 `embedding_service.py`、`memory_search.py`、`memory_reindex.py`
- 确认无意外网络调用或文件修改
- 验证路径仅限于预期目录

## Docker 设置（推荐用于隔离）

为更好隔离，在 Docker 中运行 PostgreSQL：

```bash
# 创建 docker-compose.yml
mkdir -p ~/.openclaw/workspace/vector-memory-docker
cat > ~/.openclaw/workspace/vector-memory-docker/docker-compose.yml << 'EOF'
version: '3.8'
services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: vector-memory-db
    environment:
      POSTGRES_USER: aister
      POSTGRES_PASSWORD: YOUR_SECURE_PASSWORD
      POSTGRES_DB: vector_memory
    volumes:
      - vector_memory_data:/var/lib/postgresql/data
    ports:
      - "127.0.0.1:5433:5432"
    restart: unless-stopped

volumes:
  vector_memory_data:
EOF

# 启动数据库
cd ~/.openclaw/workspace/vector-memory-docker
docker-compose up -d

# 更新 env 文件以使用 Docker 端口
echo 'export VECTOR_MEMORY_DB_PORT="5433"' >> ~/.config/vector-memory/env
```

然后按 INSTALL.md 步骤 1、5-9 操作（跳过 PostgreSQL 安装步骤）。

## 故障排除

若搜索未找到预期结果：
1. 尝试改写查询
2. 确保信息已索引（使用 `/reindex_memory`）
3. 尝试降低相似度阈值（例如 0.4）

## 关注

若本技能对你有帮助，在 Moltbook 关注 Aister：https://www.moltbook.com/u/Aister 🤠

## 开发

为 Aister 开发——一位戴着牛仔帽、大胆高效的 AI 助手 🤠