README.md

Claude can explain anything. Engram makes sure you still know it next month.

claude plugin marketplace add nagisanzenin/engram
claude plugin install engram@engram

Then, inside Claude Code:

/learn kalman filters        ← or music theory, or Rust lifetimes, or anything

That's the whole onboarding. No config, no account, no cards to write. Requires python3 (stock macOS/Linux one is fine — stdlib only).

On OpenAI Codex? Engram is an omni-repo — the same skills and engine run there too (codex plugin marketplace add nagisanzenin/engram). See INSTALL-CODEX.md.

Wait — what is this?

You already ask Claude to explain things. It explains beautifully. You nod, you feel smart, and ten days later it's gone — because a chat has no memory of you, no test of whether you really got it, and no plan for the forgetting that starts the moment you close the terminal.

Engram is what's missing around the explanation: a tutor that makes you do the thinking, an examiner that checks you actually got it, and a scheduler that brings each idea back right before your brain drops it.

Concretely, installing it gives you: three slash commands (/learn, /review, /coach), a quiet session hook that tells you when reviews are due (and says nothing otherwise), and a state folder at ~/.claude/learning/ that you own and can read.

 recall
 100% ─┐ just reading                100% ─┐ with engram
       │\                                  │\      ●╌╌╌●╌╌╌╌╌●╌╌╌╌╌╌╌●╌╌
       │ \                                 │ \    ╱    ╲╱      ╲╱
       │  \__                              │  ●──╱
       │     \____                         │
       │          \_______                 │   each ● = a 2–4 minute /review,
   0% ─┴──────────────────── day 30    0% ─┴─  booked just before you'd forget

The loop

  YOU ──→  /learn transformers
            │
            ▼
  ┌────────────────────────────────────────────────────────────────┐
  │  CURRICULUM ARCHITECT                                          │
  │  breaks the topic into a first-principles concept map:         │
  │  "what must be understood before what" — never chapter order.  │
  │  flags the few THRESHOLD concepts † that unlock everything.    │
  └────────────────────────────────────────────────────────────────┘
            │
            ▼
  ┌────────────────────────────────────────────────────────────────┐
  │  THE TUTOR  (your normal Claude chat, under strict rules)      │
  │                                                                │
  │  per concept:  open a question → you PREDICT → struggle a      │
  │  little (hints, not answers) → resolve → you EXPLAIN IT BACK   │
  │                                                                │
  │  threshold concepts get a generated interactive HTML           │
  │  explorable — sliders and prediction gates, not more text.     │
  └────────────────────────────────────────────────────────────────┘
            │   your answers, verbatim (crash-safe stash on disk)
            ▼
  ┌────────────────────────────────────────────────────────────────┐
  │  THE ASSESSOR  (separate agent — grades blind)                 │
  │  sees only the rubric and your words, never the lesson.        │
  │  every grade becomes a receipt on disk. no receipts,           │
  │  no mastery claim.                                             │
  └────────────────────────────────────────────────────────────────┘
            │   receipts
            ▼
  ┌────────────────────────────────────────────────────────────────┐
  │  THE SCHEDULER  (engram.py — deterministic code, not vibes)    │
  │  FSRS-4.5 fits your personal forgetting curves and books       │
  │  each concept's next review just before you'd lose it.         │
  └────────────────────────────────────────────────────────────────┘
            │
            ▼
  next session:  [engram] 6 reviews due (transformers: 6) · ~4 min
                     │
                     ├──→  /review   2–4 minutes of free recall
                     └──→  /coach    weekly: stats · dashboard · tuning

A real session, condensed

From the first live topic taught with Engram (transformer internals). Note who does the thinking:

◆ node 6/13 · nonlinearity-necessity †

engram   Delete σ for a second. The FFN is now just W₂·(W₁·x).
         What is W₂·W₁ — and what has the two-layer FFN collapsed into?

you      i dont know really

engram   Fine — that's a commitment. Forget matrices. W₁ = "×2",
         W₂ = "×3". Run a number through both, nothing in between.
         Two steps of computation… or secretly one?

you      basically 2x3

