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 始終返回源文件的絕對路徑

這確保了無論文件最初是如何添加到內存中的，路徑引用都是一致的。