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)

BASH

npm install -g mcpmem@latest

Quick Start

Option 1: Using Environment Variables (Simplest)

BASH

# 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

Initialize configuration:
BASH
```
mcpmem init
```

Edit the configuration file and add your OpenAI API key:

JSON

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

Test the configuration:
BASH
```
mcpmem test
```

CLI Usage

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

📝 Storing Memories

BASH

# 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

BASH

# Semantic search 
mcpmem search "database issues"

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

📋 Listing Memories

BASH

# Show recent memories
mcpmem list

# Show more memories
mcpmem list --limit 50

🔍 Getting Specific Memory

BASH

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

🗑️ Deleting Memories

BASH

# 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

BASH

# Show database statistics
mcpmem stats

# Show database file location and details
mcpmem ls_db

📚 Help

BASH

# 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 for the API key and model settings.

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

BASH

# 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

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

Development

Building

BASH

# Install dependencies
pnpm install

# Build the project
pnpm build

# Type checking
pnpm tc

Testing

BASH

# 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

BASH

# Check configuration and connectivity
mcpmem test

# View database statistics
mcpmem stats

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

License

MIT

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

View on GitHub View on NPM