Memory Bank MCP With Remote SSH Support 🧠

支持远程 SSH 的 Memory Bank MCP 🧠

一个用于管理 Memory Bank 的 Model Context Protocol (MCP) 服务，让 AI 助手能够跨会话存储和检索信息。现在支持远程服务！

概述 📋

Memory Bank 服务为 AI 助手提供了一组工具和资源，用于与 Memory Bank 交互。Memory Bank 是结构化的信息存储库，可帮助跨多个会话维持上下文并跟踪进度。

功能 ✨

• Memory Bank 管理：初始化、查找和管理 Memory Bank
• 文件操作：读取和写入 Memory Bank 中的文件
• 进度跟踪：跟踪进度并更新 Memory Bank 文件
• 决策记录：记录重要决策及其背景和备选方案
• 活动上下文管理：维护和更新活动上下文信息
• 模式支持：检测并使用 .clinerules 文件实现特定模式的行为
• UMB 命令：使用 UMB 命令临时更新 Memory Bank 文件
• 健壮的错误处理：妥善处理错误，并在可能时继续运行
• 状态前缀系统：立即了解 Memory Bank 的运行状态
• 远程服务支持：通过 SSH 将 Memory Bank 存储在远程服务上

目录结构 📁

默认情况下，Memory Bank 会在项目根目录中使用 memory-bank 目录。使用 --path 选项指定项目路径时，Memory Bank 将在 <project_path>/memory-bank 中创建或访问。

你可以使用 --folder 选项自定义 Memory Bank 文件夹的名称。例如，如果设置 --folder custom-memory，Memory Bank 将在 <project_path>/custom-memory 中创建或访问。

如需了解自定义文件夹名称的详细信息，请参阅自定义 Memory Bank 文件夹名称。

最新改进 🛠️

• 远程服务支持：通过 SSH 将 Memory Bank 存储在远程服务上
• 可自定义文件夹名称：现在可以为 Memory Bank 指定自定义文件夹名称
• 统一的目录结构：Memory Bank 现在始终在项目根目录中使用已配置的文件夹名称
• 改进的初始化：即使 .clinerules 文件不存在，Memory Bank 现在也能正常工作
• 更完善的路径处理：改进了对绝对路径和相对路径的处理
• 改进的目录检测：更准确地检测已有的 memory-bank 目录
• 更健壮的错误处理：妥善处理与 .clinerules 文件相关的错误

如需了解详细信息，请参阅 Memory Bank 错误修复。

安装 🚀

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Memory Bank：

npx -y @smithery/cli install @aakarsh-sasi/memory-bank-mcp --client claude

手动安装

# 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

使用 npx 💻

你可以使用 npx 直接运行 Memory Bank MCP，无需安装：

# 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

如需了解使用 npx 的更多详细信息，请参阅 npx-usage.md。

使用远程服务模式 🌐

Memory Bank MCP 现已支持通过 SSH 将 Memory Bank 存储在远程服务上。这样你可以：

1. 集中管理 Memory Bank：将所有项目记忆存放在同一位置
2. 共享 Memory Bank：多位用户可以访问同一个 Memory Bank
3. 持久化存储：即使本地计算机被清空，你的 Memory Bank 仍会保留

远程服务要求

• 可通过 SSH 访问远程服务
• 已设置 SSH 密钥身份验证（不支持密码身份验证）
• 对指定目录拥有足够权限，可以创建和修改文件

SSH 密钥设置

要为远程服务设置 SSH 密钥身份验证：

1. 生成新的 SSH 密钥对（如果你还没有）：

   # Using modern Ed25519 algorithm (recommended)
   ssh-keygen -t ed25519 -C "[email protected]"
   
   # OR using RSA if required for compatibility
   ssh-keygen -t rsa -b 4096 -C "[email protected]"
   

2. 启动 SSH 代理并添加密钥：

   # Start the agent
   eval "$(ssh-agent -s)"
   
   # Add your key
   ssh-add ~/.ssh/id_ed25519  # or ~/.ssh/id_rsa if you used RSA
   

