Memorium

Content apps give a class a syllabus. Supermemory gives it a memory. Memorium gives the teacher a plan.

Memorium is a Supermemory-powered classroom memory layer. It gives every student an isolated long-term memory, an adaptive mastery graph, a personal recall surface, and a report card. It also gives the teacher a class-level memory map that reads across all students, identifies the next concept to teach, and turns class-wide gaps into assigned interventions.

Most tools stop at showing you the gaps. This one reasons over the class memory and makes the pedagogical decision:

Instead of "the class is failing recursion," Memorium says: "This week, teach functions. The class is failing recursion the hardest, but they are not ready for it yet. Functions is the foundation that unblocks it, and it opens up thirteen more concepts."

---

Table of Contents

• Core Idea
• Key Features
• Classroom Modes
• Mastery & Pedagogical Mechanics
• System Architecture
• Getting Started
• Verification & Testing
• Project Directory Structure

---

Core Idea

Most education software stores static content. Memorium stores dynamic learning state.

A teacher does not merely need another quiz or chatbot. A teacher needs to know:

• What each student has mastered and what they are starting to forget.
• What each student is ready to learn next based on prerequisite readiness.
• What the whole class is stuck on, and why.
• Which students need targeted review, and the exact conceptual reason behind recommendation plans.

Why a Graph, Not a Vector Database?

A vector database only knows that two concepts are similar. However, learning depends on a different relationship: "concept B requires concept A".

“Recursion requires functions” is not a similarity relationship; it is a directed prerequisite edge. Memorium utilizes Supermemory Local to construct a real knowledge graph from plain relationship sentences. When seeding student memories, Supermemory extracts the prerequisite rules as explicit graph edges. This allows semantic recall queries (e.g. "what must I learn before decorators?") to return exact prerequisite chains by walking the graph rather than executing simple vector similarity searches.

---

Key Features

Student Experience

• Adaptive Quiz Console: Select an enrolled student and answer questions that walk their concept frontier.
• Mastery Graph: Visualize cognitive state dynamically with vis-network. Nodes grow larger as mastery increases, colored dynamically by mastery bands (Red = Gap, Amber = Learning, Green = Mastered, Brown = Rusty).
• Reset View Controls: Easily reset filters, search queries, and physics layout parameters (gravity, spring tension) back to default settings with a single click.
• Personal Ask Box: Type questions (e.g. explain closures to me) to query the student's own RAG-backed cloud memory dataset.
• Timeline & Memory Inspection: Check the student's practice timeline, cloud memory state, and RAG traces.
• Automated Study Guides & Report Cards: Synthesize custom learning guides from past incorrect attempts and generate progress summaries.

Teacher Experience

• Class Heat Map: Inspect class-average mastery across all concepts.
• Graph-Reasoned Teaching Plan: View prioritized concepts the class is ready to learn next, ranked by conceptual utility and unlock value.
• Class-Level RAG Search: Ask multi-student queries (e.g. who has mastered recursion?) to query class state.
• Review Interventions: Instantly assign targeted reviews to all students marked red or rusty on any given concept.
• Roster & Class Setup: Register a list of student names in one bulk action.

---

Classroom Modes

The project supports two modes configured in the environment:

• demo Mode (Default): Runs entirely offline and locally with zero dependencies. It manages all state locally and seeds the database with mock student profiles (Alice, Bob, Cara).
• cloud Mode: Integrates with the running Supermemory Local (or Cloud) server. It pushes learning traces, creates student datasets, and powers the RAG ask boxes with multi-tenant cloud storage.

---

Mastery & Pedagogical Mechanics

1. Mastery Score Calculation

Every concept starts with a baseline weight of 0.2 (Red). Quiz answers update weights exponentially:

• Correct Answer: $w_{\text{new}} = w + 0.35 \times (1 - w)$
• Incorrect Answer: $w_{\text{new}} = w - 0.15 \times w$

Weight Range	Band (Color)	Meaning
< 0.35	Red	Gap (unlearned)
0.35 to 0.75	Amber	Learning (in progress)
> 0.75	Green	Mastered

• Forgetting Decay ("Rusty" Flag): If a student has not practiced a mastered concept for over 14 days, it is flagged as Rusty (Amber border) in the UI.

2. Quiz Frontier Engine

The quiz walks the prerequisite graph to identify the student's frontier:

1. Ignores retired and mastered concepts.
2. Only includes concepts whose prerequisites are all at least Amber (weight $\ge 0.35$).
3. Prioritizes strengthening existing Amber concepts before introducing new Red concepts.

3. Graph-Reasoned Pedagogy (Teacher Plan)

Instead of recommending lessons purely based on high failure rates, the teacher copilot ranks topics by their prerequisite readiness and downstream value:

$$ \text{Score} = \text{Count}(\text{Ready students}) \times (1 + \text{Count}(\text{Downstream concept unlocks})) $$

---

System Architecture

Browser SPA (HTML/CSS/Vanilla JS)
  ├── vis-network (Dynamic Mastery Graphs)
  └── Lucide Icons (Visual controls)
       │
       ▼ REST / JSON API (Port 8002)
FastAPI Backend (app.py)
  ├── SQLite Ledger (ledger.py: local persistence of weights, students, & plans)
  └── Classroom Provider Factory (providers.py)
       ├── DemoProvider (offline mock database)
       └── CloudProvider (Supermemory Local client via http/JSON API)
            │
            ▼ REST API (Port 6767)
Supermemory Local Server
  ├── student_<student_id> (Private student datasets)
  ├── class_graph (Combined class heat map dataset)
  └── class_interventions (Teacher assigned reviews)

---

Getting Started

Prerequisites

• Python 3.11+
• FastAPI, Uvicorn, and HTTPX installed in your Python environment.
• A local Supermemory Local instance (for cloud mode).

Step 1: Start Supermemory Local

To run the local embeddings and graph memory engine:

npx supermemory@latest local

Note: This starts the server on http://localhost:6767 and configures local embeddings.

Step 2: Configure Environment

Create a .env file in the root directory:

CLASSROOM_MODE=local
SUPERMEMORY_API_URL=http://localhost:6767
SUPERMEMORY_API_KEY=sm_... # Leave blank for local unauthenticated dev

Step 3: Run the Backend Server

cd backend
python -m uvicorn app:app --port 8002 --host 127.0.0.1

Step 4: Open the Web UI

Open your browser and navigate to:

http://localhost:8002

---

Verification & Testing

Product Logic Smoke Test

To validate the offline curriculum parsing, quiz progression, decay mechanics, and intervention loops:

python backend/test_demo.py

Live Supermemory Local Verification

To run a complete end-to-end lifecycle check against your active local Supermemory server (serve, remember, recall, and forget):

python backend/verify_cloud.py

---

Project Directory Structure

• backend/app.py: Exposes endpoints for the SPA.
• backend/providers.py: Classroom provider interface, DemoProvider, and CloudProvider.
• backend/ledger.py: Handles SQLite storage.
• curriculum/python.json: Default Python prerequisite curriculum database.
• frontend/index.html: Main SPA html structure.
• frontend/app.js: Frontend state management, Vis.js rendering, and event listeners.
• frontend/style.css: Layout styling and animations.