memory-mcp-server

pigmej/memory-mcp-server

3.2

If you are the rightful owner of memory-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Memory MCP Server is a lightweight server designed to provide persistent storage and retrieval of user-specific information, supporting multiple access protocols and a web UI for data management.

Memory MCP Server

A lightweight memory MCP (Model Context Protocol) server that provides persistent storage and retrieval of user-specific information including aliases, notes, observations, and hints. The server supports multiple access protocols and includes a web UI for data management with configurable semantic search capabilities.

Features

Memory Types

  • Aliases: Bidirectional mappings between terms and phrases
  • Notes: Personal information and reminders with categories
  • Observations: Contextual information about entities
  • Hints: Guidance for LLM interactions and workflows

Multiple Access Methods

  • MCP STDIO: Direct MCP protocol for AI clients
  • MCP HTTP API: HTTP Streaming MCP endpoints
  • HTTP REST API: Traditional REST endpoints
  • Web UI: Browser-based management interface
  • Combined Server: All interfaces in one server

Advanced Capabilities

  • Semantic Search: Configurable embedding models for intelligent search
  • User Separation: Keep data separate by user ID
  • RAG Support: Vector embeddings with similarity search
  • Export/Import: JSON and CSV export capabilities
  • Real-time Search: Search across all memory types simultaneously

āš ļø Important Notice

I use this MCP server on a daily basis, but I also use multiple AI tools to work on the codebase, so your mileage may vary. The server is actively developed and tested in my workflow, but different setups and use cases might encounter issues.

Installation

uvx --from git+https://github.com/pigmej/memory-mcp-server.git memory-mcp-server

Or install globally with uv:

uv tool install --from git+https://github.com/pigmej/memory-mcp-server.git memory-mcp-server

For local development:

git clone https://github.com/pigmej/memory-mcp-server.git
cd memory-mcp-server
uv sync
uvx --from . memory-mcp-server

Quick Start

1. Initialize the Server

memory-mcp-server init

2. Choose Your Server Mode

Combined Server (Recommended)

Run all interfaces on one port:

memory-mcp-server combined
  • Web UI: http://localhost:8080/ui/
  • MCP API: http://localhost:8080/mcp/
  • REST API: http://localhost:8080/api/
Individual Servers

Run specific interfaces separately:

# MCP STDIO (for AI clients)
memory-mcp-server stdio

# HTTP REST API only
memory-mcp-server http --port 8000

# Web UI only
memory-mcp-server web --port 8080

# MCP HTTP API (standalone)
memory-mcp-server mcp --port 8001

Configuration

Configuration File

Create a config.yaml file:

# Database settings
database:
  url: "sqlite:///memory_mcp.db"
  echo: false

# Server settings
server:
  host: "localhost"
  web_port: 8080
  http_port: 8000

# Embedding/Search settings
embedding:
  model_name: "all-MiniLM-L6-v2"  # Fast, lightweight
  # model_name: "all-mpnet-base-v2"  # Better quality
  similarity_threshold: 0.3
  max_results: 10
  cache_embeddings: true

# Logging
logging:
  level: "INFO"
  # file_path: "memory_mcp.log"

Environment Variables

# Database
DB_URL=sqlite:///memory_mcp.db

# Server
SERVER_HOST=0.0.0.0
SERVER_WEB_PORT=8080

# Embedding model
EMBEDDING_MODEL_NAME=all-mpnet-base-v2
EMBEDDING_SIMILARITY_THRESHOLD=0.5
EMBEDDING_MAX_RESULTS=20

# Logging
LOG_LEVEL=INFO

Command Line Options

# Custom config file
memory-mcp-server --config myconfig.yaml combined

# Custom host/port
memory-mcp-server combined --host 0.0.0.0 --port 8080

# Debug mode
memory-mcp-server --debug combined

Usage Examples

Web Interface

  1. Open http://localhost:8080 in your browser
  2. Create aliases, notes, observations, and hints
  3. Use the search interface to find information
  4. Export data as JSON or CSV

MCP HTTP API

# Create an alias
curl -X POST http://localhost:8080/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "create_alias",
    "arguments": {
      "source": "AI",
      "target": "Artificial Intelligence",
      "bidirectional": true
    }
  }'

# Search memories
curl -X POST http://localhost:8080/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "search_memories",
    "arguments": {
      "query": "machine learning",
      "limit": 10
    }
  }'

# List available tools
curl http://localhost:8080/mcp/tools/list

REST API

# Get all aliases
curl http://localhost:8080/api/aliases

# Create a note
curl -X POST http://localhost:8080/api/notes \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Meeting Notes",
    "content": "Discussed project timeline and deliverables",
    "category": "Work"
  }'

# Search across all types
curl -X POST http://localhost:8080/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "project", "limit": 5}'

Embedding Models

The server supports various sentence-transformer models:

Fast & Lightweight

  • all-MiniLM-L6-v2 (default) - 384 dimensions, fast
  • all-MiniLM-L12-v2 - 384 dimensions, better quality

High Quality

  • all-mpnet-base-v2 - 768 dimensions, best quality
  • all-distilroberta-v1 - 768 dimensions, good balance

Multilingual

  • paraphrase-multilingual-MiniLM-L12-v2 - 384 dimensions
  • paraphrase-multilingual-mpnet-base-v2 - 768 dimensions

Configure via embedding.model_name in config or EMBEDDING_MODEL_NAME environment variable.

Architecture

The server uses a clean, modular architecture:

memory_mcp_server/
ā”œā”€ā”€ assembly.py              # ASGI app composition layer
ā”œā”€ā”€ cli.py                   # Command-line interface
ā”œā”€ā”€ config.py                # Configuration management
ā”œā”€ā”€ models/                  # Pydantic data models
ā”‚   ā”œā”€ā”€ alias.py            # Alias model
ā”‚   ā”œā”€ā”€ note.py             # Note model
ā”‚   ā”œā”€ā”€ observation.py      # Observation model
ā”‚   ā””ā”€ā”€ hint.py             # Hint model
ā”œā”€ā”€ database/                # SQLAlchemy models and database layer
ā”‚   ā”œā”€ā”€ connection.py       # Database connection management
ā”‚   ā”œā”€ā”€ models.py           # SQLAlchemy models
ā”‚   ā””ā”€ā”€ repositories.py     # Data access layer
ā”œā”€ā”€ services/                # Business logic layer
ā”‚   ā”œā”€ā”€ memory_service.py   # Core memory operations
ā”‚   ā””ā”€ā”€ search_service.py   # Search and RAG capabilities
ā”œā”€ā”€ protocols/               # Protocol handlers
ā”‚   ā”œā”€ā”€ mcp_server.py       # MCP protocol implementation
ā”‚   ā””ā”€ā”€ http_server.py      # HTTP REST API
ā””ā”€ā”€ web/                     # Web UI components
    ā”œā”€ā”€ server.py           # Web server
    ā”œā”€ā”€ templates/          # Jinja2 templates
    ā””ā”€ā”€ static/             # CSS and static files

Design Principles

  • Separation of Concerns: Each component has a single responsibility
  • ASGI Composition: Individual servers return ASGI apps for flexible deployment
  • Configuration-Driven: Extensive configuration options
  • Protocol Agnostic: Same business logic serves multiple protocols

Development

Setup

git clone <repository>
cd memory-mcp-server
uv sync --dev

Testing

pytest
pytest --cov=memory_mcp_server

Code Quality

ruff format memory_mcp_server/
ruff check memory_mcp_server/
mypy memory_mcp_server/

License

MIT License