# MCP Vector Memory

**Persistent vector memory for AI coding agents.** Give your AI agents long-term memory that survives across conversations.

Works with **Antigravity** · **VS Code / Copilot** · **Claude Code** · **Codex**

---

## The Problem

AI coding agents forget everything between conversations. Every new session starts from zero — they repeat questions, lose architectural decisions, and forget how your project is set up.

## The Solution

**MCP Vector Memory** gives your agents persistent, semantic memory. Agents can save and search memories using natural language. Memories are stored locally in SQLite with vector similarity search — **no API keys, no cloud, no cost**.

```
Agent: "I need to set up the database"
  → search_memory("database setup") 
  → Returns: "PostgreSQL 18 with pgvector, HNSW index, user=app_user..."
  → Agent works WITH full context from past sessions
```

## Quick Start

### 1. Install

```bash
pip install mcp-vector-memory
```

### 2. Configure Your IDE

<details>
<summary><b>🌌 Google Antigravity</b></summary>

Add to `~/.gemini/antigravity/mcp_config.json`:

```json
{
  "mcpServers": {
    "memory": {
      "command": "mcp-vector-memory",
      "args": [],
      "env": {}
    }
  }
}
```
</details>

<details>
<summary><b>💻 VS Code / GitHub Copilot</b></summary>

Create `.vscode/mcp.json` in your workspace:

```json
{
  "mcp": {
    "servers": {
      "memory": {
        "command": "mcp-vector-memory",
        "args": [],
        "env": {}
      }
    }
  }
}
```
</details>

<details>
<summary><b>🤖 Claude Code (CLI & Desktop)</b></summary>

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "memory": {
      "command": "mcp-vector-memory",
      "args": [],
      "env": {}
    }
  }
}
```
</details>

<details>
<summary><b>⚡ OpenAI Codex (CLI & IDE)</b></summary>

Add to your Codex MCP configuration:

```json
{
  "mcpServers": {
    "memory": {
      "command": "mcp-vector-memory",
      "args": [],
      "env": {}
    }
  }
}
```
</details>

### 3. Restart your IDE

That's it. Your agents now have persistent memory.

## Tools Available

| Tool | Description |
|------|-------------|
| `search_memory` | Semantic search over past memories |
| `save_memory` | Save a decision, context, or learning |
| `list_projects` | List all projects with memory counts |
| `get_stats` | Memory system statistics |

## How It Works

```
┌─────────────────┐     ┌──────────────────────┐     ┌─────────────┐
│   AI Agent      │────▶│  MCP Vector Memory   │────▶│   SQLite    │
│  (any IDE)      │◀────│  (local process)     │◀────│  + vectors  │
└─────────────────┘     └──────────────────────┘     └─────────────┘
                              │
                         Embeddings
                      (all-MiniLM-L6-v2)
                        runs locally
```

1. Agent calls `save_memory` → text is embedded locally → stored in SQLite with vector index
2. Agent calls `search_memory` → query is embedded → SQLite finds most similar memories
3. Everything runs **locally**. No API calls, no cloud, no cost.

## Configuration

All configuration is via environment variables:

| Variable | Default | Description |
|----------|---------|-------------|
| `MCP_MEMORY_BACKEND` | `sqlite` | Database backend (`sqlite` or `postgres`) |
| `MCP_MEMORY_DATA_DIR` | `~/.mcp-vector-memory` | SQLite data directory |
| `MCP_MEMORY_EMBEDDING_PROVIDER` | `local` | Embedding provider (`local` or `openai`) |
| `MCP_MEMORY_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Embedding model name |

### PostgreSQL Backend (Optional)

For production deployments with PostgreSQL + pgvector:

```bash
pip install mcp-vector-memory[postgres]
```

```bash
MCP_MEMORY_BACKEND=postgres
PGHOST=localhost
PGPORT=5432
PGUSER=mcp_memory
PGPASSWORD=your_password
PGDATABASE=mcp_memory
```

### Docker (PostgreSQL)

```bash
docker compose up -d
```

See [docker-compose.yml](docker-compose.yml) for the full setup.

### OpenAI Embeddings (Optional)

For higher quality embeddings via OpenAI API:

```bash
pip install mcp-vector-memory[openai]
export OPENAI_API_KEY=sk-...
export MCP_MEMORY_EMBEDDING_PROVIDER=openai
```

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT — see [LICENSE](LICENSE)