MindXpansion/memory-manager

Memory Manager MCP Server

An advanced cognitive-inspired memory management system for the Model Context Protocol (MCP) that provides persistent storage with brain-like memory processing features including consolidation, decay, reinforcement, and intelligent retrieval.

🧠 Overview

Memory Manager MCP Server implements sophisticated memory models inspired by human cognition:

• Working Memory: Active, immediate information processing
• Episodic Memory: Event-based memories with contextual details
• Semantic Memory: Factual knowledge and concepts
• Procedural Memory: How-to knowledge and skills

The system features automatic memory consolidation, natural decay patterns, reinforcement learning, and intelligent indexing for efficient retrieval.

🌟 Key Features

Cognitive Processing

• Memory Consolidation: Automatically merges related memories like human sleep consolidation
• Memory Decay: Natural forgetting curves for non-reinforced memories
• Reinforcement Learning: Strengthens frequently accessed or important memories
• Smart Indexing: Efficient retrieval with semantic search capabilities

Storage & Security

• Layered Storage: Primary, secondary, and archival memory layers
• Encryption: Built-in memory encryption for sensitive data
• Guardian Module: Security policies and access control
• Monitoring: Real-time performance and health tracking

Management Features

• Categorization: Project, technical, conversation, and configuration memories
• Retention Policies: Configurable retention periods per category
• Backup/Restore: Full state export and import capabilities
• Analytics: Memory usage metrics and insights

📋 Prerequisites

macOS

• Node.js 18.0.0 or higher
• npm or yarn package manager
• Git (for cloning the repository)
• Claude Desktop app (for MCP integration)

Windows

• Node.js 18.0.0 or higher
• npm or yarn package manager
• Git for Windows
• Claude Desktop app (for MCP integration)
• Windows Terminal or PowerShell (recommended)

🚀 Installation Guide

macOS Installation

1. Clone the repository

   cd ~/Documents
   git clone [repository-url] memory-manager
   cd memory-manager
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Configure Claude Desktop

   Open Claude Desktop configuration:

   code ~/Library/Application\ Support/Claude/claude_desktop_config.json
   

   Add the Memory Manager to your MCP servers:

   {
     "mcpServers": {
       "memory-manager": {
         "command": "node",
         "args": ["/Users/YOUR_USERNAME/Documents/memory-manager/dist/server.js"],
         "env": {
           "NODE_ENV": "production"
         }
       }
     }
   }
   

5. Restart Claude Desktop

   • Quit Claude Desktop completely
   • Reopen Claude Desktop
   • The Memory Manager should appear in your MCP tools

Windows Installation

1. Clone the repository

   cd C:\Users\YOUR_USERNAME\Documents
   git clone [repository-url] memory-manager
   cd memory-manager
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Configure Claude Desktop

   Open Claude Desktop configuration:

   notepad "$env:APPDATA\Claude\claude_desktop_config.json"
   

   Add the Memory Manager to your MCP servers:

   {
     "mcpServers": {
       "memory-manager": {
         "command": "node",
         "args": ["C:\\Users\\YOUR_USERNAME\\Documents\\memory-manager\\dist\\server.js"],
         "env": {
           "NODE_ENV": "production"
         }
       }
     }
   }
   

5. Restart Claude Desktop

   • Close Claude Desktop completely
   • Reopen Claude Desktop
   • The Memory Manager should appear in your MCP tools

🔧 Configuration

Storage Configuration

Edit config.json to customize storage settings:

{
  "storage": {
    "basePath": "storage",
    "maxSize": 104857600,  // 100MB in bytes
    "retentionPeriods": {
      "shortTerm": 86400000,      // 24 hours
      "longTerm": 31536000000,    // 365 days
      "conversation": 604800000   // 7 days
    }
  },
  "categories": [
    "project",
    "technical",
    "conversation",
    "configuration"
  ],
  "defaultCategory": "technical"
}

Memory Categories & Retention

📚 Usage Examples

Store a Memory

// Store project information
await store_memory({
  content: "Database schema redesign completed with improved indexing",
  type: "semantic",
  retention: "long-term",
  context: {
    environment: "production",
    tags: ["database", "optimization", "project-x"],
    emotional_state: 0.8,
    attention_level: 0.9
  }
});

Retrieve Memories

// Search by type
await retrieve_memories({
  query: { type: "semantic" }
});

// Search by tags
await retrieve_memories({
  query: { tags: ["database"] }
});

Reinforce Important Memories

await reinforce_memory({
  id: "memory-id-123",
  context: {
    emotional_state: 0.9,
    attention_level: 1.0,
    related_memories: ["memory-id-456", "memory-id-789"]
  }
});

🛠️ Development

Available Scripts

npm run build      # Build TypeScript to JavaScript
npm run dev        # Development mode with auto-reload
npm run clean      # Clean build directory
npm run lint       # Run ESLint
npm run format     # Format code with Prettier
npm run test       # Run tests

Testing with Demo Scripts

node demo.js                    # Basic functionality demo
node feeling-demo.js           # Emotional context storage
node gratitude-demo.js         # Gratitude memory example
node improvement-demo.js       # System improvement tracking
node implementation-plan.js    # Project planning storage

🔍 Troubleshooting

Common Issues

1. "Memory Manager not showing in Claude"

   • Ensure the path in claude_desktop_config.json is absolute
   • Check that the build was successful (npm run build)
   • Restart Claude Desktop completely

2. "Permission denied" errors

   • macOS: Check file permissions with ls -la
   • Windows: Run terminal as Administrator
   • Ensure storage directory is writable

3. "Module not found" errors

   • Delete node_modules and reinstall: rm -rf node_modules && npm install
   • Ensure Node.js version is 18.0.0 or higher: node --version

4. Storage issues

   • Check available disk space
   • Verify storage path exists and is writable
   • Check logs in memory-manager.log

Debug Mode

Enable debug logging by setting the environment variable:

# macOS/Linux
export LOG_LEVEL=debug

# Windows
set LOG_LEVEL=debug

📊 Monitoring

Health Check Endpoint

The server runs a health check endpoint on port 3000:

curl http://localhost:3000/health

Logs

• Application logs: memory-manager.log
• Error logs: memory-manager-error.log
• MCP communication: Check Claude Desktop logs

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit changes: git commit -m 'Add amazing feature'
4. Push to branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

This project is licensed under a Noncommercial No-Derivatives license - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by cognitive science research on human memory systems
• Built for the Model Context Protocol (MCP) ecosystem
• Designed for integration with Claude Desktop

📞 Support

• Create an issue on GitHub for bugs or feature requests
• Check existing issues before creating new ones
• Include logs and system information when reporting bugs

Copyright (c) 2025 MindXpansion.ai

This project is licensed under a Noncommercial No-Derivatives license. You may use and share unmodified copies for noncommercial purposes only. No selling, charging for access/hosting, or derivative works (including modifications) are permitted. See the full terms in . See GitHub, https://github.com/MindXpansion/memory-manager, License.