🚀 MemCloud

One-Click MemMachine Deployments Across Any Cloud

Deploy AI-powered memory systems to GCP, AWS, or Azure in under 20 minutes

🎯 Quick Start • 📚 Documentation • ☁️ Choose Cloud • 🔧 Features • 🤝 Contributing

🎯 What is MemCloud?

MemCloud is a production-ready platform that enables one-click deployments of MemMachine instances across any major cloud provider. Built for the MemVerge hackathon and designed for enterprise adoption.

🎨 Beautiful Dashboard

Deploy and manage MemMachine instances through an intuitive Next.js interface

⚡ Lightning Fast

From zero to production in ~20 minutes with copy-paste commands

💰 Cost Optimized

Scale-to-zero support. Pay only for what you use. Starting at $15/month

⭐ Key Features

Feature	Description
🌐 Multi-Cloud	Deploy to GCP, AWS, or Azure with identical commands
🐳 Custom Docker Image	Pre-built with PostgreSQL support (psycopg2 fix)
🔗 Neo4j Aura Integration	No infrastructure management, just works
📊 Real-Time Monitoring	Track deployment status and instance health
🔒 Production-Ready	Security, monitoring, backups included
📖 Elite Documentation	25+ troubleshooting scenarios documented

🚀 Quick Start

Choose Your Cloud and Deploy in 3 Steps

Google Cloud

$15-30/month ⚡ Fastest 🎯 Easiest

Amazon Web Services

$45-65/month 🏢 Enterprise 🔐 Compliance

Microsoft Azure

$30-55/month 💼 Microsoft Shops 🔧 .NET Integration

Not sure which to choose? → Cloud Comparison Guide

📚 Documentation

Document	Purpose	Audience
README_DEPLOYMENT.md	📖 Start here - Overview & quick start	Everyone
DEPLOYMENT_MASTER_INDEX.md	☁️ Cloud comparison & decision guide	Decision makers
DEPLOY_GCP.md	🔵 Step-by-step GCP deployment	GCP users
DEPLOY_AWS.md	🟠 Step-by-step AWS deployment	AWS users
DEPLOY_AZURE.md	🔷 Step-by-step Azure deployment	Azure users
TROUBLESHOOTING_RUNBOOK.md	🐛 Error reference (25+ scenarios)	When things break
SECURITY.md	🔒 Security best practices	DevOps & Security
DIRECTORY_STRUCTURE.md	📁 Repository organization	Contributors

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                      🌐 User Browser                         │
└─────────────────┬───────────────────────────────────────────┘
                  │ HTTPS
                  ▼
┌─────────────────────────────────────────────────────────────┐
│           📱 Frontend Dashboard (Next.js)                    │
│           • Instance Management                              │
│           • Real-time Deployment Status                      │
└─────────────────┬───────────────────────────────────────────┘
                  │ REST API
                  ▼
┌─────────────────────────────────────────────────────────────┐
│            ⚙️ Backend API (FastAPI)                          │
│            • Deployment Orchestration                        │
│            • Multi-Cloud Support                             │
└─────┬─────────────────────────────────────┬─────────────────┘
      │                                     │
      │ Orchestrates                        │ Stores Metadata
      ▼                                     ▼
┌─────────────────────┐          ┌──────────────────────────┐
│ 🧠 MemMachine       │          │   🗄️ PostgreSQL         │
│    Instance         │          │   Database               │
│    (Cloud Run/      │          │   • Instance tracking    │
│     Fargate/ACI)    │          │   • User data            │
│                     │          │   • API keys             │
│  +                  │          └──────────────────────────┘
│ 📊 Neo4j Aura       │
│    (External SaaS)  │
└─────────────────────┘

🔧 What Makes This Special?

1. 🐳 Custom Docker Image with PostgreSQL Support

The game-changing discovery that took 6+ attempts to solve

MemMachine's official image lacks PostgreSQL support. We solved it:

# Install psycopg2 to the EXACT location where MemMachine expects it
RUN /usr/local/bin/python3 -m pip install --no-cache-dir \
    --target=/app/.venv/lib/python3.12/site-packages \
    psycopg2-binary

Why this matters:

✅ Works with Cloud SQL, RDS, Azure Database for PostgreSQL
✅ Same image works across ALL clouds
✅ No runtime installation (fast startup)
✅ Production-tested and verified

📦 Location: memmachine-docker/

📖 How to build the custom image

# For GCP
cd memmachine-docker
docker build -t gcr.io/$PROJECT_ID/memmachine-custom:latest .
docker push gcr.io/$PROJECT_ID/memmachine-custom:latest

# For AWS
docker build -t $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/memmachine-custom:latest .
docker push $AWS_ACCOUNT_ID.dkr.ecr.$REGION.amazonaws.com/memmachine-custom:latest

# For Azure
docker build -t $ACR_LOGIN_SERVER/memmachine-custom:latest .
docker push $ACR_LOGIN_SERVER/memmachine-custom:latest

Full instructions in memmachine-docker/README.md

