Memory Bank MCP 🧠

A Model Context Protocol (MCP) server for managing Memory Banks, allowing AI assistants to store and retrieve information across sessions.

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

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.

Recent Improvements 🛠️

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.

Installation 🚀

# Install from npm
npm install @movibe/memory-bank-mcp

# Or install globally
npm install -g @movibe/memory-bank-mcp

# Or run directly with npx (no installation required)
npx @movibe/memory-bank-mcp

Usage with npx 💻

You can run Memory Bank MCP directly without installation using npx:

# Run with default settings
npx @movibe/memory-bank-mcp

# Run with specific mode
npx @movibe/memory-bank-mcp --mode code

# Run with custom project path
npx @movibe/memory-bank-mcp --path /path/to/project

# Run with custom folder name
npx @movibe/memory-bank-mcp --folder custom-memory-bank

# Show help
npx @movibe/memory-bank-mcp --help

For more detailed information about using npx, see npx-usage.md.

Configuring in Cursor 🖱️

Cursor is an AI-powered code editor that supports the Model Context Protocol (MCP). To configure Memory Bank MCP in Cursor:

Use Memory Bank MCP with npx:

No need to install the package globally. You can use npx directly:
```
# Verify npx is working correctly
npx @movibe/memory-bank-mcp --help
```
Open Cursor Settings:
- Go to Settings (⚙️) > Extensions > MCP
- Click on "Add MCP Server"
Configure the MCP Server:
- Name: Memory Bank MCP
- Command: npx
- Arguments: @movibe/memory-bank-mcp --mode code (or other mode as needed)
Save and Activate:
- Click "Save"
- Enable the MCP server by toggling it on
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.

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

Code Mode 👨‍💻
- Focus: Code implementation and development
- Usage: npx @movibe/memory-bank-mcp --mode code
- Best for: Writing, refactoring, and optimizing code
Architect Mode 🏗️
- Focus: System design and architecture
- Usage: npx @movibe/memory-bank-mcp --mode architect
- Best for: Planning project structure, designing components, and making architectural decisions
Ask Mode ❓
- Focus: Answering questions and providing information
- Usage: npx @movibe/memory-bank-mcp --mode ask
- Best for: Getting explanations, clarifications, and information
Debug Mode 🐛
- Focus: Troubleshooting and problem-solving
- Usage: npx @movibe/memory-bank-mcp --mode debug
- Best for: Finding and fixing bugs, analyzing issues
Test Mode ✅
- Focus: Testing and quality assurance
- Usage: npx @movibe/memory-bank-mcp --mode test
- Best for: Writing tests, test-driven development

Switching Modes

You can switch modes in several ways:

When starting the server:

npx @movibe/memory-bank-mcp --mode architect

During a session:
```
memory-bank-mcp switch_mode mode=debug
```

In Cursor:

/mcp memory-bank-mcp switch_mode mode=test

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 🧩

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
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
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 🔄

Initialization: The AI assistant connects to the MCP server and initializes a Memory Bank
Tool Calls: The AI assistant calls tools provided by the MCP server to read/write Memory Bank files
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 and uses Conventional Commits 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 file.

Usage 📝

As a Command Line Tool 💻

# 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 📚

import { MemoryBankServer } from "@movibe/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 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 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.