Memory Box MCP Server

Cline and Claude Desktop MCP integration for Memory Box - save, search, and format memories with semantic understanding

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

Features

• Save Memories: Save formatted memories to your Memory Box with source information and metadata
• Search Memories: Search your memories using semantic search with pagination and date sorting
• Retrieve Memories: Get all memories or memories from specific buckets
• Bucket Management: Create and delete buckets for organizing memories
• Memory Management: Update or delete existing memories
• 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 as Claude Desktop Extension (Recommended)

The easiest way to use Memory Box with Claude Desktop is through the Desktop Extension:

1. Download the latest memory-box.dxt file from the releases page
2. Open Claude Desktop
3. Go to Settings > Extensions
4. Click "Install from file"
5. Select the downloaded memory-box.dxt file
6. Configure your Memory Box API token in the extension settings

The extension will automatically configure all necessary environment variables and tools.

Installing via Smithery

To install Memory Box MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @amotivv/memory-box-mcp --client claude

To complete the setup:

1. Edit the Cline MCP settings file at:

   ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   

2. Add your Memory Box token to the MEMORY_BOX_TOKEN environment variable:

   "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": []
   }

3. 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:

Use the save_memory tool to save this information about vector databases: "Vector databases like pgvector store and query high-dimensional vectors for semantic search applications."

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:

Use the search_memories tool to find information about "vector databases"

Parameters:

• query (required): The search query
• debug (optional): Include debug information in results (default: false)

Get All Memories

Retrieve all memories:

Use the get_all_memories tool to show me all my saved memories

Get Bucket Memories

Get memories from a specific bucket:

Use the get_bucket_memories tool to show me memories in the "Learning" bucket

Parameters:

• bucket_id (required): The bucket to retrieve memories from

Format Memory

Format a text according to the memory system prompt without saving:

Use the format_memory tool to format this text: "Vector databases like pgvector store and query high-dimensional vectors for semantic search applications."

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:

Use the get_related_memories tool with memory ID 123

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:

Use the check_memory_status tool with memory ID 123

Parameters:

• memory_id (required): The ID of the memory to check status for

Get Usage Stats

Retrieve user usage statistics and plan information:

Use the get_usage_stats tool to show me my current plan and usage metrics

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.

Get Buckets

List all available buckets:

Use the get_buckets tool to show me all available buckets

This tool returns a list of all buckets with their names, IDs, memory counts, and creation dates.

Create Bucket

Create a new bucket for organizing memories:

Use the create_bucket tool to create a bucket named "Project Ideas"

Parameters:

• bucket_name (required): Name of the bucket to create

Delete Bucket

Delete an existing bucket:

Use the delete_bucket tool to delete the bucket named "Old Notes"

Parameters:

• bucket_name (required): Name of the bucket to delete
• force (optional): Force deletion even if bucket contains memories (default: false)

Update Memory

Update an existing memory's content, bucket, or metadata:

Use the update_memory tool to update memory ID 123 with new text: "Updated information about vector databases"

Parameters:

• memory_id (required): The ID of the memory to update
• text (optional): New text content for the memory
• bucket_id (optional): New bucket for the memory
• reference_data (optional): Updated reference data including relationships

Delete Memory

Delete a specific memory:

Use the delete_memory tool to delete memory ID 123

Parameters:

• memory_id (required): The ID of the memory to delete

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:

You are a helpful AI assistant. When storing memories with Memory Box, follow these enhanced formatting guidelines:

1. STRUCTURE: Format memories based on the type of information:
   - TECHNICAL: "TECHNICAL - [Brief topic]: [Concise explanation with specific details]"
   - DECISION: "DECISION - [Brief topic]: [Decision made] because [rationale]. Alternatives considered: [options]."
   - SOLUTION: "SOLUTION - [Problem summary]: [Implementation details that solved the issue]"
   - CONCEPT: "CONCEPT - [Topic]: [Clear explanation of the concept with examples]"
   - REFERENCE: "REFERENCE - [Topic]: [URL, tool name, or resource] for [specific purpose]"
   - APPLICATION: "APPLICATION - [App name]: [User-friendly description] followed by [technical implementation details]"

2. FORMATTING GUIDELINES:
   - CREATE FOCUSED MEMORIES: Each memory should contain a single clear concept or topic
   - USE DIVERSE TERMINOLOGY: Include both technical terms AND user-friendly alternatives
   - INCLUDE SEARCHABLE KEYWORDS: Begin with common terms a user might search for
   - BALANCE DETAIL LEVELS: Include both high-level descriptions and key technical details
   - LENGTH: Keep memories between 50-150 words
   - ALWAYS include the current date in YYYY-MM-DD format

3. MEMORY STORAGE PARAMETERS:
   - Use the "text" parameter for your formatted memory content
   - Set "source_type" to "llm_plugin"
   - Include appropriate "reference_data" with source information and context

4. REFERENCE DATA STRUCTURE:
   - source.platform: Identify your platform (e.g., "claude_desktop", "cline")
   - source.type: Always set to "llm_plugin"
   - source.version: Optional version information
   - context.conversation_id: Include when available to link related conversation memories
   - context.message_id: Optional identifier for the specific message

5. SPECIAL FORMATS:
   - For user facts, preferences, or personal details: "YYYY-MM-DD: FACT: [User] [specific preference/attribute/information]"
   - For reference materials: Include specific details about where to find the information

6. RELATED MEMORIES: After finding memories with search, check if there are related memories using the get_related_memories tool with the memory_id from search results. Present these additional memories to provide the user with more context.

7. RETRIEVAL CONSIDERATION: Before storing an important memory, consider: "What search terms might someone use to find this information later?" and ensure those terms are included.

How to Customize the System Prompt

To customize the system prompt:

1. Edit the Cline MCP settings file at:

   ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   

2. Add your custom system prompt to the SYSTEM_PROMPT environment variable:

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

3. Restart Cline to apply the changes

System Prompt Helper

The Memory Box MCP server includes a helper script for managing the system prompt:

# View the current system prompt
cd <path-to-repository>
npm run prompt-helper -- view

# Reset to the default system prompt
cd <path-to-repository>
npm run prompt-helper -- reset

# Validate a custom system prompt
cd <path-to-repository>
npm run prompt-helper -- validate

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:

1. Check that your Memory Box token is correctly configured
2. Verify that your Memory Box instance is running and accessible
3. Check the Cline logs for any error messages

Development

To make changes to the server:

1. Edit the source code in <path-to-repository>/src/
2. Rebuild the server:

   cd <path-to-repository>
   npm run build
   

3. Restart Cline to apply the changes

Building the Desktop Extension

To build the Desktop Extension package:

1. Install dependencies:

   npm install
   

2. Build the extension:

   npm run build-extension
   

3. The built extension will be available at dist/memory-box.dxt

Release Process

1. Update version in package.json
2. Update CHANGELOG.md with new changes
3. Commit changes
4. Create a new GitHub release
5. Upload the memory-box.dxt file as a release asset