Memory Bank MCP With Remote SSH Support 🧠

一个用于管理记忆库的模型上下文协议（MCP）服务器，允许AI助手在会话之间存储和检索信息。现在支持远程服务器！

概览 📋

记忆库服务器为AI助手提供了一组工具和资源，以与记忆库进行交互。记忆库是结构化的信息存储库，有助于在多个会话中保持上下文并跟踪进度。

功能 ✨

• 记忆库管理：初始化、查找和管理记忆库
• 文件操作：在记忆库中读写文件
• 进度跟踪：跟踪进度并更新记忆库文件
• 决策记录：记录带有上下文和备选方案的重要决策
• 活动上下文管理：维护和更新活动上下文信息
• 模式支持：检测并使用.clinerules文件以实现特定模式的行为
• UMB命令：使用UMB命令临时更新记忆库文件
• 强大的错误处理：优雅地处理错误并在可能的情况下继续操作
• 状态前缀系统：立即查看记忆库的操作状态
• 远程服务器支持：通过SSH在远程服务器上存储记忆库

目录结构 📁

默认情况下，记忆库会在项目的根目录下使用一个memory-bank目录。当你使用--path选项指定项目路径时，记忆库将在<project_path>/memory-bank创建或访问。

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

有关自定义文件夹名称的更多详细信息，请参阅自定义记忆库文件夹名称。

最近的改进 🛠️

• 远程服务器支持：通过SSH将你的记忆库存储在远程服务器上
• 可自定义文件夹名称：你现在可以为记忆库指定自定义文件夹名称
• 一致的目录结构：记忆库现在始终使用项目根目录中配置的文件夹名称
• 增强的初始化：即使不存在.clinerules文件，记忆库也能正常工作
• 更好的路径处理：改进了绝对路径和相对路径的处理
• 改进的目录检测：更好地检测现有的memory-bank目录
• 更强大的错误处理：优雅地处理与.clinerules文件相关的错误

有关更多详细信息，请参阅 Memory Bank Bug Fixes。

安装 🚀

# 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 Banks：多个用户可以访问同一个 Memory Bank
3. 持久存储：即使您的本地机器被清除，您的 Memory Bank 仍然存在

远程服务器要求

• 对远程服务器的 SSH 访问权限
• 设置 SSH 密钥认证（不支持密码认证）
• 在指定目录中创建/修改文件的足够权限

SSH 密钥设置

要为远程服务器设置 SSH 密钥认证：

1. 生成一个新的 SSH 密钥对（如果您还没有的话）：

   # 使用现代 Ed25519 算法（推荐）
   ssh-keygen -t ed25519 -C "your_email@example.com"
   
   # 或者如果需要兼容性，则使用 RSA
   ssh-keygen -t rsa -b 4096 -C "your_email@example.com"
   

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

   # 启动代理
   eval "$(ssh-agent -s)"
   
   # 添加您的密钥
   ssh-add ~/.ssh/id_ed25519  # 如果您使用了 RSA，则为 ~/.ssh/id_rsa
   

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

   # 最简单的方法（如果可用）
   ssh-copy-id username@your-remote-host.com
   
   # 替代方法：手动复制您的公钥
   cat ~/.ssh/id_ed25519.pub  # 复制输出
   

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

4. 测试您的连接：

   ssh username@your-remote-host.com
   

   您应该能够在没有密码的情况下登录。

有关更详细的 SSH 密钥设置说明，请参阅我们的 SSH Keys Guide。

远程服务器配置

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

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：

   # 验证 npx 是否正常工作
   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 交互：

• 初始化记忆库: /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. 代码模式 👨‍💻

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

2. 架构模式 🏗️

   • 重点：系统设计和架构
   • 使用方法：npx @aakarsh-sasi/memory-bank-mcp --mode architect
   • 最适合：规划项目结构、设计组件以及做出架构决策

3. 询问模式 ❓

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

4. 调试模式 🐛

   • 重点：故障排除和解决问题
   • 使用方法：npx @aakarsh-sasi/memory-bank-mcp --mode debug
   • 最适合：查找和修复错误、分析问题

5. 测试模式 ✅

   • 重点：测试和质量保证
   • 使用方法：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. 在光标中：

   /mcp memory-bank-mcp switch_mode mode=test
   

4. 使用 .clinerules 文件：
   在您的项目中创建一个 .clinerules-[mode] 文件，当检测到该文件时，自动切换到相应的模式。

Memory Bank MCP 的工作原理 🧠

Memory Bank MCP 基于模型上下文协议 (MCP) 构建，使 AI 助手能够与外部工具和资源进行交互。以下是其工作原理：

核心组件 🧩

1. 记忆库：以 markdown 文件形式存储的结构化信息仓库：

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

2. MCP 服务器：为 AI 助手提供与记忆库交互的工具和资源：

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

3. 模式系统：支持不同的操作模式：

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

数据流 🔄

1. 初始化：AI 助手连接到 MCP 服务器并初始化一个记忆库
2. 工具调用：AI 助手调用由 MCP 服务器提供的工具来读写记忆库文件
3. 上下文维护：记忆库在会话之间维护上下文，允许 AI 回忆之前的决策和进度

记忆库结构 📂

记忆库使用标准化结构来组织信息：

• 产品上下文：项目概述、目标、技术栈和架构
• 活动上下文：当前状态、正在进行的任务、已知问题和下一步骤
• 进度：项目更新和里程碑的按时间顺序记录
• 决策日志：带有背景、替代方案和后果的重要决策记录
• 系统模式：架构模式、代码模式和文档模式

高级功能 🚀

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

版本控制 📌

本项目遵循语义化版本控制，并使用规范提交格式编写提交信息。当更改合并到主分支时，版本号会自动更新，并基于提交信息生成变更日志。

• 主版本在出现破坏性变更时增加（提交信息包含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 文件。

内存银行状态系统 🚦

内存银行MCP实现了一个状态前缀系统，该系统提供了对内存银行操作状态的即时可见性：

状态指示器

每次来自使用内存银行MCP的AI助手的响应都以这些状态指示器之一开头：

• [MEMORY BANK: ACTIVE]: 内存银行可用且正在用于提供上下文感知响应
• [MEMORY BANK: INACTIVE]: 内存银行不可用或配置不当
• [MEMORY BANK: UPDATING]: 内存银行当前正在更新（在执行UMB命令期间）

此系统确保用户始终知道AI助手是在完全上下文意识下运行还是仅基于有限信息。

好处

• 透明度：用户始终了解AI是否能够访问完整的项目上下文
• 故障排除：立即显示内存银行配置不正确的情况
• 上下文意识：帮助用户理解为什么某些响应可能缺乏历史背景

更多详细信息，请参阅内存银行状态前缀系统。