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

Clone and build
git clone <repository-url> cd memory-server npm install npm run build
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.

Deploy Server

HTTP connection URL

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

Enables agents to maintain persistent memory through three-tiered architecture: short-term session context with TTL, long-term user profiles and preferences, and searchable episodic event history with sentiment analysis. Provides comprehensive memory management for personalized AI interactions.

Memory MCP Server

Memory MCP Server

Overview

Architecture

Memory Types

Data Storage

Installation

Prerequisites

Setup

API Reference

Tools

Resources

Prompts

Usage Examples

User Profile Management

Session Context

Data Models

Long-term Memory Structure

Episodic Memory Structure

Development

Commands

Testing

Production Considerations

Performance

Security

Reliability

Monitoring

Troubleshooting

Common Issues

Debug Mode

License

Support

Tools

New MCP Servers

MCP directory API