3. 将公钥复制到远程服务：

   # Easiest method (if available)
   ssh-copy-id [email protected]
   
   # Alternative: manually copy your public key
   cat ~/.ssh/id_ed25519.pub  # copy the output
   

   然后将密钥粘贴到远程服务上的 ~/.ssh/authorized_keys 文件中。

4. 测试连接：

   ssh [email protected]
   

   你应该可以无需密码登录。

如需更详细的 SSH 密钥设置说明，请参阅我们的 SSH 密钥指南。

远程服务配置

要使用远程服务模式，需要提供以下参数：

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

默认情况下，SSH 密钥路径为 ~/.ssh/your_ssh_key。你可以使用 --ssh-key 选项指定其他密钥。

远程服务示例

# 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

在 Cursor 中配置 🖱️

Cursor 是一款支持 Model Context Protocol（MCP）的 AI 代码编辑器。要在 Cursor 中配置 Memory Bank MCP：

1. 通过 npx 使用 Memory Bank MCP：

   无需全局安装软件包。你可以直接使用 npx：

   # Verify npx is working correctly
   npx @aakarsh-sasi/memory-bank-mcp --help
   

2. 打开 Cursor 设置：

   • 前往设置（⚙️）> 扩展 > MCP
   • 点击“添加 MCP 服务”

3. 配置 MCP 服务：

   • 名称：Memory Bank MCP
   • 命令：npx
   • 参数：@aakarsh-sasi/memory-bank-mcp --mode code（或根据需要选择其他模式）

   远程服务配置：

   • 参数：@aakarsh-sasi/memory-bank-mcp --mode code --remote --remote-user username --remote-host example.host.com --remote-path /home/username/memory-bank

4. 保存并启用：

   • 点击“保存”
   • 切换开关以启用 MCP 服务

5. 验证连接：

   • 在 Cursor 中打开一个项目
   • Memory Bank MCP 此时应已启用，并可在 AI 交互中使用

如需 Cursor 的详细配置说明和高级用法，请参阅 cursor-integration.md。

在 Cursor 中使用 🤖

配置完成后，你可以在 Cursor 中通过 AI 命令与 Memory Bank MCP 交互：

• 初始化 Memory Bank：/mcp memory-bank-mcp initialize_memory_bank path=./memory-bank
• 跟踪进度：/mcp memory-bank-mcp track_progress action="Feature Implementation" description="Implemented feature X"
• 记录决策：/mcp memory-bank-mcp log_decision title="API Design" context="..." decision="..."
• 切换模式：/mcp memory-bank-mcp switch_mode mode=code

MCP 模式及其用途 🔄

Memory Bank MCP 支持不同的运行模式，可针对特定任务优化 AI 交互：

可用模式

1. Code 模式 👨‍💻

   • 重点：代码实现与开发
   • 用法：npx @aakarsh-sasi/memory-bank-mcp --mode code
   • 适用于：编写、重构和优化代码

2. Architect 模式 🏗️

   • 重点：系统设计与架构
   • 用法：npx @aakarsh-sasi/memory-bank-mcp --mode architect
   • 适用于：规划项目结构、设计组件和制定架构决策

3. Ask 模式 ❓

   • 重点：回答问题并提供信息
   • 用法：npx @aakarsh-sasi/memory-bank-mcp --mode ask
   • 适用于：获取解释、澄清和信息

4. Debug 模式 🐛

   • 重点：故障排查与问题解决
   • 用法：npx @aakarsh-sasi/memory-bank-mcp --mode debug
   • 适用于：查找并修复错误、分析问题

5. Test 模式 ✅

   • 重点：测试与质量保障
   • 用法：npx @aakarsh-sasi/memory-bank-mcp --mode test
   • 适用于：编写测试、进行测试驱动开发

切换模式

你可以通过多种方式切换模式：

1. 启动服务时：

   npx @aakarsh-sasi/memory-bank-mcp --mode architect
   

2. 会话期间：

   memory-bank-mcp switch_mode mode=debug
   

