MCP Memory Bank

MCP Memory Bank

A personal long-term memory server for AI assistants, implemented as an MCP server (Model Context Protocol). Designed for individual use, not for teams. Allows you to save and restore context between sessions. Requires Python 3.10+.

Version 1.1.1

What's new

• Atomic file writes: Markdown documents are now written via temp file + fsync + os.replace, which prevents file corruption on crashes.
• Resilient document parsing: invalid YAML frontmatter and malformed tags no longer break index synchronization.

Why do you need this?

💰 Token savings

The main cost when working with AI assistants (especially in development) comes from reading context. Every extra file read by the agent ends up in the context and is paid for on every request.

Memory Bank solves this problem by:

• At session start, the assistant only receives what matters most — documents with the core flag.
• Other knowledge is loaded on demand, only when actually needed.
• The agent stops aimlessly reading project files and immediately knows the architecture, current task, constraints, and status.

🧠 Long-term memory

A regular assistant forgets everything after the chat is closed. Memory Bank preserves decisions made, architectural details, agreements, and any other important context between sessions.

• No repeated explanations — the agent remembers why this particular database was chosen, what constraints were imposed, what architectural trade-offs were made.
• When resuming work (even after a week or a month), the assistant is immediately up to date with the last state of the project.
• All changes are synchronized automatically — the agent writes documents itself using the provided tools.

✅ Task management

Memory Bank helps organize work on a project:

• Break large tasks into stages.
• The agent stores the task list directly in the project memory.
• In the morning, ask the assistant: "What's our task for today?" — and it will answer by checking the current activeTask.md document.
• The agent tracks progress, records completed steps, and you always stay informed about the current state of tasks.

Installation

pip install mcp-memory-bank

After installation, the mcp-memory-bank command becomes available in PATH. If Python is installed in a non-standard way, this may not happen. In that case, add the path to the executable manually.

The author uses Cline, so the configuration below is for Cline. Since the protocol is standard, mcp-memory-bank should work with other AI agents as well, but the configuration may differ slightly.

Setup in Cline

Open Cline settings → MCP Servers → add the server manually.

Choose one of two storage modes:

Mode 1: Global storage

All projects are stored in one place, isolated by project_id. Data is stored by default in the user's system directory (via platformdirs):

{
  "mcpServers": {
    "memory-bank": {
      "disabled": false,
      "type": "stdio",
      "command": "mcp-memory-bank"
    }
  }
}

Configure once — works for all projects automatically. On each tool call, the agent passes project_id — and the data goes to the correct storage.

Mode 2: Local storage in the project (for Cline)

Each project's data is stored directly in its directory (.memory_bank/ inside the project). This is convenient in Cline, since the agent receives the project path via Current Working Directory.

{
  "mcpServers": {
    "memory-bank": {
      "disabled": false,
      "type": "stdio",
      "command": "mcp-memory-bank",
      "args": ["--project-local"]
    }
  }
}

Important: in --project-local mode, the project_id parameter is used as an absolute path to the project root. Cline passes it automatically via Current Working Directory.

Add .memory_bank/ to the project's .gitignore — memory is developer-specific.

Connecting RULES.md

Copy the RULES.md file from this repository to the Cline instructions settings (Settings → Custom Instructions) or add it to your project's .clinerules — this will teach the assistant how to work with memory.

Important: according to the rules, the agent should initialize the Memory Bank on the first request if the bank is empty. However, sometimes the agent immediately focuses on your task and skips this step. In that case, simply ask: "Initialize the Memory Bank".

How it works

Project identification

Each tool call contains a project_id parameter — a unique project identifier. The server uses it to isolate data between projects.

It is recommended to pass the absolute path to the project root (for Cline — this is Current Working Directory). When passing a path as project_id, you can use the --project-local argument and store bank documents in the project folder.

However, any meaningful string identifier is valid as project_id. In that case, only global storage is available and the --project-local argument cannot be used.

Storage

Global mode — storage structure:

~/.local/share/mcp-memory-bank/
├── index.db
├── common_storage/
│   └── documents/
│       └── shared-checklist.md
└── projects/
    ├── my_project_a1b2c3d4/    ← slug from project_id
    │   └── documents/
    │       ├── context.md
    │       └── activeTask.md
    └── another_project_e5f6a7b8/
        └── ...

Local mode (--project-local) — storage structure:

/path/to/your/project/
└── .memory_bank/
    ├── documents/
    │   ├── context.md
    │   └── activeTask.md
    └── index.db

Each document is a human-readable Markdown file with metadata in YAML frontmatter:

---
tags:
  - decision
  - architecture
core: false
lastModified: '2026-03-09T01:00:00Z'
---
# Architectural Decisions

## Database Selection
...

The SQLite index is synchronized incrementally on tool calls — files remain the source of truth.

Common shared storage

Memory Bank also supports a shared storage area that is not tied to a single project.

