# 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
1. Clone or download this repository
2. Install dependencies:
```bash
npm install
```
## Usage
### Running the Server
```bash
npm start
```
For development with auto-reload:
```bash
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`
```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:
```bash
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 remember
- `tags` (optional): Array of tags to categorize the memory
- `metadata` (optional): Additional metadata as key-value pairs
**Example**:
```json
{
"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 tags
- `limit` (optional): Maximum number of results (default: 10)
**Example**:
```json
{
"query": "dark mode",
"tags": ["preferences"],
"limit": 5
}
```
### 3. list_memories
List all stored memories with optional filtering.
**Parameters**:
- `tags` (optional): Filter by specific tags
- `limit` (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 to `true` to 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 identifier
- `content`: The memory content
- `tags`: Array of tags
- `metadata`: Custom metadata object
- `timestamp`: ISO 8601 timestamp of when the memory was created
## Example Use Cases
1. **User Preferences**: Store user preferences that persist across conversations
2. **Project Context**: Remember project details, architecture decisions, and requirements
3. **Learning**: Store facts and knowledge the AI should remember
4. **Task Tracking**: Keep track of ongoing tasks and their status
5. **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.json` file
- Back up the `memories.json` file 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.js` or `C:\\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.
