Skip to content

coinsspor/MemoryVaultAI

BranchesTags

Repository files navigation

# MemoryVault AI 🧠💎

Store Your Memories Forever with AI-Powered Intelligence

Filecoin Lighthouse Next.js OpenAI

Live Demo: vault.coinsspor.com

📖 Table of Contents

🌟 Overview

MemoryVault AI is a decentralized photo storage platform that combines the permanence of Filecoin blockchain storage with the intelligence of AI-powered semantic search.

Your precious memories deserve more than temporary cloud subscriptions—they deserve forever.

Why MemoryVault?

  • 🔒 Permanent Storage: Pay once, store forever on Filecoin
  • 🤖 AI Intelligence: Automatic image tagging with OpenAI Vision
  • 🔍 Semantic Search: Find photos by content, not just filename
  • 💰 Cost Effective: No recurring subscriptions
  • 🌐 Truly Decentralized: Your data, your control
  • ⚡ Fast Retrieval: IPFS + Filecoin gateway integration

🎯 The Problem We Solve

Traditional Cloud Storage Issues:

❌ Subscription Fatigue: Monthly fees that never end
❌ Vendor Lock-in: Your memories trapped in one platform
❌ Manual Organization: Hours spent tagging and categorizing
❌ Search Limitations: Can only find what you manually labeled
❌ No Permanence Guarantee: Services can shut down or change terms

MemoryVault Solution:

✅ One-Time Payment: Pay once for permanent Filecoin storage
✅ Blockchain Permanence: Cryptographically guaranteed durability
✅ AI Auto-Tagging: Intelligent content recognition
✅ Natural Search: "sunset beach" or "birthday cake" - just search naturally
✅ True Ownership: You control your data via wallet address

✨ Key Features

🚀 Core Functionality

  • Wallet-Based Authentication: Secure login via MetaMask
  • One-Click Upload: Drag-and-drop photo upload to Filecoin
  • AI Auto-Tagging: OpenAI Vision API analyzes images and generates tags
  • Semantic Search: Tag-based filtering and filename search
  • Gallery View: Beautiful grid layout with hover previews
  • Direct Download: Retrieve photos directly from Filecoin/IPFS
  • Balance Tracking: Real-time FIL and USDFC balance display

🎨 User Experience

  • Responsive Design: Works on desktop, tablet, and mobile
  • Progress Tracking: Real-time upload progress with status updates
  • Hover Effects: Interactive gallery with smooth animations
  • Dark Mode: Beautiful gradient UI optimized for viewing photos

🛠 Technology Stack

Frontend

  • Next.js 14: React framework with App Router
  • TypeScript: Type-safe development
  • Tailwind CSS: Utility-first styling
  • RainbowKit: Wallet connection UI
  • Wagmi: Ethereum wallet hooks

Blockchain & Storage

  • Filecoin Calibration Testnet: Decentralized storage network
  • Lighthouse.storage: IPFS + Filecoin gateway (production)
  • Synapse SDK: Filecoin Onchain Cloud (attempted, see notes below)
  • IPFS: Content-addressed storage

AI & Database

  • OpenAI Vision API (gpt-4o-mini): Image analysis and tagging
  • Supabase: Metadata storage and indexing
  • PostgreSQL: Relational database

Development Tools

  • Ethers.js v6: Ethereum interactions
  • Vercel: Deployment platform
  • Git: Version control

🏗 Architecture

┌─────────────────────────────────────────────────────────┐
│                    User Interface                        │
│              (Next.js + React + Tailwind)               │
└────────────────────┬────────────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         │                       │
    ┌────▼─────┐          ┌────▼──────┐
    │  Wallet  │          │    AI     │
    │ (MetaMask)│         │  (OpenAI) │
    └────┬─────┘          └────┬──────┘
         │                     │
         │                     ▼
         │            ┌─────────────────┐
         │            │  Auto-Tagging   │
         │            │   (Fallback)    │
         │            └─────────┬───────┘
         │                      │
         ▼                      ▼
    ┌─────────────────────────────────┐
    │      Lighthouse.storage         │
    │  (IPFS + Filecoin Integration)  │
    └────────────┬────────────────────┘
                 │
         ┌───────┴────────┐
         │                │
    ┌────▼─────┐    ┌────▼──────┐
    │   IPFS   │    │ Filecoin  │
    │ (Fast)   │    │(Permanent)│
    └──────────┘    └───────────┘
         │                │
         └────────┬───────┘
                  │
          ┌───────▼────────┐
          │   Supabase     │
          │  (Metadata)    │
          └────────────────┘

