The Memory MCP Server provides a three-tiered memory management system for AI agents, enabling persistent context storage, personalization, and historical tracking across user interactions.
Short-term Memory: Store and retrieve volatile, session-specific data with configurable TTL (default 30 minutes) for maintaining conversational state, with automatic expiration to prevent memory leaks.
Long-term User Profiles: Create and manage persistent user profiles containing demographics, contact information, preferences (interests, communication style), and custom settings for cross-session personalization.
Episodic Memory: Record time-stamped interactions and experiences with context, outcomes, sentiment analysis (positive, negative, neutral), and searchable tags for organized event tracking.
Advanced Retrieval: Search episodic memories by keywords or specific fields, retrieve complete memory sets with filtering and sorting options, and access structured data via standardized JSON resource URIs.
AI-Powered Insights: Utilize built-in prompts (memory_summary, personalization_insights) to generate high-level summaries and personalization recommendations based on stored memory data.
Production-Ready: Ensures data reliability through atomic disk writes to local JSON files, comprehensive error handling, automatic cleanup, structured logging, and configurable storage locations and TTL settings.
Built using JavaScript/Node.js runtime for implementing the memory server functionality
Requires Node.js runtime environment for execution and deployment
Uses npm package manager for dependency management and build processes
Implemented in TypeScript for type safety and requires compilation to JavaScript
Copyright 2025 Chris Bunting cbuntingde@gmail.com
Memory MCP Server
MIT License
Memory MCP Server
A production-ready Model Context Protocol (MCP) server implementing a robust three-tiered memory architecture designed for vertical AI agents and applications requiring sophisticated context management.
Overview
The Memory MCP Server provides a comprehensive, persistent, and session-based memory management system through three specialized and configurable memory types:
Short-term Memory: Volatile, session-specific context with a configurable Time-To-Live (TTL), ideal for maintaining conversational state or temporary operational data. (Default TTL: 30 minutes)
Long-term Memory: Persistent storage for user profiles, preferences, demographics, and other stable, long-lived data that defines user characteristics.
Episodic Memory: A searchable, time-stamped log of events, interactions, and experiences, enriched with sentiment analysis and tagging for advanced context retrieval and pattern recognition.
This architecture enables AI agents to maintain continuity across sessions, personalize interactions based on historical data, and reason over past events to provide more intelligent and context-aware responses.
Architecture
Project Structure
The project is organized with a clear separation of concerns, promoting maintainability, scalability, and testability.
Memory Tiers
Memory Type | Persistence | Primary Use Case | TTL | Storage Mechanism |
Short-term | In-memory only | Session context, temporary state, conversational flow. | Configurable (default: 30 minutes) | Volatile RAM |
Long-term | Disk-based (JSON) | User profiles, preferences, demographics, contact info. | Permanent (until explicitly deleted) |
|
Episodic | Disk-based (JSON) | Event history, experiences, interactions, sentiment tracking. | Permanent (until explicitly deleted) |
|
Data Flow
Request: An MCP client (e.g., an AI agent) sends a request via a tool, resource, or prompt.
Handler: The appropriate handler (
ToolHandlers.ts,ResourceHandlers.ts, orPromptHandlers.ts) receives and parses the request.Validation: Input parameters are validated using
Validation.ts.Store Interaction: The handler interacts with
MemoryStore.tsto perform CRUD operations on the respective memory tier.Persistence: For long-term and episodic memories, data is atomically written to JSON files on disk.
Response: The result is formatted and returned to the MCP client.
Logging: All operations are logged via
Logger.tsfor monitoring and debugging.
Installation
Prerequisites
Node.js: Version 16.0 or higher.
npm: Version 7.0 or higher (or yarn/pnpm).
MCP Client: An application or environment that can connect to and utilize MCP servers (e.g., Cline, Claude Desktop).
Setup
Clone the Repository
git clone https://github.com/cbuntingde/memory-mcp-server.git cd memory-mcp-serverInstall Dependencies
npm install # or yarn install # or pnpm installBuild the Project Compile the TypeScript source code into JavaScript.
npm run buildConfigure Your MCP Client You need to inform your MCP client about the Memory Server. This is typically done by adding a configuration entry to your client's settings file (e.g.,
cline_mcp_settings.jsonfor Cline, orclaude_desktop_config.jsonfor Claude Desktop).Example MCP Configuration:
{ "mcpServers": { "memory-server": { "command": "node", "args": ["./path/to/memory-mcp-server/build/index.js"], "env": { "MEMORY_DATA_DIR": "./custom-memory-data" // Optional: override default data directory }, "settings": { "dataDirectory": "./memory-mcp-server/memory-data", // Optional: can also be set here "defaultTTLMinutes": 30, // Optional: override default short-term TTL "logLevel": "info" // Optional: set logging level (trace, debug, info, warn, error) } } } }Replace
API Reference
The server exposes its functionality through MCP Tools, Resources, and Prompts.
Tools
Tools are used for actions that modify or retrieve specific data.
Tool Name | Description | Required Parameters | Optional Parameters |
| Stores a key-value pair in a session's short-term memory. |
(string),
(string),
(any JSON-serializable) |
(number) |
| Retrieves all data for a given session from short-term memory. |
(string) | - |
| Creates or updates a user's long-term memory profile. |
(string),
(object) | - |
| Retrieves a user's long-term memory profile. |
(string) | - |
| Adds a new event or experience to a user's episodic memory. |
(string),
(string) |
(string),
(string),
('positive', 'negative', 'neutral'),
(string[]),
(string) |
| Retrieves all episodic memories for a user, optionally sorted. |
(string) |
('timestamp_asc', 'timestamp_desc', 'sentiment'),
(number) |
| Searches a user's episodic memory by keyword, tag, or sentiment. |
(string),
(string) |
('event', 'context', 'outcome', 'tags'),
(number) |
Resources
Resources provide access to structured data, typically in JSON format.
Resource URI | Description | Returns |
| Fetches the complete long-term memory profile for a specific user. | JSON object representing the user's profile. |
| Fetches all episodic memory entries for a specific user. | JSON array of episodic memory objects. |
Prompts
Prompts are templates that guide an AI agent to generate responses based on memory data.
Prompt Name | Description | Required Arguments | Optional Arguments |
| Generates a comprehensive summary of a user's profile and recent history. |
(string) |
(number, default: 10) |
| Extracts key personalization opportunities from a user's long-term and episodic data. |
(string) | - |
Usage Examples
Here are practical examples demonstrating how to interact with the Memory MCP Server using its tools.
Managing a User Profile (Long-term Memory)
Recording and Searching Interactions (Episodic Memory)
Maintaining Session Context (Short-term Memory)
Generating a User Summary (Prompt)
Data Models
Long-term Memory Structure
Data stored in long-term.json follows this structure:
Episodic Memory Structure
Data stored in episodic.json follows this structure:
Development
Available Scripts
Testing
The project includes a functional test suite located in test-memory.js. These tests verify the core functionality of all memory operations.
To run the tests:
Ensure the project is built:
npm run buildExecute the test script:
npm run testornode test-memory.js
The tests will create and use a temporary data directory to avoid interfering with production data.
Code Style and Quality
TypeScript: All code is written in TypeScript for type safety and better developer experience.
ESLint & Prettier: Configured for consistent code style and quality (ensure you have editor plugins or run linting manually).
Logging: Comprehensive logging is implemented using
Logger.ts. Log levels can be configured via environment variables or MCP settings.Validation: All external inputs are rigorously validated using
Validation.tsto prevent errors and ensure data integrity.
Production Considerations
Performance
Memory Operations (Short-term): Typically < 5ms. Operates entirely in memory.
Disk Operations (Long-term/Episodic): Typically < 50ms on modern SSDs. File I/O is atomic and synchronous to ensure data consistency.
Search Operations (Episodic): Performance scales linearly with the number of records. < 100ms for datasets up to 10,000 records. For larger datasets, consider integrating a dedicated search engine (e.g., Lunr.js, ElasticSearch).
Memory Usage: Primarily determined by the size of in-memory short-term data and the active working set of long-term/episodic data loaded from disk.
Security
Input Validation: All parameters passed to tools and resources are strictly validated for type, format, and content to prevent injection attacks and malformed data.
Data Sanitization: While the server itself doesn't render HTML, data is stored in a way that assumes it might be used in contexts where escaping is necessary.
File System Security: The server writes to a specific, configurable directory. Ensure this directory has appropriate permissions to prevent unauthorized access or modification.
No External Dependencies: The server has no network dependencies, reducing the attack surface.
Local Data Storage: All data is stored locally on the file system. You are responsible for securing the host machine and the data directory.
Reliability & Data Integrity
Atomic Writes: Disk writes for long-term and episodic memories are performed atomically (write to a temporary file, then rename) to prevent data corruption if the process is interrupted.
Graceful Degradation: If the data directory becomes unwritable, the server will log errors but continue to function for short-term memory operations.
Automatic Cleanup: Short-term memory entries are automatically purged when their TTL expires, preventing memory leaks.
Error Handling: Comprehensive error handling is implemented throughout, with clear error messages returned to the MCP client where appropriate.
Monitoring & Observability
Structured Logging: All operations are logged with relevant context (user ID, session ID, operation type, duration) in a structured format (JSON), making it easy to parse and analyze logs.
Log Levels: Configurable log levels (
trace,debug,info,warn,error) allow for verbose debugging during development and minimal logging in production.Health Checks: The server responds to standard MCP pings, allowing for basic health monitoring.
Data Integrity Checks: On startup, the server can optionally verify the basic structure of existing data files (planned for future versions).
Troubleshooting
Common Issues
Server fails to start or MCP client cannot connect.
Verify Node.js Version: Ensure you are using Node.js 16.0 or higher (
node -v).Check Build Step: Run
npm run buildto ensure the TypeScript code is compiled to/build/index.js.Check File Path: In your MCP client configuration, double-check the path to
build/index.js. It should be an absolute path or a path relative to where the MCP client is run.Examine Logs: Check the console output from the MCP client or the terminal where you might be running the server directly for error messages. Enable debug logging:
DEBUG=memory-server:* node build/index.js.
Data is not persisting across server restarts.
Data Directory Permissions: Ensure the
memory-data/directory (or your customdataDirectory) exists and is writable by the process running the server.Disk Space: Verify that there is sufficient disk space available on the volume where the data directory is located.
Configuration: Confirm that the
dataDirectorysetting in your MCP configuration is pointing to the correct and intended location.
"Memory not found" errors.
ID Validation: Double-check the
userIdorsessionIdfor typos or incorrect formatting.TTL Expiration: For short-term memory, confirm that the session has not expired (i.e., its TTL has not been exceeded).
Operation Sequencing: Ensure that data was written to memory before attempting to read it. Check logs for previous write operations.
Debug Mode
For detailed debugging output, you can run the server with the DEBUG environment variable set:
This will enable verbose logging for all components of the memory server, providing insights into internal operations, data flow, and potential issues.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
Please ensure all code adheres to the project's coding standards and includes appropriate tests for new functionality.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
Issues & Bug Reports: Please use the GitHub Issues page to report bugs or request features.
Production Implementation: This server is built with a focus on robustness, security, and operational reliability, making it suitable for integration into production AI systems and applications.