engram   That's the whole secret, and you just said it. ×2 then ×3 = ×6:
         two linear layers fuse into ONE. Fifty of them? Still one matrix.
         Depth means nothing until a nonlinearity blocks the fuse —
         and that's why σ is not optional.

At session end, the assessor — which never saw that dialogue — graded the learner's six answers: 1 recalled · 4 partial · 1 first-retrieval, while the tutor was convinced the session went great. The schedule believed the assessor. That separation is the point: your future reviews are built on verified evidence, not on the tutor's enthusiasm (or yours).

Three commands, one habit

Everything else is ambient: the session hook nudges when reviews are due and is silent otherwise.

Why it works (the science, in one breath)

Engram implements the four most-replicated findings in learning science — and deliberately skips the popular myths (no "learning styles"; that theory failed every controlled test):

1. Structure — knowledge is a graph, so topics are decomposed by chains of necessity ("why must this be true?"), never by chapter order.
2. Generation — the mind keeps what it makes. You predict, attempt, and explain back before being told. Even failed attempts measurably improve what sticks next (the pretesting effect).
3. Retention — testing is the learning (not the measurement of it), and spacing beats bingeing. Free recall on an FSRS schedule fitted to your own review history.
4. Honest adaptation — it adapts from your measured retention, calibration, and error patterns. Confidence is only recorded when you actually state it; grades only exist as written receipts.
5. Motivation & wisdom, honestly — it makes your real competence growth visible at the moment it happens (the memory that now lasts 4× longer — not points or streaks, which backfire on motivated adults), and it carries you through the hard part: struggle named as encoding, lapses absolved not pitied, backlogs met with amnesty. Two new layers, every claim adversarially verified against the primary source — docs/05-affective-layers.md.
6. Visuals that earn their keep (v0.5) — interactive explorables are built when the content rewards manipulation (a parameter to drag, a process that unfolds — declared per concept by the curriculum architect, never inferred from a "visual learner" label), always wrapped in predict → act → explain guidance, because the guidance is what carries the effect (scaffolded simulations beat identical unscaffolded ones, g+ = 0.60). You choose the eagerness (visuals eager|threshold|off), and your own review receipts then measure whether the medium actually holds better for you — docs/06-visual-encoding.md.

What it looks like

Your mastery map, any time (/learn shows it, /coach renders the full dashboard):

transformers — Transformers from first principles
██▒▒▒▒▒▒▒▒▒▒▒░░░░░░░░░░░  1 retained · 6 learning · 6 untouched

● contextual-meaning        due 2026-07-09   S=3.7d
◐ residual-stream        †  due 2026-07-06   S=1.4d
◐ nonlinearity-necessity †  due 2026-07-06   S=1.4d
· depth-necessity        †  due —            S=—

Interactive explorables — self-contained HTML with prediction gates (content stays locked until you commit a guess), guided manipulable models, and embedded retrieval prompts. Built for threshold concepts by default; set visuals eager and they're also built whenever a concept's own structure rewards manipulation (the curriculum architect declares this per node — features you can drag, processes that unfold); or just ask mid-lesson: "make it visual." A local HTML dashboard (/coach dashboard) with per-topic maps, retention-by-strength bars vs. the 85% target band, honest calibration, an encoding-medium comparison (do explorable-encoded concepts hold better for you? — your own receipts answer), and your next-7-days forecast. Both live in ~/.claude/learning/artifacts/ — no network, ever.

FAQ

How is this different from just asking Claude to explain? Asking produces understanding; understanding decays on the same curve as everything else. Engram adds the three things a chat can't: verification (did you actually get it?), memory across sessions (a learner model in files, not context), and a future (every concept has a scheduled next encounter). The explanation is the easy 20%.

Is this Anki? Anki schedules cards you write and grades yourself. Engram teaches the material, writes the assessment from the dialogue, grades it blind, and schedules concepts on the same family of algorithm (FSRS) — with an actual tutor attached. If you love Anki, think: Anki where the deck builds itself from a Socratic lesson and the grader isn't you.

Non-code topics? Yes — the engine doesn't care. History, music theory, statistics, anatomy (it routes memorization-heavy content to mnemonics instead of derivation-theater).

What if I just want the answer? Say "just tell me" — it complies immediately, no lecture. It also quietly schedules that concept for earlier review, because told-not-derived decays faster. Your call, honestly priced.

