Learner Memory System

Learner Memory System is an AP Biology tutor built around a model of the person using it - a structured, inspectable record of what a learner understands and which misconceptions keep resurfacing.

The model is not a black box: every belief links to the message that produced it, the tutor reads a scoped slice before answering, and a dashboard shows beliefs forming and resolving next to the chat. One Next.js app over Postgres, two prompts total - a Memory Extractor and a Tutor. No vectors, no agent framework.

A competent tutor is one prompt and a chat box - an afternoon of work, and not the interesting part. The interesting part is memory that visibly changes what the tutor says next and that the learner can open and read.

Most chat "memory" is the transcript, which you cannot point at or reason over. So the design question was what a learner model should be if it has to be shown on a screen and defended: typed records with provenance, not retrieved text.

Memory is defined by what it is not: not chat history, but a small set of typed records - per-concept mastery signals and named misconceptions with a lifecycle - derived from the conversation and stored as queryable facts.

Two prompts, one per turn: an Extractor that returns a validated structured object, and a Tutor that reads a scoped slice of memory plus a short window of raw turns. Durable memory and the ephemeral window stay separate, which is what stops the design collapsing back into memory-as-transcript.

Deliberately not built, each for a stated reason:

• No vectors or embeddings - the concept space is closed, so extraction is classification into an enum.
• No BKT or IRT - mastery is a simple additive heuristic shown as buckets, not a decimal.
• No auth or multi-tenancy - one learner, with the seam named in future work rather than half-built.

Five tables; deliberately no snapshot table for current mastery. memory_events is append-only and the source of truth - one row per observation, a signed delta on a concept. concepts is a fixed 12-slug taxonomy from the AP Biology units, and the Extractor may only emit those slugs, enforced as a Zod enum.

Mastery is computed on read as a clamped sum of a concept's deltas around a 0.5 baseline. Zero events reads as UNKNOWN, distinct from events that net to 0.5. The tutor and dashboard never see the raw number - only four ordinal buckets, a view over the score, so changing a threshold changes the view and never the data.

Every event and misconception carries the id of the message that produced it. That one column powers both the "recent updates" feed and the "why does the AI believe this?" view - no beliefs from nowhere. Vitest covers the pure functions - derive, apply, scope, the extractor schema, the tutor's prompt assembly - without a live provider.

• Structured, inspectable learner model: per-concept mastery and named misconceptions
• Every belief traceable to the message that produced it
• Misconceptions with a lifecycle - active until the learner demonstrates understanding, then resolved on screen
• Tutor reads a scoped slice of memory, not the whole profile
• Dashboard feed of model changes, next to the chat

• The invariants that mattered ended up in the schema, not the prompt - a unique constraint made extraction idempotent, a partial index made resolution unambiguous.
• Provenance is a feature, not bookkeeping. Once every belief points at its cause, "why does the AI believe this?" becomes a query.
• Deciding what memory was not - transcript, embeddings, a snapshot - removed more work than any feature added.