Scofieldkoh/mcp_server

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:

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 remember
• tags (optional): Array of tags to categorize the memory
• metadata (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 tags
• limit (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 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.