Memory Mesh CLI

A command-line tool to configure AI-powered knowledge management for development teams using Memory Mesh MCP integration.

Overview

The Memory Mesh CLI provides two essential commands for setting up Memory Mesh MCP integration:

• init - Initialize your project with Memory Mesh configuration files and IDE integration
• install - Configure MCP server connection to Memory Mesh service

This CLI enables AI assistants in your IDE to access and create memory fragments, search team knowledge, explore relationships, and maintain institutional knowledge across your development team.

Installation

npm install -g @memory-mesh/mcp-server

Or use directly with npx:

npx @memory-mesh/mcp-server init
npx @memory-mesh/mcp-server install

Commands

Initialize Project

Initialize your project with Memory Mesh configuration:

npx @memory-mesh/mcp-server init

Options:

• --ide <ide> - IDE to configure (default: "cursor")
• --output-dir <dir> - Output directory for IDE config files (default: ".")
• --workspace-id <id> - Optional: Memory Mesh workspace ID to fetch fragment types
• --api-token <token> - Optional: Memory Mesh API access token to fetch fragment types
• --memory-mesh-url <url> - Optional: Memory Mesh API URL (default: "https://memory-mesh.com")
• --skip-auto-install - Skip automatic MCP server installation (default: false)
• --pre-prompt <text> - Custom pre-prompt to prepend to system prompt

Pre-Prompt Customization

The init command supports customizing the AI system prompt for your specific project needs through pre-prompts:

Methods to specify a pre-prompt:

1. CLI Option: Use --pre-prompt "Your custom instructions" directly in the command
2. File-Based: Create a .pre-prompt.md file in your project root directory
3. Interactive: The CLI will prompt you if no pre-prompt is provided via the above methods

Pre-prompt behavior:

• Pre-prompts are prepended to the system prompt fetched from Memory Mesh API
• They allow project-specific customization (coding standards, patterns, preferences)
• The final prompt structure: Custom Pre-Prompt → Memory Mesh API System Prompt

Example usage:

# Via CLI option
npx @memory-mesh/mcp-server init --pre-prompt "Follow strict TypeScript patterns and use functional programming"

# Via file (create .pre-prompt.md in project root)
echo "Use our company's coding standards and always include unit tests" > .pre-prompt.md
npx @memory-mesh/mcp-server init

Use cases:

• Project-specific coding standards and patterns
• Team conventions and best practices
• Technology-specific guidelines
• Custom AI behavior preferences

Auto-Detection & Auto-Install Behavior

The init command includes intelligent auto-detection and auto-install features:

1. IDE Detection: Automatically detects existing MCP installations across multiple IDEs
2. Auto-Install: If no MCP installation is found, prompts to automatically install
3. Smart Configuration: Creates IDE-specific configuration files with repository context

Supported IDEs for Auto-Detection:

