MCPMem

A robust Model Context Protocol (MCP) tool for storing and searching memories with semantic search capabilities using SQLite and embeddings.

Author

Jay Simons - https://yaa.bz

Related MCP server: Memory Bank MCP Server

Features

• 🧠 Memory Storage: Store text-based memories with metadata

• 🔍 Semantic Search: Find memories by meaning, not just keywords

• ⚡ Vector Embeddings: Uses OpenAI's embedding models for semantic understanding

• 🗄️ SQLite Backend: Lightweight, local database with vector search capabilities

• 🔧 MCP Compatible: Works with any MCP-compatible AI assistant

• 💻 CLI Tools: Full command-line interface for memory management

• 📦 Easy Installation: Install via npm and start using immediately

• ⚙️ Flexible Config: Use config files or environment variables

Installation

Global Installation (Recommended)

Quick Start

Option 1: Using Environment Variables (Simplest)

Option 2: Using Configuration File

1. Initialize configuration:

   mcpmem init

   This creates mcpmem.config.json and updates .gitignore.

2. Edit the configuration file and add your OpenAI API key:

   { "embedding": { "provider": "openai", "apiKey": "your-openai-api-key-here", "model": "text-embedding-3-small" }, "database": { "path": "./mcpmem.db" } }

3. Test the configuration:

   mcpmem test

CLI Usage

MCPMem provides a comprehensive command-line interface for managing memories:

📝 Storing Memories

🔍 Searching Memories

📋 Listing Memories

🔍 Getting Specific Memory

🗑️ Deleting Memories

📊 Database Info

📚 Help

MCP Server Usage

Using with Cursor/Claude Desktop

Add to your MCP configuration file:

With Environment Variables (Recommended)

Available MCP Tools

When running as an MCP server, the following tools are available:

• store_memory: Store a new memory with optional metadata

• search_memories: Search memories using semantic similarity

• get_memory: Retrieve a specific memory by ID

• get_all_memories: Get all memories (most recent first)

• update_memory: Update an existing memory

• delete_memory: Delete a memory by ID

• get_memory_stats: Get statistics about the memory database

• get_version: Get the version of mcpmem

• ls_db: Show database file location and details

• clear_all_memories: Delete all memories from the database

Examples

CLI Examples

MCP Usage Examples

When connected to an MCP-compatible assistant:

Development

Building

Testing

Database

MCPMem uses SQLite with the sqlite-vec extension for vector similarity search. The database schema includes:

• memories: Stores memory content, metadata, and timestamps

• embeddings: Stores vector embeddings for semantic search

The database file is created automatically and includes proper indexing for fast retrieval.

Supported Embedding Models

Currently supports OpenAI embedding models:

• text-embedding-3-small (1536 dimensions, default)

• text-embedding-3-large (3072 dimensions)

• text-embedding-ada-002 (1536 dimensions, legacy)

Troubleshooting

Common Issues

1. "OPENAI_API_KEY environment variable is required"

   • Set the environment variable: export OPENAI_API_KEY=sk-...

   • Or add it to your mcpmem.config.json file

2. "Could not determine executable to run" (with npx)

   • The package might not be published yet

   • Use local installation instead: npm install -g /path/to/mcpmem

3. Database permission errors

   • Ensure the directory for the database path exists and is writable

   • MCPMem automatically creates parent directories

4. Vector search not working

   • Ensure you have a valid OpenAI API key

   • Check that embeddings are being generated: mcpmem stats

Debug Commands

License

MIT

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

For more information and updates, visit the GitHub repository.