Skip to main content
Glama
memory-bank-mcp

memory-bank-mcp

by diaz3618

Memory Bank MCP

NPM Version Semgrep CE scan License: MIT

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.

Related repos:

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

Related MCP server: Adaptive Reasoning Server

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

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

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.

Available Tools

36 tools
add_progress_entryC

Add a structured progress entry to the Memory Bank. Provides a type-safe API for logging progress with categories and metadata.

Inputs: type (required), summary (required), details, files, +1 more.

add_session_noteA

Add a timestamped session note to the active context. Useful for recording observations, blockers, or context that should persist.

Inputs: note (required), category.

batch_read_filesA

Read multiple Memory Bank files in a single request. More efficient than individual reads for loading context.

Inputs: files (required), includeEtags.

batch_write_filesA

Write multiple Memory Bank files in a single request. Supports optimistic concurrency via ETags.

Inputs: files (required), stopOnError.

create_backupA

Create a backup of the current Memory Bank state, or list existing backups. Backups are stored in the parent directory with timestamped names.

Inputs: backupDir, listOnly.

debug_mcp_configB

Debug the current MCP configuration

Inputs: verbose.

finalize_thinking_sessionA

Persist the outcome of a thinking session into Memory Bank files. Accepts only human-facing summary fields — raw thoughts are NEVER persisted. Writes to existing Memory Bank files (active-context.md, decision-log.md, progress.md) via existing mechanisms.

Inputs: summary (required), decision, tasks, nextSteps, +2 more.

get_context_bundleA

Get all Memory Bank files in a single response for quick context loading. Returns all core files (product-context, active-context, progress, decision-log, system-patterns) as a combined JSON object.

Inputs: includeEtags.

get_context_digestA

Get a compact summary of the Memory Bank for context-limited situations. Returns recent progress entries, current tasks, known issues, and recent decisions.

Inputs: maxProgressEntries, maxDecisions, includeSystemPatterns.

get_instructionsA

⚠️ CALL THIS FIRST. Get comprehensive instructions for using the Memory Bank MCP server. Call this tool FIRST at the start of every session to understand the available tools and recommended workflow.

Inputs: no named parameters.

get_memory_bank_statusB

Check Memory Bank status

Inputs: no named parameters.

get_targeted_contextA

Returns a budgeted, minimal "context pack" for a query by using the knowledge graph as an index. Reads only the smallest relevant slices of Memory Bank files instead of dumping full documents. Prefer this over get_context_bundle or batch_read_files for most questions.

Inputs: query (required), maxChars, maxFiles, graphLimit, +2 more.

graph_add_doc_pointerA

Link a knowledge graph entity to a specific Memory Bank file (and optional heading). This helps get_targeted_context find the right file excerpts for a query. The file path is validated before saving.

Inputs: entityNameOrId (required), docPath (required), heading, note.

graph_add_observationB

Add an observation about an entity. Observations are facts, notes, or information associated with entities.

Inputs: entity (required), text (required), storeId, source, +1 more.

graph_delete_entityB

Delete an entity from the knowledge graph, or delete a specific observation if observationId is provided.

Inputs: entity (required), storeId, observationId.

graph_maintainC

Perform maintenance operations on the knowledge graph: rebuild snapshot from event log, or compact event history.

Inputs: operation (required), storeId.

graph_open_nodesB

Open specific nodes and their neighborhood. Returns a subgraph with the requested entities and their connections.

Inputs: nodes (required), storeId, depth.

graph_upsert_entityB

Create or update an entity in the knowledge graph. If an entity with the same name exists, it will be updated.

Inputs: name (required), entityType (required), storeId, attrs.

initialize_memory_bankC

Initialize a Memory Bank in the specified directory

Inputs: path (required).

list_memory_bank_filesD

List Memory Bank files

Inputs: no named parameters.

list_storesA

List all registered Memory Bank stores. Returns the currently active store and any additional configured stores from the persistent registry.

Inputs: no named parameters.

log_decisionC

Log a decision in the decision log

Inputs: title (required), context (required), decision (required), alternatives, +1 more.

migrate_file_namingB

Migrate Memory Bank files from camelCase to kebab-case naming convention

Inputs: no named parameters.

read_memory_bank_fileA

Read a file from the Memory Bank. Returns content with ETag for optimistic concurrency control.

Inputs: filename (required), includeEtag.

restore_backupA

Restore the Memory Bank from a specified backup. By default, creates a backup of the current state before restoring.

Inputs: backupId (required), createPreRestoreBackup.

search_memory_bankC

Search across all Memory Bank files with full-text search

Inputs: query (required), files, maxResults, caseSensitive.

select_storeB

Manage Memory Bank stores. Actions: select (switch active store), register (add to registry), unregister (remove from registry). Default action is "select" for backward compatibility.

Inputs: action, path, storeId, kind.

sequential_thinkingA

Record a numbered thinking step for structured reasoning, or reset session history. Use this to break complex problems into sequential steps with optional branching and revision. The raw thought text is NOT returned — only metadata. Call finalize_thinking_session when done to persist outcomes to Memory Bank. Set reset:true to clear thinking history instead of recording a thought.

Inputs: thought, nextThoughtNeeded, thoughtNumber, totalThoughts, +7 more.

set_memory_bank_pathB

Set a custom path for the Memory Bank

Inputs: path.

switch_modeA

Switch to a specific mode, get current mode info, or manage UMB (Update Memory Bank) state. Call with no parameters to get current mode. Set umb:true to activate UMB, umb:false to deactivate.

Inputs: mode, umb, umbCommand.

track_progressC

Track progress and update Memory Bank files

Inputs: action (required), description (required), updateActiveContext.

update_active_contextC

Update the active context file

Inputs: tasks, issues, nextSteps.

update_tasksB

Update the current tasks list in active context. Can add, remove, or replace tasks.

Inputs: add, remove, replace.

write_memory_bank_fileA

Write to a Memory Bank file. Supports optimistic concurrency control via ifMatchEtag.

Inputs: filename (required), content (required), ifMatchEtag.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 36 tools

    Disambiguation5/5

    Each tool targets a specific operation (e.g., adding progress, reading files, managing knowledge graph) with detailed descriptions that clearly differentiate their purposes. Overlap is minimal and well-documented.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern in snake_case (e.g., add_progress_entry, batch_read_files, graph_upsert_entity), making the set predictable and easy to navigate.

    Tool Count2/5

    36 tools is well above the typical well-scoped range of 3-15, making the surface feel heavy. While many tools are individually useful, the count suggests the server may be trying to cover too many subdomains.

    Completeness4/5

    Core CRUD operations for files and knowledge graph, progress tracking, backups, and search are covered. However, there is no explicit file deletion tool, which represents a minor gap in an otherwise complete surface.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP memory server that gives AI assistants durable project memory across coding sessions, storing context, changes, and decisions.
      1 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Open-source MCP server that gives AI coding assistants persistent memory, recording conversations and file changes to build user profiles and provide context across sessions.
      77 npm
      MIT