Memory MCP Server

A production-ready Model Context Protocol server implementing three-tiered memory architecture for vertical agents.

Overview

The Memory MCP Server provides persistent and session-based memory capabilities through three specialized memory types:

• Short-term Memory: Session context with configurable TTL (default: 30 minutes)
• Long-term Memory: Persistent user profiles, preferences, and demographics
• Episodic Memory: Searchable event history with sentiment analysis and tagging

Architecture

Memory Types

Type	Persistence	Use Case	TTL
Short-term	In-memory only	Session context, temporary state	Configurable (default 30m)
Long-term	Disk storage	User profiles, preferences, demographics	Permanent
Episodic	Disk storage	Event history, experiences, interactions	Permanent

Data Storage

memory-data/
├── long-term.json      # User profiles and preferences
└── episodic.json       # Event and experience logs

Installation

Prerequisites

• Node.js 16.0 or higher
• npm 7.0 or higher

Setup

1. Clone and build

   git clone <repository-url>
   cd memory-server
   npm install
   npm run build
   

2. Configure MCP

   Add to your MCP configuration (e.g., cline_mcp_settings.json):

   {
     "mcpServers": {
       "memory-server": {
         "command": "node",
         "args": ["./memory-server/build/index.js"],
         "settings": {
           "dataDirectory": "./memory-server/memory-data",
           "defaultTTLMinutes": 30
         }
       }
     }
   }
   

API Reference

Tools

Tool	Description	Required Parameters
set_short_term_memory	Store session data with TTL	sessionId, key, value
get_short_term_memory	Retrieve session data	sessionId
set_long_term_memory	Store user profile data	userId
get_long_term_memory	Retrieve user profile	userId
add_episodic_memory	Record event/experience	userId, event, context
get_episodic_memory	Retrieve user events	userId
search_episodic_memory	Search event history	userId, query

Resources

• memory://long-term/{userId} - User profile data (JSON)
• memory://episodic/{userId} - User event history (JSON)

Prompts

• memory_summary - Generate comprehensive user memory summary
• personalization_insights - Extract personalization opportunities

Usage Examples

User Profile Management

// Store user preferences
await server.set_long_term_memory({
  userId: "user-123",
  demographics: { age: 35, location: "New York" },
  preferences: { seating: "poolside", temperature: "cool" }
});

// Record interaction
await server.add_episodic_memory({
  userId: "user-123",
  event: "Guest requested poolside seating",
  context: "Arrived for dinner, asked for poolside table",
  outcome: "Seated at requested location",
  sentiment: "positive",
  tags: ["seating", "dinner"]
});

Session Context

// Store session state
await server.set_short_term_memory({
  sessionId: "session-456", 
  key: "current_order",
  value: { items: ["salad", "wine"], table: 12 },
  ttlMinutes: 45
});

Data Models

Long-term Memory Structure

{
  "userId": {
    "demographics": {
      "age": "number",
      "location": "string", 
      "occupation": "string"
    },
    "contact": {
      "email": "string",
      "phone": "string"
    },
    "preferences": {
      "seating": "string",
      "temperature": "string",
      "communicationStyle": "string"
    },
    "lastUpdated": "timestamp"
  }
}

Episodic Memory Structure

{
  "id": "episodic_{timestamp}_{randomId}",
  "userId": "string",
  "sessionId": "string",
  "event": "string",
  "context": "string", 
  "outcome": "string",
  "sentiment": "positive|negative|neutral",
  "timestamp": "number",
  "tags": ["string"]
}

Development

Commands

npm run build      # Build for production
npm run watch      # Development mode with file watching
npm run inspector  # Run MCP debugging tools

Testing

npm run build      # Build first
node test-memory.js  # Run functional tests

Production Considerations

Performance

• Memory operations: <10ms
• Disk operations: <50ms (SSD)
• Search operations: <100ms (1000 memories)
• Memory usage: Linear with data volume

Security

• Input validation on all parameters
• Atomic file operations preventing corruption
• No external API dependencies
• Local-only data storage

Reliability

• Graceful degradation when storage unavailable
• Automatic memory cleanup for expired sessions
• Data persistence with automatic recovery
• Comprehensive error handling

Monitoring

• Structured logging for all operations
• Error tracking with diagnostic information
• Data integrity verification on startup
• Performance metrics available

Troubleshooting

Common Issues

Server fails to start

• Verify Node.js version >= 16.0
• Run npm run build to compile TypeScript
• Check file permissions on build/index.js

Data not persisting

• Ensure memory-data/ directory is writable
• Verify disk space availability
• Check system logs for I/O errors

Memory not found

• Validate userId/sessionId format
• Check TTL expiration for short-term memory
• Verify operation sequencing

Debug Mode

DEBUG=memory-server:* node build/index.js

License

MIT License - see LICENSE file for details.

Support

• Issues: Create GitHub issue
• Email: cbuntingde@gmail.com
• Documentation: Refer to inline code comments

---

Enterprise-grade production implementation with comprehensive error handling, type safety, and operational reliability.