Marginalia: An Open-Source AI Tool Framework for Educational Scenarios

Marginalia is a self-hostable open-source AI tool framework for educational scenarios. Its core concept is to guide students to use large language models responsibly through social contracts rather than monitoring mechanisms. Built on technologies like Cloudflare Workers, D1, R2, and Vectorize, its goal is to make AI a clear and honest part of course assignments and rebuild trust between teachers and students in AI.

Current discussions on AI entering classrooms mostly focus on monitoring methods (such as detectors and blocking mechanisms). Marginalia takes the opposite approach: relying on social contracts, teachers set tools for specific purposes, the tools clearly inform students of their identity and behavior patterns, and students use them with full knowledge. The core goal is to establish a healthy AI usage culture, making AI a teaching partner rather than a monitoring object.

Marginalia provides three types of tools for teachers:

1. AI Tutoring Assistants (Agents)：Customizable conversation styles, supporting outline mode (state machine enforces conversation flow instead of relying on system prompts);
2. Traceable Knowledge Base (Sources)：Generates answers with citations based on document libraries selected by teachers, fostering students' awareness of information traceability;
3. Provenance Tracking for Writing：Marks the source of written content (manual input, pasted, or AI-generated) to ensure transparency.

Uses Cloudflare's native tech stack: Workers (serverless computing), D1 (SQLite database), R2 (object storage), Vectorize (vector database), Workers AI (inference service), with TypeScript as the programming language. The monthly operating cost for a 30-student course is approximately $5-15 (excluding LLM API call fees), which is highly cost-effective.

Marginalia supports independent deployment by institutions, with no callback mechanism or shared backend, requiring users to prepare their own API keys. Deployment steps include: configuring Workers, creating Cloudflare resources (D1/R2/Vectorize), setting up keys (Anthropic API, etc.), configuring Google OAuth, database migration and deployment, logging in to create courses. Local development can be completed by copying sample files, configuring keys, running migrations, and starting the service.

Privacy design highlights: no centralized backend, no data sharing, transparent instructions before tool use, no hidden monitoring. The v1.0 version supports multi-course management; teachers can see a course selector upon login, students directly access registered courses, and efficient management is achieved through cross-course agent reuse mechanisms.

Educational significance: Provides new ideas for AI education tools, replacing technical restrictions with transparency and trust, and serving as a reference for the educational technology field. In terms of open source, it uses the Apache 2.0 license; maintainers keep the design streamlined, welcome community PRs, and ensure the project's sustainable development.