I'm a visual learner — will it build me visuals? Careful — two different things are true. "Visual learner" as a learning style is a debunked theory (matching instruction to a diagnosed style has failed every controlled test), so Engram will never route content by that label. But interactive visuals as a medium are real and measured — strongest exactly when the concept itself is manipulable (a parameter to drag, a process that unfolds) and when the interaction is guided, which is how Engram builds them. So: the content decides what qualifies (each concept carries a declared visual affordance), you decide the eagerness — say "build visuals eagerly" or run python3 scripts/engram.py visuals eager (or threshold/off; you can also just ask "make it visual" on any concept mid-lesson) — and then your own review receipts quietly measure whether explorable-encoded concepts actually hold better for you. /coach shows the verdict with honest sample sizes. Preference honored, evidence in charge: docs/06-visual-encoding.md.

I have ADHD / I keep getting bored and quitting — is there a mode for that? Yes: an opt-in Focus profile. It doesn't add a game — no XP, streaks, or badges (the evidence says those backfire on motivated adults; see docs/05). It turns up dials Engram already has: one node per session so you can't drift, your real memory-growth surfaced every review ("this now lasts ~4× longer" — a true stability number, not points), and amnesty whenever you return to a backlog instead of a guilt pile. Two ways to switch it, whichever you like:

• Just say so in /learn or /coach — "I have ADHD, turn on focus mode."
• Run it yourself: python3 scripts/engram.py focus on (or off, or status).

It's stored as a declared need in your learner model, honored across all three commands — not a "learning style" (Engram rejects those). Works for anyone who wants it; ADHD just gets the intensity. Full rationale and evidence: docs/05-affective-layers.md.

Where's my data? ~/.claude/learning/ — learner model, concept graphs, grade receipts, misconception log, artifacts. Human-readable JSON. Your learning state never leaves your machine: the engine (engram.py) is stdlib-only with no network code, and the dashboard is a local file. The one exception is the curriculum architect, which uses web search on the topic and goal you give it when building a new map — so keep secrets out of the goal line, or ask for an offline map. (Override the location with ENGRAM_HOME.)

Why does it keep testing me? Because retrieval is the treatment, not the measurement. A century of memory research in four words: testing is the learning.

.claude-plugin/     plugin.json, marketplace.json          (Claude Code)
.codex-plugin/      plugin.json                            (Codex)
.agents/plugins/    marketplace.json                       (Codex marketplace)
skills/             learn / review / coach  (+ _shared: dialogue grammar, Explorable Contract)
agents/             engram-curriculum-architect · engram-assessor · engram-artifact-smith  (Claude Code)
codex/agents/       *.toml ports of the three subagents     (Codex)
hooks/              SessionStart re-anchor (self-resolving; silent when nothing is due)
scripts/engram.py   deterministic core: FSRS-4.5, state, receipts, stats, dashboard, selftest
docs/               theory · prior art · architecture · roadmap  ·  INSTALL-CODEX.md

Documents

More from the same workshop

Five Claude Code plugins from the same workshop. Most share one habit: let a deterministic core decide, and never let the producer of work grade it.

• effortmining — benchmark-calibrated per-subagent reasoning effort: dispatch the cheapest tier a blind grader still accepts. ~64.7% fewer output tokens at equal quality, pre-registered.
• idiolect — human-voice writing engine: 60+ measured voices plus a deterministic AI-tell scanner and a blind auditor, so text reads like a person, not a model.
• production-grade — turns "build me X" into a gated multi-agent pipeline (architecture → tests → security → CI/CD) with a receipt for every phase. Engram's verification patterns started here.
• less — a minimal comms protocol for Claude: a per-turn hook makes replies answer-first, pick-list-driven, and calm, without touching the work.

Stars

If Engram earned its keep, a star helps the next person find it.

_{GitHub restricted the stargazer-timeline API to repo collaborators, so the live history chart no longer renders inline. Click the badge for the interactive graph.}

_{An engram is the physical trace a memory leaves in neural tissue (Semon, 1904; experimentally located by Josselyn, Tonegawa et al. in the 2010s). Building durable ones is literally this plugin's job. · MIT license · changelog}