README.md•5.88 kB
# 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**
```bash
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`):
```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
```javascript
// 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
```javascript
// 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
```json
{
"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
```json
{
"id": "episodic_{timestamp}_{randomId}",
"userId": "string",
"sessionId": "string",
"event": "string",
"context": "string",
"outcome": "string",
"sentiment": "positive|negative|neutral",
"timestamp": "number",
"tags": ["string"]
}
```
## Development
### Commands
```bash
npm run build # Build for production
npm run watch # Development mode with file watching
npm run inspector # Run MCP debugging tools
```
### Testing
```bash
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
```bash
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.