• Cursor: ~/.cursor/mcp.json, ~/Library/Application Support/Cursor/, ~/.config/cursor/
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• VS Code: ~/Library/Application Support/Code/User/, ~/.vscode/
• Cline: ~/.cline/, ~/Library/Application Support/Cline/, ~/.config/cline/
• Zed: ~/.zed/, ~/Library/Application Support/Zed/, ~/.config/zed/
• Windsurf: ~/.windsurf/, ~/Library/Application Support/Windsurf/, ~/.config/windsurf/
• JetBrains IDEs: ~/Library/Application Support/JetBrains/*/mcp.json
• Sublime Text: ~/Library/Application Support/Sublime Text/Packages/User/
• Vim/Neovim: ~/.vim/, ~/.config/nvim/
• Emacs: ~/.emacs.d/

This command creates project-specific IDE configuration files:

• .cursor/rules/memory-mesh.mdc - Cursor IDE rules for Memory Mesh MCP integration

The configuration includes:

• Repository context and workspace mapping
• Fragment type definitions (knowledge, recipe, solution, template, code-snippet, styling)
• Available Memory Mesh MCP tools and usage guidelines
• Pre-task and post-task workflows for AI assistants

Install MCP Server Connection

Configure MCP server connection to Memory Mesh:

npx @memory-mesh/mcp-server install --api-token <token>

Options:

• --api-token <token> - Memory Mesh API access token (required)
• --memory-mesh-url <url> - Memory Mesh API URL (default: "https://memory-mesh.com")
• --db-path <path> - Custom database file path (default: "~/.memory-mesh-mcp/cache.db")

This command:

1. Validates your Memory Mesh API connection and authentication
2. Configures the MCP server connection in your IDE's configuration
3. Sets up the remote HTTP transport to Memory Mesh MCP endpoint
4. Creates the database directory structure for local caching

Run Local MCP Server (Legacy/Development)

For backwards compatibility or development purposes, run a local MCP server:

npx @memory-mesh/mcp-server server

Options:

• Environment variables:
  • MEMORY_MESH_API_TOKEN or MEMORY_MESH_ACCESS_TOKEN - Your API token (required)
  • MEMORY_MESH_BASE_URL - Memory Mesh API URL (default: "https://memory-mesh.com")
  • DEFAULT_WORKSPACE_ID - Default workspace ID for operations

Note: This local server mode is provided for backwards compatibility with older IDE configurations. The remote MCP server connection (configured via install command) is recommended for optimal performance and reliability.

Usage Workflow

1. Get your API token from the Memory Mesh web interface

2. Initialize your project (with workspace selection):

   npx @memory-mesh/mcp-server init --api-token <token>

   Or let the CLI prompt you for the token:

   npx @memory-mesh/mcp-server init

   With pre-prompt customization:

   # With custom pre-prompt via CLI
   npx @memory-mesh/mcp-server init --api-token <token> --pre-prompt "Follow our React coding standards"
   
   # With pre-prompt file
   echo "Use TypeScript strict mode and functional patterns" > .pre-prompt.md
   npx @memory-mesh/mcp-server init --api-token <token>

3. Install MCP server connection:

   npx @memory-mesh/mcp-server install --api-token <token>

4. Restart your IDE to load the MCP server configuration

Memory Mesh MCP Tools

Once configured, AI assistants in your IDE will have access to these Memory Mesh tools:

Core Fragment Management

• create_memory_fragment - Create new memory fragments (knowledge, recipe, solution, template, etc.)
• search_memory_fragments - AI-powered semantic search with similarity scores and filters
• get_memory_fragment_content - Retrieve full content of specific fragments by ID

Knowledge Discovery & Navigation

• find_related_fragments - Discover fragments connected through shared tags and relationships
• explore_workspace_graph - Get knowledge graph visualization with nodes and relationships
• explore_tag_connections - Navigate fragments through specific tag relationships
• list_workspaces - List accessible workspaces with permissions

AI Assistant Workflow

The tools are designed for a comprehensive knowledge management workflow:

1. Search existing knowledge first (search_memory_fragments)
2. Explore relationships if you need more context:
   • explore_workspace_graph - Overall knowledge structure
   • explore_tag_connections - Tag-based relationships
   • find_related_fragments - Fragment connections
3. Create new fragments when discovering novel solutions (create_memory_fragment)
4. Iterate until you have complete context for your task

Configuration

Remote MCP Server Configuration (Recommended)

The CLI updates your IDE's MCP configuration file (e.g., ~/.cursor/mcp.json) with:

{
  "mcpServers": {
    "memory-mesh": {
      "url": "https://memory-mesh.com/api/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer your-api-token"
      }
    }
  }
}

Local MCP Server Configuration (Legacy)

For backwards compatibility with IDEs requiring stdio MCP servers:

{
  "mcpServers": {
    "memory-mesh-local": {
      "command": "npx",
      "args": ["@memory-mesh/mcp-server", "server"],
      "env": {
        "MEMORY_MESH_API_TOKEN": "your-api-token",
        "MEMORY_MESH_BASE_URL": "https://memory-mesh.com"
      }
    }
  }
}

Environment Variables for Local Server:

• MEMORY_MESH_API_TOKEN or MEMORY_MESH_ACCESS_TOKEN - Your API token (required)
• MEMORY_MESH_BASE_URL - Memory Mesh API URL (default: "https://memory-mesh.com")
• DEFAULT_WORKSPACE_ID - Default workspace ID for operations

Project Configuration Files

The init command creates project-specific configuration:

.cursor/rules/memory-mesh.mdc - Contains:

• Repository and workspace context mapping
• Fragment type definitions and IDs
• Complete Memory Mesh MCP tool documentation
• Usage guidelines and workflow instructions
• Pre-task and post-task workflows for AI assistants
• Custom pre-prompt content (if specified during init)

Database & Caching

The install command sets up local database structure:

• Default location: ~/.memory-mesh-mcp/cache.db
• Purpose: Local caching and sync state management
• Customizable: Use --db-path to specify custom location

Package Architecture

This package provides two modes of Memory Mesh MCP integration:

🌐 Remote MCP Server (Recommended)

The primary and recommended integration method:

• What it is: Direct HTTP connection from your IDE to Memory Mesh MCP service
• Configuration: Via init and install CLI commands
• Benefits: Always up-to-date, no local server management, optimal performance
• Integration Flow: IDE MCP Client → memory-mesh.com/api/mcp

🖥️ Local MCP Server (Legacy/Backwards Compatibility)

A local proxy server for older IDE configurations or special use cases:

# Run local MCP server mode
npx @memory-mesh/mcp-server server

# Or with specific configuration
MEMORY_MESH_API_TOKEN="your-token" npx @memory-mesh/mcp-server server

Local Server Features:

• Proxy Mode: Acts as a local MCP server that proxies requests to Memory Mesh API
• Stdio Transport: Compatible with IDEs that require stdio MCP servers
• Demo Mode: Falls back to demo tools when Memory Mesh API is unavailable
• Error Handling: Structured JSON-RPC error responses with proper error codes

When to use Local Server:

• ⚠️ Legacy IDE configurations that require stdio MCP servers
• 🔧 Development and testing of MCP integration
• 🌐 Network-restricted environments requiring local proxy

Important Notes:

• 🚨 Use Remote MCP Server when possible - it's faster, more reliable, and always current
• 📦 Backwards Compatibility - Local server mode is maintained for older IDE setups
• 🔄 Real-time Sync - Local server includes background streaming for real-time updates

Integration Flow Comparison

Remote (Recommended):

1. CLI Configuration (init + install) →
2. IDE MCP Client →
3. Memory Mesh MCP Service (hosted at memory-mesh.com)

Local (Legacy):

1. CLI Configuration (init + install) →
2. Local MCP Server (npx @memory-mesh/mcp-server server) →
3. IDE MCP Client (via stdio) →
4. Memory Mesh MCP Service (proxied)

Troubleshooting

Common Issues

"API token is required" - The init command requires an API token to fetch workspace information and fragment types. Provide it via:

• Command line: --api-token <token>
• Environment variable: MEMORY_MESH_API_TOKEN
• Interactive prompt (CLI will ask if not provided)

"Failed to connect to Memory Mesh service" - Check:

• Network connectivity to memory-mesh.com
• API token validity and permissions
• Workspace access permissions

"MCP server not found in IDE" - After installation:

• Restart your IDE completely
• Check MCP configuration file exists (e.g., ~/.cursor/mcp.json)
• Verify the configuration JSON syntax is valid

"Pre-prompt not appearing in generated rules" - Check:

• Pre-prompt was specified correctly via --pre-prompt, .pre-prompt.md file, or interactive prompt
• API credentials are provided (pre-prompts require successful API connection)
• Generated .cursor/rules/memory-mesh.mdc file contains your custom pre-prompt at the top

"Want to update pre-prompt for existing project" - Solutions:

• Re-run init command with new --pre-prompt value (will prompt to overwrite existing files)
• Manually edit the .pre-prompt.md file and re-run init
• Update the generated .cursor/rules/memory-mesh.mdc file directly (not recommended as it may be overwritten)

Requirements

• Node.js >= 18.0.0
• Valid Memory Mesh workspace and API credentials
• Compatible IDE with MCP support (Cursor, Claude Desktop, VS Code, etc.)

License

MIT