# 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
- **💾 Persistent Storage**: SQLite database with vector indexing via `sqlite-vec`
- **🏷️ Smart Organization**: Categories and tags for better memory organization
- **🔒 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
- **📈 Access Tracking**: Monitors memory usage with access counts and timestamps for optimization
- **🧠 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 |
| **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
│
└── .gitignore # Git exclusions
```
## 🗂️ Organization Guide
This project is organized for clarity and ease of use:
- **`main.py`** - Start here! Main server entry point
- **`src/`** - 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](https://docs.astral.sh/uv/) package manager
- Claude Desktop app
**Installing uv** (if not already installed):
macOS and Linux:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Verify installation:
```bash
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:
```bash
# Run without installation (like npx)
uvx vector-memory-mcp --working-dir /path/to/your/project
```
**Claude Desktop Configuration** (using uvx):
```json
{
"mcpServers": {
"vector-memory": {
"command": "uvx",
"args": [
"vector-memory-mcp",
"--working-dir",
"/absolute/path/to/your/project"
]
}
}
}
```
> **Note**: Publishing to PyPI is in progress. See [PUBLISHING.md](PUBLISHING.md) for details.
#### Option 2: Install from Source (For Development)
1. **Clone the project**:
```bash
git clone <repository-url>
cd vector-memory-mcp
```
2. **Install dependencies** (automatic with uv):
Dependencies are automatically managed via inline metadata in main.py. No manual installation needed.
To verify dependencies:
```bash
uv pip list
```
3. **Test the server**:
```bash
# Test with sample working directory
uv run main.py --working-dir ./test-memory
```
4. **Configure Claude Desktop**:
Copy the example configuration:
```bash
cp claude-desktop-config.example.json ~/path/to/your/config/
```
Open Claude Desktop Settings → Developer → Edit Config, and add (replace paths with absolute paths):
```json
{
"mcpServers": {
"vector-memory": {
"command": "uv",
"args": [
"run",
"/absolute/path/to/vector-memory-mcp/main.py",
"--working-dir",
"/your/project/path"
]
}
}
}
```
Important: Use absolute paths, not relative paths.
5. **Restart Claude Desktop** and look for the MCP integration icon.
#### Option 3: Install with pipx (Alternative)
```bash
# Install globally (once published to PyPI)
pipx install vector-memory-mcp
# Run
vector-memory-mcp --working-dir /path/to/your/project
```
**Claude Desktop Configuration** (using pipx):
```json
{
"mcpServers": {
"vector-memory": {
"command": "vector-memory-mcp",
"args": ["--working-dir", "/absolute/path/to/your/project"]
}
}
}
```
## 📚 Usage Guide
### Available Tools
#### 1. `store_memory` - Store Knowledge
Store coding experiences, solutions, and insights:
```
Please store this memory:
Content: "Fixed React useEffect infinite loop by adding dependency array with [userId, apiKey]. The issue was that the effect was recreating the API call function on every render."
Category: bug-fix
Tags: ["react", "useEffect", "infinite-loop", "hooks"]
```
#### 2. `search_memories` - Semantic Search
Find relevant memories using natural language:
```
Search for: "React hook dependency issues"
```
#### 3. `list_recent_memories` - Browse Recent
See what you've stored recently:
```
Show me my 10 most recent memories
```
#### 4. `get_memory_stats` - Database Health
View memory database statistics:
```
Show memory database statistics
```
#### 5. `clear_old_memories` - Cleanup
Clean up old, unused memories:
```
Clear memories older than 30 days, keep max 1000 total
```
#### 6. `get_by_memory_id` - Retrieve Specific Memory
Get full details of a specific memory by its ID:
```
Get memory with ID 123
```
Returns all fields including content, category, tags, timestamps, access count, and metadata.
#### 7. `delete_by_memory_id` - Delete Memory
Permanently remove a specific memory from the database:
```
Delete memory with ID 123
```
Removes the memory from both metadata and vector tables atomically.
### Memory Categories
| Category | Use Cases |
|----------|-----------|
| `code-solution` | Working code snippets, implementations |
| `bug-fix` | Bug fixes and debugging approaches |
| `architecture` | System design decisions and patterns |
| `learning` | New concepts, tutorials, insights |
| `tool-usage` | Tool configurations, CLI commands |
| `debugging` | Debugging techniques and discoveries |
| `performance` | Optimization strategies and results |
| `security` | Security considerations and fixes |
| `other` | Everything else |
## 🔧 Configuration
### Command Line Arguments
The server requires working directory specification:
```bash
# Run with uv (recommended)
uv run main.py --working-dir /path/to/project
# Working directory is where memory database will be stored
uv run main.py --working-dir ~/projects/my-project
```
### Working Directory Structure
```
your-project/
├── memory/
│ └── vector_memory.db # SQLite database with vectors
├── src/ # Your project files
└── other-files...
```
### Security Limits
- **Max memory content**: 10,000 characters
- **Max total memories**: 10,000 entries
- **Max search results**: 50 per query
- **Max tags per memory**: 10 tags
- **Path validation**: Blocks suspicious characters
## 🎯 Use Cases
### For Individual Developers
```
# Store a useful code pattern
"Implemented JWT refresh token logic using axios interceptors"
# Store a debugging discovery
"Memory leak in React was caused by missing cleanup in useEffect"
# Store architecture decisions
"Chose Redux Toolkit over Context API for complex state management because..."
```
### For Team Workflows
```
# Store team conventions
"Team coding style: always use async/await instead of .then() chains"
# Store deployment procedures
"Production deployment requires running migration scripts before code deploy"
# Store infrastructure knowledge
"AWS RDS connection pooling settings for high-traffic applications"
```
### For Learning & Growth
```
# Store learning insights
"Understanding JavaScript closures: inner functions have access to outer scope"
# Store performance discoveries
"Using React.memo reduced re-renders by 60% in the dashboard component"
# Store security learnings
"OWASP Top 10: Always sanitize user input to prevent XSS attacks"
```
## 🔍 How Semantic Search Works
The server uses **sentence-transformers** to convert your memories into 384-dimensional vectors that capture semantic meaning:
### Example Searches
| Query | Finds Memories About |
|-------|---------------------|
| "authentication patterns" | JWT, OAuth, login systems, session management |
| "database performance" | SQL optimization, indexing, query tuning, caching |
| "React state management" | useState, Redux, Context API, state patterns |
| "API error handling" | HTTP status codes, retry logic, error responses |
### Similarity Scoring
- **0.9+ similarity**: Extremely relevant, almost exact matches
- **0.8-0.9**: Highly relevant, strong semantic similarity
- **0.7-0.8**: Moderately relevant, good contextual match
- **0.6-0.7**: Somewhat relevant, might be useful
- **<0.6**: Low relevance, probably not helpful
## 📊 Database Statistics
The `get_memory_stats` tool provides comprehensive insights:
```json
{
"total_memories": 247,
"memory_limit": 10000,
"usage_percentage": 2.5,
"categories": {
"code-solution": 89,
"bug-fix": 67,
"learning": 45,
"architecture": 23,
"debugging": 18,
"other": 5
},
"recent_week_count": 12,
"database_size_mb": 15.7,
"health_status": "Healthy"
}
```
### Statistics Fields Explained
- **total_memories**: Current number of memories stored in the database
- **memory_limit**: Maximum allowed memories (default: 10,000)
- **usage_percentage**: Database capacity usage (total_memories / memory_limit * 100)
- **categories**: Breakdown of memory count by category type
- **recent_week_count**: Number of memories created in the last 7 days
- **database_size_mb**: Physical size of the SQLite database file on disk
- **health_status**: Overall database health indicator based on usage and performance metrics
## 🛡️ Security Features
### Input Validation
- Sanitizes all user input to prevent injection attacks
- Removes control characters and null bytes
- Enforces length limits on all content
### Path Security
- Validates and normalizes all file paths
- Prevents directory traversal attacks
- Blocks suspicious character patterns
### Resource Limits
- Limits total memory count and individual memory size
- Prevents database bloat and memory exhaustion
- Implements cleanup mechanisms for old data
### SQL Safety
- Uses parameterized queries exclusively
- No dynamic SQL construction from user input
- SQLite WAL mode for safe concurrent access
## 🔧 Troubleshooting
### Common Issues
#### Server Not Starting
```bash
# Check if uv is installed
uv --version
# Test server manually
uv run main.py --working-dir ./test
# Check Python version
python --version # Should be 3.10+
```
#### Claude Desktop Not Connecting
1. Verify absolute paths in configuration
2. Check Claude Desktop logs: `~/Library/Logs/Claude/`
3. Restart Claude Desktop after config changes
4. Test server manually before configuring Claude
#### Memory Search Not Working
- Verify sentence-transformers model downloaded successfully
- Check database file permissions in memory/ directory
- Try broader search terms
- Review memory content for relevance
#### Performance Issues
- Run `get_memory_stats` to check database health
- Use `clear_old_memories` to clean up old entries
- Consider increasing hardware resources for embedding generation
### Debug Mode
Run the server manually to see detailed logs:
```bash
uv run main.py --working-dir ./debug-test
```
## 🚀 Advanced Usage
### Batch Memory Storage
Store multiple related memories by calling the tool multiple times through Claude Desktop interface.
### Memory Organization Strategies
#### By Project
Use tags to organize by project:
- `["project-alpha", "frontend", "react"]`
- `["project-beta", "backend", "node"]`
- `["project-gamma", "devops", "docker"]`
#### By Technology Stack
- `["javascript", "react", "hooks"]`
- `["python", "django", "orm"]`
- `["aws", "lambda", "serverless"]`
#### By Problem Domain
- `["authentication", "security", "jwt"]`
- `["performance", "optimization", "caching"]`
- `["testing", "unit-tests", "mocking"]`
### Integration with Development Workflow
#### Code Review Learnings
```
"Code review insight: Extract validation logic into separate functions for better testability and reusability"
```
#### Sprint Retrospectives
```
"Sprint retrospective: Using feature flags reduced deployment risk and enabled faster rollbacks"
```
#### Technical Debt Tracking
```
"Technical debt: UserService class has grown too large, needs refactoring into smaller domain-specific services"
```
## 📈 Performance Benchmarks
Based on testing with various dataset sizes:
| Memory Count | Search Time | Storage Size | RAM Usage |
|--------------|-------------|--------------|-----------|
| 1,000 | <50ms | ~5MB | ~100MB |
| 5,000 | <100ms | ~20MB | ~200MB |
| 10,000 | <200ms | ~40MB | ~300MB |
*Tested on MacBook Air M1 with sentence-transformers/all-MiniLM-L6-v2*
## 🔧 Advanced Implementation Details
### Database Indexes
The memory store uses 4 optimized indexes for performance:
1. **idx_category**: Speeds up category-based filtering and statistics
2. **idx_created_at**: Optimizes temporal queries and recent memory retrieval
3. **idx_content_hash**: Enables fast deduplication checks via SHA-256 hash lookups
4. **idx_access_count**: Improves cleanup algorithm efficiency by tracking usage patterns
### Deduplication System
Content deduplication uses SHA-256 hashing to prevent storing identical memories:
- Hash calculated on normalized content (trimmed, lowercased)
- Check performed before insertion
- Duplicate attempts return existing memory ID
- Reduces storage overhead and maintains data quality
### Access Tracking
Each memory tracks usage statistics for intelligent management:
- **access_count**: Number of times memory retrieved via search or direct access
- **last_accessed_at**: Timestamp of most recent access
- **created_at**: Original creation timestamp
- Used by cleanup algorithm to identify valuable vs. stale memories
### Cleanup Algorithm
Smart cleanup prioritizes memory retention based on multiple factors:
1. **Recency**: Newer memories are prioritized over older ones
2. **Access patterns**: Frequently accessed memories are protected
3. **Age threshold**: Configurable days_old parameter for hard cutoff
4. **Count limit**: Maintains max_memories cap by removing least valuable entries
5. **Scoring system**: Combines access_count and recency for retention decisions
## 🤝 Contributing
This is a standalone MCP server designed for personal/team use. For improvements:
1. **Fork** the repository
2. **Modify** as needed for your use case
3. **Test** thoroughly with your specific requirements
4. **Share** improvements via pull requests
## 📄 License
This project is released under the MIT License.
## 🙏 Acknowledgments
- **sqlite-vec**: Alex Garcia's excellent SQLite vector extension
- **sentence-transformers**: Nils Reimers' semantic embedding library
- **FastMCP**: Anthropic's high-level MCP framework
- **Claude Desktop**: For providing the MCP integration platform
---
**Built for developers who want persistent AI memory without the complexity of dedicated vector databases.**
Raw data
{
"_id": null,
"home_page": null,
"name": "vector-memory-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, model-context-protocol, vector-search, sqlite, embeddings, semantic-search, claude, ai-memory",
"author": null,
"author_email": "Xsaven <xsaven@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/60/c9/60dc8ff56035cac5a904ba5d34f33567e27d9d6f13c6a6a6b7a866bb67d5/vector_memory_mcp-1.0.0.tar.gz",
"platform": null,
"description": "# Vector Memory MCP Server\n\nA **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.\n\n## \u2728 Features\n\n- **\ud83d\udd0d Semantic Search**: Vector-based similarity search using 384-dimensional embeddings\n- **\ud83d\udcbe Persistent Storage**: SQLite database with vector indexing via `sqlite-vec`\n- **\ud83c\udff7\ufe0f Smart Organization**: Categories and tags for better memory organization\n- **\ud83d\udd12 Security First**: Input validation, path sanitization, and resource limits\n- **\u26a1 High Performance**: Fast embedding generation with `sentence-transformers`\n- **\ud83e\uddf9 Auto-Cleanup**: Intelligent memory management and cleanup tools\n- **\ud83d\udcca Rich Statistics**: Comprehensive memory database analytics\n- **\ud83d\udd04 Automatic Deduplication**: SHA-256 content hashing prevents storing duplicate memories\n- **\ud83d\udcc8 Access Tracking**: Monitors memory usage with access counts and timestamps for optimization\n- **\ud83e\udde0 Smart Cleanup Algorithm**: Prioritizes memory retention based on recency, access patterns, and importance\n\n## \ud83d\udee0\ufe0f Technical Stack\n\n| Component | Technology | Purpose |\n|-----------|------------|---------|\n| **Vector DB** | sqlite-vec | Vector storage and similarity search |\n| **Embeddings** | sentence-transformers/all-MiniLM-L6-v2 | 384D text embeddings |\n| **MCP Framework** | FastMCP | High-level tools-only server |\n| **Dependencies** | uv script headers | Self-contained deployment |\n| **Security** | Custom validation | Path/input sanitization |\n| **Testing** | pytest + coverage | Comprehensive test suite |\n\n## \ud83d\udcc1 Project Structure\n\n```\nvector-memory-mcp/\n\u251c\u2500\u2500 main.py # Main MCP server entry point\n\u251c\u2500\u2500 README.md # This documentation\n\u251c\u2500\u2500 requirements.txt # Python dependencies\n\u251c\u2500\u2500 pyproject.toml # Modern Python project config\n\u251c\u2500\u2500 .python-version # Python version specification\n\u251c\u2500\u2500 claude-desktop-config.example.json # Claude Desktop config example\n\u2502\n\u251c\u2500\u2500 src/ # Core package modules\n\u2502 \u251c\u2500\u2500 __init__.py # Package initialization\n\u2502 \u251c\u2500\u2500 models.py # Data models & configuration\n\u2502 \u251c\u2500\u2500 security.py # Security validation & sanitization\n\u2502 \u251c\u2500\u2500 embeddings.py # Sentence-transformers wrapper\n\u2502 \u2514\u2500\u2500 memory_store.py # SQLite-vec operations\n\u2502\n\u2514\u2500\u2500 .gitignore # Git exclusions\n```\n\n## \ud83d\uddc2\ufe0f Organization Guide\n\nThis project is organized for clarity and ease of use:\n\n- **`main.py`** - Start here! Main server entry point\n- **`src/`** - Core implementation (security, embeddings, memory store)\n- **`claude-desktop-config.example.json`** - Configuration template\n\n**New here?** Start with `main.py` and `claude-desktop-config.example.json`\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n- Python 3.10 or higher (recommended: 3.11)\n- [uv](https://docs.astral.sh/uv/) package manager\n- Claude Desktop app\n\n**Installing uv** (if not already installed):\n\nmacOS and Linux:\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\nVerify installation:\n```bash\nuv --version\n```\n\n### Installation\n\n#### Option 1: Quick Install via uvx (Recommended)\n\nThe easiest way to use this MCP server - no cloning or setup required!\n\n**Once published to PyPI**, you can use it directly:\n\n```bash\n# Run without installation (like npx)\nuvx vector-memory-mcp --working-dir /path/to/your/project\n```\n\n**Claude Desktop Configuration** (using uvx):\n```json\n{\n \"mcpServers\": {\n \"vector-memory\": {\n \"command\": \"uvx\",\n \"args\": [\n \"vector-memory-mcp\",\n \"--working-dir\",\n \"/absolute/path/to/your/project\"\n ]\n }\n }\n}\n```\n\n> **Note**: Publishing to PyPI is in progress. See [PUBLISHING.md](PUBLISHING.md) for details.\n\n#### Option 2: Install from Source (For Development)\n\n1. **Clone the project**:\n ```bash\n git clone <repository-url>\n cd vector-memory-mcp\n ```\n\n2. **Install dependencies** (automatic with uv):\n Dependencies are automatically managed via inline metadata in main.py. No manual installation needed.\n\n To verify dependencies:\n ```bash\n uv pip list\n ```\n\n3. **Test the server**:\n ```bash\n # Test with sample working directory\n uv run main.py --working-dir ./test-memory\n ```\n\n4. **Configure Claude Desktop**:\n\n Copy the example configuration:\n ```bash\n cp claude-desktop-config.example.json ~/path/to/your/config/\n ```\n\n Open Claude Desktop Settings \u2192 Developer \u2192 Edit Config, and add (replace paths with absolute paths):\n\n ```json\n {\n \"mcpServers\": {\n \"vector-memory\": {\n \"command\": \"uv\",\n \"args\": [\n \"run\",\n \"/absolute/path/to/vector-memory-mcp/main.py\",\n \"--working-dir\",\n \"/your/project/path\"\n ]\n }\n }\n }\n ```\n\n Important: Use absolute paths, not relative paths.\n\n5. **Restart Claude Desktop** and look for the MCP integration icon.\n\n#### Option 3: Install with pipx (Alternative)\n\n```bash\n# Install globally (once published to PyPI)\npipx install vector-memory-mcp\n\n# Run\nvector-memory-mcp --working-dir /path/to/your/project\n```\n\n**Claude Desktop Configuration** (using pipx):\n```json\n{\n \"mcpServers\": {\n \"vector-memory\": {\n \"command\": \"vector-memory-mcp\",\n \"args\": [\"--working-dir\", \"/absolute/path/to/your/project\"]\n }\n }\n}\n```\n\n## \ud83d\udcda Usage Guide\n\n### Available Tools\n\n#### 1. `store_memory` - Store Knowledge\nStore coding experiences, solutions, and insights:\n\n```\nPlease store this memory:\nContent: \"Fixed React useEffect infinite loop by adding dependency array with [userId, apiKey]. The issue was that the effect was recreating the API call function on every render.\"\nCategory: bug-fix\nTags: [\"react\", \"useEffect\", \"infinite-loop\", \"hooks\"]\n```\n\n#### 2. `search_memories` - Semantic Search\nFind relevant memories using natural language:\n\n```\nSearch for: \"React hook dependency issues\"\n```\n\n#### 3. `list_recent_memories` - Browse Recent\nSee what you've stored recently:\n\n```\nShow me my 10 most recent memories\n```\n\n#### 4. `get_memory_stats` - Database Health\nView memory database statistics:\n\n```\nShow memory database statistics\n```\n\n#### 5. `clear_old_memories` - Cleanup\nClean up old, unused memories:\n\n```\nClear memories older than 30 days, keep max 1000 total\n```\n\n#### 6. `get_by_memory_id` - Retrieve Specific Memory\nGet full details of a specific memory by its ID:\n\n```\nGet memory with ID 123\n```\n\nReturns all fields including content, category, tags, timestamps, access count, and metadata.\n\n#### 7. `delete_by_memory_id` - Delete Memory\nPermanently remove a specific memory from the database:\n\n```\nDelete memory with ID 123\n```\n\nRemoves the memory from both metadata and vector tables atomically.\n\n### Memory Categories\n\n| Category | Use Cases |\n|----------|-----------|\n| `code-solution` | Working code snippets, implementations |\n| `bug-fix` | Bug fixes and debugging approaches |\n| `architecture` | System design decisions and patterns |\n| `learning` | New concepts, tutorials, insights |\n| `tool-usage` | Tool configurations, CLI commands |\n| `debugging` | Debugging techniques and discoveries |\n| `performance` | Optimization strategies and results |\n| `security` | Security considerations and fixes |\n| `other` | Everything else |\n\n## \ud83d\udd27 Configuration\n\n### Command Line Arguments\n\nThe server requires working directory specification:\n\n```bash\n# Run with uv (recommended)\nuv run main.py --working-dir /path/to/project\n\n# Working directory is where memory database will be stored\nuv run main.py --working-dir ~/projects/my-project\n```\n\n### Working Directory Structure\n\n```\nyour-project/\n\u251c\u2500\u2500 memory/\n\u2502 \u2514\u2500\u2500 vector_memory.db # SQLite database with vectors\n\u251c\u2500\u2500 src/ # Your project files\n\u2514\u2500\u2500 other-files...\n```\n\n### Security Limits\n\n- **Max memory content**: 10,000 characters\n- **Max total memories**: 10,000 entries\n- **Max search results**: 50 per query\n- **Max tags per memory**: 10 tags\n- **Path validation**: Blocks suspicious characters\n\n## \ud83c\udfaf Use Cases\n\n### For Individual Developers\n\n```\n# Store a useful code pattern\n\"Implemented JWT refresh token logic using axios interceptors\"\n\n# Store a debugging discovery \n\"Memory leak in React was caused by missing cleanup in useEffect\"\n\n# Store architecture decisions\n\"Chose Redux Toolkit over Context API for complex state management because...\"\n```\n\n### For Team Workflows\n\n```\n# Store team conventions\n\"Team coding style: always use async/await instead of .then() chains\"\n\n# Store deployment procedures\n\"Production deployment requires running migration scripts before code deploy\"\n\n# Store infrastructure knowledge\n\"AWS RDS connection pooling settings for high-traffic applications\"\n```\n\n### For Learning & Growth\n\n```\n# Store learning insights\n\"Understanding JavaScript closures: inner functions have access to outer scope\"\n\n# Store performance discoveries\n\"Using React.memo reduced re-renders by 60% in the dashboard component\"\n\n# Store security learnings\n\"OWASP Top 10: Always sanitize user input to prevent XSS attacks\"\n```\n\n## \ud83d\udd0d How Semantic Search Works\n\nThe server uses **sentence-transformers** to convert your memories into 384-dimensional vectors that capture semantic meaning:\n\n### Example Searches\n\n| Query | Finds Memories About |\n|-------|---------------------|\n| \"authentication patterns\" | JWT, OAuth, login systems, session management |\n| \"database performance\" | SQL optimization, indexing, query tuning, caching |\n| \"React state management\" | useState, Redux, Context API, state patterns |\n| \"API error handling\" | HTTP status codes, retry logic, error responses |\n\n### Similarity Scoring\n\n- **0.9+ similarity**: Extremely relevant, almost exact matches\n- **0.8-0.9**: Highly relevant, strong semantic similarity \n- **0.7-0.8**: Moderately relevant, good contextual match\n- **0.6-0.7**: Somewhat relevant, might be useful\n- **<0.6**: Low relevance, probably not helpful\n\n## \ud83d\udcca Database Statistics\n\nThe `get_memory_stats` tool provides comprehensive insights:\n\n```json\n{\n \"total_memories\": 247,\n \"memory_limit\": 10000,\n \"usage_percentage\": 2.5,\n \"categories\": {\n \"code-solution\": 89,\n \"bug-fix\": 67,\n \"learning\": 45,\n \"architecture\": 23,\n \"debugging\": 18,\n \"other\": 5\n },\n \"recent_week_count\": 12,\n \"database_size_mb\": 15.7,\n \"health_status\": \"Healthy\"\n}\n```\n\n### Statistics Fields Explained\n\n- **total_memories**: Current number of memories stored in the database\n- **memory_limit**: Maximum allowed memories (default: 10,000)\n- **usage_percentage**: Database capacity usage (total_memories / memory_limit * 100)\n- **categories**: Breakdown of memory count by category type\n- **recent_week_count**: Number of memories created in the last 7 days\n- **database_size_mb**: Physical size of the SQLite database file on disk\n- **health_status**: Overall database health indicator based on usage and performance metrics\n\n## \ud83d\udee1\ufe0f Security Features\n\n### Input Validation\n- Sanitizes all user input to prevent injection attacks\n- Removes control characters and null bytes\n- Enforces length limits on all content\n\n### Path Security\n- Validates and normalizes all file paths\n- Prevents directory traversal attacks\n- Blocks suspicious character patterns\n\n### Resource Limits\n- Limits total memory count and individual memory size\n- Prevents database bloat and memory exhaustion\n- Implements cleanup mechanisms for old data\n\n### SQL Safety\n- Uses parameterized queries exclusively\n- No dynamic SQL construction from user input\n- SQLite WAL mode for safe concurrent access\n\n## \ud83d\udd27 Troubleshooting\n\n### Common Issues\n\n#### Server Not Starting\n```bash\n# Check if uv is installed\nuv --version\n\n# Test server manually\nuv run main.py --working-dir ./test\n\n# Check Python version\npython --version # Should be 3.10+\n```\n\n#### Claude Desktop Not Connecting\n1. Verify absolute paths in configuration\n2. Check Claude Desktop logs: `~/Library/Logs/Claude/`\n3. Restart Claude Desktop after config changes\n4. Test server manually before configuring Claude\n\n#### Memory Search Not Working\n- Verify sentence-transformers model downloaded successfully\n- Check database file permissions in memory/ directory\n- Try broader search terms\n- Review memory content for relevance\n\n#### Performance Issues\n- Run `get_memory_stats` to check database health\n- Use `clear_old_memories` to clean up old entries\n- Consider increasing hardware resources for embedding generation\n\n### Debug Mode\n\nRun the server manually to see detailed logs:\n\n```bash\nuv run main.py --working-dir ./debug-test\n```\n\n## \ud83d\ude80 Advanced Usage\n\n### Batch Memory Storage\n\nStore multiple related memories by calling the tool multiple times through Claude Desktop interface.\n\n### Memory Organization Strategies\n\n#### By Project\nUse tags to organize by project:\n- `[\"project-alpha\", \"frontend\", \"react\"]`\n- `[\"project-beta\", \"backend\", \"node\"]`\n- `[\"project-gamma\", \"devops\", \"docker\"]`\n\n#### By Technology Stack\n- `[\"javascript\", \"react\", \"hooks\"]`\n- `[\"python\", \"django\", \"orm\"]`\n- `[\"aws\", \"lambda\", \"serverless\"]`\n\n#### By Problem Domain\n- `[\"authentication\", \"security\", \"jwt\"]`\n- `[\"performance\", \"optimization\", \"caching\"]`\n- `[\"testing\", \"unit-tests\", \"mocking\"]`\n\n### Integration with Development Workflow\n\n#### Code Review Learnings\n```\n\"Code review insight: Extract validation logic into separate functions for better testability and reusability\"\n```\n\n#### Sprint Retrospectives\n```\n\"Sprint retrospective: Using feature flags reduced deployment risk and enabled faster rollbacks\"\n```\n\n#### Technical Debt Tracking\n```\n\"Technical debt: UserService class has grown too large, needs refactoring into smaller domain-specific services\"\n```\n\n## \ud83d\udcc8 Performance Benchmarks\n\nBased on testing with various dataset sizes:\n\n| Memory Count | Search Time | Storage Size | RAM Usage |\n|--------------|-------------|--------------|-----------|\n| 1,000 | <50ms | ~5MB | ~100MB |\n| 5,000 | <100ms | ~20MB | ~200MB |\n| 10,000 | <200ms | ~40MB | ~300MB |\n\n*Tested on MacBook Air M1 with sentence-transformers/all-MiniLM-L6-v2*\n\n## \ud83d\udd27 Advanced Implementation Details\n\n### Database Indexes\n\nThe memory store uses 4 optimized indexes for performance:\n\n1. **idx_category**: Speeds up category-based filtering and statistics\n2. **idx_created_at**: Optimizes temporal queries and recent memory retrieval\n3. **idx_content_hash**: Enables fast deduplication checks via SHA-256 hash lookups\n4. **idx_access_count**: Improves cleanup algorithm efficiency by tracking usage patterns\n\n### Deduplication System\n\nContent deduplication uses SHA-256 hashing to prevent storing identical memories:\n- Hash calculated on normalized content (trimmed, lowercased)\n- Check performed before insertion\n- Duplicate attempts return existing memory ID\n- Reduces storage overhead and maintains data quality\n\n### Access Tracking\n\nEach memory tracks usage statistics for intelligent management:\n- **access_count**: Number of times memory retrieved via search or direct access\n- **last_accessed_at**: Timestamp of most recent access\n- **created_at**: Original creation timestamp\n- Used by cleanup algorithm to identify valuable vs. stale memories\n\n### Cleanup Algorithm\n\nSmart cleanup prioritizes memory retention based on multiple factors:\n1. **Recency**: Newer memories are prioritized over older ones\n2. **Access patterns**: Frequently accessed memories are protected\n3. **Age threshold**: Configurable days_old parameter for hard cutoff\n4. **Count limit**: Maintains max_memories cap by removing least valuable entries\n5. **Scoring system**: Combines access_count and recency for retention decisions\n\n## \ud83e\udd1d Contributing\n\nThis is a standalone MCP server designed for personal/team use. For improvements:\n\n1. **Fork** the repository\n2. **Modify** as needed for your use case\n3. **Test** thoroughly with your specific requirements\n4. **Share** improvements via pull requests\n\n## \ud83d\udcc4 License\n\nThis project is released under the MIT License.\n\n## \ud83d\ude4f Acknowledgments\n\n- **sqlite-vec**: Alex Garcia's excellent SQLite vector extension\n- **sentence-transformers**: Nils Reimers' semantic embedding library \n- **FastMCP**: Anthropic's high-level MCP framework\n- **Claude Desktop**: For providing the MCP integration platform\n\n---\n\n**Built for developers who want persistent AI memory without the complexity of dedicated vector databases.**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A secure, vector-based memory server for Claude Desktop using sqlite-vec and sentence-transformers",
"version": "1.0.0",
"project_urls": {
"Homepage": "https://github.com/xsaven/vector-memory-mcp",
"Issues": "https://github.com/xsaven/vector-memory-mcp/issues",
"Repository": "https://github.com/xsaven/vector-memory-mcp"
},
"split_keywords": [
"mcp",
" model-context-protocol",
" vector-search",
" sqlite",
" embeddings",
" semantic-search",
" claude",
" ai-memory"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4453cbec35330497a37147b74cd922a98a3af89e7dba671cbc8771a2a3188138",
"md5": "a33eef7fa4f9f24b2ef1b2e6af11bc69",
"sha256": "8c8e70daf0a365b19e834cb051d88327835dc4d36ca2cefef22e67db864ee78e"
},
"downloads": -1,
"filename": "vector_memory_mcp-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a33eef7fa4f9f24b2ef1b2e6af11bc69",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23827,
"upload_time": "2025-10-11T00:00:20",
"upload_time_iso_8601": "2025-10-11T00:00:20.283309Z",
"url": "https://files.pythonhosted.org/packages/44/53/cbec35330497a37147b74cd922a98a3af89e7dba671cbc8771a2a3188138/vector_memory_mcp-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "60c960dc8ff56035cac5a904ba5d34f33567e27d9d6f13c6a6a6b7a866bb67d5",
"md5": "8e03142d9897021862ee133a48f47477",
"sha256": "6ccce1d6e1db4291afdb571d14273aef2592dc3cbbc4a041ccc6bbc0af624fb1"
},
"downloads": -1,
"filename": "vector_memory_mcp-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "8e03142d9897021862ee133a48f47477",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 32322,
"upload_time": "2025-10-11T00:00:21",
"upload_time_iso_8601": "2025-10-11T00:00:21.905091Z",
"url": "https://files.pythonhosted.org/packages/60/c9/60dc8ff56035cac5a904ba5d34f33567e27d9d6f13c6a6a6b7a866bb67d5/vector_memory_mcp-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-11 00:00:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "xsaven",
"github_project": "vector-memory-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"0.3.0"
]
]
},
{
"name": "sqlite-vec",
"specs": [
[
">=",
"0.1.6"
]
]
},
{
"name": "sentence-transformers",
"specs": [
[
">=",
"2.2.2"
]
]
}
],
"lcname": "vector-memory-mcp"
}
JSON
