Vector Memory

🚀 向量内存MCP服务器

这是一个MCP服务器，它赋予AI助手从文件或自由格式笔记中保存和检索信息的能力。它就像一个长期记忆系统，你可以存储文档，并在之后使用自然语言检索相关信息。

📖 完整使用指南 | 🔗 PyPI软件包 | 🌐 MCP注册表

🚀 快速开始

安装

# 通过pip安装
pip install mcp-server-vector-memory

# 通过uvx（隔离环境）安装
uvx mcp-server-vector-memory

# 从源代码安装
git clone https://github.com/NeerajG03/vector-memory.git
cd vector-memory
uv sync

基础用法

通过pip安装后：

# 启动服务器
mcp-server-vector-memory

# 管理内存
vector-memory-manage list
vector-memory-cleanup stats

从源代码运行：

uv run vector_memory.py
uv run manage_memory.py list
uv run cleanup.py stats

与AI客户端集成

Claude桌面端 (~/Library/Application Support/Claude/claude_desktop_config.json)：

{
  "mcpServers": {
    "vector-memory": {
      "command": "uvx",
      "args": ["mcp-server-vector-memory"]
    }
  }
}

Codex CLI (~/.config/codex/mcp_config.toml)：

[servers.vector-memory]
command = "uvx"
args = ["mcp-server-vector-memory"]

完整的集成示例和高级配置请参阅 USAGE.md。

✨ 主要特性

• 🧠 语义记忆：使用自然语言保存和检索文本
• 📄 多格式支持：支持PDF、TXT和Markdown文件
• ✍️ 自由格式笔记：无需创建文件即可存储临时文本片段
• 🔄 自动更新：重新保存文件时会自动删除旧版本
• 🎯 智能分块：根据文件类型优化分块大小
• 🔍 语义搜索：即使没有精确的单词匹配也能找到信息
• 🗂️ 内存管理：内置工具可列出、搜索和清理内存
• 🔒 数据隔离：使用独立的Redis数据库和命名空间

📦 安装指南

前提条件

• Python 3.12或更高版本
• 在本地端口6379上运行的Redis服务器
• UV包管理器

启动Redis

# 使用Docker
docker run -d -p 6379:6379 redis:latest

# 或者在macOS上使用Homebrew
brew install redis
brew services start redis

📚 详细文档

配置

你可以使用环境变量或编辑 vector_memory.py 来自定义服务器：

环境变量

• REDIS_URL：Redis连接字符串（默认：redis://localhost:6379/0）
  • 格式：redis://host:port/db_number
  • 示例：redis://localhost:6379/1（使用数据库1）

代码中的常量

• INDEX_NAME：向量存储索引名称（默认：mcp_vector_memory）
  • 所有键都使用此命名空间作为前缀以避免冲突
• MODEL_NAME：嵌入模型（默认：sentence-transformers/all-MiniLM-L6-v2）

数据隔离

服务器使用多层隔离机制：

1. 数据库编号：默认使用Redis数据库0（可通过URL配置）
2. 索引命名空间：所有键都以 mcp_vector_memory:* 为前缀
3. 元数据标签：每个文档都使用源文件路径进行标记

这确保了你的向量内存数据不会与其他Redis应用程序冲突。

架构

┌─────────────────┐
│  Claude/Client  │
└────────┬────────┘
         │ MCP协议
         │
┌────────▼────────┐
│  向量内存       │
│   MCP服务器     │
└────────┬────────┘
         │
         ├─────► HuggingFace嵌入
         │
         └─────► Redis向量存储

内存管理

包含两个管理工具：

• vector-memory-manage - 具有搜索和选择性删除功能的交互式工具
• vector-memory-cleanup - 快速清理命令

完整文档和示例请参阅 USAGE.md。

开发

要在开发模式下运行并启用自动重新加载：

uv run --reload vector_memory.py

故障排除

Redis连接错误

确保Redis正在运行：

redis-cli ping
# 应返回：PONG

模型下载

首次运行服务器时，它将下载嵌入模型（约80MB）。这是正常现象，且只会发生一次。

文件未找到错误

服务器接受绝对路径（/full/path/to/file.txt）和相对路径（./docs/file.txt），但会在存储前自动将其转换为绝对路径。如果未找到文件，请检查路径相对于服务器运行位置是否正确。

路径处理

• 输入：接受绝对（/full/path/to/file.txt）和相对（./docs/file.txt）路径
• 存储：所有路径在保存到内存之前都会转换为绝对路径
• 输出：recall_from_memory 始终返回源文件的绝对路径

这确保了无论文件最初是如何添加到内存中的，路径引用都是一致的。