# MCP Vector Memory
Semantic memory storage and retrieval for AI agents via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
Store knowledge as vector embeddings and retrieve them later through natural language similarity search — giving AI agents persistent, searchable long-term memory.
## Features
- **4 MCP Tools**: `save_memory`, `search_memory`, `list_projects`, `get_stats`
- **Vector Search**: Cosine similarity via pgvector (HNSW index) or SQLite (brute-force)
- **Multiple Embedding Providers**: Gemini (default), OpenAI, Local (MiniLM)
- **Project Tagging**: Organize memories by project/category
- **Dual Transport**: stdio (MCP client config) or SSE (HTTP service)
## Quick Start
### Install
```bash
pip install -e .
```
### Run (stdio — for MCP clients)
```bash
mcp-vector-memory
```
### Run (SSE — as HTTP service)
```bash
MCP_MEMORY_TRANSPORT=sse mcp-vector-memory
```
### MCP Client Configuration
Add to your MCP config (e.g. `mcp_config.json`):
```json
{
"mcpServers": {
"vertex-memory": {
"command": "mcp-vector-memory",
"env": {
"MCP_MEMORY_BACKEND": "postgres",
"MCP_MEMORY_EMBEDDINGS": "gemini",
"MCP_MEMORY_PG_HOST": "localhost",
"MCP_MEMORY_PG_PORT": "5432",
"MCP_MEMORY_PG_USER": "vertexhub",
"MCP_MEMORY_PG_PASS": "your-password",
"MCP_MEMORY_PG_DB": "mcp_memory",
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
## Environment Variables
| Variable | Default | Description |
|---|---|---|
| `MCP_MEMORY_BACKEND` | `postgres` | Database backend: `postgres` or `sqlite` |
| `MCP_MEMORY_EMBEDDINGS` | `gemini` | Embedding provider: `gemini`, `openai`, `local` |
| `MCP_MEMORY_TRANSPORT` | `stdio` | MCP transport: `stdio` or `sse` |
| `MCP_MEMORY_PORT` | `3001` | SSE server port |
| `MCP_MEMORY_LOG_LEVEL` | `INFO` | Log level |
| `MCP_MEMORY_PG_HOST` | `localhost` | PostgreSQL host |
| `MCP_MEMORY_PG_PORT` | `5432` | PostgreSQL port |
| `MCP_MEMORY_PG_USER` | `vertexhub` | PostgreSQL user |
| `MCP_MEMORY_PG_PASS` | — | PostgreSQL password |
| `MCP_MEMORY_PG_DB` | `mcp_memory` | PostgreSQL database |
| `MCP_MEMORY_SQLITE_PATH` | `memory.db` | SQLite file path |
| `GEMINI_API_KEY` | — | Google Gemini API key |
| `OPENAI_API_KEY` | — | OpenAI API key |
## Architecture
```
┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
│ MCP Client │────▶│ FastMCP │────▶│ Embedding │
│ (AI Agent) │ │ Server │ │ Provider │
└─────────────────┘ │ │ │ (Gemini/OAI) │
│ 4 tools: │ └─────────────────┘
│ save_memory │ │
│ search_mem │ ▼
│ list_proj │ ┌─────────────────┐
│ get_stats │────▶│ DB Backend │
└──────────────┘ │ (pgvector/ │
│ sqlite-vec) │
└─────────────────┘
```
## Docker
```bash
# Build
docker build -t mcp-vector-memory .
# Run (SSE mode)
docker run -p 3001:3001 \
-e MCP_MEMORY_PG_HOST=your-db-host \
-e MCP_MEMORY_PG_PASS=your-password \
-e GEMINI_API_KEY=your-key \
mcp-vector-memory
```
## License
MIT — see [LICENSE](LICENSE).
