MCP Memory

MCP Memory: Persistent Memory for AI Conversations 🧠

MCP Memory is an Elasticsearch-backed knowledge graph system that gives AI models persistent memory beyond the limits of their context windows. Built for the Model Context Protocol (MCP), it ensures your LLMs remember important information forever, creating more coherent, personalized, and effective AI conversations.

🌟 Why AI Models Need Persistent Memory

AI assistants often struggle with:

• Forgetting crucial details from earlier conversations
• Requiring repeated context for new chats
• Losing valuable insights as conversation history fills up
• Inability to reference past work or decisions

MCP Memory addresses these issues by creating a structured, searchable memory store that preserves context indefinitely, enabling meaningful, long-term relationships with users.

✨ Key Features

• 📊 Persistent Memory: Store and retrieve information across multiple sessions
• 🔍 Smart Search: Find information with Elasticsearch queries
• 📓 Contextual Recall: AI prioritizes relevant information based on the conversation
• 🧩 Relational Understanding: Connect concepts with relationships
• 🔄 Long-term / Short-term Memory: Distinguish between temporary and important knowledge
• 🗂️ Memory Zones: Organize information into separate domains (projects, clients, topics)
• 🔒 Reliable & Scalable: Built on Elasticsearch for enterprise-grade performance

🚀 5-Minute Setup

Prerequisites

• Docker: Required for running Elasticsearch (or a local Elasticsearch installation)
• Node.js: Version 18 or higher
• npm: For package management

Clone the repository:

git clone https://github.com/mcp-servers/mcp-servers.git
cd mcp-servers/memory

Install dependencies:

npm install

Start Elasticsearch (using Docker):

npm run es:start

Build the project:

npm run build

🔌 Connecting to Claude Desktop

MCP Memory works with Claude Desktop, giving Claude persistent memory across conversations:

1. Copy and configure the launch script:

   Copy launch.example:

   cp launch.example launch.sh
   nano launch.sh

   Copy

   Make the script executable:

   chmod +x launch.sh

   Copy

2. Add the command to Claude Desktop:

   • Open Claude Desktop Settings
   • Navigate to the "Commands" section
   • Click "Add New Command"
   • Configure as follows:
     • Name: MCP Memory
     • Command: /path/to/mcp-servers/memory/launch.sh
     • Arguments: Leave empty
     • Run in background: Yes
     • Show in menu: Yes

3. Verify connection:

   • Start the command from Claude Desktop
   • You should see a notification that Claude is connected to MCP Memory
   • Try asking Claude about something you discussed in a previous conversation!

💡 How It Works

MCP Memory creates a structured knowledge graph where:

• Entities represent people, concepts, projects, or anything worth remembering
• Relations connect entities, creating a network of associations
• Observations capture specific details about entities
• Relevance scoring determines what information to prioritize

When integrated with an LLM, the system automatically:

• Stores new information learned during conversations
• Retrieves relevant context when needed
• Builds connections between related concepts
• Forgets unimportant details while preserving critical knowledge

🛠️ Example: How Agents Use Memory

From the User's Perspective

Conversation 1: Initial Information

User: My daughter's name is Emma and she's turning 8 next month.
 
Claude: That's wonderful! Emma will be turning 8 next month. Is there anything special you're planning for her birthday?
(Behind the scenes: Claude stores "Emma" as an entity of type "Person" with observations about her age and birthday timing)

Conversation 2: Days or Weeks Later

User: I'm thinking about what to get for a gift.
 
Claude: If you're looking for gift ideas for Emma's 8th birthday coming up, have you considered what her current interests are? At that age, many children enjoy creative items, books, or educational games.
(Behind the scenes: Claude retrieved the entity "Emma", her age, and the fact that her birthday is approaching)

Conversation 3: After the Birthday

User: The party went really well on Saturday!
 
Claude: I'm glad Emma's 8th birthday party was a success on Saturday! Did she enjoy the gifts she received?
(Behind the scenes: Claude updates the observations about Emma, noting that her birthday party occurred on a Saturday and went well)

How the Agent Uses Memory

When the user mentions something important, the agent:

1. Recognizes important information worth remembering
2. Stores it in memory by creating entities, relations, and observations
3. Updates existing information when new details emerge

When the user mentions something related to stored information, the agent:

1. Searches memory for relevant context based on the current conversation
2. Retrieves important details that might be helpful
3. Incorporates this information naturally into its responses

🧰 Admin Tools

MCP Memory includes a comprehensive admin CLI for maintaining your knowledge graph:

# Search the memory
node dist/admin-cli.js search "Emma birthday"
 
# View details about a specific entity
node dist/admin-cli.js entity "Emma"
 
# Back up your entire memory system
node dist/admin-cli.js backup memory-backup.json

📚 Advanced Features

Memory Zones

Organize knowledge into separate domains:

# Create a project-specific memory zone
node dist/admin-cli.js zones add client-acme "ACME Corp Project Knowledge"
 
# Import data into that zone
node dist/admin-cli.js import acme-data.json client-acme

Conversational Memory Management

You can also instruct the assistant to organize memories in different zones through natural conversation:

Creating and Using Memory Zones

User: Claude, can you create a new memory zone called "work-project" for storing information about my current work project?
 
Claude: I've created a new memory zone called "work-project". I'll store information related to your work project in this zone. What would you like me to remember about your project?
 
User: The project deadline is March 15th, and we're building a new inventory management system.
 
Claude: I've stored information about your work project in the "work-project" zone, including the March 15th deadline and that you're building an inventory management system. I'll keep future information about this project organized in this zone.
(Behind the scenes: Claude creates a new memory zone and stores project information specifically in that zone)

Retrieving Zone-Specific Information

User: What do you remember about my work project?
 
Claude: Based on what we've discussed about your work project, I recall that you're building an inventory management system with a deadline of March 15th.
(Behind the scenes: Claude specifically searches the "work-project" zone for relevant information)

Switching Between Memory Zones

User: Claude, let's switch to my "cooking" memory zone now. I want to discuss a recipe.
 
Claude: I've switched to your "cooking" memory zone. What recipe would you like to discuss today?
(Behind the scenes: Claude updates its memory context to prioritize searching in the "cooking" zone)
 
User: What was that pasta dish I told you about last month?
 
Claude: From our previous conversations in your cooking zone, you shared a carbonara recipe that used pancetta, eggs, pecorino cheese, and black pepper. You mentioned it was a family favorite that you learned during your trip to Rome.
(Behind the scenes: Claude searches specifically in the "cooking" zone to find this information)

By organizing memory into separate zones, conversations become more relevant and focused on the current topic or project.

Search Capabilities

Leverage Elasticsearch's powerful search features:

# Fuzzy search (finds "meeting" even with typo)
node dist/admin-cli.js search "meteing notes"
 
# Zone-specific search
node dist/admin-cli.js search "budget" client-acme

🤝 Contributing

Contributions are welcome! See CONTRIBUTING.md for details.

📝 License

MIT