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

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)

npm install -g mcpmem@latest

Quick Start

Option 1: Using Environment Variables (Simplest)

# Set your API key
export OPENAI_API_KEY=sk-your-openai-api-key-here

# Optional: Customize model and database path
export OPENAI_MODEL=text-embedding-3-small
export MCPMEM_DB_PATH=/path/to/memories.db

# Test the configuration
mcpmem test

# Start using the CLI or MCP server
mcpmem stats

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

# Store a simple memory
mcpmem store "Remember to review the quarterly reports"

# Store memory with metadata
mcpmem store "API endpoint returns 500 errors" -m '{"project":"web-app","severity":"high"}'

🔍 Searching Memories

# Semantic search 
mcpmem search "database issues"

# Custom limits and thresholds
mcpmem search "bugs" --limit 5 --threshold 0.8

📋 Listing Memories

# Show recent memories
mcpmem list

# Show more memories
mcpmem list --limit 50

🔍 Getting Specific Memory

# Get memory details by ID
mcpmem get abc123-def456-789

🗑️ Deleting Memories

# Delete with confirmation
mcpmem delete abc123-def456-789

# Force delete (no confirmation)
mcpmem delete abc123-def456-789 --force

# Clear all memories (with confirmation)
mcpmem clear

# Force clear all memories (no confirmation)
mcpmem clear --force

📊 Database Info

# Show database statistics
mcpmem stats

# Show database file location and details
mcpmem ls_db

📚 Help

# Show all available commands
mcpmem --help

# Show detailed examples and usage
mcpmem help-commands

# Get help for a specific command
mcpmem search --help

MCP Server Usage

Using with Cursor/Claude Desktop

Add to your MCP configuration file:

With Environment Variables (Recommended)

{
  "mcpServers": {
    "mcpmem": {
      "command": "mcpmem",
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key-here",
        "OPENAI_MODEL": "text-embedding-3-small",
        "MCPMEM_DB_PATH": "/path/to/memories.db"
      }
    }
  }
}

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

# Store project-related memories
mcpmem store "Fixed the authentication bug in user login" -m '{"project":"web-app","type":"bug-fix"}'
mcpmem store "Meeting notes: Discussed Q4 roadmap priorities" -m '{"type":"meeting","quarter":"Q4"}'

# Search for memories
mcpmem search "authentication issues"
mcpmem search "meeting" --limit 3

# Manage memories
mcpmem list --limit 10
mcpmem get memory-id-here
mcpmem delete old-memory-id --force
mcpmem clear --force

MCP Usage Examples

When connected to an MCP-compatible assistant:

Assistant: I'll help you store that memory about the bug fix.

*Uses store_memory tool*
- Content: "Fixed authentication timeout issue in production"
- Metadata: {"severity": "high", "environment": "production"}

Memory stored successfully with ID: abc123-def456

Assistant: Let me search for previous issues related to authentication.

*Uses search_memories tool with query "authentication problems"*

Found 3 related memories:
1. Fixed authentication timeout issue (similarity: 85%)
2. Updated auth middleware configuration (similarity: 78%)
3. Resolved login redirect bug (similarity: 72%)

Development

Building

# Install dependencies
pnpm install

# Build the project
pnpm build

# Type checking
pnpm tc

Testing

# Run tests
pnpm test

# Test configuration
mcpmem test

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

# Check configuration and connectivity
mcpmem test

# View database statistics
mcpmem stats

# List recent memories to verify storage
mcpmem list --limit 5

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.