Skip to content

README.md

Latest commit

 

History

History
156 lines (106 loc) · 8.31 KB

README.md

File metadata and controls

156 lines (106 loc) · 8.31 KB

Cerebro

Cerebro

Your personal knowledge brain in the cloud — capture from anywhere, search by meaning.

Cerebro gives you a single place to store every fleeting thought, decision, and reminder — then find it again by asking what it meant, not what words you used. It runs on Supabase (free tier), talks to your AI tools over MCP, and accepts input from Discord, Teams, Alexa, iMessage, or any MCP client.

The stack is deliberately simple: a PostgreSQL database with vector search, an AI gateway for embeddings, and Edge Functions for each integration. No middleware layers, no paid connectors, no glue services.

Inspired by the Open Brain project by Nate B. Jones.

How It Works

Capturing: You send a thought from any source (chat message, voice command, AI tool). Cerebro generates a vector embedding and extracts structured metadata (topics, people, action items, type) in parallel, then stores everything as a single row.

Searching: You describe what you're looking for in plain language. Cerebro embeds your query and runs a cosine similarity search across all stored thoughts — so "career decisions" finds a note about "Sarah thinking about leaving her job" even with zero overlapping words.

Getting Started

→ Complete Setup Guide — Start here. Walks you through everything from core infrastructure to optional features, with verification tests at every step.

The setup guide covers:

  1. Core Infrastructure — Supabase + OpenRouter + MCP server (~20 min)
  2. Capture Sources — Discord, Teams, Alexa, and/or iMessage
  3. Calendar Reminders — Auto-create O365/Google events from dates in thoughts
  4. Daily & Weekly Digest — AI summaries to chat channels + email
  5. File Attachments — AI vision scanning of images, PDFs, and documents
  6. Task Management — Complete, reopen, and delete tasks with natural language

Quick links: Core Setup · Discord · Teams · Alexa · iMessage · Reminders · Digest · File Attachments · Task Management

🤖 Using an AI coding tool? AI-Guided Setup — Let your AI walk you through the deployment step by step.

What You Need

Service Purpose Cost
Supabase Database + Edge Functions Free tier
OpenRouter Embeddings + metadata extraction ~$0.10–0.30/month

What Gets Built

  • PostgreSQL + pgvector database with semantic search
  • MCP server (Supabase Edge Function) with 12 tools:
    • search_thoughts — Semantic similarity search
    • list_thoughts — Browse recent with filters
    • thought_stats — Summary statistics
    • capture_thought — Save with auto-embedding + metadata extraction
    • complete_task — Mark a task as done by semantic match
    • reopen_task — Reopen a completed task
    • delete_task — Soft-delete a thought
    • search_series_bible — Search fiction series bibles (characters, worldbuilding, timeline, plot arcs)
    • search_style_guide — Search author style guides (voice, word lists, formatting)
    • search_editorial_history — Search past editorial findings across pipeline runs
    • search_cover_specs — Search book cover design specifications
    • capture_publishing — Write content into any publishing collection
  • Supabase Storage — File attachments with signed URLs (1 GB free)
  • Access key auth — Simple, secure, no OAuth complexity

Capture Sources

Source How Guide
Any MCP client Direct tool calls via MCP server Getting Started
Microsoft Teams DM or @mention the Cerebro bot Teams Setup
Discord /capture and /search slash commands Discord Setup
Alexa "Alexa, tell cerebro …" voice commands Alexa Setup
iMessage Text commands via BlueBubbles (Mac server + Cloudflare tunnel) iMessage Setup

Features

Daily & Weekly Digest

Automated AI-powered summaries delivered to Teams, Discord, and email. The daily digest (every morning) covers key themes, action items, people, and upcoming reminders. The weekly digest (Sundays) provides a deeper analysis of recurring patterns, goal progress, completed tasks, and relationship touchpoints. Chat channels auto-register on first capture; email uses Resend (free tier: 100/day).

→ Digest Setup

Also available on-demand via Alexa: "ask cerebro for my daily digest" / "ask cerebro for my weekly digest"

Calendar Reminders

When you mention a date or time in a captured thought, Cerebro automatically creates a calendar event on O365 and/or Google Calendar. Works from any capture source.

→ Reminders Setup

Example: "remind me to call the dentist next Wednesday at 5 AM" → creates a calendar event for Wed 5:00 AM.

File Attachments

Send images, PDFs, and documents to any capture channel. Cerebro uses AI vision to scan and extract content, then optionally stores the file in Supabase Storage.

  • 📷 Image OCR and description via GPT-4o-mini vision
  • 📄 PDF and document analysis via Gemini 2.0 Flash
  • 💾 Optional file storage (1 GB free on Supabase)
  • 🔍 Search and filter thoughts by file attachment

→ File Attachments Setup

Task Management

Track task lifecycle with natural language. Complete, reopen, and delete tasks by describing them — Cerebro uses AI to match the right one.

  • ✅ Complete tasks: "done: quarterly report"
  • 🔄 Reopen tasks: "reopen: quarterly report"
  • 🗑️ Soft-delete thoughts: "delete: old reminder"
  • 🔍 Filter by status in MCP tools (open/done/deleted)

→ Task Management Setup

Project Structure

docs/           — Setup guides and documentation
extensions/     — Feature extensions (coming soon)
integrations/   — MCP server, Teams capture, Discord capture, Alexa voice, iMessage capture, daily digest
schemas/        — Database schemas and migrations (including publishing collections)
scripts/        — Database client (dbsql.py) and publishing ingest CLI (cerebro_ingest.py)

Connecting Your AI

Works with any MCP-compatible client:

Client Connection Method
Claude Desktop Settings → Connectors → Add custom connector → paste URL
ChatGPT Settings → Apps & Connectors → Create → paste URL
Claude Code claude mcp add --transport http cerebro <url> --header "x-brain-key: <key>"
Cursor/VS Code Remote MCP URL or mcp-remote bridge

Publishing Collections

Cerebro includes four specialized collections for AI-powered fiction editing pipelines:

  • Series Bible — Characters, worldbuilding, timeline, settings, plot arcs for fiction series
  • Style Guide — Author voice, word preferences, formatting rules, genre conventions
  • Editorial History — Findings from editing passes (voice, pacing, continuity, craft issues)
  • Cover Specs — Book cover design specifications (palettes, typography, imagery)

Each collection uses the same pgvector semantic search as thoughts. The capture_publishing tool writes to any collection; dedicated search tools retrieve context during editing. A Python ingest CLI (scripts/cerebro_ingest.py) bulk-loads markdown files (series bibles, style guides) with automatic heading-based chunking and category detection.

On-Prem Version

A fully self-hosted version is available at cerebro-onprem — replaces all cloud services with Docker containers (PostgreSQL, MinIO, Express.js) and Ollama for local AI.

License

FSL-1.1-MIT — Based on Open Brain by Nate B. Jones.