Vector Memory MCP Server

An MCP server that gives AI assistants the ability to save and recall information from files or free-form notes. Works like a long-term memory system where you can store documents and retrieve relevant information later using natural language.

📖 Complete Usage Guide | 🔗 PyPI Package | 🌐 MCP Registry

Features

🧠 Semantic Memory: Save and recall text using natural language
📄 Multi-Format Support: PDF, TXT, and Markdown files
✍️ Free-Form Notes: Store ad-hoc text snippets without creating files
🔄 Auto-Update: Re-saving a file automatically removes old versions
🎯 Smart Chunking: Optimizes chunk size based on file type
🔍 Semantic Search: Find information even without exact word matches
🗂️ Memory Management: Built-in tools to list, search, and clean up memory
🔒 Data Isolation: Separate Redis databases and namespaces

Prerequisites

Python 3.12 or higher
Redis server running locally on port 6379
UV package manager

Start Redis

# Using Docker
docker run -d -p 6379:6379 redis:latest

# Or using Homebrew on macOS
brew install redis
brew services start redis

Quick Start

Installation

# Via pip
pip install mcp-server-vector-memory

# Via uvx (isolated environment)
uvx mcp-server-vector-memory

# From source
git clone https://github.com/NeerajG03/vector-memory.git
cd vector-memory
uv sync

Basic Usage

After pip install:

# Run the server
mcp-server-vector-memory

# Manage memory
vector-memory-manage list
vector-memory-cleanup stats

From source:

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

Integration with AI Clients

Claude Desktop (~/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"]

See USAGE.md for complete integration examples and advanced configuration.

Configuration

You can customize the server using environment variables or by editing vector_memory.py:

Environment Variables

REDIS_URL: Redis connection string (default: redis://localhost:6379/0)
- Format: redis://host:port/db_number
- Example: redis://localhost:6379/1 (use database 1)

Constants in Code

INDEX_NAME: Vector store index name (default: mcp_vector_memory)
- All keys are prefixed with this namespace to avoid conflicts
MODEL_NAME: Embedding model (default: sentence-transformers/all-MiniLM-L6-v2)

Data Isolation

The server uses multiple layers of isolation:

Database number: Uses Redis DB 0 by default (configurable via URL)
Index namespace: All keys prefixed with mcp_vector_memory:*
Metadata tagging: Each document tagged with source file path

This ensures your vector memory data won't conflict with other Redis applications.

Architecture

┌─────────────────┐
│  Claude/Client  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│  Vector Memory  │
│   MCP Server    │
└────────┬────────┘
         │
         ├─────► HuggingFace Embeddings
         │
         └─────► Redis Vector Store

Memory Management

Two management tools are included:

vector-memory-manage - Interactive tool with search and selective deletion
vector-memory-cleanup - Quick cleanup commands

See USAGE.md for complete documentation and examples.

Development

To run in development mode with auto-reload:

uv run --reload vector_memory.py

Troubleshooting

Redis Connection Error

Ensure Redis is running:

redis-cli ping
# Should return: PONG

Model Download

The first time you run the server, it will download the embedding model (~80MB). This is normal and only happens once.

File Not Found Errors

The server accepts both absolute and relative file paths, but automatically converts them to absolute paths for storage. If a file is not found, check that the path is correct relative to where the server is running.

Path Handling

Input: Accepts both absolute (/full/path/to/file.txt) and relative (./docs/file.txt) paths
Storage: All paths are converted to absolute paths before being saved to memory
Output: recall_from_memory always returns absolute paths to source files

This ensures consistent path references regardless of how files were originally added to memory.

Vector Memory