2. 🔗 Neo4j Aura Integration (Zero Infrastructure)

Before	After
❌ Self-host Neo4j on Cloud Run	✅ Use Neo4j Aura (managed SaaS)
❌ VPC networking complexity	✅ Works immediately
❌ $100+/month	✅ $0-65/month (free tier available)
❌ Manual scaling & backups	✅ Fully managed

Simply provide your Neo4j Aura credentials:

{
  "neo4j_uri": "neo4j+s://xxxxx.databases.neo4j.io",
  "neo4j_user": "neo4j",
  "neo4j_password": "your-password"
}

Get Neo4j Aura: https://neo4j.com/cloud/aura/ (Free tier available)

3. 📊 Comprehensive Documentation

✅ Copy-paste commands that work
✅ Verification at every step
✅ Troubleshooting for 25+ errors
✅ Production checklists
✅ Security best practices

☁️ Deployment Options

Cloud Provider Comparison

Feature	🔵 GCP	🟠 AWS	🔷 Azure
Container Platform	Cloud Run	ECS Fargate	Container Instances
Database	Cloud SQL	RDS PostgreSQL	Azure DB for PostgreSQL
Monthly Cost	$15-30 🏆	$45-65	$30-55
Deployment Time	~20 min 🏆	~25 min	~20 min
Scale to Zero	✅ Native	✅ Native	⚠️ Requires Container Apps
Free Tier	$300 (90 days)	12 months	$200 (30 days)
Best For	Startups, MVPs	Enterprise, Compliance	Microsoft Shops

🏆 Winner: GCP for cost and simplicity 💼 Runner-up: AWS for enterprise features 🔷 Alternative: Azure for Microsoft ecosystem

See detailed comparison →

💻 Technology Stack

Backend

Frontend

Infrastructure

🎬 Getting Started

Prerequisites

☁️ Cloud account (GCP, AWS, or Azure)
🐳 Docker installed locally
🔑 Neo4j Aura account (free tier available)
⚙️ Cloud CLI installed (gcloud, aws, or az)

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/memcloud.git
cd memcloud

# 2. Choose your cloud and follow the guide
# For GCP:
open DEPLOY_GCP.md

# For AWS:
open DEPLOY_AWS.md

# For Azure:
open DEPLOY_AZURE.md

Deployment Flow

Step 1: 📖 Read deployment guide for your cloud Step 2: 🔧 Setup cloud account and enable APIs Step 3: 🐳 Build custom Docker image with psycopg2 Step 4: 🗄️ Deploy PostgreSQL database Step 5: 🚀 Deploy backend and frontend services Step 6: ✅ Verify deployment and test Step 7: 🎉 Production ready!

📊 Project Stats

Metric	Count
📄 Lines of Documentation	15,000+
🗂️ Deployment Guides	5 (GCP, AWS, Azure + 2 reference)
🐛 Errors Documented	25+ with solutions
☁️ Cloud Providers	3 (GCP, AWS, Azure)
⏱️ Deployment Time	~20 minutes
💰 Starting Cost	$15/month
✅ Success Rate	100% (when following guides)

🔒 Security

All credentials are managed securely:

✅ No hardcoded API keys or passwords
✅ Environment variables and secret managers
✅ Comprehensive .gitignore
✅ Security documentation included

See: SECURITY.md for full guidelines.

🤝 Contributing

We welcome contributions! Here's how:

🍴 Fork the repository
🌿 Create a feature branch (git checkout -b feature/amazing-feature)
💾 Commit your changes (git commit -m 'Add amazing feature')
📤 Push to the branch (git push origin feature/amazing-feature)
🎉 Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🌟 Acknowledgments

Built for the MemVerge Hackathon 🏆

Special thanks to:

🧠 MemVerge for MemMachine
📊 Neo4j for Aura
☁️ GCP, AWS, Azure for cloud platforms

📞 Support

Need Help?

🚀 Ready to Deploy?

Choose your cloud and get started in 20 minutes!

Made with ❤️ for the MemVerge community

⭐ Star us on GitHub if this helped you!

Name		Name	Last commit message	Last commit date
backend		backend
docs/archive		docs/archive
frontend		frontend
memmachine-docker		memmachine-docker
scripts		scripts
.env.template.txt		.env.template.txt
.gitignore		.gitignore
DEPLOYMENT_MASTER_INDEX.md		DEPLOYMENT_MASTER_INDEX.md
DEPLOY_AWS.md		DEPLOY_AWS.md
DEPLOY_AZURE.md		DEPLOY_AZURE.md
DEPLOY_GCP.md		DEPLOY_GCP.md
DIRECTORY_STRUCTURE.md		DIRECTORY_STRUCTURE.md
README.md		README.md
README_DEPLOYMENT.md		README_DEPLOYMENT.md
SECURITY.md		SECURITY.md
TROUBLESHOOTING_RUNBOOK.md		TROUBLESHOOTING_RUNBOOK.md

Latest commit

History

Folders and files

Repository files navigation