# 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.