Cogni

Cogni decides what to study, when to study, and how — so you just show up. Feed it your syllabi, lecture notes, past exams, and course materials. It classifies and processes everything automatically, extracts your topics, maps your professor's grading weights, and generates a prioritized study plan every morning based on your current mastery, upcoming exams, and grade risk. The tutor pulls from your actual course materials and remembers you between sessions. Flashcards are scheduled by FSRS at the card and topic level. It tracks your grades and tells you exactly what you need on the final. You can even study through your own Claude via MCP. All you do is study. Always BYOK on Vercel + Supabase.

Run it two ways: self-hosted for a single user, or hosted multi-tenant — one operator running a public instance for many users (open / invite-code / .edu signup gating, per-user AI quotas, kill-switches, legal pages, and more). Either way it stays BYOK and self-hostable.

> v2.1.0 — "Hardening": a deep security + correctness pass — RLS lockdown (browser clients are read-only; all writes go through authorized server routes), race-safety DB constraints, conflict-aware calendar scheduling (study blocks fit the gaps around your real events), restored Canvas sync, fixed spaced-repetition graduation, plus broad input-validation and UI-robustness fixes — backed by 168 unit + integration tests and live end-to-end coverage. Builds on v2.0.0 — "Memory · MCP · Grades" (persistent tutor memory, a built-in MCP server, grade tracking with a "what do I need on the final" calculator, Canvas import, semester standing, mastery decay). Everything is additive and BYOK. Requires running [supabase/big-update.sql](supabase/big-update.sql) once before deploying (idempotent). See the [CHANGELOG](CHANGELOG.md) for the full list.

> Beta: Cogni is under active development. Expect rough edges, verify important study data, and test thoroughly before relying on it for critical coursework.

🔄 How it works

1. Upload your course materials — syllabi, lecture notes, past exams, anything you have. Claude classifies each file, extracts topics with professor weights, exam dates, the grade breakdown, and prerequisite links. Your course is fully mapped in minutes.
2. Every morning a plan is generated — the scheduler scores every topic by mastery deficit, professor weight, exam proximity, and grade risk. It allocates your session time, orders your flashcard review, and writes study blocks to your calendar.
3. Open the app and study — flashcard review, tutor sessions, and quizzes all update your mastery in real time. The tutor remembers you between sessions and opens with a recap. Tomorrow's plan adapts to what you did today.
4. Or study through your own Claude — connect Cogni as an MCP server and review cards, run exam prep, and log sessions from Claude Code / Desktop. It all writes back to your mastery, schedule, and streak.

You don't decide what to study. Cogni does.

📸 Screenshots

Sign in — Google OAuth or email/password Today — AI-generated daily plan with streak, insight, and study tasks

Courses — coverage and mastery bars per course Topics — per-topic mastery, coverage, and due card count

Flashcard review — FSRS 4-point rating (Again / Hard / Good / Easy) Tutor → flashcards — inline card generation during a session

Tutor → quiz — MC with LaTeX rendering and auto-grading Essay mode — split-view editor with tracked changes and three assist levels

Inbox — upload files, Haiku classifies and routes them automatically Progress — 30-day mastery trends and weak areas across all courses

Exams + materials — scores, processed materials, test history Calendar — study blocks written to a dedicated Cogni Study calendar

Settings — BYOK key status, calendar connection, session length, daily message limit

🧠 Features