🔗 Filecoin Integration

Current Implementation: Lighthouse.storage

We use Lighthouse.storage as our primary Filecoin storage solution:

Why Lighthouse?

  • ✅ Production-Ready: Stable, reliable API
  • ✅ Filecoin-Backed: Automatically creates Filecoin storage deals
  • ✅ IPFS Gateway: Fast retrieval via dedicated gateways
  • ✅ Simple Integration: API key authentication
  • ✅ Officially Supported: Listed in Filecoin documentation

How It Works:

  1. User uploads photo via web interface
  2. File sent to Lighthouse API
  3. Lighthouse stores on IPFS (immediate availability)
  4. Lighthouse creates Filecoin deals (permanent storage)
  5. Returns CID for future retrieval

Code Example:

import lighthouse from '@lighthouse-web3/sdk'

const output = await lighthouse.upload([file], apiKey)
const cid = output.data.Hash // IPFS CID

// Retrieve from IPFS gateway
const url = `https://gateway.lighthouse.storage/ipfs/${cid}`

Synapse SDK Exploration

We also explored Filecoin Onchain Cloud (Synapse SDK) for deeper integration:

Implementation Status:

  • ✅ Payment setup completed (deposit + approveService)
  • ✅ Storage service creation successful
  • ❌ Upload fails with Exit Code 33 (contract revert)

Issue Details:

  • Problem: Calibration testnet contract instability
  • Error: Exit Code 33 - Contract revert during upload()
  • Reported: Filed issue in #fil-builders Slack channel
  • Verified: Other builders experiencing same issue
  • Context: Recent FWSS contract upgrade may be related

Code Implemented (Ready for Mainnet):

// Payment setup
await synapse.payments.deposit(depositAmount, TOKENS.USDFC)
await synapse.payments.approveService(PANDORA_SERVICE, rate, lockup)

// Storage creation
const storage = await synapse.createStorage()

// Upload (currently fails on testnet)
await storage.upload(bytes, { callbacks... })

Future Plans: Once Synapse SDK testnet stabilizes or mainnet alpha launches, we will:

  1. Integrate both Lighthouse and Synapse for redundancy
  2. Add PDP (Proof of Data Possession) verification
  3. Implement FilCDN for faster retrieval
  4. Enable USDFC stablecoin payments

Documentation:

  • Synapse SDK code: src/lib/synapse.ts
  • Attempted integration: src/hooks/usePayment.ts
  • Issue logs available in Git history

🤖 AI-Powered Tagging

OpenAI Vision Integration

Intelligent Content Recognition:

MemoryVault uses OpenAI's gpt-4o-mini vision model to automatically analyze uploaded images:

// AI analyzes image content
const tags = await analyzeImage(file)
// Returns: ["sunset", "beach", "ocean", "vacation", "summer"]

What Gets Tagged:

  • 🎨 Objects: People, animals, food, vehicles
  • 🌈 Colors: Dominant color palettes
  • 😊 Mood: Happy, serene, energetic
  • 📍 Location Type: Beach, mountain, urban, indoor
  • 🎭 Activities: Swimming, dining, celebration

Current Status: Fallback System Active

⚠️ OpenAI API Status:

The AI tagging code is fully implemented and functional, but currently using fallback mode due to OpenAI API rate limits on the free tier.

Fallback Tags Generated:

  • File type (jpeg, png, gif)
  • Upload year (2025)
  • Generic tags (photo, memory)

Why Fallback?

  • OpenAI free tier: 3 requests/minute
  • During testing, we exceeded rate limits
  • Production deployment will use paid tier with higher limits

