long-term-memory-mcp

Long Term Memory MCP Server

A Model Context Protocol (MCP) server that provides long-term memory capabilities for LLMs using Azure Table Storage.

Features

This MCP server provides three main tools for managing long-term memories:

1. GetMemories - Retrieve all memories for a specific user identifier (UPN)
2. SaveMemory - Save a new memory for a user with concise memory text
3. DeleteMemory - Delete a specific memory by its memory ID

Prerequisites

• .NET 9.0 SDK or later
• Azure Storage Account (Table Storage)

Setup

1. Clone or download this project
2. Copy the example configuration file and configure your Azure Storage connection:

   cp appsettings.json.example appsettings.json
   

3. Edit appsettings.json and replace the placeholder values with your actual Azure Storage account details:

   {
     "ConnectionStrings": {
       "AzureTableStorage": "DefaultEndpointsProtocol=https;AccountName=YOUR_STORAGE_ACCOUNT_NAME;AccountKey=YOUR_STORAGE_ACCOUNT_KEY;EndpointSuffix=core.windows.net"
     }
   }
   

4. Restore NuGet packages:

   dotnet restore
   

5. Run the server:

   dotnet run
   

The server will start on http://localhost:5000/mcp by default.

Endpoints

• MCP Endpoint: http://localhost:5000/mcp
• SSE Endpoint: http://localhost:5000/mcp/sse (for older clients)
• Health Check: http://localhost:5000/health
• Info: http://localhost:5000

MCP Tools

GetMemories

Retrieves all long-term memories for a specific user identifier (UPN).

Parameters:

• userIdentifier (string): User identifier (UPN) to retrieve memories for

Returns: Simple line-by-line text format of memory contents (concise for LLM context)

LLM Usage Rules:

• Call this tool ONLY ONCE when a new conversation starts to load the user's memory context
• DO NOT mention memory IDs or discuss the existence of memories with the user unless they explicitly ask
• Use retrieved memories silently as background context to inform responses
• If you don't know the user's UPN/identifier, ASK the user for it before calling this tool
• Memories should enhance understanding of user preferences, history, and context without being explicitly referenced

SaveMemory

Saves a new long-term memory for a specific user identifier (UPN).

Parameters:

• userIdentifier (string): User identifier (UPN) to save memory for
• conciseMemoryText (string): Concise but informative memory text to store for long-term context

Returns: JSON object with memory details including generated memory ID

LLM Usage Rules:

• Save concise, meaningful information that would be valuable for future conversations
• Focus on user preferences, important facts, goals, context, and significant details
• Keep memories concise but informative - avoid saving trivial information
• Save memories when you learn something new about the user that would enhance future interactions
• Don't save every detail - only information that provides lasting value

DeleteMemory

Deletes a specific long-term memory by its memory ID.

Parameters:

• memoryText (string): Exact memory text to delete (obtained from GetMemories response)

Returns: JSON object indicating success/failure

LLM Usage Rules:

• Use this tool when conflicting information emerges that contradicts an existing memory
• Delete duplicate or near-duplicate memories when identified after retrieving memories
• Remove memories that are no longer relevant or have been superseded by newer, more accurate information
• Only delete memories when there's a clear reason (conflict, duplication, or obsolescence)
• Use the exact memory text from the GetMemories response to specify which memory to delete

Azure Table Storage

The server uses Azure Table Storage to persist memories with the following structure:

• Table Name: LongTermMemories
• Partition Key: User identifier (UPN)
• Row Key: Unique memory ID (GUID)
• Properties: MemoryText, CreatedAt, UpdatedAt

Configuration

The Azure Storage connection string is configured in appsettings.json. The appsettings.json file is excluded from version control for security reasons. Use the provided appsettings.json.example as a template to create your own configuration file.

Important Security Notes:

• Never commit appsettings.json to version control as it contains sensitive connection strings
• Always use appsettings.json.example as a template for new deployments
• For production environments, consider using Azure Key Vault or environment variables for additional security

Usage with MCP Clients

This server can be used with any MCP-compatible client such as:

• Claude Desktop
• Cursor IDE
• Custom MCP clients

Connect to http://localhost:5000 to access the memory tools.

Development

The project structure:

LongTermMemoryMcp/
├── Models/
│   └── MemoryEntity.cs          # Azure Table Storage entity
├── Services/
│   └── MemoryService.cs         # Business logic for memory operations
├── Tools/
│   └── LongTermMemoryTools.cs   # MCP tool definitions
├── Program.cs                   # Main application setup
├── appsettings.json            # Configuration
└── LongTermMemoryMcp.csproj    # Project file

Error Handling

All tools include comprehensive error handling and return descriptive error messages when operations fail.