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.

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:

pip install mcp-mem hipporag

Or install from source:

git clone https://github.com/ddkang1/mcp-mem.git
cd mcp-mem
pip install -e .
pip install hipporag

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

Usage

You can run the MCP server directly:

mcp-mem

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

mcp-mem --sse

You can also specify host and port for SSE transport:

mcp-mem --sse --host 127.0.0.1 --port 3001

Configuration

Basic Configuration

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

"memory": {
    "command": "/path/to/mcp-mem",
    "args": [],
    "type": "stdio",
    "pollingInterval": 30000,
    "startupTimeout": 30000,
    "restartOnFailure": true
}

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:

EMBEDDING_MODEL_NAME="your-model" LLM_NAME="your-llm" mcp-mem

For convenience, you can use the provided example script:

./examples/run_with_env_vars.sh

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

git clone https://github.com/ddkang1/mcp-mem.git
cd mcp-mem
pip install -e ".[dev]"

Running Tests

pytest

Code Style

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

black src tests
isort src tests
flake8 src tests

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.