• FSRS spaced repetition — full card-level state (stability, difficulty, reps, lapses). 4-point ratings: Again / Hard / Good / Easy. Atomic RPC updates FSRS state and topic mastery in one transaction.
• AI study planner — daily plan prioritized by mastery deficit × professor weight × exam proximity. Generates a 6-day ahead preview. Writes flashcard review blocks to Google Calendar. Plans, streaks, due cards, and calendar blocks all use your local timezone (auto-detected at onboarding).
• Claude-powered tutor — four modes: Answer (direct), Teach (Socratic), Focus (weak-area routing), Essay (split-view editor with tracked changes). Deep thinking mode switches to Claude Opus 4.8 with extended thinking for hard problems. Native web search. Inline flashcard, quiz, chart, and Mermaid-diagram generation. Session persistence with auto-naming.
• Professor profiling — builds a per-professor wiki from past exams, syllabi, and graded materials. Tracks question depth, phrasing style, and topic weights. Persists across semesters — add a new course with the same professor and their profile is already there.
• Syllabus profiler — upload a PDF, Claude extracts topics with professor weights, exam dates, and grade breakdowns. RAG-enriched before extraction.
• RAG over course materials — pgvector with OpenAI text-embedding-3-small (1536 dims). Keyword search fallback if no OpenAI key. Top-5 chunks injected into every tutor context.
• Inbox pipeline — upload files or notes → Haiku (+ vision) classifies tier, course, and due date → auto-triggers profiler (tier 1) and flashcard generation (tier 1–2).
• Persistent tutor memory — after a session ends, a single Haiku call distills it into a session summary, a rolling per-course digest, and typed facts (misconceptions, preferences, goals). The next session opens with a "welcome back — last time…" recap, and the misconceptions feed back into your study plan. Memory is viewable, deletable, and pausable in Settings.
• Wiki memory — the tutor and profiler also write durable insights to per-user markdown files (learning_profile.md, professor_*.md), loaded verbatim into every session.
• Grade tracker + "what do I need?" — a per-course gradebook (scheme auto-extracted from your syllabus, or synced from Canvas). Shows your current weighted grade and the answer to the real question — "I need 84% on the final for an A" — with secured/out-of-reach states.
• Semester standing — one honest verdict per course (on-track / at-risk / critical) composed from grade risk, exam readiness, overdue work, and study consistency, surfaced at the top of Progress.
• Mastery decay — knowledge you crammed and ignored decays over time (read-time, after a 7-day grace, 60-day half-life), so a stale high score resurfaces in your weak areas instead of lying to you.
• Prerequisite graph — the profiler links topics to what they build on; a weak prerequisite (mastery

🔌 Connect your own Claude (MCP)

Cogni ships a built-in Model Context Protocol server, so you can study through Claude Code or Claude Desktop using your own Claude subscription — and everything writes back to your account.

Generate a token in Settings → Connect your Claude, then claude mcp add the URL it shows. /mcp then exposes 14 tools and 4 prompts:

• Read — list_courses, get_course_overview (incl. your grade standing), get_weak_topics, search_materials, get_due_cards, get_learning_profile, get_study_plan, research (multi-query, cited)
• Write — review_card (FSRS + mastery), grade_answer, create_flashcards (paced), log_study_session (memory + streak), complete_assignment (replans), record_quiz_result
• Prompts — tutor, exam_prep, review_session, homework_help

Tokens are stored only as SHA-256 hashes with a 180-day expiry. Every call is guarded (fail-closed writes, per-day read/write quotas, ownership-validated) and audited.

⚙️ Architecture

Two-level spaced repetition. Each flashcard carries full FSRS state (stability, difficulty, reps, lapses, state, last_review, next_review_date). Topic mastery is a separate blended score updated on every review, quiz, and exam. The scheduler uses topic mastery to allocate session time; FSRS drives card-level scheduling independently.

Atomic review RPC. review_card_atomic() runs a single Postgres transaction that updates all FSRS fields on the flashcard and applies mastery evidence to topic_mastery (idempotent per rating tap via a client_review_id gate).

Unified mastery model (EWMA). Every source of evidence — flashcard reviews, quizzes, exams, tutor grading, and distilled conversation signals — updates topic mastery through one exponential moving average: next = old + learning_rate × (observed − old) (cold-start adopts the observed value; confidence rises +0.05 per event). Observed level by flashcard rating: Again = 0, Hard = 0.45, Good = 0.75, Easy = 1.0. Learning rates by source: tutorgrade 0.35, quizstandalone 0.6, quizinsession 0.3, exam 0.7, conversation 0.12, and flashcard_base 0.25 scaled by 1/√(cards in topic). The displayed score is no longer path-order-dependent.

Scheduler priority formula.

priority = (deficit) × professor_weight × examProximityMultiplier × gradeRiskBoost × prereqBoost

where deficit = professor_weight − effectiveMastery (+0.15 if the topic has a recently-recorded misconception), prereqBoost = 1.3× for a weak prerequisite (mastery 30 days = 1×, >14 = 1.5×, >7 = 2×, >3 = 3×, ≤3 = 5×; a grade-weight multiplier scales by the upcoming exam's share of the final grade. Mastery is read as time-decayed effectiveMastery. Session minutes are allocated proportionally across courses, capped at 4 review blocks/day.

Karpathy wiki pattern. The tutor has a write_wiki_pattern tool that writes markdown to per-user files in Supabase Storage. The profiler writes professor_*.md on every syllabus upload. All wiki files are loaded verbatim into tutor session context on every request — no vector retrieval, just direct inject.

Streaming tutor with native web search. Anthropic Messages API with streaming. Tools: create_flashcards, create_quiz, create_chart, open_essay_mode, grade_answer, suggest_edit, write_wiki_pattern. Real-time web lookup via Anthropic's native web_search_20250305 tool. Markdown answers render LaTeX (KaTeX) and Mermaid diagrams.

RAG pipeline. OpenAI text-embedding-3-small (1536 dims) stored in pgvector with an IVFFlat index. Chunks: 3200 chars, 400-char overlap, split on paragraph/sentence boundaries. Retrieval: top-5 chunks per query, course-scoped. Falls back to LIKE keyword search if no OpenAI key is present.

Inbox classification pipeline. Upload → Haiku (+ vision for PDFs/images) classifies tier (1 = syllabus, 2 = primary, 3 = supplementary, 4 = misc), course, homework status, and due date → triggers profiler for tier-1 materials → triggers flashcard generation for tier-1 and tier-2 materials with fewer than 5 existing cards per topic.

Persistent memory system. ~45 minutes after a session's last message (or lazily on next open), a single Haiku call distills the transcript into a session_summaries row, a rolling course_memory digest (≤3200 chars), and typed student_memory facts. Recorded misconceptions feed the scheduler; the digest is injected into the next session's prompt and surfaced as a recap. Long histories are compacted (cached brief + last 12 verbatim) so the first token is never gated by summarization.

Mastery decay. Mastery is stored as a unified EWMA evidence score, but read everywhere through effectiveMastery = score · exp(−ln2 · (days − 7) / 60) after a 7-day grace — so the scheduler, weak-areas, readiness, and MCP all reflect what you know now, not what you crammed weeks ago.

Durable job substrate. Profiling, embedding, flashcard generation, and memory distillation run as rows in a jobs table claimed via FOR UPDATE SKIP LOCKED (with an expired-lock reaper). Post-response draining (after()) keeps uploads and onboarding fast; a daily cron sweeps anything left.

Grade math. Per-course weighted grade with points-proportional remaining weight, so the "what do I need on the final?" projection works even with a pending final inside an already-graded category. The grade-risk signal feeds the scheduler (priority boost), the daily insight, the tutor's context, and the semester-standing verdict.

Prompt caching. Up to four cache breakpoints (tools, static system, RAG block, last user message) cut repeat-context cost; a per-surface usage ledger estimates spend and cache savings.

🛠️ Tech Stack

| Layer | Tech | |-------|------| | Framework | Next.js 16, React 19, TypeScript 5 | | Database | Supabase (PostgreSQL + pgvector + Auth + Storage) | | AI — reasoning | Claude Sonnet 4.6 (tutor, profiler, exams, web enrichment) | | AI — deep thinking | Claude Opus 4.8 with extended thinking (tutor deep think mode) | | AI — lightweight | Claude Haiku 4.5 (flashcards, quizzes, inbox classification, session naming) | | AI — embeddings | OpenAI text-embedding-3-small (optional; enables RAG) | | MCP server | @modelcontextprotocol/sdk (bring-your-own-Claude: 14 tools, 4 prompts) | | Spaced repetition | ts-fsrs 5.3.2 | | Styling | Tailwind CSS 4, shadcn/ui | | Animation | Framer Motion | | Charts | Recharts | | Rich text | TipTap | | Math rendering | KaTeX | | Diagrams | Mermaid | | Icons | Phosphor Icons | | File export | @react-pdf/renderer, docx |

🚀 Setup / Deployment

> Setup takes ~30–45 minutes. You'll need a Supabase account and a Vercel account. The steps below cover a quick single-user self-host; for production multi-tenant hosting, follow [DEPLOYMENT.md](DEPLOYMENT.md) (see [Production / multi-tenant hosting](#-production--multi-tenant-hosting)).

Step 1 — Fork and deploy

[](https://vercel.com/new/clone?repository-url=https://github.com/arshawnarbabi/Cogni)

Fork the repo and deploy to Vercel, or run locally with npm run dev. Vercel Hobby (free) is sufficient — Fluid Compute gives crons a 300s duration and 100 crons per project, so you don't need Pro to run the daily scheduler.

Step 2 — Supabase project

Create a new Supabase project, then enable the Vault extension (Dashboard → Database → Extensions → supabase_vault) — it stores your API keys and calendar tokens. Then set up the database:

• Fresh install: paste [supabase/setup.sql](supabase/setup.sql) into the SQL editor and run it once. It bundles every migration (through v2.1.0) in the correct order and is idempotent, so it's safe to re-run.
• Upgrading (from v1.3.x or v2.0.0): run [supabase/big-update.sql](supabase/big-update.sql) once — it adds everything through v2.1.0 (memory, MCP tokens, grades, Canvas, jobs, semester data, plus the v2.1.0 RLS lockdown and race-safety constraints) and is self-contained + idempotent. setup.sql and old-prod + big-update.sql produce a byte-identical schema.
• Manual: run the individual files in the order in [supabase/README.md](supabase/README.md).

Step 3 — Environment variables

Add these to your Vercel project settings (or .env.local for local dev):

| Variable | Required | Description | |----------|----------|-------------| | NEXT_PUBLIC_SUPABASE_URL | ✅ | Supabase project URL | | NEXT_PUBLIC_SUPABASE_ANON_KEY | ✅ | Supabase anon key | | SUPABASE_SERVICE_ROLE_KEY | ✅ | Supabase service role key | | CRON_SECRET | ✅ | Long random secret used by Vercel cron endpoints | | NEXT_PUBLIC_APP_URL | ✅ | Your deployment URL (e.g. https://your-app.vercel.app) | | GOOGLE_CALENDAR_CLIENT_ID | Optional | Google Cloud Console — Calendar OAuth | | GOOGLE_CALENDAR_CLIENT_SECRET | Optional | Google Cloud Console — Calendar OAu

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: arshawnarbabi
• Source: arshawnarbabi/Cogni
• License: MIT
• Homepage: https://trycogni.arshawnarbabi.com/

Install and usage instructions live in the source repository linked above.