mcp-with-ssh

# Memory Bank MCP With Remote SSH Support 🧠 [](https://www.npmjs.com/package/@aakarsh-sasi/memory-bank-mcp) [](https://opensource.org/licenses/MIT) [](https://github.com/movibe/memory-bank-mcp/actions/workflows/test.yml) [](https://smithery.ai/server/@aakarsh-sasi/memory-bank-mcp) A Model Context Protocol (MCP) server for managing Memory Banks, allowing AI assistants to store and retrieve information across sessions. Now with remote server support! <a href="https://glama.ai/mcp/servers/@aakarsh-sasi/memory-bank-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@aakarsh-sasi/memory-bank-mcp/badge" alt="Memory Bank MCP server" /> </a> ## Overview 📋 Memory Bank Server provides a set of tools and resources for AI assistants to interact with Memory Banks. Memory Banks are structured repositories of information that help maintain context and track progress across multiple sessions. ## Features ✨ - **Memory Bank Management**: Initialize, find, and manage Memory Banks - **File Operations**: Read and write files in Memory Banks - **Progress Tracking**: Track progress and update Memory Bank files - **Decision Logging**: Log important decisions with context and alternatives - **Active Context Management**: Maintain and update active context information - **Mode Support**: Detect and use .clinerules files for mode-specific behavior - **UMB Command**: Update Memory Bank files temporarily with the UMB command - **Robust Error Handling**: Gracefully handle errors and continue operation when possible - **Status Prefix System**: Immediate visibility into Memory Bank operational state - **Remote Server Support**: Store Memory Banks on a remote server using SSH ## Directory Structure 📁 By default, Memory Bank uses a `memory-bank` directory in the root of your project. When you specify a project path using the `--path` option, the Memory Bank will be created or accessed at `<project_path>/memory-bank`. You can customize the name of the Memory Bank folder using the `--folder` option. For example, if you set `--folder custom-memory`, the Memory Bank will be created or accessed at `<project_path>/custom-memory`. For more details on customizing the folder name, see [Custom Memory Bank Folder Name](docs/custom-folder-name.md). ## Recent Improvements 🛠️ - **Remote Server Support**: Store your Memory Bank on a remote server via SSH - **Customizable Folder Name**: You can now specify a custom folder name for the Memory Bank - **Consistent Directory Structure**: Memory Bank now always uses the configured folder name in the project root - **Enhanced Initialization**: Memory Bank now works even when .clinerules files don't exist - **Better Path Handling**: Improved handling of absolute and relative paths - **Improved Directory Detection**: Better detection of existing memory-bank directories - **More Robust Error Handling**: Graceful handling of errors related to .clinerules files For more details, see [Memory Bank Bug Fixes](docs/memory-bank-bug-fixes.md). ## Installation 🚀 ### Installing via Smithery To install Memory Bank for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@aakarsh-sasi/memory-bank-mcp): ```bash npx -y @smithery/cli install @aakarsh-sasi/memory-bank-mcp --client claude ``` ### Manual Installation ```bash # Install from npm npm install @aakarsh-sasi/memory-bank-mcp # Or install globally npm install -g @aakarsh-sasi/memory-bank-mcp # Or run directly with npx (no installation required) npx @aakarsh-sasi/memory-bank-mcp ``` ## Usage with npx 💻 You can run Memory Bank MCP directly without installation using npx: ```bash # Run with default settings npx @aakarsh-sasi/memory-bank-mcp # Run with specific mode npx @aakarsh-sasi/memory-bank-mcp --mode code # Run with custom project path npx @aakarsh-sasi/memory-bank-mcp --path /path/to/project # Run with custom folder name npx @aakarsh-sasi/memory-bank-mcp --folder custom-memory-bank # Run with remote server npx @aakarsh-sasi/memory-bank-mcp --remote --remote-user username --remote-host example.host.com --remote-path /home/username/memory-bank # Show help npx @aakarsh-sasi/memory-bank-mcp --help ``` For more detailed information about using npx, see [npx-usage.md](docs/npx-usage.md). ## Using Remote Server Mode 🌐 Memory Bank MCP now supports storing your Memory Bank on a remote server via SSH. This allows you to: 1. **Centralize your Memory Bank**: Keep all your project memory in one place 2. **Share Memory Banks**: Multiple users can access the same Memory Bank 3. **Persistent Storage**: Your Memory Bank persists even if your local machine is wiped ### Remote Server Requirements - SSH access to the remote server - SSH key authentication set up (password authentication is not supported) - Sufficient permissions to create/modify files in the specified directory ### SSH Key Setup To set up SSH key authentication for the remote server: 1. **Generate a new SSH key pair** (if you don't already have one): ```bash # Using modern Ed25519 algorithm (recommended) ssh-keygen -t ed25519 -C "your_email@example.com" # OR using RSA if required for compatibility ssh-keygen -t rsa -b 4096 -C "your_email@example.com" ``` 2. **Start the SSH agent and add your key**: ```bash # Start the agent eval "$(ssh-agent -s)" # Add your key ssh-add ~/.ssh/id_ed25519 # or ~/.ssh/id_rsa if you used RSA ``` 3. **Copy your public key to the remote server**: ```bash # Easiest method (if available) ssh-copy-id username@your-remote-host.com # Alternative: manually copy your public key cat ~/.ssh/id_ed25519.pub # copy the output ``` Then paste the key into the `~/.ssh/authorized_keys` file on the remote server. 4. **Test your connection**: ```bash ssh username@your-remote-host.com ``` You should be able to log in without a password. For more detailed SSH key setup instructions, see our [SSH Keys Guide](docs/ssh-keys-guide.md). ### Remote Server Configuration To use remote server mode, you need to provide the following parameters: ```bash npx @aakarsh-sasi/memory-bank-mcp --remote \ --ssh-key ~/.ssh/your_ssh_key \ --remote-user username \ --remote-host example.host.com \ --remote-path /home/username/memory-bank ``` By default, the SSH key is assumed to be at `~/.ssh/your_ssh_key`. You can specify a different key using the `--ssh-key` option. ### Remote Server Example ```bash # Using with a server at example.host.com npx @aakarsh-sasi/memory-bank-mcp --remote \ --remote-user username \ --remote-host example.host.com \ --remote-path /home/username/memory-bank ``` ## Configuring in Cursor 🖱️ Cursor is an AI-powered code editor that supports the Model Context Protocol (MCP). To configure Memory Bank MCP in Cursor: 1. **Use Memory Bank MCP with npx**: No need to install the package globally. You can use npx directly: ```bash # Verify npx is working correctly npx @aakarsh-sasi/memory-bank-mcp --help ``` 2. **Open Cursor Settings**: - Go to Settings (⚙️) > Extensions > MCP - Click on "Add MCP Server" 3. **Configure the MCP Server**: - **Name**: Memory Bank MCP - **Command**: npx - **Arguments**: `@aakarsh-sasi/memory-bank-mcp --mode code` (or other mode as needed) For remote server: - **Arguments**: `@aakarsh-sasi/memory-bank-mcp --mode code --remote --remote-user username --remote-host example.host.com --remote-path /home/username/memory-bank` 4. **Save and Activate**: - Click "Save" - Enable the MCP server by toggling it on 5. **Verify Connection**: - Open a project in Cursor - The Memory Bank MCP should now be active and available in your AI interactions For detailed instructions and advanced usage with Cursor, see [cursor-integration.md](docs/cursor-integration.md). ### Using with Cursor 🤖 Once configured, you can interact with Memory Bank MCP in Cursor through AI commands: - **Initialize a Memory Bank**: `/mcp memory-bank-mcp initialize_memory_bank path=./memory-bank` - **Track Progress**: `/mcp memory-bank-mcp track_progress action="Feature Implementation" description="Implemented feature X"` - **Log Decision**: `/mcp memory-bank-mcp log_decision title="API Design" context="..." decision="..."` - **Switch Mode**: `/mcp memory-bank-mcp switch_mode mode=code` ## MCP Modes and Their Usage 🔄 Memory Bank MCP supports different operational modes to optimize AI interactions for specific tasks: ### Available Modes 1. **Code Mode** 👨‍💻 - Focus: Code implementation and development - Usage: `npx @aakarsh-sasi/memory-bank-mcp --mode code` - Best for: Writing, refactoring, and optimizing code 2. **Architect Mode** 🏗️ - Focus: System design and architecture - Usage: `npx @aakarsh-sasi/memory-bank-mcp --mode architect` - Best for: Planning project structure, designing components, and making architectural decisions 3. **Ask Mode** ❓ - Focus: Answering questions and providing information - Usage: `npx @aakarsh-sasi/memory-bank-mcp --mode ask` - Best for: Getting explanations, clarifications, and information 4. **Debug Mode** 🐛 - Focus: Troubleshooting and problem-solving - Usage: `npx @aakarsh-sasi/memory-bank-mcp --mode debug` - Best for: Finding and fixing bugs, analyzing issues 5. **Test Mode** ✅ - Focus: Testing and quality assurance - Usage: `npx @aakarsh-sasi/memory-bank-mcp --mode test` - Best for: Writing tests, test-driven development ### Switching Modes You can switch modes in several ways: 1. **When starting the server**: ```bash npx @aakarsh-sasi/memory-bank-mcp --mode architect ``` 2. **During a session**: ```bash memory-bank-mcp switch_mode mode=debug ``` 3. **In Cursor**: ``` /mcp memory-bank-mcp switch_mode mode=test ``` 4. **Using .clinerules files**: Create a `.clinerules-[mode]` file in your project to automatically switch to that mode when the file is detected. ## How Memory Bank MCP Works 🧠 Memory Bank MCP is built on the Model Context Protocol (MCP), which enables AI assistants to interact with external tools and resources. Here's how it works: ### Core Components 🧩 1. **Memory Bank**: A structured repository of information stored as markdown files: - `product-context.md`: Overall project information and goals - `active-context.md`: Current state, ongoing tasks, and next steps - `progress.md`: History of project updates and milestones - `decision-log.md`: Record of important decisions with context and rationale - `system-patterns.md`: Architecture and code patterns used in the project 2. **MCP Server**: Provides tools and resources for AI assistants to interact with Memory Banks: - Runs as a standalone process - Communicates with AI assistants through the MCP protocol - Provides a set of tools for managing Memory Banks 3. **Mode System**: Supports different operational modes: - `code`: Focus on code implementation - `ask`: Focus on answering questions - `architect`: Focus on system design - `debug`: Focus on debugging issues - `test`: Focus on testing ### Data Flow 🔄 1. **Initialization**: The AI assistant connects to the MCP server and initializes a Memory Bank 2. **Tool Calls**: The AI assistant calls tools provided by the MCP server to read/write Memory Bank files 3. **Context Maintenance**: The Memory Bank maintains context across sessions, allowing the AI to recall previous decisions and progress ### Memory Bank Structure 📂 Memory Banks use a standardized structure to organize information: - **Product Context**: Project overview, objectives, technologies, and architecture - **Active Context**: Current state, ongoing tasks, known issues, and next steps - **Progress**: Chronological record of project updates and milestones - **Decision Log**: Record of important decisions with context, alternatives, and consequences - **System Patterns**: Architecture patterns, code patterns, and documentation patterns ### Advanced Features 🚀 - **UMB Command**: Temporarily update Memory Bank files during a session without committing changes - **Mode Detection**: Automatically detect and switch modes based on user input - **File Migration**: Tools for migrating between different file naming conventions - **Language Standardization**: All Memory Bank files are generated in English for consistency ## Versioning 📌 This project follows [Semantic Versioning](https://semver.org/) and uses [Conventional Commits](https://www.conventionalcommits.org/) for commit messages. The version is automatically bumped and a changelog is generated based on commit messages when changes are merged into the main branch. - **Major version** is bumped when there are breaking changes (commit messages with `BREAKING CHANGE` or `!:`) - **Minor version** is bumped when new features are added (commit messages with `feat:` or `feat(scope):`) - **Patch version** is bumped for all other changes (bug fixes, documentation, etc.) For the complete history of changes, see the [CHANGELOG.md](CHANGELOG.md) file. ## Usage 📝 ### As a Command Line Tool 💻 ```bash # Initialize a Memory Bank memory-bank-mcp initialize_memory_bank path=./memory-bank # Track progress memory-bank-mcp track_progress action="Feature Implementation" description="Implemented feature X" # Log a decision memory-bank-mcp log_decision title="API Design" context="..." decision="..." # Switch mode memory-bank-mcp switch_mode mode=code ``` ### As a Library 📚 ```typescript import { MemoryBankServer } from "@aakarsh-sasi/memory-bank-mcp"; // Create a new server instance const server = new MemoryBankServer(); // Start the server server.run().catch(console.error); ``` ## Contributing 👥 Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests. ## License 📄 This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Memory Bank Status System 🚦 Memory Bank MCP implements a status prefix system that provides immediate visibility into the operational state of the Memory Bank: ### Status Indicators Every response from an AI assistant using Memory Bank MCP begins with one of these status indicators: - **`[MEMORY BANK: ACTIVE]`**: The Memory Bank is available and being used to provide context-aware responses - **`[MEMORY BANK: INACTIVE]`**: The Memory Bank is not available or not properly configured - **`[MEMORY BANK: UPDATING]`**: The Memory Bank is currently being updated (during UMB command execution) This system ensures users always know whether the AI assistant is operating with full context awareness or limited information. ### Benefits - **Transparency**: Users always know whether the AI has access to the full project context - **Troubleshooting**: Makes it immediately obvious when Memory Bank is not properly configured - **Context Awareness**: Helps users understand why certain responses may lack historical context For more details, see [Memory Bank Status Prefix System](docs/memory-bank-status-prefix.md).