MCP Memory

A Model Context Protocol (MCP) server implementing memory solutions for data-rich applications with efficient knowledge graph capabilities.

Overview

This MCP server implements a memory solution for data-rich applications that involve searching information from many sources including uploaded files. It uses HippoRAG internally to manage memory through an efficient knowledge graph. HippoRAG is a required dependency for this package.

Related MCP server: Memory Custom

Features

• Session-based Memory: Create and manage memory for specific chat sessions

• Efficient Knowledge Graph: Uses HippoRAG for memory management

• Multiple Transport Support: Works with both stdio and SSE transports

• Search Capabilities: Search information from various sources including uploaded files

• Automatic Resource Management: TTL-based cleanup for both sessions and memory instances

Installation

Install from PyPI:

Or install from source:

Note: HippoRAG is a required dependency for mcp-mem to function.

Usage

You can run the MCP server directly:

By default, it uses stdio transport. To use SSE transport:

You can also specify host and port for SSE transport:

Configuration

Basic Configuration

To use this tool with Claude in Windsurf, add the following configuration to your MCP config file:

The command field should point to the directory where you installed the python package using pip.

Environment Variable Configuration

You can configure the LLM and embedding models used by mcp-mem through environment variables:

• EMBEDDING_MODEL_NAME: Name of the embedding model to use (default: "text-embedding-3-large")

• EMBEDDING_BASE_URL: Base URL for the embedding API (optional)

• LLM_NAME: Name of the LLM model to use (default: "gpt-4o-mini")

• LLM_BASE_URL: Base URL for the LLM API (optional)

• OPENAI_API_KEY: OpenAI API key (required)

Memory Management Configuration

The server includes automatic resource management features:

• Session TTL: Automatically removes session directories after a specified number of days of inactivity. Set using the session_ttl_days configuration parameter (default: None - disabled).

• Instance TTL: Automatically offloads HippoRAG instances from memory after a specified period of inactivity. Set using the instance_ttl_minutes configuration parameter (default: 30 minutes).

  This feature helps manage memory usage by unloading inactive instances while preserving the underlying data. When an offloaded instance is accessed again, it will be automatically reloaded from disk.

Example usage:

For convenience, you can use the provided example script:

Available Tools

The MCP server provides the following tools:

• create_memory: Create a new memory for a given chat session

• store_memory: Add memory to a specific session

• retrieve_memory: Retrieve memory from a specific session

Development

Installation for Development

Running Tests

Code Style

This project uses Black for formatting, isort for import sorting, and flake8 for linting:

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.