MCPMem

You can store, organize, and semantically search memories using MCPMem. It combines a lightweight SQLite database with vector embeddings to let you retrieve memories by meaning, not just keywords, and works smoothly with any MCP-compatible assistant. Use the MCPMem server to store memories, run semantic searches, and manage your memory corpus from your MCP-enabled workflow.

How to use

Set up MCPMem as an MCP server and connect it to your MCP-enabled assistant. You will be able to store memories with optional metadata, perform semantic searches that consider meaning, and retrieve or manage memories through a set of available tools. Use the assistant to store new memories, search for related memories, list recent memories, get specific memory details, and delete or clear memories as needed. The system uses a local SQLite database to store memories and embeddings for fast semantic retrieval.

How to install

# Global installation (recommended)
npm install -g mcpmem@latest

# Prerequisites: ensure Node.js and npm are installed
node -v
npm -v

# Example setup with environment variables
export OPENAI_API_KEY=sk-your-openai-api-key-here
export OPENAI_MODEL=text-embedding-3-small
export MCPMEM_DB_PATH=/path/to/memories.db

# Quick test and start
mcpmem test
mcpmem stats

# If you prefer a configuration file, you can initialize and edit it
mcpmem init

# Example configuration file content (mcpmem.config.json)
{
  "embedding": {
    "provider": "openai", 
    "apiKey": "your-openai-api-key-here",
    "model": "text-embedding-3-small"
  },
  "database": {
    "path": "./mcpmem.db"
  }
}

# Test the configuration
mcpmem test

Configuration and MCP server usage

MCPMem is designed to connect to an MCP-compatible assistant as an MCP server. The following standard configuration shows how to expose the server through an MCP entry point and specify environment variables for secure access to embeddings and the local database.

{
  "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"
      },
      "args": []
    }
  }
}

Tools and what you can do with them

The MCPMem server exposes a set of tools to manage memories and interact with the memory database. You can store memories, search semantically, retrieve specific memories, update entries, delete memories, and inspect database statistics.

Available tools include store_memory, search_memories, get_memory, get_all_memories, update_memory, delete_memory, get_memory_stats, get_version, ls_db, and clear_all_memories. Use these tools through your MCP client to perform actions directly from your assistant workflow.

Troubleshooting and tips

Common issues can involve missing API keys, incorrect API models, or database path permissions. Ensure OPENAI_API_KEY is set in the environment or in the configuration file, verify the chosen embedding model, and confirm the database file path is writable. If vector search isn’t returning results, verify that embeddings are generated and that the database is accessible.

Debug steps you can run locally include testing the MCPMem configuration, checking database statistics, and listing recent memories to verify storage.

Notes and examples

Examples show how to store memories with optional metadata, how to perform semantic searches with a query, and how to manage the memory set. You can store project notes, bug reports, meeting notes, or any textual memories, each optionally annotated with metadata such as project, type, severity, or environment.

Available tools

store_memory

Store a new memory with optional metadata for later semantic search and retrieval.

search_memories

Perform a semantic search over stored memories and return the most relevant results.

get_memory

Retrieve a specific memory by its unique identifier.

get_all_memories

Fetch all memories, typically returned with the most recent first.

update_memory

Update the content or metadata of an existing memory.

delete_memory

Delete a memory by its ID.

get_memory_stats

Get statistics about the memory database, such as counts and sizes.

get_version

Return the version of mcpmem running on the server.

ls_db

Show the database file location and its details.

clear_all_memories

Remove all memories from the database.