🧠 MCP Memory Server

Advanced Memory System for Claude Desktop - Transform Claude into an AI assistant with photographic memory using MCP (Model Context Protocol).

✨ What it does

Imagine Claude with persistent memory that:

🧠 Remembers everything from your conversations
🔍 Automatically retrieves context when you reference past topics
🤖 Understands references like "that project", "this company", "he/she"
📈 Builds knowledge over time across all your sessions
🛠️ Auto-captures results from web searches and other tools

🚀 Quick Start

Prerequisites

Node.js 18+
Azure Cosmos DB account
OpenAI API key
Claude Desktop

Installation

git clone https://github.com/PlumyCat/mcp-memory-server.git
cd mcp-memory-server
npm install
npm run build

Configuration

Environment setup:

cp .env.example .env
# Edit .env with your API keys

Claude Desktop configuration:

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-memory-server/dist/index.js"],
      "cwd": "/path/to/mcp-memory-server"
    }
  }
}

Test the magic:

You: "I'm working on a TypeScript project using CosmosDB"
Claude: [Responds normally + automatic background storage]

# Later...
You: "What was that project we discussed?"
Claude: "You mentioned working on a TypeScript project using CosmosDB..."

🎯 Key Features

🧠 Intelligent Memory Storage

Automatic entity extraction (people, companies, projects, tools)
Semantic storage with OpenAI embeddings
Conversation context preservation
Smart deduplication

🔍 Advanced Search & Retrieval

Semantic similarity search
Entity relationship mapping
Timeline-based retrieval
Context-aware responses

🤖 Entity Resolution

Automatic pronoun resolution ("he" → "John Smith")
Reference understanding ("that company" → "Microsoft")
Cross-conversation entity linking
Confidence scoring

📊 Analytics & Insights

Conversation pattern analysis
Entity interaction timelines
Knowledge growth tracking
Usage statistics

🛠️ Available Tools

The server provides 6 MCP tools for Claude:

Tool	Description	Example Usage
`memory_store`	Store information with auto entity extraction	Automatically triggered during conversations
`memory_search`	Semantic search through stored memories	"Find all discussions about React"
`context_inject`	Get relevant context for current query	"What did we discuss about this project?"
`entity_resolve`	Resolve references to actual entities	"Who is 'he' referring to?"
`conversation_analyze`	Analyze conversation patterns	"Show my discussion statistics"
`memory_timeline`	Get timeline of entity interactions	"Timeline of Microsoft mentions"

📁 Project Structure

mcp-memory-server/
├── src/
│   ├── config/          # Azure Cosmos DB configuration
│   ├── memory/          # Core memory system (RAG, storage, graph)
│   ├── types/           # TypeScript type definitions
│   ├── utils/           # Entity extraction, context injection
│   └── server.ts        # Main MCP server implementation
├── scripts/             # Maintenance and health check scripts
├── tests/               # Unit and integration tests
├── docs/                # Technical documentation
└── dist/                # Compiled JavaScript (generated)

🏗️ Architecture

Core Components

RAG System: Vector similarity search with OpenAI embeddings
Entity Extractor: NLP-based entity recognition with custom patterns
Memory Storage: Optimized CosmosDB integration with smart indexing
Context Injector: Intelligent context retrieval for conversations
Graph Engine: Entity relationship mapping and traversal

Data Flow

graph TD
    A[User Message] --> B[Entity Extraction]
    B --> C[Embedding Generation]
    C --> D[CosmosDB Storage]
    D --> E[Semantic Search]
    E --> F[Context Injection]
    F --> G[Enhanced Claude Response]

🔧 Configuration

Environment Variables

# Azure Cosmos DB
COSMOS_ENDPOINT=https://your-account.documents.azure.com:443/
COSMOS_KEY=your-primary-key
COSMOS_DATABASE_NAME=memory-db
COSMOS_CONTAINER_CONVERSATIONS=conversations
COSMOS_CONTAINER_ENTITIES=entities

# OpenAI
OPENAI_API_KEY=your-openai-api-key

# Optional
NODE_ENV=production
LOG_LEVEL=info
MEMORY_RETENTION_DAYS=30

Advanced Configuration

See Configuration Guide for detailed setup options.

🧪 Testing

# Run all tests
npm test

# Health check
npm run health-check

# Test memory functionality
npm run test-memory

📊 Performance

Storage: Optimized CosmosDB indexing for sub-100ms queries
Search: Vector similarity with 95%+ accuracy
Memory: Efficient entity deduplication and compression
Scalability: Handles 1000+ entities with consistent performance

🛣️ Roadmap

✅ Completed

Core memory storage and retrieval
Entity extraction and resolution
Semantic search with embeddings
CosmosDB integration
MCP server implementation

🔄 In Progress

Intelligent entity deduplication
Auto-capture of all MCP tool results
Enhanced entity classification patterns
Contradiction detection system

🔮 Planned

Multi-user memory isolation
Graph traversal with Gremlin queries
Advanced analytics dashboard
Memory compression and archiving

See Roadmap for detailed feature planning.

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

git clone https://github.com/PlumyCat/mcp-memory-server.git
cd mcp-memory-server
npm install
npm run dev

📚 Documentation

Usage Guide - Comprehensive usage examples
API Reference - Detailed API documentation
Architecture - Technical architecture details
Troubleshooting - Common issues and solutions

🆘 Support

📖 Check the Usage Guide for examples
🐛 Report issues on GitHub Issues
💬 Discuss on GitHub Discussions

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Model Context Protocol (MCP) for the foundational protocol
Claude Desktop for the AI assistant platform
Azure Cosmos DB for scalable data storage
OpenAI for embedding generation
Compromise.js for natural language processing

⭐ Star History

Made with ❤️ for the Claude Desktop community

MCP Memory Server