"A $0/month context-aware, multimodal second brain powered by Google Gemini 2.5/3.5, Meta WhatsApp, Telegram, and Notion."
Ocean is an intelligent, context-aware AI operating system designed to run your life, research, study roadmaps, whiteboard notes, tasks, and second-brain retrieval directly from your favorite messaging apps (WhatsApp & Telegram).
Instead of dealing with clunky Notion interfaces on mobile, you simply talk to Ocean in natural human language, drop links, snap photos of whiteboards and handwritten notes, or ask questions across your entire knowledge base and standalone folder hierarchies. Ocean remembers your recent chat context, routes your intent across specialized intelligence modules, researches canonical papers and documentation on the fly, and organizes everything into a structured, interconnected Notion workspace.
┌────────────────────────┐
│ 🌊 Ocean v2.4 Core │
└───────────┬────────────┘
│
┌──────────────────┬─────────────────────┼─────────────────────┬──────────────────┐
▼ ▼ ▼ ▼ ▼
📱 PROACTIVE WA TEXT 📂 FOLDER EXPLORER 🔍 DEEP BLOCK QA 📈 WEEKLY VELOCITY 🧠 SECOND BRAIN
• 24h fallback temp• "What's in notes" • "What's in budget" • Midnight 12AM IST• Natural QA
• Free utility tier• Breadcrumb paths • Numbers & line items• Momentum score • Multi-DB search
• Zero blocked cron• Zero hardcoding • Grounded synthesis • Notion Archive • Direct URL cites
• Dual TG+WA dispatch• Archive guidance • Table & list reading• Safe lifecycle • 205 unit tests
- Automatic 24-Hour Window Fallback: When Ocean initiates a message to you outside Meta's 24-hour service window (e.g. 12:00 AM midnight cron task reminders or weekly retrospective pings), Ocean automatically detects the window expiration and dispatches via your approved
ocean_notificationUtility Template for $0. - Dual Telegram + WhatsApp Dispatch: Midnight task reminders and velocity digests ping both your WhatsApp and Telegram simultaneously with zero delivery failures.
- Zero Hardcoding Dynamic Graph: Ocean crawls and caches your entire Notion workspace tree from root to leaves, resolving live breadcrumb paths (e.g.
Home > Notes > Year 1 Budget...,Home > Miscellaneous > Finances for Umass fall). - Folder Exploration: Ask "what's in my notes?", "what's in miscellaneous?", or "show me my notes folder", and Ocean lists all child documents and subpages with direct clickable deep links.
- Archive Lifecycle: Ask "archive year one budget" or "send finances to archive", and Ocean moves the page into your Archive Index database with date metadata and deep links.
- Full-Block Content Reading: Ocean recursively extracts child blocks (paragraphs, bullet lists, tables, numbered items, and to-dos) from any standalone Notion document.
- Granular Synthesis: Ask "can you tell me what's in that year one budget?" or "did I write about finances for Umass fall?", and Gemini synthesizes an unconstrained response detailing exact line items, figures, and takeaways.
- Weekly Momentum Tracking: Evaluates tasks completed vs carried over, learning roadmaps advanced, LeetCode problems solved, and research papers digested over the past 7 days.
- Gemini Velocity Synthesis: Generates a momentum score (0-100), executive headline, breakthrough milestones, bottlenecks, and sets 3 high-leverage strategic priorities for next week.
- Dual Delivery: Automatically creates a structured
📈 Weekly Velocity Review — [Date]page in Notion and sends a punchy executive digest to WhatsApp and Telegram every Sunday evening (or on demand by asking "how was my week?").
- Full-Workspace Semantic Retrieval: Ask natural questions about your past notes, papers, or tasks (e.g. "What were the key takeaways from the MoE papers?", "What did I note about consistent hashing?", "Find my notes on my personal website").
- Multi-Database Retrieval: Seamlessly scans workspace global search, Subjects DB, Resources DB, Tasks DB, and Daily Logs.
- Grounded Synthesis with Direct Links: Synthesizes clear answers grounded in your Notion notes and cites exact pages with clickable Notion URLs.
- Zero-Effort Visual Notes: Snap photos of whiteboard architecture diagrams, handwritten study notes, code screenshots, receipts, or official forms directly in WhatsApp or Telegram.
- Structured Notion Ingestion: Automatically routes to Daily Logs / MIND (for diagrams and notes) or creates items in Tasks Tracker (for receipts and actionable docs) with deep links.
- Instant Ingestion: Send any URL (ArXiv paper, GitHub repo, Substack post, technical blog, YouTube video) with zero prompt.
- Unconstrained Depth & Essence: Synthesizes core essence, key takeaways, and practical engineering implications, resolves canonical domain tags, and logs to Notion Resources DB with a direct clickable deep-link.
-
Nightly Workspace Hygiene: Automated GitHub Actions cron audit (
cron/find_duplicates.py) scans Subjects, Tasks, and Resources using hybrid fuzzy token sorting, sequence matching, and Jaccard containment ($\ge 70%$ ). -
Live Review Dashboard: Generates the structured
🧹 Notion Cleanup & Duplicate Reviewpage in Notion with clickable links and recommends moving misclassified items to true domain tags.
- Rolling Context Buffer: Remembers recent conversation turns (per WhatsApp phone number or Telegram chat ID) with automatic 30-minute session TTL.
- Natural Follow-ups: Ask "What are my high priority tasks?" followed by "others?", "more", or "next", and Ocean seamlessly paginates through items without repeating.
-
Anti-Rambling Guardrails: Short follow-up questions (
$\le 4$ words) are protected from being accidentally saved as philosophical essays or journal entries.
- Deep Knowledge & Search Grounding: Turn any exploratory topic (e.g. "Mixture of Experts architecture", "Distributed Consensus with Raft") into a comprehensive syllabus.
- Direct In-Page Clickable Resources: Every Subject page in Notion is built with embedded clickable paper/documentation links, type badges (
[Paper],[Docs],[Video]), and 1-sentence takeaways. - 3-Way Database Orchestration: Automatically synchronizes
Subjects,Resources, andTasks Trackerso that checking off study tasks updates the visual% Completedprogress bar.
-
Hybrid Fuzzy Similarity Engine: Scans
Subjects,Tasks, andResourcesusingdifflib.SequenceMatcher, token sort ratio, and Jaccard containment ($\ge 70%$ ). - Dedicated Review Page in Notion: Publishes a clean, clickable Notion Cleanup & Duplicate Review dashboard.
- 100% Non-Destructive: Never deletes or alters pages automatically—gives you pairwise links, timestamps, and actionable advice to resolve duplicates with a single click.
- Substack Mode: Formats long-form thoughts into Substack-ready drafts with automatic title generation, core thesis extraction, and tags.
- Ramblings & Journaling: Captures unformatted brain dumps, reflections, and streams of consciousness into a dedicated Notion database.
-
Algorithm & Complexity Evaluator: Reviews problem practice notes, calculates time and space complexity (
$O(N)$ , $O(1)$), and generates targeted edge-case interview testing questions.
- Every task created, subject compiled, note logged, or query returned includes a direct
🔗 https://app.notion.com/...deep-link so you never have to browse manually.
┌───────────────────────────┐ ┌────────────────────────────────┐
│ WhatsApp (Meta Cloud API) │──┐ │ FastAPI Webhook Server │
└───────────────────────────┘ │ │ (Hosted 24/7 on Render) │
├─────▶│ • 2-Stage Gemini Routing │──▶ Notion Workspace
┌───────────────────────────┐ │ │ • Conversational Memory │ • Tasks Tracker DB
│ Telegram Bot API │──┘ │ • Background Task Worker │ • Subjects DB
└───────────────────────────┘ └────────────────────────────────┘ • Resources DB
• Substack & Mind DB
• LeetCode Log DB
┌────────────────────────────────┐
│ GitHub Actions (Proactive) │
│ • 08:00 AM Reminder Digest │──▶ Telegram Digest
│ • Daily LeetCode Cleanup │
│ • Automated Duplicate Audit │
└────────────────────────────────┘
- Reactive Path (Real-time Messaging):
- WhatsApp/Telegram payloads arrive at the FastAPI server on Render.
- Stage 1: Fast Gemini module classification (
TASKS,MIND,LEARNING,LEETCODE). - Stage 2: Deep structured Pydantic schema extraction.
- Long-running operations (like Grounding + Link Verification + Multi-DB writes) execute in background threadpools with immediate chat acknowledgments.
- Proactive Path (GitHub Actions Cron):
- Runs daily independent of Render to scan deadlines, clean up expired practice items, audit duplicate entries, and push morning digests.
notion-assistant/
├── app/
│ ├── main.py # FastAPI application & 2-stage Gemini router
│ ├── memory.py # Sliding-window conversational memory & state tracker
│ ├── learning_service.py # Grounding curriculum compiler & resource engine
│ ├── duplicate_detector.py # Fuzzy token similarity & duplicate cluster engine
│ ├── cleanup_reporter.py # Notion Cleanup & Review dashboard generator
│ ├── notion_client.py # Resilient Notion API client with automatic retries
│ ├── whatsapp_client.py # Meta WhatsApp Cloud API wrapper
│ ├── telegram_client.py # Telegram Bot API client
│ ├── schemas.py # Pydantic models for structured output & validation
│ └── config.py # Environment configuration & fail-fast validator
├── cron/
│ ├── check_reminders.py # Daily morning reminder digest script
│ ├── cleanup_leetcode.py # Automatic LeetCode practice status cleaner
│ └── find_duplicates.py # Duplicate detection audit & reporter script
├── tests/
│ ├── test_main.py # Webhook & endpoint integration tests
│ ├── test_memory.py # Conversational memory & pagination tests
│ ├── test_learning.py # Learning curriculum & resource pipeline tests
│ ├── test_duplicate_detector.py # Similarity & cleanup dashboard tests
│ ├── test_notion_client.py # Notion client unit tests
│ └── test_whatsapp_client.py # WhatsApp integration tests
├── .github/workflows/
│ ├── reminders.yml # Daily scheduled GitHub Actions cron job
│ └── keep_alive.yml # Render free-tier keep-alive pinger
├── requirements.txt # Production dependencies
├── Procfile # Render start command
└── README.md
git clone https://github.com/RohanMali2003/notion-assistant.git
cd notion-assistant
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # Or on Windows: .venv\Scripts\activate
# Install dependencies
pip install -r requirements.txtCreate a .env file in the root directory:
# Notion Credentials & Database IDs
NOTION_TOKEN=secret_your_notion_integration_token
NOTION_TASKS_DB_ID=your_tasks_database_id
NOTION_SUBJECTS_DB_ID=your_subjects_database_id
NOTION_RESOURCES_DB_ID=your_resources_database_id
NOTION_SUBSTACK_ID=your_substack_database_id
NOTION_RAMBLINGS_ID=your_ramblings_database_id
NOTION_DAILY_LOGS_ID=your_daily_logs_database_id
NOTION_LEETCODE_LOG_DB_ID=your_leetcode_database_id
# Google Gemini AI
GEMINI_API_KEY=your_gemini_api_key
GEMINI_MODEL=gemini-3.5-flash-lite
# WhatsApp Cloud API
WHATSAPP_TOKEN=your_meta_system_user_token
WHATSAPP_PHONE_NUMBER_ID=your_whatsapp_phone_number_id
WHATSAPP_VERIFY_TOKEN=your_custom_webhook_verify_token
# Telegram Bot API
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
TELEGRAM_CHAT_ID=your_telegram_chat_id
# App Environment
APP_ENV=productionuvicorn app.main:app --reload --port 8000pytestAll 174 unit tests pass with zero external network dependencies!
You can manually trigger any of Ocean's maintenance scripts anytime:
# Run duplicate audit across Notion
python cron/find_duplicates.py
# Run morning deadline check & digest
python cron/check_reminders.py
# Run LeetCode practice cleanup
python cron/cleanup_leetcode.py| Component | Provider | Tier | Cost |
|---|---|---|---|
| Messaging | Meta WhatsApp Cloud API | Free (1,000 conversations/month) | $0.00 |
| Messaging | Telegram Bot API | Unlimited Free Tier | $0.00 |
| Compute / API | Render Web Service | Free Instance Tier | $0.00 |
| Intelligence | Google AI Studio (Gemini 2.5 / 3.5) | Free Tier (1M TPM / 15 RPM) | $0.00 |
| Database | Notion Official API | Free Integration Tier | $0.00 |
| Proactive Cron | GitHub Actions | 2,000 free workflow minutes/month | $0.00 |
| Total | $0.00 / month |
Distributed under the MIT License. See LICENSE for more information.
Ocean v2.0 — Crafted with ❤️ by Rohan Mali & powered by Google Gemini.