Vector Memory MCP Server

Semantic memory storage for AI assistants. Store decisions, patterns, and context that persists across sessions.

A local-first MCP server that provides vector-based memory storage. Uses local embeddings and SQLite with sqlite-vec for fast, private semantic search — all in a single file.

Features

• Local & Private - All embeddings generated locally (all-MiniLM-L6-v2, 384-dim), data stored in a single SQLite file

• Semantic Search - Hybrid vector + full-text search with intent-based ranking

• Batch Operations - Store, update, delete, and retrieve multiple memories at once

• Session Waypoints - Save and restore project context between sessions

• Conversation History - Index and search Claude Code session transcripts

• MCP Native - Standard protocol, works with any MCP-compatible client

Related MCP server: Memorious MCP

Installation

There are two ways to install Vector Memory, depending on how much integration you want.

Option A: Claude Code Plugin (recommended)

Install as a plugin to get the full experience: MCP server, session lifecycle hooks, waypoint skills, and context monitoring — all managed automatically.

# Add the marketplace
claude plugin marketplace add AerionDyseti/vector-memory-mcp

# Install the plugin
claude plugin install vector-memory@vector-memory-mcp

This clones the repo and runs the MCP server directly from source. Hooks handle session start/clear/compact events, and skills provide /waypoint:set, /waypoint:get, and memory usage guidance.

Option B: MCP Server Only

Install just the MCP server via npm if you want memory storage without hooks or skills, or if you're using a non-Claude Code MCP client.

bun install -g @aeriondyseti/vector-memory-mcp

First install downloads ML models (~90MB). This may take a minute.

Then add to your MCP client config (e.g., ~/.claude/settings.json):

{
  "mcpServers": {
    "vector-memory": {
      "type": "stdio",
      "command": "bunx",
      "args": ["--bun", "@aeriondyseti/vector-memory-mcp"]
    }
  }
}

Prerequisites

• Bun 1.0+

• An MCP-compatible client (Claude Code, Claude Desktop, etc.)

Tools

Restart your MCP client after installation. You now have access to:

Usage

Store a memory:

You: "Remember that we use Drizzle ORM for database access"
Assistant: [calls store_memories]

Search memories:

You: "What did we decide about the database?"
Assistant: [calls search_memories with relevant query]

Session waypoints:

You: "Save context for next session"
Assistant: [calls set_waypoint with summary, completed items, next steps]

Conversation history (requires --enable-history):

You: "What did we discuss about the API design last week?"
Assistant: [calls search_memories with history_only: true, history_before/after filters]

Storage Model

All memories live in a single global database (~/.vector-memory/memories.db) shared by every project. Each memory is tagged with the project (working directory) it was stored from:

• Searches default to all projects — results carry their project path, and hits from the current project rank slightly higher. Use scope: "project" to restrict a search to the current repo.

• Waypoints are per-project and resolved automatically from the working directory.

• A repo-local database is still available via --db-file or VECTOR_MEMORY_DB_PATH (note: keep the db on local disk — WAL mode misbehaves on network filesystems like NFS home directories).

Migrating repo-local databases

Projects that used the old per-repo .vector-memory/ layout can be imported into the global store:

# Import the current repo's .vector-memory/memories.db
bunx @aeriondyseti/vector-memory-mcp consolidate

# Scan a whole directory tree and import every repo-local db found
bunx @aeriondyseti/vector-memory-mcp consolidate ~/Development --recursive

# Preview without writing (prints planned imports and ID re-keys)
bunx @aeriondyseti/vector-memory-mcp consolidate --dry-run

Consolidation tags every imported memory with its repo's path, preserves embeddings and usefulness stats, deduplicates by ID, re-keys waypoints to their per-project IDs (remapping references), and backs up the global db first. --archive renames the source .vector-memory/ to .vector-memory.migrated/ after a successful import; --force skips the live-server check.

Configuration

CLI flags:

Release Channels

Plugin users: The plugin runs the @latest npm release.

npm users: The stable release is what you get by default:

bun install -g @aeriondyseti/vector-memory-mcp

Pre-releases are published to @next for testing upcoming changes. They are unstable and may break without notice — use at your own risk.

# Install the pre-release channel
bun install -g @aeriondyseti/vector-memory-mcp@next

# Go back to stable
bun install -g @aeriondyseti/vector-memory-mcp@latest

Warning: Pre-release versions may include breaking changes, incomplete features, or data migration requirements that haven't been finalized. Do not use them in production workflows you depend on.

Migrating from 1.x (LanceDB)

Version 2.0 replaced LanceDB with SQLite (sqlite-vec) for storage. If you have existing data from 1.x, the server will detect it automatically and prompt you to migrate:

vector-memory-mcp migrate

This reads your LanceDB directory, writes a new SQLite file, and prints instructions to swap them. Your original data is preserved until you manually remove it.

What changed:

• Storage: LanceDB directory (~845 files) → single .db file

• Dependencies: 223MB (@lancedb/lancedb + apache-arrow) → 24KB (sqlite-vec)

• Runtime: Node.js support dropped, Bun required (for bun:sqlite)

Development

git clone https://github.com/AerionDyseti/vector-memory-mcp.git
cd vector-memory-mcp
bun install

bun run test      # Run all tests
bun run dev       # Watch mode
bun run typecheck # Type checking

See CHANGELOG.md for release history and ROADMAP.md for planned features.

Contributing

Contributions welcome! See issues for areas we'd love help with.

License

MIT - see LICENSE

Built with MCP SDK, sqlite-vec, and Transformers.js