Memory Bank MCP

An MCP server that gives AI assistants persistent memory across sessions. It stores project context, decisions, and progress in structured markdown files — locally or on a remote server via SSH.

Quick Start

# Run directly (no install needed)
npx @diazstg/memory-bank-mcp

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

Via Smithery (Claude Desktop)

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

Configuration

Add to your editor's MCP config (.vscode/mcp.json, Cursor, Claude Desktop, etc.):

{
  "servers": {
    "memory-bank-mcp": {
      "command": "npx",
      "args": ["-y",
          "@diazstg/memory-bank-mcp",
          "--username",
          "your-github-username"
      ],
      "type": "stdio"
    }
  }
}

Tip: Including --username is highly recommended for proper progress tracking.

Common Options

npx @diazstg/memory-bank-mcp --username "github-user"   # Username for progress tracking (recommended)
npx @diazstg/memory-bank-mcp --mode code                # Set operational mode
npx @diazstg/memory-bank-mcp --path /my/project         # Custom project path
npx @diazstg/memory-bank-mcp --folder my-memory         # Custom folder name (default: memory-bank)
npx @diazstg/memory-bank-mcp --help                     # All options

Remote Server (SSH)

Store your Memory Bank on a remote server:

npx @diazstg/memory-bank-mcp --remote \
  --remote-user username \
  --remote-host example.com \
  --remote-path /home/username/memory-bank \
  --ssh-key ~/.ssh/id_ed25519

See Remote Server Guide and SSH Keys Guide.

How It Works

Memory Bank stores project context as markdown files in a memory-bank/ directory:

| File | Purpose | |------|---------| | product-context.md | Project overview, goals, tech stack | | active-context.md | Current state, ongoing tasks, next steps | | progress.md | Chronological record of updates | | decision-log.md | Decisions with context and rationale | | system-patterns.md | Architecture and code patterns |

The AI assistant reads these files at the start of each session and updates them as work progresses, maintaining continuity across conversations.

MCP Tools

| Tool | Description | |------|-------------| | initialize_memory_bank | Create a new Memory Bank | | get_memory_bank_status | Check current status | | read_memory_bank_file | Read a specific file | | write_memory_bank_file | Write/update a file | | track_progress | Add a progress entry | | log_decision | Record a decision | | update_active_context | Update current context | | switch_mode | Change operational mode | | graph_upsert_entity | Create or update a knowledge graph entity | | graph_add_observation | Add an observation to an entity | | graph_link_entities | Create a relation between entities | | graph_search | Search entities by name or type | | graph_open_nodes | Get full details of specific entities | | graph_compact | Compact the event log |

Modes

| Mode | Focus | |------|-------| | code | Implementation and development | | architect | System design and planning | | ask | Q&A and information retrieval | | debug | Troubleshooting and diagnostics | | test | Testing and quality assurance |

Modes can be set via CLI (--mode code), tool call (switch_mode), or .mcprules-[mode] files. See Usage Modes.

As a Library

import { MemoryBankServer } from "@diazstg/memory-bank-mcp";

const server = new MemoryBankServer();
server.run().catch(console.error);

Documentation

| Topic | Link | |-------|------| | Getting Started | npx usage, build with Bun, custom folder | | Guides | Remote server, SSH keys, usage modes, status system, migration, debug MCP | | Integrations | VS Code/Copilot, Claude Code, Cursor, Cline, Roo Code, generic MCP | | Reference | MCP protocol, rules format, file naming | | Development | Architecture, testing, logging |

Alternative: HTTP + PostgreSQL + Redis

The feature/http-postgres-redis-supabase branch provides a cloud-native variant that replaces stdio/local-filesystem with HTTP Streamable MCP transport, PostgreSQL (via Supabase) for storage, and Redis for caching. It is deployed exclusively via Docker and is not published to npm. See the branch README for setup instructions.

Contributing

See CONTRIBUTING.md.

License

See LICENSE.