This MCP server provides tools for interacting with a Memory Box instance, allowing you to save and search memories using semantic search directly from Cline and Claude Desktop.
Related Projects
This MCP server is designed to work with [Memory Box](https://memorybox.dev), a semantic memory storage and retrieval system powered by vector embeddings.
Memory Box provides the backend API that this MCP server communicates with, allowing you to:
- Store memories with vector embeddings for semantic search
- Organize memories into customizable buckets
- Search for memories based on meaning, not just keywords
- Retrieve memories with detailed context
- Find semantically related memories
- Track memory processing status
For more information about Memory Box, including how to set up your own instance, please visit the [Memory Box website](https://memorybox.dev).
Features
- **Save Memories**: Save formatted memories to your Memory Box with source information and metadata
- **Search Memories**: Search your memories using semantic search
- **Retrieve Memories**: Get all memories or memories from specific buckets
- **Find Related Memories**: Discover semantically similar memories
- **Check Memory Status**: Monitor the processing status of your memories
- **Format Memories**: Format memories according to a structured system prompt
- **Usage Statistics**: View your current plan, usage metrics, and resource limits
Installation
The server has been installed and configured for use with Cline. Note that you need a running Memory Box instance (either self-hosted or using the hosted version at memorybox.amotivv.ai) to use this MCP server.
Installing via Smithery
To install Memory Box MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@amotivv/memory-box-mcp):
To complete the setup:
- Edit the Cline MCP settings file at: ``` ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ```
- Add your Memory Box token to the `MEMORY_BOX_TOKEN` environment variable: ```json "memory-box-mcp": { "command": "node", "args": [ "<path-to-repository>/build/index.js" ], "env": { "MEMORY_BOX_API_URL": "https://memorybox.amotivv.ai", "MEMORY_BOX_TOKEN": "your-token-here", "DEFAULT_BUCKET": "General" }, "disabled": false, "autoApprove": [] } ```
- Optionally, you can customize the default bucket by changing the `DEFAULT_BUCKET` value.
Usage
Once configured, you can use the following tools in Cline:
Save Memory
Save a memory to Memory Box with proper formatting:
Parameters:
- `text` (required): The memory content to save
- `bucket_id` (optional): The bucket to save the memory to (default: "General")
- `format` (optional): Whether to format the memory according to the system prompt (default: true)
- `type` (optional): The type of memory (TECHNICAL, DECISION, SOLUTION, CONCEPT, REFERENCE, APPLICATION, FACT) for formatting (default: "TECHNICAL")
- `source_type` (optional): Type of memory source (default: "llm_plugin")
- `reference_data` (optional): Additional metadata about the memory source and context
Search Memories
Search for memories using semantic search:
Parameters:
- `query` (required): The search query
- `debug` (optional): Include debug information in results (default: false)
Get All Memories
Retrieve all memories:
Get Bucket Memories
Get memories from a specific bucket:
Parameters:
- `bucket_id` (required): The bucket to retrieve memories from
Format Memory
Format a text according to the memory system prompt without saving:
Parameters:
- `text` (required): The text to format
- `type` (optional): The type of memory (TECHNICAL, DECISION, SOLUTION, CONCEPT, REFERENCE, APPLICATION, FACT) (default: "TECHNICAL")
Get Related Memories
Find semantically similar memories to a specific memory:
Parameters:
- `memory_id` (required): The ID of the memory to find related memories for
- `min_similarity` (optional): Minimum similarity threshold (0.0-1.0) for related memories (default: 0.7)
Check Memory Status
Check the processing status of a memory:
Parameters:
- `memory_id` (required): The ID of the memory to check status for
Get Usage Stats
Retrieve user usage statistics and plan information:
This tool returns:
- Current plan information (e.g., free, basic, professional, legacy)
- User status and limit enforcement information
- Current month usage metrics (store operations, search operations, API calls)
- Data processing volume with human-readable formatting
- Resource limits based on your plan (if applicable)
- Operation breakdown by type
No parameters are required for this operation.
Customization
System Prompt Customization
The Memory Box MCP server uses a system prompt to format memories according to specific guidelines. You can customize this prompt to change how memories are formatted.
Default System Prompt
The default system prompt includes formatting guidelines for different types of memories:
How to Customize the System Prompt
To customize the system prompt:
- Edit the Cline MCP settings file at: ``` ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json ```
- Add your custom system prompt to the `SYSTEM_PROMPT` environment variable: ```json "memory-box-mcp": { "command": "node", "args": [ "<path-to-repository>/build/index.js" ], "env": { "MEMORY_BOX_API_URL": "https://your-memory-box-instance", "MEMORY_BOX_TOKEN": "your-token-here", "DEFAULT_BUCKET": "General", "SYSTEM_PROMPT": "Your custom system prompt here..." }, "disabled": false, "autoApprove": [] } ``` A template file is provided at `<path-to-repository>/system-prompt-template.txt` that you can copy and modify.
- Restart Cline to apply the changes
System Prompt Helper
The Memory Box MCP server includes a helper script for managing the system prompt:
Other Configuration Options
You can also customize these environment variables:
- `MEMORY_BOX_API_URL`: The URL of your Memory Box instance
- `MEMORY_BOX_TOKEN`: Your authentication token for Memory Box
- `DEFAULT_BUCKET`: The default bucket to use when saving memories
Troubleshooting
If you encounter issues:
- Check that your Memory Box token is correctly configured
- Verify that your Memory Box instance is running and accessible
- Check the Cline logs for any error messages
Development
To make changes to the server:
- Edit the source code in `<path-to-repository>/src/`
- Rebuild the server: ``` cd <path-to-repository> npm run build ```
- Restart Cline to apply the changes