AI Memory MCP Server
A cross-platform Model Context Protocol (MCP) server that provides persistent memory storage for AI assistants. This server allows AI models to store, retrieve, and manage memories across conversations.
Features
- Persistent Storage: Memories are stored in a JSON file and survive server restarts
- Rich Memory Management: Store memories with content, tags, and custom metadata
- Powerful Search: Search memories by keywords or filter by tags
- Cross-Platform: Works on Windows, macOS, and Linux
- Easy Integration: Compatible with any MCP client (Claude Desktop, etc.)
Installation
Prerequisites
- Node.js 18.0.0 or higher
Setup
- Clone or download this repository
- Install dependencies:
npm install
Usage
Running the Server
npm start
For development with auto-reload:
npm run dev
Configuration
Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"ai-memory": {
"command": "node",
"args": ["/absolute/path/to/mcp_server/index.js"]
}
}
}
Other MCP Clients
Use the stdio transport and point to the index.js file:
node /path/to/mcp_server/index.js
Available Tools
1. store_memory
Store a new memory or piece of knowledge.
Parameters:
content(required): The content to remembertags(optional): Array of tags to categorize the memorymetadata(optional): Additional metadata as key-value pairs
Example:
{
"content": "User prefers dark mode UI",
"tags": ["preferences", "ui"],
"metadata": {
"priority": "high"
}
}
2. search_memories
Search through stored memories using keywords or tags.
Parameters:
query(optional): Search query (searches in content)tags(optional): Filter by specific tagslimit(optional): Maximum number of results (default: 10)
Example:
{
"query": "dark mode",
"tags": ["preferences"],
"limit": 5
}
3. list_memories
List all stored memories with optional filtering.
Parameters:
tags(optional): Filter by specific tagslimit(optional): Maximum number of results (default: 50)
4. delete_memory
Delete a specific memory by its ID.
Parameters:
id(required): The ID of the memory to delete
5. clear_memories
Clear all stored memories. Use with caution!
Parameters:
confirm(required): Must be set totrueto confirm deletion
6. get_memory_stats
Get statistics about stored memories (total count, tags, etc.).
Returns: Statistics including total count, tag counts, and timestamps.
Available Resources
memory://all
Complete list of all stored memories in JSON format.
memory://stats
Statistics about stored memories including counts and tag distribution.
Data Storage
Memories are stored in memories.json in the server directory. Each memory has:
id: Unique identifiercontent: The memory contenttags: Array of tagsmetadata: Custom metadata objecttimestamp: ISO 8601 timestamp of when the memory was created
Example Use Cases
- User Preferences: Store user preferences that persist across conversations
- Project Context: Remember project details, architecture decisions, and requirements
- Learning: Store facts and knowledge the AI should remember
- Task Tracking: Keep track of ongoing tasks and their status
- Conversation History: Store important points from previous conversations
Security Notes
- The memory file is stored locally on the machine running the server
- No data is sent to external services
- Ensure proper file permissions on the
memories.jsonfile - Back up the
memories.jsonfile regularly if you store important information
Troubleshooting
Server won't start
- Ensure Node.js 18+ is installed:
node --version - Check that dependencies are installed:
npm install - Verify file permissions on the server directory
Memories not persisting
- Check write permissions on the server directory
- Ensure the server process isn't being killed before writes complete
- Check for errors in the console output
Can't connect from Claude Desktop
- Verify the path in the configuration is absolute, not relative
- Check that the configuration JSON is valid
- Restart Claude Desktop after changing the configuration
- Check Claude Desktop logs for connection errors
Platform-Specific Notes
Windows
- Use forward slashes or escaped backslashes in the config path
- Example:
C:/Users/YourName/mcp_server/index.jsorC:\\Users\\YourName\\mcp_server\\index.js
macOS/Linux
- Ensure the index.js file has execute permissions:
chmod +x index.js - Use absolute paths starting with
/or~
License
MIT
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
Support
For issues and questions, please open an issue on the GitHub repository.