{"id":31160203,"url":"https://github.com/sderosiaux/oblivian","last_synced_at":"2026-05-06T02:33:40.737Z","repository":{"id":313707731,"uuid":"1052349439","full_name":"sderosiaux/oblivian","owner":"sderosiaux","description":"🧠 AI-Powered Spaced Repetition Learning App with Claude Desktop Integration","archived":false,"fork":false,"pushed_at":"2025-09-08T01:01:59.000Z","size":154,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-08T01:12:11.011Z","etag":null,"topics":["ai","claude-desktop","education","flashcards","fsrs","learning","mcp","nextjs","spaced-repetition","sqlite","study-tool","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sderosiaux.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-07T22:58:25.000Z","updated_at":"2025-09-08T01:02:02.000Z","dependencies_parsed_at":"2025-09-08T01:12:44.325Z","dependency_job_id":"03e3caa5-4b5d-43dd-b4d5-8e2eac88667e","html_url":"https://github.com/sderosiaux/oblivian","commit_stats":null,"previous_names":["sderosiaux/oblivian"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/sderosiaux/oblivian","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sderosiaux%2Foblivian","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sderosiaux%2Foblivian/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sderosiaux%2Foblivian/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sderosiaux%2Foblivian/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sderosiaux","download_url":"https://codeload.github.com/sderosiaux/oblivian/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sderosiaux%2Foblivian/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275867762,"owners_count":25542811,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-19T02:00:09.700Z","response_time":108,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-desktop","education","flashcards","fsrs","learning","mcp","nextjs","spaced-repetition","sqlite","study-tool","typescript"],"created_at":"2025-09-19T02:23:57.174Z","updated_at":"2026-05-06T02:33:40.717Z","avatar_url":"https://github.com/sderosiaux.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🧠 Oblivian - AI-Powered Spaced Repetition Learning\n\n\u003cdiv align=\"center\"\u003e\n\n![Next.js](https://img.shields.io/badge/Next.js-15-black?style=flat-square\u0026logo=next.js)\n![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue?style=flat-square\u0026logo=typescript)\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Neon-green?style=flat-square\u0026logo=postgresql)\n![MCP](https://img.shields.io/badge/MCP-Compatible-purple?style=flat-square)\n![Claude Desktop](https://img.shields.io/badge/Claude_Desktop-Ready-orange?style=flat-square)\n![License](https://img.shields.io/badge/License-MIT-green?style=flat-square)\n\n**Master any subject with AI-generated flashcards and scientifically-proven spaced repetition**\n\n[Live Demo](https://oblivian.vercel.app) • [Documentation](#-documentation) • [Getting Started](#-getting-started) • [Claude Desktop Integration](#-claude-desktop-integration)\n\n\u003c/div\u003e\n\n---\n\n## ✨ Features\n\n### 🎯 Core Learning Features\n- **FSRS Algorithm** - State-of-the-art spaced repetition scheduling for optimal memory retention\n- **Advanced Notes** - Add deeper insights and explanations to cards for comprehensive learning\n- **Multiple Card Types** - Basic, Cloze deletion, Multiple choice, and Explanation cards\n- **Smart Study Sessions** - Adaptive difficulty based on your performance with session timing\n- **Progress Tracking** - Visual analytics, learning streaks, and detailed statistics\n- **Deck Rankings** - Discover popular decks based on community usage\n\n### 🤖 AI Integration\n- **Claude Desktop MCP** - Generate high-quality flashcards using Claude's AI directly from your desktop\n- **API Token Authentication** - Secure token-based access for AI features\n- **Batch Card Generation** - Create up to 100 cards at once with AI assistance\n- **Smart Recommendations** - AI-powered similar deck suggestions using OpenAI embeddings stored in pgvector\n- **Natural Language Commands** - Create decks and cards with simple prompts\n\n### 🎨 Modern Design\n- **Beautiful UI** - Clean, minimalist interface inspired by Apple, Linear, and Stripe\n- **Responsive Design** - Optimized for desktop, tablet, and mobile devices\n- **Custom Theming** - Tailwind CSS v3 with custom design system\n- **Smooth Animations** - Polished interactions and transitions\n- **Professional Components** - Reusable, consistent UI components\n\n## 🚀 Getting Started\n\n### Prerequisites\n- Node.js 18+\n- npm or yarn\n- PostgreSQL database (we recommend [Neon](https://neon.tech))\n\n### Installation\n\n1. **Clone the repository**\n```bash\ngit clone https://github.com/sderosiaux/oblivian.git\ncd oblivian\n```\n\n2. **Install dependencies**\n```bash\nnpm install\n```\n\n3. **Set up environment variables**\n```bash\ncp .env.example .env.local\n```\n\nEdit `.env.local` with your configuration:\n```env\nDATABASE_URL=\"postgresql://...\"  # Your Neon PostgreSQL connection string\nJWT_SECRET=\"your-secret-key\"     # Generate a secure random string\n# Optional: configure OpenAI embeddings for deck similarity\nOPENAI_API_KEY=\"your-openai-api-key\"\nOPENAI_EMBEDDING_MODEL=\"text-embedding-3-small\"\nEMBEDDING_PROVIDER=\"openai\"\n```\n\n4. **Initialize the database**\n```bash\nnpm run db:push\n```\n\n5. **Start the development server**\n```bash\nnpm run dev\n```\n\nVisit `http://localhost:3000` to see your app running! 🎉\n\n### Deployment\n\nThe app is configured for automatic deployment on Vercel:\n\n1. Push to GitHub\n2. Connect your repository to Vercel\n3. Add environment variables in Vercel dashboard\n4. Deploy automatically on every push to main\n\n## 🤖 Claude Desktop Integration\n\nOblivian integrates with Claude Desktop using the Model Context Protocol (MCP) for AI-powered card generation.\n\n### Setup MCP\n\n1. **Create an API token** in the Settings page after logging in\n\n2. **Configure Claude Desktop** by adding to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"oblivian\": {\n      \"command\": \"/opt/homebrew/bin/npx\",\n      \"args\": [\n        \"-y\",\n        \"mcp-remote\",\n        \"https://oblivian.vercel.app/api/mcp\",\n        \"--header\",\n        \"Authorization: Bearer ${OBLIVIAN_TOKEN}\"\n      ],\n      \"env\": {\n        \"OBLIVIAN_TOKEN\": \"YOUR_API_TOKEN\"\n      }\n    }\n  }\n}\n```\n\nReplace `YOUR_API_TOKEN` with the token from Settings.\n\n3. **Restart Claude Desktop** and start generating cards with natural language:\n   - \"Create 20 flashcards about Python programming\"\n   - \"Generate cards for learning Spanish vocabulary with advanced notes\"\n   - \"Make a deck about World War II with explanations\"\n\n### MCP Tools Available\n- `list_decks` - View all your decks\n- `create_deck` - Create new decks with title, description, level, and language\n- `update_deck` - Update deck properties (title, description, level, language, visibility)\n- `delete_deck` - Delete a deck and all its cards\n- `create_cards_batch` - Generate multiple cards at once with advanced notes\n- `list_cards` - Browse cards in a deck\n- `update_card` - Edit a single card's content\n- `update_cards_batch` - Update multiple cards at once\n- `delete_card` - Remove a single card\n- `delete_cards_batch` - Delete multiple cards at once\n- `get_api_info` - Get information about the API connection\n\n## 📚 Documentation\n\n### Creating Cards\n\n#### Manual Creation\n1. Navigate to a deck\n2. Click \"Add Card\"\n3. Choose card type and enter content\n4. Add advanced notes for deeper insights\n5. Save and start studying\n\n#### AI Generation with Claude\n1. Configure Claude Desktop with MCP\n2. Ask Claude to create cards: \"Create flashcards about [topic] with advanced notes\"\n3. Cards are automatically added to your selected deck\n4. Review and edit as needed\n\n### Study Workflow\n1. Start a study session from any deck\n2. Review cards and expand advanced notes if needed\n3. Rate your recall (Again/Hard/Good/Easy)\n4. Cards are rescheduled based on FSRS algorithm\n5. Track your progress and maintain streaks\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [FSRS Algorithm](https://github.com/open-spaced-repetition/fsrs.js) - Advanced spaced repetition scheduling\n- [Claude Desktop](https://claude.ai) - AI-powered card generation\n- [Model Context Protocol](https://modelcontextprotocol.io) - MCP integration\n- [Neon](https://neon.tech) - Serverless PostgreSQL\n- [Next.js](https://nextjs.org) - The React framework\n- [Vercel](https://vercel.com) - Deployment and hosting\n- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework\n- [Drizzle ORM](https://orm.drizzle.team) - TypeScript ORM\n\n## 💖 Support\n\nIf you find Oblivian helpful, please consider:\n- ⭐ Starring this repository\n- 🐛 Reporting bugs and suggesting features\n- 📢 Sharing with friends and colleagues\n- 🤝 Contributing to the codebase\n\n---\n\n\u003cdiv align=\"center\"\u003e\nBuilt with ❤️ for learners everywhere\n\n[Live Demo](https://oblivian.vercel.app) • [Report Bug](https://github.com/sderosiaux/oblivian/issues) • [Request Feature](https://github.com/sderosiaux/oblivian/issues)\n\u003c/div\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsderosiaux%2Foblivian","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsderosiaux%2Foblivian","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsderosiaux%2Foblivian/lists"}