Code Location:

  • Main AI logic: src/lib/ai.ts
  • Integration: src/hooks/useUpload.ts
  • Fallback generation: generateFallbackTags()

Console Output Examples:

When AI Works:

🤖 Analyzing image with OpenAI Vision...
✅ AI generated tags: ["sushi", "food", "japanese", "salmon", "rice"]

When Fallback Activates:

⚠️ OpenAI API rate limit reached
🏷️ Generated tags: ["photo", "2025", "jpeg", "memory"]

Testing AI Tagging

To test with real OpenAI Vision API:

  1. Add OpenAI API key with credits to .env.local
  2. Upload a new photo
  3. Check browser console for AI analysis
  4. Tags will appear in Search page

Production Ready:

  • ✅ Code tested and working
  • ✅ Graceful fallback implemented
  • ✅ Ready for deployment with proper API credits

🚀 Setup Instructions

Prerequisites

  • Node.js 18+
  • npm or yarn
  • MetaMask wallet
  • Filecoin Calibration testnet FIL (from faucet)

1. Clone Repository

git clone https://github.com/yourusername/memoryvault-ai.git
cd memoryvault-ai

2. Install Dependencies

npm install

3. Environment Variables

Create .env.local:

# Filecoin Calibration Testnet
NEXT_PUBLIC_FILECOIN_RPC=https://api.calibration.node.glif.io/rpc/v1
NEXT_PUBLIC_CHAIN_ID=314159
NEXT_PUBLIC_USDFC_ADDRESS=0xb3042734b608a1B16e9e86B374A3f3e389B4cDf0

# WalletConnect (optional)
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id

# Lighthouse Storage
NEXT_PUBLIC_LIGHTHOUSE_API_KEY=your_lighthouse_api_key

# OpenAI (optional, will use fallback if not provided)
NEXT_PUBLIC_OPENAI_API_KEY=your_openai_key

# Supabase
NEXT_PUBLIC_SUPABASE_URL=your_supabase_url
NEXT_PUBLIC_SUPABASE_ANON_KEY=your_supabase_anon_key

4. Database Setup

Create a Supabase table:

CREATE TABLE memories (
  id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  owner_address TEXT NOT NULL,
  piece_cid TEXT NOT NULL,
  file_name TEXT NOT NULL,
  file_type TEXT NOT NULL,
  file_size BIGINT NOT NULL,
  tags TEXT[] DEFAULT '{}',
  description TEXT DEFAULT '',
  location TEXT,
  mood TEXT,
  created_at TIMESTAMP DEFAULT NOW(),
  thumbnail_url TEXT
);

CREATE INDEX idx_owner_address ON memories(owner_address);
CREATE INDEX idx_tags ON memories USING GIN(tags);

5. Run Development Server

npm run dev

Visit http://localhost:3000

6. Get Testnet Tokens

Filecoin Calibration FIL:

USDFC (if using Synapse SDK):

  • Available in Filecoin Calibration testnet

📁 Project Structure

memoryvault-ai/
├── src/
│   ├── app/
│   │   ├── page.tsx              # Landing page
│   │   ├── upload/
│   │   │   └── page.tsx          # Upload interface
│   │   ├── gallery/
│   │   │   └── page.tsx          # Photo gallery
│   │   ├── search/
│   │   │   └── page.tsx          # Semantic search
│   │   ├── layout.tsx            # Root layout
│   │   ├── providers.tsx         # Web3 providers
│   │   └── globals.css           # Global styles
│   ├── components/
│   │   └── Navbar.tsx            # Navigation component
│   ├── hooks/
│   │   ├── useUpload.ts          # Upload logic + AI
│   │   ├── useBalance.ts         # Wallet balance
│   │   └── usePayment.ts         # Synapse payments
│   ├── lib/
│   │   ├── ai.ts                 # OpenAI Vision integration
│   │   ├── synapse.ts            # Synapse SDK (testnet attempt)
│   │   ├── supabase.ts           # Database client
│   │   └── chains.ts             # Filecoin network config
│   └── types/
├── public/                        # Static assets
├── .env.local                     # Environment variables (not in repo)
├── .gitignore                     # Git ignore rules
├── package.json                   # Dependencies
├── tsconfig.json                  # TypeScript config
├── tailwind.config.ts             # Tailwind config
└── README.md                      # This file

