Secure vector-based memory server providing persistent semantic memory for AI
Vector Memory MCP Server
A secure, vector-based memory server for Claude Desktop using sqlite-vec and sentence-transformers. This MCP server provides persistent semantic memory capabilities that enhance AI coding assistants by remembering and retrieving relevant coding experiences, solutions, and knowledge.
✨ Features
- 🔍 Semantic Search: Vector-based similarity search using 384-dimensional embeddings
- 🏷️ Semantic Normalization: Auto-merge similar tags, normalize categories, structured colon tags
- 📊 IDF Tag Weights: Frequency-based weighting for improved search relevance
- 💾 Persistent Storage: SQLite database with vector indexing via
sqlite-vec - 🔒 Security First: Input validation, path sanitization, and resource limits
- ⚡ High Performance: Fast embedding generation with
sentence-transformers - 🧹 Auto-Cleanup: Intelligent memory management and cleanup tools
- 📈 Rich Statistics: Comprehensive memory database analytics
- 🔄 Automatic Deduplication: SHA-256 content hashing prevents storing duplicate memories
- 🧠 Smart Cleanup Algorithm: Prioritizes memory retention based on recency, access patterns, and importance
🛠️ Technical Stack
| Component | Technology | Purpose |
|---|---|---|
| Vector DB | sqlite-vec | Vector storage and similarity search |
| Embeddings | sentence-transformers/all-MiniLM-L6-v2 | 384D text embeddings |
| Normalization | Semantic similarity + guards | Tag/category auto-merge |
| MCP Framework | FastMCP | High-level tools-only server |
| Dependencies | uv script headers | Self-contained deployment |
| Security | Custom validation | Path/input sanitization |
| Testing | pytest + coverage | Comprehensive test suite |
📁 Project Structure
vector-memory-mcp/
├── main.py # Main MCP server entry point
├── README.md # This documentation
├── requirements.txt # Python dependencies
├── pyproject.toml # Modern Python project config
├── .python-version # Python version specification
├── claude-desktop-config.example.json # Claude Desktop config example
│
├── src/ # Core package modules
│ ├── __init__.py # Package initialization
│ ├── models.py # Data models & configuration
│ ├── security.py # Security validation & sanitization
│ ├── embeddings.py # Sentence-transformers wrapper
│ ├── memory_store.py # SQLite-vec operations
│ ├── README_AGENTS.md # Agent documentation (4 levels)
│ └── CASES_AGENTS.md # Use cases for Brain ecosystem
│
└── .gitignore # Git exclusions
🗂️ Organization Guide
This project is organized for clarity and ease of use:
main.py- Start here! Main server entry pointsrc/- Core implementation (security, embeddings, memory store)claude-desktop-config.example.json- Configuration template
New here? Start with main.py and claude-desktop-config.example.json
🚀 Quick Start
Prerequisites
- Python 3.10 or higher (recommended: 3.11)
- uv package manager
- Claude Desktop app
Installing uv (if not already installed):
macOS and Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Verify installation:
uv --version
Installation
Option 1: Quick Install via uvx (Recommended)
The easiest way to use this MCP server - no cloning or setup required!
Once published to PyPI, you can use it directly:
# Run without installation (like npx)
uvx vector-memory-mcp --working-dir /path/to/your/project
Claude Desktop Configuration (using uvx):
{
"mcpServers": {
"vector-memory": {
"command": "uvx",
"args": [
"vector-memory-mcp",
"--working-dir",
"/absolute/path/to/your/project",
"--memory-limit",
"100000"
]
}
}
}
Note:
--memory-limitis optional. Omit it to use default 10,000 entries.
Note: Publishing to PyPI is in progress. See PUBLISHING.md for details.
Option 2: Install from Source (For Development)
Clone the project:
git clone <repository-url> cd vector-memory-mcpInstall dependencies (automatic with uv): Dependencies are automatically managed via inline metadata in main.py. No manual installation needed.
To verify dependencies:
uv pip listTest the server:
# Test with sample working directory uv run main.py --working-dir ./test-memoryConfigure Claude Desktop:
Copy the example configuration:
cp claude-desktop-config.example.json ~/path/to/your/config/Open Claude Desk
Tools (4)
add_memoryStore a new memory with content, category, and tags for future semantic retrieval.search_memoryPerform a vector-based similarity search to find relevant past experiences or solutions.get_statsRetrieve comprehensive memory database analytics and storage statistics.cleanup_memoryRun the smart cleanup algorithm to manage memory limits based on recency and importance.Configuration
{"mcpServers": {"vector-memory": {"command": "uvx", "args": ["vector-memory-mcp", "--working-dir", "/absolute/path/to/your/project", "--memory-limit", "100000"]}}}