This is a personal project by Ivan Nardini to explore how to build a Model Context Protocol (MCP) server for Vertex AI Memory Bank.
Vertex AI Memory Bank MCP server is not a Google product. And it is not officially support.
Vertex AI Memory Bank MCP Server
A simple MCP (Model Context Protocol) server that enables LLMs to generate and retrieve long-term memories using Vertex AI's Memory Bank.
Why This Project?
This server demonstrates how to build an MCP server with Vertex AI Memory Bank. It has been inspired by a developer request and released for developers.
Prerequisites
- Python 3.11 or higher
- Google Cloud account with Vertex AI API enabled
- Basic understanding of async Python (helpful but not required)
Quick Start
Setup Google Cloud
# Install gcloud CLI (if not already installed)
# https://cloud.google.com/sdk/docs/install
# Authenticate
gcloud auth application-default login
# Set your project
gcloud config set project YOUR_PROJECT_ID
# Enable Vertex AI API
gcloud services enable aiplatform.googleapis.com
Install
# Clone the repository
git clone https://github.com/yourusername/vertex-ai-memory-bank-mcp.git
cd vertex-ai-memory-bank-mcp
# Install with pip
pip install -r requirements.txt
# OR install with uv (faster, recommended)
uv sync
# For running examples (optional)
pip install -e ".[examples]"
# OR with uv
uv sync --extra examples
Configure
# Copy the example environment file
cp .env.example .env
# Edit .env with your project details
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
Run Your First Example
Interactive Tutorial (Recommended): Open get_started_with_memory_bank_mcp.ipynb in Jupyter
Or try the command-line examples:
# Basic MCP Client Usage
python examples/basic_usage.py
# Gemini Agent with Memory
python examples/gemini_memory_agent.py
# Automatic Tool Calling with Gemini
python examples/automatic_tool_calling.py
Use with Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"memory-bank": {
"command": "python",
"args": ["/path/to/memory_bank_server.py"],
"env": {
"GOOGLE_CLOUD_PROJECT": "your-project-id",
"GOOGLE_CLOUD_LOCATION": "us-central1"
}
}
}
}
Key Concepts
Memory Scope
Memories are scoped to users or contexts:
scope = {"user_id": "alice123"}
Memory Topics
Categorize what to remember:
topics = ["USER_PREFERENCES", "USER_PERSONAL_INFO"]
Semantic Search
Find relevant memories with similarity search:
search_query = "programming preferences"
top_k = 5
Available Tools
| Tool | Purpose | Example Use Case |
|---|---|---|
initialize_memory_bank |
Set up connection to Vertex AI | First-time setup |
generate_memories |
Extract memories from conversations | After chat sessions |
retrieve_memories |
Fetch relevant memories | Personalize responses |
create_memory |
Manually add a memory | Store user preferences |
delete_memory |
Remove specific memory | User requests deletion |
list_memories |
View all stored memories | Debugging/inspection |
Common Patterns
Pattern 1: Conversation Memory
# After each conversation turn
await session.call_tool(
"generate_memories",
{
"conversation": conversation_history,
"scope": {"user_id": user_id},
"wait_for_completion": True
}
)
Pattern 2: Explicit Memory
# Store specific facts
await session.call_tool(
"create_memory",
{
"fact": "User prefers dark mode",
"scope": {"user_id": user_id}
}
)
Pattern 3: Context Retrieval
# Get relevant context before responding
memories = await session.call_tool(
"retrieve_memories",
{
"scope": {"user_id": user_id},
"search_query": user_message,
"top_k": 5
}
)
Project Structure
vertex-ai-memory-bank-mcp/
├── memory_bank_server.py # Main entry point
├── src/ # Modular source code
│ ├── __init__.py
│ ├── server.py # Server orchestration
│ ├── tools.py # MCP tool implementations
│ ├── config.py # Configuration management
│ ├── app_state.py # Application state
│ ├── validators.py # Input validation
│ └── formatters.py # Data formatting
├── examples/ # Usage examples
│ ├── basic_usage.py # Basic MCP client usage
│ ├── automatic_tool_calling.py # Automatic function calling
│ └── claude_config.json # Claude Desktop config
├── get_started_with_memory_bank_mcp.ipynb # Getting started tutorial
├── pyproject.toml # Project config (pip & uv)
├── requirements.txt # Dependencies (pip)
├── uv.lock # Lock file (uv)
├── .env.example # Environment template
├── .gitignore # Git ignore rules
├── .python-version # Python version
├── README.md # This file
└── LICENSE # Apache 2.0 License
Troubleshooting
"Connection closed" error
Solution: Check that your MCP server is using stderr for logging, not stdout.
"Not authenticated"
Solution: Run gcloud auth application-default login
Contributing
This project is meant to inspire. Feel free to fork and create your own version as well as share your production implementations.
Resources
- Interactive Tutorial - Start here!
- Model Context Protocol Docs
- Vertex AI Memory Bank
- MCP Server Examples
License
This project is licensed under the Apache 2.0 License.
Metadata
Release files for iflow-mcp_inardini-vertex-memory-bank-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0.tar.gz | 69.7 kB | Without provenance | Details for iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0-py3-none-any.whl |
Total release size: 87.4 kB
Release files / iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0.tar.gz |
|---|---|
| Size | 69.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c5653aadebca74179d8f8bcdbb29e019237d22d359b41907bd271139b11c5910
|
|
BLAKE2b-256 checksum How to use checksums |
5e411fab94cb0f631eef22d9d8eb0e784cd89edfd8e72c303595abf700b9c742
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_inardini_vertex_memory_bank_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 17.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5027aeee4f24cfd3249ba4c8a92fc8e93cdffbb74115e118374387662a83da92
|
|
BLAKE2b-256 checksum How to use checksums |
9bab52d29b293fb0523e4266fd05a8da3d8acd38dfcb637f2d26ff866cd8af00
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.2 {"installer":{"name":"uv","version":"0.10.2","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_inardini-vertex-memory-bank-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.