• The agent uses project_id="" (empty string) to read or write documents in common storage.
• To place a document in common storage, ask the agent to do so — for example: "Save this checklist to the shared storage."
• Common storage is useful for reusable information shared across projects, such as release checklists, personal notes, or reference documents.
• memory_bank_read_context(project_id=<project>) does not automatically load common documents.
• memory_bank_search_by_tags(project_id=<project>, tags=[...]) searches both the current project storage and the common shared storage.

Protocol

Concept

• All information is stored as documents (Markdown text + metadata)
• Each document has: a name (name), content (content), tags (tags), a core flag, and a modification date
• The core=true flag means the document is loaded automatically at every session start
• Documents without core are loaded on demand — to save context

Tools

All tools accept the required project_id parameter.

memory_bank_read_context(project_id)

The main tool for starting a session. Returns:

• Metadata of all documents (without content)
• Full content of core documents only (core=true)

Parameters:

Returns:

{
  "documents": [
    {
      "common": false,
      "name": "context.md",
      "tags": ["context", "global"],
      "core": true,
      "lastModified": "2026-03-09T01:00:00Z",
      "size": 753,
      "content": "# Project: ...\n\n..."
    },
    {
      "common": false,
      "name": "activeTask.md",
      "tags": ["task", "active"],
      "core": true,
      "lastModified": "2026-03-09T01:15:00Z",
      "size": 1024,
      "content": "# Current Task: ...\n\n..."
    },
    {
      "common": false,
      "name": "architecture.md",
      "tags": ["decision", "architecture"],
      "core": false,
      "lastModified": "2026-03-08T18:00:00Z",
      "size": 2048,
      "content": null
    }
  ]
}

memory_bank_read_documents(project_id, names)

Reads one or more documents by name.

Parameters:

Returns:

{
  "documents": [
    {
      "common": false,
      "name": "architecture.md",
      "tags": ["decision", "architecture"],
      "core": false,
      "lastModified": "2026-03-08T18:00:00Z",
      "size": 2048,
      "content": "# Architectural Decisions\n\n## Database Selection\n\nDecided to use PostgreSQL..."
    }
  ]
}

If a document is not found — null is returned for the corresponding element.

memory_bank_write_document(project_id, name, content, tags, core)

Creates a new document or completely overwrites an existing one.

Parameters:

Returns:

{
  "success": true,
  "name": "activeTask.md",
  "lastModified": "2026-03-09T01:20:00Z"
}

memory_bank_search_by_tags(project_id, tags)

Searches documents by tags. Returns documents that have all of the specified tags. Content is not returned — only metadata. To read content, use read_documents.When project_id is not empty, the search includes both the current project storage and the common shared storage.

Parameters:

Returns:

{
  "documents": [
    {
      "common": false,
      "name": "architecture.md",
      "tags": ["decision", "architecture", "database"],
      "core": false,
      "lastModified": "2026-03-08T18:00:00Z",
      "size": 2048
    },
    {
      "common": true,
      "name": "release-checklist.md",
      "tags": ["release", "checklist", "shared"],
      "core": false,
      "lastModified": "2026-03-10T09:00:00Z",
      "size": 8192
    }
  ]
}

memory_bank_append_content(project_id, name, content, tags, core)

Appends text to the end of an existing document without reading its content into the LLM context. The server reads the file internally, appends the new content with a blank line separator, and saves it back.

This is the preferred way to update log-style documents (e.g., progress.md) — it avoids loading the full document into context on every update.

If the document does not exist, it will be created (tags are required in that case).

Parameters:

Returns:

{
  "success": true,
  "name": "progress.md",
  "lastModified": "2026-03-09T21:00:00Z",
  "contentLength": 1024
}

contentLength — total length of the document content after the append (in characters).

memory_bank_delete_document(project_id, name)

Deletes an existing document by name.

If the document does not exist, the tool returns an error.

Parameters:

Returns:

{
  "success": true,
  "name": "obsolete.md"
}

If the document is not found:

{
  "error": "Document not found: obsolete.md"
}

Recommended documents

Document names are recommendations. Any meaningful names in camelCase.md or kebab-case.md format are allowed.

Command-line arguments

--response-delay: workaround for extended thinking bug

In Cline 3.71.0, when using models with extended thinking (e.g., Claude Opus with the "Extended thinking" option), a race condition occurs: Cline doesn't have time to pass thinking blocks back to the Claude API before receiving a response from the MCP server. This causes a hang after the "Thinking..." message.

Fix: add a 100 ms delay — this is enough to resolve the issue:

{
  "mcpServers": {
    "memory-bank": {
      "disabled": false,
      "type": "stdio",
      "command": "mcp-memory-bank",
      "args": ["--project-local", "--response-delay", "100"]
    }
  }
}

Note: the --response-delay argument is only relevant when using extended thinking. For regular usage, the delay can be omitted.