3. 在 Cursor 中：

   /mcp memory-bank-mcp switch_mode mode=test
   

4. 使用 .clinerules 文件： 在项目中创建 .clinerules-[mode] 文件，检测到该文件时即可自动切换到对应模式。

Memory Bank MCP 的工作原理 🧠

Memory Bank MCP 基于 Model Context Protocol（MCP）构建，该协议可让 AI 助手与外部工具和资源交互。其工作原理如下：

核心组件 🧩

1. Memory Bank：以 Markdown 文件形式存储信息的结构化仓库：

   • product-context.md：项目整体信息与目标
   • active-context.md：当前状态、正在进行的任务和后续步骤
   • progress.md：项目更新和里程碑的历史记录
   • decision-log.md：重要决策及其背景和理由的记录
   • system-patterns.md：项目中使用的架构和代码模式

2. MCP 服务：为 AI 助手提供工具和资源，以便与 Memory Bank 交互：

   • 作为独立进程运行
   • 通过 MCP 协议与 AI 助手通信
   • 提供一组用于管理 Memory Bank 的工具

3. 模式系统：支持不同的运行模式：

   • code：专注于代码实现
   • ask：专注于回答问题
   • architect：专注于系统设计
   • debug：专注于调试问题
   • test：专注于测试

数据流 🔄

1. 初始化：AI 助手连接到 MCP 服务并初始化 Memory Bank
2. 工具调用：AI 助手调用 MCP 服务提供的工具，读取或写入 Memory Bank 文件
3. 上下文维护：Memory Bank 会在不同会话之间保留上下文，让 AI 能够回忆先前的决策和进展

Memory Bank 结构 📂

Memory Bank 使用标准化结构来组织信息：

• 产品上下文：项目概览、目标、技术和架构
• 当前上下文：当前状态、正在进行的任务、已知问题和后续步骤
• 进展：项目更新和里程碑的时间顺序记录
• 决策日志：重要决策及其背景、备选方案和后果的记录
• 系统模式：架构模式、代码模式和文档模式

高级功能 🚀

• UMB 命令：在会话期间临时更新 Memory Bank 文件，而不提交更改
• 模式检测：根据用户输入自动检测并切换模式
• 文件迁移：用于在不同文件命名约定之间迁移的工具
• 语言标准化：所有 Memory Bank 文件均以英语生成，以保持一致性

版本管理 📌

本项目遵循 语义化版本，并使用 Conventional Commits 编写提交消息。更改合并到主分支时，系统会根据提交消息自动升级版本并生成更新日志。

• 主版本号：存在破坏性更改时升级（提交消息包含 BREAKING CHANGE 或 !:）
• 次版本号：添加新功能时升级（提交消息包含 feat: 或 feat(scope):）
• 补丁版本号：其他所有更改（错误修复、文档等）都会升级

完整的更改历史请参阅 CHANGELOG.md 文件。

用法 📝

作为命令行工具 💻

# 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

作为库 📚

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.md。

许可证 📄

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

Memory Bank 状态系统 🚦

Memory Bank MCP 实现了状态前缀系统，可让你即时了解 Memory Bank 的运行状态：

状态指示器

使用 Memory Bank MCP 的 AI 助手所做的每个回复都以以下状态指示器之一开头：

• [MEMORY BANK: ACTIVE]：Memory Bank 可用，且正在用于提供具备上下文感知能力的回复
• [MEMORY BANK: INACTIVE]：Memory Bank 不可用或配置不正确
• [MEMORY BANK: UPDATING]：Memory Bank 当前正在更新（执行 UMB 命令期间）

借助此系统，用户始终可以了解 AI 助手是在充分感知上下文的情况下运行，还是只能获取有限的信息。

优势

• 透明度：用户始终可以了解 AI 是否能够访问完整的项目上下文
• 问题排查：Memory Bank 配置不正确时会一目了然
• 上下文感知：帮助用户理解为什么某些回复可能缺少历史上下文

详情请参阅 Memory Bank 状态前缀系统。