# Memory Vault MCP server

> Provides a persistent local-first memory layer for AI applications using Postgres and pgvector with hybrid semantic and keyword search.

- Repository: https://github.com/MihaiBuilds/memory-vault
- Page: https://hostedmcp.org/servers/mihaibuilds/memory-vault
- Official: yes
- Transport: stdio
- Stars: 67
- License: MIT
- Latest version: 1.6.1

## Install

### Claude Code

```sh
claude mcp add --env 'DB_PASSWORD=<YOUR_DB_PASSWORD>' --env 'DB_HOST=<DB_HOST>' --env 'DB_NAME=<DB_NAME>' --env 'DB_PORT=<DB_PORT>' --env 'DB_USER=<DB_USER>' memory-vault -- docker run -i --rm ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1
```

### Cursor (`~/.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "memory-vault": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1"
      ],
      "env": {
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_HOST": "<DB_HOST>",
        "DB_NAME": "<DB_NAME>",
        "DB_PORT": "<DB_PORT>",
        "DB_USER": "<DB_USER>"
      }
    }
  }
}
```

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "memory-vault": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1"
      ],
      "env": {
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_HOST": "<DB_HOST>",
        "DB_NAME": "<DB_NAME>",
        "DB_PORT": "<DB_PORT>",
        "DB_USER": "<DB_USER>"
      }
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"memory-vault","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1"],"env":{"DB_PASSWORD":"<YOUR_DB_PASSWORD>","DB_HOST":"<DB_HOST>","DB_NAME":"<DB_NAME>","DB_PORT":"<DB_PORT>","DB_USER":"<DB_USER>"}}'
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "memory-vault": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1"
      ],
      "env": {
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_HOST": "<DB_HOST>",
        "DB_NAME": "<DB_NAME>",
        "DB_PORT": "<DB_PORT>",
        "DB_USER": "<DB_USER>"
      }
    }
  }
}
```

### Codex

```sh
codex mcp add memory-vault --env 'DB_PASSWORD=<YOUR_DB_PASSWORD>' --env 'DB_HOST=<DB_HOST>' --env 'DB_NAME=<DB_NAME>' --env 'DB_PORT=<DB_PORT>' --env 'DB_USER=<DB_USER>' -- docker run -i --rm ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.memory-vault]
command = "docker"
args = ["run", "-i", "--rm", "ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1"]

[mcp_servers.memory-vault.env]
DB_PASSWORD = "<YOUR_DB_PASSWORD>"
DB_HOST = "<DB_HOST>"
DB_NAME = "<DB_NAME>"
DB_PORT = "<DB_PORT>"
DB_USER = "<DB_USER>"
```

### Gemini CLI

```sh
gemini mcp add -s user -e 'DB_PASSWORD=<YOUR_DB_PASSWORD>' -e 'DB_HOST=<DB_HOST>' -e 'DB_NAME=<DB_NAME>' -e 'DB_PORT=<DB_PORT>' -e 'DB_USER=<DB_USER>' memory-vault docker -- run -i --rm ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1
```

### Gemini settings.json (`~/.gemini/settings.json`)

```json
{
  "mcpServers": {
    "memory-vault": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/mihaibuilds/memory-vault-mcp:1.6.1"
      ],
      "env": {
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_HOST": "<DB_HOST>",
        "DB_NAME": "<DB_NAME>",
        "DB_PORT": "<DB_PORT>",
        "DB_USER": "<DB_USER>"
      }
    }
  }
}
```

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `DB_PASSWORD` | yes | yes | Postgres password for DB_USER |
| `DB_HOST` | yes | no | Hostname of the Postgres+pgvector instance Memory Vault connects to (e.g. 'host.docker.internal' when Postgres runs on the host, 'localhost' when running natively, or the service name when both run in compose) |
| `DB_NAME` | yes | no | Postgres database name |
| `DB_PORT` | yes | no | Postgres port |
| `DB_USER` | yes | no | Postgres user with read/write access to the memory vault database |
| `MCP_HTTP_ALLOWED_HOSTS` | no | no |  |
| `MCP_HTTP_ENABLED` | no | no |  |

## Tools (6)

- `recall`: Search your memories for information relevant to a query. Returns chunks ranked by relevance using hybrid search (vector + full-text + RRF). Uses query enrichment (keyword extraction + variation) for better recall. Results are budgeted to fit within max_tokens to avoid flooding context. Args: query: The search query — a question, topic, or keyword phrase. spaces: Filter to specific memory spaces (e.g. ["default", "projects"]). If omitted, searches all spaces. since: Only return memories after this date (ISO format, e.g. "2025-01-01"). limit: Maximum number of results (default 10, max 50). max_tokens: Token budget for results (default 2000). ef_search: How much of the vector index to search, 1-1000. Omit to use the default (40). Raise it when a search should have found something and did not — better recall, slower query. Worth trying before concluding a memory is missing.
- `remember`: Store a new memory in the system. The text is embedded and stored as a searchable chunk. Use this to save important information, decisions, or knowledge. Args: text: The text content to remember. space: Which memory space to store it in (default "default"). source: Where this memory comes from (default "mcp"). speaker: Who said/wrote this — "human" or "assistant" (default "human").
- `forget`: Soft-delete a memory chunk by ID. The chunk is removed from search results but stays in the database for potential recovery. Sets importance to 0 and marks it in metadata. Args: chunk_id: The UUID of the chunk to forget.
- `purge_forgotten`: Permanently delete memories that were forgotten a while ago. `forget` is a soft delete: the memory stops appearing in search but the row stays, so it can be recovered. Nothing removed it afterwards, so a vault that is edited often accumulated one dead row per edit forever. This is the deliberate, irreversible half. It is never automatic — there is no timer that quietly deletes your memories — and it only touches memories already marked forgotten, never active ones. Args: older_than_days: Only purge memories forgotten at least this many days ago. The default keeps a month of recovery, so purging right after an accidental forget still spares it. Pass 0 to purge every forgotten memory regardless of age.
- `move_memory`: Move a stored memory into a different space. The memory keeps its content and embedding; only the space it belongs to changes. Its knowledge-graph entries are rebuilt in the target space so the graph and search agree about where it lives. The target space must already exist — use the dashboard or the API to create one first. Args: chunk_id: The UUID of the chunk to move. target_space: Name of the space to move it into.
- `memory_status`: Get the current status of the memory system. Returns database health, chunk counts per space, and embedding model info.

## FAQ

### Does this require a GPU to run?

No, it is designed to be CPU-only by default, running embeddings and entity extraction on a normal laptop.

### How can I run Memory Vault quickly?

The easiest way is using Docker Compose with a single command.
