Memory Bank MCP Server

A Model Context Protocol (MCP) server implementing the Memory Bank system based on the cursor-memory-bank custom modes.

Overview

This MCP server provides structured workflow tools for managing software development projects through different complexity levels and phases:

• VAN Mode: Project initialization and complexity assessment
• PLAN Mode: Detailed implementation planning
• CREATIVE Mode: Design and architecture decisions
• IMPLEMENT Mode: Code implementation and execution
• REFLECT+ARCHIVE Mode: Project reflection and documentation archiving

Features

🎯 VAN Mode (Entry Point)

• Initialize new projects with complexity levels 1-4
• Set up Memory Bank file structure
• Determine appropriate next mode based on complexity

📋 PLAN Mode (Planning)

• Generate implementation plans based on complexity level
• Create detailed step-by-step approaches
• Identify components requiring creative phases

🎨 CREATIVE Mode (Design)

• Architecture design with multiple options analysis
• Algorithm design with complexity considerations
• UI/UX design with accessibility and usability focus
• Structured documentation of design decisions

⚒️ IMPLEMENT Mode (Execution)

• Phase-based implementation for complex projects
• Integration testing and documentation
• Progress tracking and status updates

🤔 REFLECT+ARCHIVE Mode (Completion)

• Implementation reflection and lessons learned
• Complete project archiving
• Preparation for next task initialization

Installation

Option 1: Use with npx (Recommended)

No installation required! Use directly with npx:

npx -y @nicavcrm/memory-bank-mcp

Option 2: Install globally

npm install -g @nicavcrm/memory-bank-mcp

Option 3: Install locally for development

git clone <your-repo-url>
cd memory-bank-mcp
npm install
npm run build

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "memory-bank": {
      "command": "npx",
      "args": [
        "-y",
        "@nicavcrm/memory-bank-mcp"
      ]
    }
  }
}

Cursor IDE

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "memory-bank": {
      "command": "npx",
      "args": [
        "-y",
        "@nicavcrm/memory-bank-mcp"
      ]
    }
  }
}

VS Code

Install an MCP extension for VS Code and add this to your settings:

{
  "mcp.servers": {
    "memory-bank": {
      "command": "npx",
      "args": [
        "-y",
        "@nicavcrm/memory-bank-mcp"
      ]
    }
  }
}

Other MCP Clients

Use the npx command with your MCP client:

• Command: npx
• Args: ["-y", "@nicavcrm/memory-bank-mcp"]

Quick Start

1. Add to your MCP client using the configuration examples above
2. Start a new project using the van_mode tool:

   {
     "name": "van_mode",
     "arguments": {
       "complexity": "2",
       "task_description": "Fix login bug in user authentication"
     }
   }

3. Follow the suggested workflow - the tool will guide you through PLAN → IMPLEMENT → REFLECT+ARCHIVE modes
4. Access your Memory Bank files in the .memory_bank/ directory for documentation and progress tracking

See the DEMO.md file for complete workflow examples.

Usage

With MCP Clients

The Memory Bank server is designed to work with MCP (Model Context Protocol) clients like Claude Desktop, Cursor IDE, or custom MCP implementations. Once configured (see installation section above), the tools will be available in your MCP client.

Development Mode (Local)

If you're developing or running locally:

npm start

Available Tools

1. van_mode

Initialize a project with complexity assessment.

Parameters:

• complexity (required): "1" | "2" | "3" | "4"
  • Level 1: Quick bug fix
  • Level 2: Simple enhancement
  • Level 3: Complex feature
  • Level 4: Major feature/refactor
• task_description (optional): Description of the task

Example:

{
  "complexity": "3",
  "task_description": "Implement user authentication system"
}

2. plan_mode

Create detailed implementation plan.

Parameters:

• complexity (optional): Complexity level (reads from tasks.md if not provided)

3. creative_mode

Perform design and architecture work.

Parameters:

• component_name (required): Name of component requiring design
• creative_type (required): "architecture" | "algorithm" | "uiux"
• requirements (required): Requirements and constraints

Example:

{
  "component_name": "user_auth_system",
  "creative_type": "architecture",
  "requirements": "Secure authentication with JWT tokens, OAuth integration, and role-based access control"
}

4. implement_mode

Execute implementation based on plan.

Parameters:

• phase (optional): Implementation phase for complex projects
• complexity (optional): Complexity level (reads from tasks.md if not provided)

5. reflect_archive_mode

Reflect on implementation and archive documentation.

Parameters:

• action (required): "reflect" | "archive"
  • "reflect": Review and document implementation experience
  • "archive": Create final documentation archive

Memory Bank Files

The server creates and manages several files in the .memory_bank directory:

• tasks.md: Main task tracking and status
• activeContext.md: Current context and focus
• progress.md: Implementation progress tracking
• implementation-plan.md: Detailed implementation plan
• reflection.md: Post-implementation reflection
• creative-{component}.md: Creative phase documentation
• docs/archive/project-archive.md: Final project archive

Workflow Example

# 1. Initialize project
van_mode(complexity="3", task_description="Build REST API")

# 2. Create implementation plan
plan_mode()

# 3. Design complex components (if Level 3-4)
creative_mode(component_name="api_architecture", creative_type="architecture", requirements="...")

# 4. Implement the solution
implement_mode(phase="core_components")

# 5. Reflect and archive
reflect_archive_mode(action="reflect")
reflect_archive_mode(action="archive")

Complexity Levels

• Level 1: Quick bug fixes - Direct implementation, minimal planning
• Level 2: Simple enhancements - Streamlined planning, straightforward implementation
• Level 3: Complex features - Comprehensive planning, creative phases may be required
• Level 4: Major features/refactors - Detailed architecture, phased implementation, creative design required

Development

# Development mode with auto-reload
npm run dev

# Build TypeScript
npm run build

# Run compiled server
npm start

Troubleshooting

Module Resolution Errors

If you encounter ERR_MODULE_NOT_FOUND errors when running the server, ensure:

1. Build First: Always run npm run build before npm start
2. ES Module Imports: All imports in source files use .js extensions
3. TypeScript Config: The tsconfig.json is configured for ES modules with "module": "ESNext"

# Clean build if issues persist
rm -rf dist/
npm run build
npm start

Memory Bank Directory Permissions

If the server can't create the .memory_bank directory:

# Ensure write permissions in the working directory
chmod 755 .

Integration

This MCP server can be integrated with:

• Claude Desktop: Add to MCP server configuration
• Cursor IDE: Use with MCP client capabilities
• VS Code: Through MCP extensions
• Custom clients: Any MCP-compatible application

Based On

This implementation is based on the excellent cursor-memory-bank project by vanzan01, adapted for use as an MCP server.

License

ISC