🔄 Development Journey

Iterations & Learnings

Wave 1: Design & Planning

  • ✅ Problem identification
  • ✅ Architecture design
  • ✅ Technology selection
  • ✅ Filecoin research

Wave 2: Implementation

Initial Approach: Synapse SDK

  • Implemented full payment flow
  • Created storage services
  • Blocker: Calibration testnet contract instability
  • Decision: Pivot to production-ready alternative

Pivot: Lighthouse.storage

  • Rapid integration (30 minutes)
  • Stable and working immediately
  • Filecoin-backed storage maintained
  • Result: Working demo achieved

AI Integration

  • OpenAI Vision API implementation
  • Intelligent fallback system
  • Tested with multiple image types
  • Status: Code ready, rate limits encountered

UI/UX Polish

  • Responsive gallery layout
  • Real-time upload progress
  • Tag-based search filtering
  • Professional dark theme

Challenges & Solutions

Challenge Solution Learning
Synapse SDK testnet errors Pivot to Lighthouse Have production-ready backup plans
OpenAI rate limits Intelligent fallback system Always design for graceful degradation
USDFC balance display ERC20 contract integration Deep understanding of token standards
Image layout consistency CSS aspect-ratio + flexbox Modern CSS solves complex layouts

Community Engagement

  • ✅ Reported Synapse SDK testnet issue in #fil-builders
  • ✅ Documented error logs for team reference
  • ✅ Provided feedback on Filecoin Onchain Cloud
  • ✅ Transparent development process

🗺 Roadmap

Phase 1: Core Features ✅

  • Wallet authentication
  • Filecoin storage integration (Lighthouse)
  • AI-powered tagging
  • Gallery view
  • Search functionality
  • Balance tracking

Phase 2: Enhanced Features (Q4 2025)

  • Integrate Synapse SDK (when mainnet stable)
  • PDP verification display
  • FilCDN fast retrieval
  • Video file support
  • Batch upload
  • Album organization

Phase 3: Advanced Features (Q1 2026)

  • Natural language search ("photos from last summer")
  • Face recognition (privacy-first)
  • Shared galleries (with access control)
  • Mobile app (React Native)
  • Photo editing tools
  • Print service integration

Phase 4: Ecosystem Growth (Q2 2026)

  • Multi-chain support
  • NFT minting from stored photos
  • Social features (comments, likes)
  • Marketplace for prints
  • Partner integrations
  • Enterprise storage plans

🤝 Contributing

We welcome contributions! This project is open source.

How to Contribute

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

Development Guidelines

  • Follow TypeScript best practices
  • Add comments for complex logic
  • Test on Filecoin Calibration testnet
  • Update README for new features
  • Maintain responsive design

Areas for Contribution

  • 🐛 Bug fixes
  • 🎨 UI/UX improvements
  • 📝 Documentation
  • 🧪 Testing
  • 🌐 Internationalization
  • ♿ Accessibility features

📄 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Technologies

  • Filecoin Foundation - For decentralized storage infrastructure
  • Lighthouse.storage - For production-ready Filecoin integration
  • OpenAI - For Vision API and image analysis
  • RainbowKit - For beautiful wallet connection UI
  • Supabase - For reliable database infrastructure

WaveHack Program

Built as part of the Filecoin Onchain Cloud WaveHack hackathon.

Special thanks to:

  • Filecoin developer community
  • #fil-builders Slack channel
  • WaveHack mentors and judges

📞 Contact & Links

🎉 Try It Now!

  1. Visit vault.coinsspor.com
  2. Connect your MetaMask wallet (Filecoin Calibration testnet)
  3. Upload a cherished photo
  4. Watch AI automatically tag it
  5. Search and rediscover your memories

Your memories deserve permanence. Store them on Filecoin forever. 💎

Made with ❤️ for the decentralized future

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages