Memory MCP

A Model Context Protocol (MCP) server for logging and retrieving memories from LLM conversations with intelligent context window caching capabilities.

Features

• Save Memories: Store memories from LLM conversations with timestamps and LLM identification
• Retrieve Memories: Get all stored memories with detailed metadata
• Add Memories: Append new memories without overwriting existing ones
• Clear Memories: Remove all stored memories
• Context Window Caching: Archive, retrieve, and summarize conversation context
• Relevance Scoring: Automatically score archived content relevance to current context
• Tag-based Search: Categorize and search context by tags
• Conversation Orchestration: External system to manage context window caching
• MongoDB Storage: Persistent storage using MongoDB database

Installation

Option 1: Install from npm (Recommended)

npm install -g @jamesanz/memory-mcp

The package will automatically configure Claude Desktop on installation.

Option 2: Install from source

1. Install dependencies:

npm install

2. Build the project:

npm run build

Configuration

Set the MongoDB connection string via environment variable:

export MONGODB_URI="mongodb://localhost:27017"

Default: mongodb://localhost:27017

Usage

Running the MCP Server

Start the MCP server:

npm start

Running the Conversation Orchestrator Demo

Try the interactive CLI demo:

npm run cli

The CLI demo allows you to:

• Add messages to simulate conversation
• See automatic archiving when context gets full
• Trigger manual archiving and retrieval
• Create summaries of archived content
• Monitor conversation status and get recommendations

Basic Memory Tools

1. save-memories: Save all memories to the database, overwriting existing ones

   • memories: Array of memory strings to save
   • llm: Name of the LLM (e.g., 'chatgpt', 'claude')
   • userId: Optional user identifier

2. get-memories: Retrieve all memories from the database

   • No parameters required

3. add-memories: Add new memories to the database without overwriting existing ones

   • memories: Array of memory strings to add
   • llm: Name of the LLM (e.g., 'chatgpt', 'claude')
   • userId: Optional user identifier

4. clear-memories: Clear all memories from the database

   • No parameters required

Context Window Caching Tools

5. archive-context: Archive context messages for a conversation with tags and metadata

   • conversationId: Unique identifier for the conversation
   • contextMessages: Array of context messages to archive
   • tags: Tags for categorizing the archived content
   • llm: Name of the LLM (e.g., 'chatgpt', 'claude')
   • userId: Optional user identifier

6. retrieve-context: Retrieve relevant archived context for a conversation

   • conversationId: Unique identifier for the conversation
   • tags: Optional tags to filter by
   • minRelevanceScore: Minimum relevance score (0-1, default: 0.1)
   • limit: Maximum number of items to return (default: 10)

7. score-relevance: Score the relevance of archived context against current conversation context

   • conversationId: Unique identifier for the conversation
   • currentContext: Current conversation context to compare against
   • llm: Name of the LLM (e.g., 'chatgpt', 'claude')

8. create-summary: Create a summary of context items and link them to the summary

   • conversationId: Unique identifier for the conversation
   • contextItems: Context items to summarize
   • summaryText: Human-provided summary text
   • llm: Name of the LLM (e.g., 'chatgpt', 'claude')
   • userId: Optional user identifier

9. get-conversation-summaries: Get all summaries for a specific conversation

   • conversationId: Unique identifier for the conversation

10. search-context-by-tags: Search archived context and summaries by tags

    • tags: Tags to search for

Example Usage in LLM

Basic Memory Operations

1. Save all memories (overwrites existing):

   Copy

   User: "Save all my memories from this conversation to the MCP server"
   LLM: [Uses save-memories tool with current conversation memories]
   

2. Retrieve all memories:

   Copy

   User: "Get all my memories from the MCP server"
   LLM: [Uses get-memories tool to retrieve stored memories]
   

Context Window Caching Workflow

1. Archive context when window gets full:

   Copy

   User: "The conversation is getting long, archive the early parts"
   LLM: [Uses archive-context tool to store old messages with tags]
   

2. Score relevance of archived content:

   Copy

   User: "How relevant is the archived content to our current discussion?"
   LLM: [Uses score-relevance tool to evaluate archived content]
   

3. Retrieve relevant archived context:

   Copy

   User: "Bring back the relevant archived information"
   LLM: [Uses retrieve-context tool to get relevant archived content]
   

4. Create summaries for long conversations:

   Copy

   User: "Summarize the early parts of our conversation"
   LLM: [Uses create-summary tool to condense archived content]
   

Conversation Orchestration System

The ConversationOrchestrator class provides automatic context window management:

Key Features

• Automatic Archiving: Archives content when context usage reaches 80%
• Intelligent Retrieval: Retrieves relevant content when usage drops below 30%
• Relevance Scoring: Uses keyword overlap to score archived content relevance
• Smart Tagging: Automatically generates tags based on content keywords
• Conversation State Management: Tracks active conversations and their context
• Recommendations: Provides suggestions for optimal context management

Usage Example

import { ConversationOrchestrator } from "./orchestrator.js";

const orchestrator = new ConversationOrchestrator(8000); // 8k word limit

// Add a message (triggers automatic archiving/retrieval)
const result = await orchestrator.addMessage(
  "conversation-123",
  "This is a new message in the conversation",
  "claude",
);

// Check if archiving is needed
if (result.archiveDecision?.shouldArchive) {
  await orchestrator.executeArchive(result.archiveDecision, result.state);
}

// Check if retrieval is needed
if (result.retrievalDecision?.shouldRetrieve) {
  await orchestrator.executeRetrieval(result.retrievalDecision, result.state);
}

Database Schema

Basic Memory Structure

type BasicMemory = {
  _id: ObjectId;
  memories: string[]; // Array of memory strings
  timestamp: Date; // When memories were saved
  llm: string; // LLM identifier (e.g., 'chatgpt', 'claude')
  userId?: string; // Optional user identifier
};

Extended Memory Structure (Context Caching)

type ExtendedMemory = {
  _id: ObjectId;
  memories: string[]; // Array of memory strings
  timestamp: Date; // When memories were saved
  llm: string; // LLM identifier
  userId?: string; // Optional user identifier
  conversationId?: string; // Unique conversation identifier
  contextType?: "active" | "archived" | "summary";
  relevanceScore?: number; // 0-1 relevance score
  tags?: string[]; // Categorization tags
  parentContextId?: ObjectId; // Reference to original content for summaries
  messageIndex?: number; // Order within conversation
  wordCount?: number; // Size tracking
  summaryText?: string; // Condensed version
};

Context Window Caching Workflow

The orchestration system automatically:

1. Monitors conversation length and context usage
2. Archives content when context usage reaches 80%
3. Scores relevance of archived content against current context
4. Retrieves relevant content when usage drops below 30%
5. Creates summaries to condense very long conversations

Key Features

• Conversation Grouping: All archived content is linked to specific conversation IDs
• Relevance Scoring: Simple keyword overlap scoring (can be enhanced with semantic similarity)
• Tag-based Organization: Categorize content for easy retrieval
• Summary Linking: Preserve links between summaries and original content
• Backward Compatibility: All existing memory functions work unchanged
• Automatic Management: No manual intervention required for basic operations

Development

To run in development mode:

npm run build
node build/index.js

To run the CLI demo:

npm run cli

License

ISC