memory-bank-mcp
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.
Related repos:
HTTP + Postgres + Redis variant → diaz3618/memory-bank-mcp-http — Docker deployment with HTTP transport
VS Code Extension → diaz3618/Memory-Bank-VSCode-Ext — sidebar UI and GitHub Copilot integration
Quick Start
# Run directly (no install needed)
npx @diazstg/memory-bank-mcp
# Or install globally
npm install -g @diazstg/memory-bank-mcpVia Smithery (Claude Desktop)
npx -y @smithery/cli install @diazstg/memory-bank-mcp --client claudeRelated 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
--usernameis 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 optionsRemote 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_ed25519See Remote Server Guide.
How It Works
Memory Bank stores project context as markdown files in a memory-bank/ directory:
File | Purpose |
| Project overview, goals, tech stack |
| Current state, ongoing tasks, next steps |
| Chronological record of updates |
| Decisions with context and rationale |
| 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 |
| Create a new Memory Bank |
| Check current status |
| Read a specific file |
| Write/update a file |
| Add a progress entry |
| Record a decision |
| Update current context |
| Change operational mode |
| Create or update a knowledge graph entity |
| Add an observation to an entity |
| Create a relation between entities |
| Search entities by name or type |
| Get full details of specific entities |
| Compact the event log |
Modes
Mode | Focus |
| Implementation and development |
| System design and planning |
| Q&A and information retrieval |
| Troubleshooting and diagnostics |
| 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 | |
Guides | |
Integrations | VS Code/Copilot, Claude Code, Cursor, Cline, Roo Code, generic MCP |
Reference | |
Development |
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 toolsadd_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_link_entitiesB
Create or remove a directed relationship between two entities. Use action:"unlink" to remove a relationship.
Inputs: from (required), relationType (required), to (required), storeId, +1 more.
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_searchA
Search the knowledge graph for entities and observations matching a query. Supports fuzzy matching on names and observation text.
Inputs: query (required), storeId, limit, includeNeighborhood, +1 more.
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
Scored across 36 tools
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.
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.
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.
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
Related MCP Connectors
Persistent, portable memory for AI assistants — your private memory graph, from any MCP client.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Cloud-hosted MCP server for durable AI memory
Persistent, verbatim, searchable memory for AI assistants — one memory across every MCP client.
Related MCP Servers
- AlicenseCqualityCmaintenanceAn MCP server that gives AI coding assistants persistent memory across sessions with chain-based project tracking, tickets, and structured handoffs.42GPL 3.0
- FlicenseNot gradedqualityDmaintenanceAn advanced MCP server that gives AI assistants persistent memory with machine-learning-powered semantic understanding, enabling branching memory, semantic search, and project analysis.-
- AlicenseNot gradedqualityDmaintenanceA local MCP memory server that gives AI assistants durable project memory across coding sessions, storing context, changes, and decisions.1 npm1MIT
- AlicenseNot gradedqualityBmaintenanceOpen-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 npmMIT