The mix-up worth clearing first: Engram is not an agent-memory plugin.It doesn't give your agent persistent memory, context, or knowledge of your codebase β memory MCPs and context tools do that,for the agent. Engram points the other way:it's a learning system for the human.Your agent becomes a tutor that makes you do the thinking, a blind examiner that checks you actually got it, and a scheduler that brings each idea back right before your brain drops it. The agent doesn't get smarter.You do β measurably, with receipts.
Born as a Claude Code plugin; the same skills and engine now run on six agentic platforms β including, as of v1.0.8, one that puts the tutor in your chat app:
claude plugin marketplace add nagisanzenin/engram
claude plugin install engram@engram
| Platform | Install | Then |
|---|---|---|
| Claude Code (born here) | ||
| the two commands above | /learn /review /coach |
|
| OpenAI Codex | ||
codex plugin marketplace add nagisanzenin/engram then codex plugin add engram@engram β |
||
$learn $review $coach |
||
| OpenCode | ||
"plugin": ["opencode-engram-learning"] in opencode.json ( |
||
/learn /review /coach |
||
| Hermes Agent | ||
clone + skills.external_dirs β |
||
/skill learn (or /study ) /review /coach |
||
| Google Antigravity | ||
agy plugin install https://github.com/nagisanzenin/engram |
||
/learn /review /coach |
||
| OpenClaw | ||
openclaw plugins install engram --marketplace nagisanzenin/engram β |
||
/learn /review /coach |
OpenCode: opencode.json is read globally (~/.config/opencode/opencode.json) or per-project; pin to source instead of npm with "plugin": ["git+https://github.com/nagisanzenin/engram.git"].
Antigravity: The due-review session nudge isn't ported yet, and the
architect
and smith
subagents are currently dropped by AG 1.1.4's strict installer. Everything else works the same.OpenClaw: the nudge needs
openclaw config set hooks.internal.enabled true
(OpenClaw ignores plugin hooks until internal hooks are switched on), and it fires on /new
and /reset
rather than every session. Engram's agents aren't registered β the skills spawn them through sessions_spawn
with isolated context instead, which keeps the assessor blind. Details in INSTALL-OPENCLAW.md.Then, inside your coding assistant (command spelling per your platform's row above):
/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). One state folder, every platform: learn in one tool, review in another, same schedule.
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.
Engram is | Engram is not | |---|---| a learning system for the human β you end up knowing things | agent memory β tools that persist what the agent knows (different job entirely) | a tutor that makes you produce answers before it explains | a chatbot that explains while you nod along | | a memory system β every concept gets a future review date | notes and summaries you'll never reopen | | an independent examiner that grades you blind, in writing | self-assessed "yeah, makes sense" | | plain JSON files on your machine | a cloud service, account, or subscription |
Concretely, installing it gives you: three commands (/learn
, /review
, /coach
β exact spelling per platform in the table above), a quiet session nudge that tells you when reviews are due (and says nothing otherwise β on every platform except Antigravity, whose hook port is pending; on OpenClaw it needs one config flag and fires on /new
), and a state folder at ~/.claude/learning/
that you own, can read, and share across every platform you use.
recall
100% ββ just reading 100% ββ with engram
β\ β\ βββββββββββββββββββββ
β \ β \ β± β²β± β²β±
β \__ β ββββ±
β \____ β
β \_______ β each β = a 2β4 minute /review,
0% ββ΄ββββββββββββββββββββ day 30 0% ββ΄β booked just before you'd forget
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
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).
| Command | What happens | Time |
|---|---|---|
/learn <topic> |
||
| Intake (your goal, your background) β concept map β pretest β generation-first teaching β blind grading β everything scheduled | 5β60 min, you pick | |
/review |
||
| Due concepts, free recall, interleaved across topics. The habit that makes it all permanent | 2β4 min | |
/coach |
||
| Retention stats, calibration, local HTML dashboard, schedule tuning, n-of-1 experiments | weekly-ish |
Everything else is ambient: the session hook nudges when reviews are due and is silent otherwise.
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):
Structureβ knowledge is a graph, so topics are decomposed bychains of necessity("why must this be true?"), never by chapter order. -
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). -
Retentionβ testingisthe learning (not the measurement of it), and spacing beats bingeing. Free recall on an FSRS schedule fitted to your own review history. -
Honest adaptationβ it adapts from yourmeasuredretention, calibration, and error patterns. Confidence is only recorded when you actually state it; grades only exist as written receipts. -
Motivation & wisdom, honestlyβ it makes yourrealcompetence 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. -
Visuals that earn their keep(v0.5) β interactive explorables are built when thecontentrewards 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 betterfor youβdocs/06-visual-encoding.md. -
Procedures are practiced, not recited(v1.1) β some knowledge is askill executed on instances(an integral, agit rebase
, a statistical-test choice β any domain, declared per node by the content, never by a topic label). Those nodes enter by theworked-example ladder(study β complete β faded β solve; examples first is the best-replicated novice result in math, g β 0.44) and are reviewed bysolving a fresh variantβ new numbers, same structure β next to the problems they're confused with, because practice format must match use format (transfer d = 0.58 congruent vs 0.28 not). Solutions are step-graded with the arithmeticverified by execution, and a slip is priced gentler than a wrong method. Engram stays a general learn-anything system; this layer wakes only where the content is a skill βdocs/11-the-procedure-gap.md. - The session doesn't end on a failed retrieval(v1.5) β when a concept comes back wrong, Engram re-derives it, puts something else in between, and asks again, to** onecorrect recall. Then it guarantees thedose: the first two intervals after encoding are capped so at least three spaced sessions land inside the first month. This is the largest effect in the whole evidence base β one correct recall in each of three spaced sessions beats three crammed into one68% vs 26%** at a week (the honest exposure-controlled size is d β 0.7) β and it buys durability ofthe practiced item, not transfer, which is exactly what it claims.docs/13Β§2.5 - It fits your memory, and refuses to pretend(v1.6) β the schedule's parameters are fitted from your own reviews (initial stability at 64 usable reviews, the full vector at 400), anda fit that doesn't beat your current one is refused rather than shipped. The workload/retention trade-off is drawn for you and never recommended: Anki, with the largest review dataset in existence, removed its own auto-recommendation, and Engram's receipts carry no per-review durations to price the trade honestly. - It adapts β on receipts, with your consent, in writing(v1.8, Article 12) β every change thesystemsuggests is computed from your evidence, offered with that evidence quoted, applied only on a yes, logged to an append-only ledger, and reversible. The families it may steer on areclosed: assistance level from demonstrated prior knowledge (the one aptitude-treatment interaction that survived its literature), scheduling from fitted forgetting, one specific fading metacognitive prompt, and small real choices. Styles, traits, personality and time-of-day stay dead βa system that adapts to you is one hallucinated correlation away from a horoscope, and the ledger is what keeps the difference visible.
Citations & full theory (for the skeptical β click)
The load-bearing evidence: retrieval practice (Roediger & Karpicke 2006; Karpicke & Blunt 2011, Science; Dunlosky et al. 2013 "high utility"), distributed practice (Cepeda et al. 2006; Rawson & Dunlosky 2011), desirable difficulties & the fluency illusion (Bjork 1994; Koriat & Bjork 2005), pretesting (Richland, Kornell & Kao 2009), the ~85% difficulty sweet spot (Wilson et al. 2019), self-explanation & ICAP (Chi et al. 1994; Chi & Wylie 2014), multimedia principles behind the explorables (Mayer; Paivio), step-level tutoring β human tutors (VanLehn 2011), FSRS scheduling (open-spaced-repetition, Anki's modern default), and the learning-styles refutation (Pashler, McDaniel, Rohrer & Bjork 2008).
The affective layers (v0.4): competence-as-information (Deci/Koestner/Ryan 1999 β verbal competence feedback lifts adult intrinsic motivation d=+0.33, but flips to d=β0.78 when controlling), progress salience (Harkin et al. 2016, 138 RCTs, d=0.40), curiosity's reward circuit (Gruber, Gelman & Ranganath 2014), return-after-absence amnesty (Silverman & Barasch 2023; Lally et al. 2010) β and the refusals it's built on: gamification's motivational effect is the least robust (Sailer & Homner 2020) and backfires on already-motivated adults (Hanus & Fox 2015), streaks install a proxy goal, growth-mindset framing is small and context-specific (Sisk 2018; Yeager 2019), sympathy-after-failure reads as a low-ability cue (Graham 1984), and over-helpful AI tutoring harms retention (Bastani 2025). ADHD is honored as an opt-in Focus profile that turns up the same universal dials β not a new pedagogy, and pointedly not a game.
The visual-encoding audit (v0.5): interactive simulations carry the largest verified interactivity effect (g+=0.62, D'Angelo/SRI 2014) but guidance inside the artifact is the active ingredient (scaffolded versions of the same simulation g+=0.60; guidance in inquiry d=0.50, Lazonder & Harmsen 2016); dynamic-vs-static is modest and moderator-driven (g=0.226, Berney & BΓ©trancourt 2016 β concentrated where the motion is the content, d=0.40 representational vs ββ0.05 decorative); learner control per se is worth βnothing (g=0.05, Karich 2014); seductive details reliably hurt (Sundararajan & Adesope 2020); and expertise reversal is a confirmed disordinal crossover (novices +0.505 with assistance, knowledgeable learners β0.428; Tetzlaff 2025) β which is why explorables are content-triggered, guidance-wrapped, scaffold-faded, and measured against your own receipts rather than assumed to work. What didn't survive verification is stated as open, not assumed β docs/06-visual-encoding.md.
Full treatment with design consequences: docs/01-foundations.md Β· what exists and what's missing in every other tool: docs/02-prior-art.md Β· system design: docs/03-architecture.md Β· roadmap & constitution: docs/04-roadmap.md Β· the motivation & wisdom layers: docs/05-affective-layers.md Β· the visual-encoding audit: docs/06-visual-encoding.md Β· the measured loop: docs/07-the-measured-loop.md
And the strongest external result, stated honestly. Kestin et al., Scientific Reports, June 2025 (Harvard, n=194): an AI tutor built on exactly this dialogue grammar β one step at a time, never reveal the solution, make them attempt first β produced
roughly double the learning gains of an active-learning physics classroom, in less time. The caveat is the whole reason Engram exists:
its outcome was an immediate post-test. Nobody has ever measured whether AI-tutoring gains survive to thirty days. That is the question this tool is built to answer, on you, with receipts.
Engram's central claim is separation of powers: a blind assessor grades your free recall, and its receipts drive mastery, retention, calibration, and the schedule itself. Which raises the question nobody in this space likes: who grades the grader?
Until v0.7, nobody. The oracle was a vibe β an excellent one, unmeasured. And that hole sat directly under the foundation, because if the grader is lenient, every number Engram has ever shown you is inflated, and the system has no way to find out.
So we built the audit and ran it. Then the gold set failed before the grader did, and that turned out to be the more important result.
0 of 258 | blind judgments β 86 gold items (86% adversarial) Γ 3 independent runs β where the grader awarded more credit than the strict rubric reading. Zero, on the spec that ships β and it is a repaired zero, not an untested one. Extending the set to procedure items ran the audit three times over 774 judgments and caught 3 real inflations, each traced to an ambiguity in the grader's own instructions (one of them introduced by this release). All three are closed; the number was re-earned, not extrapolated. The full account, including what the fixes cost: |
That is a claim about safety, and it is the reason the badge above says what it says. A grader that errs low makes you re-drill something you had earned β annoying, and it costs you time. A grader that errs high tells you that you know something you do not, and you stop reviewing. Only one of those is a trap, and this grader has never walked into it.
v0.7.0 shipped this section with a QWK 0.93 badge. Then an independent post-release reviewer ran the one test nobody had thought to run: it graded the gold set with a correct grader and with a deliberately fooled one.
The fooled grader scored higher. (1.000 vs 0.990.) The gold set was rewarding leniency. The instrument was inverted.
The cause was five lenient adjudications by the gold set's own author, every one of the same species: crediting an adjacent fact as partial credit. Majority is not intersection. Consonance is not pitch-set arithmetic. The history of a theory is not its mechanism. The grader had caught all five, three runs out of three β including on a fluent-but-empty item, which means the author was fooled by fluency
in the very category built to catch being fooled by fluency.
Correcting them moves agreement from 0.889 to 0.965 and QWK to 0.978. And here is the thing:
That rise is not evidence the grader got better. It is evidence the instrument had been measuring the author's inconsistency.
Worse β the corrections were prompted by the grader's own disagreements. So the QWK that follows is circular: an authored gold set cannot validate a grader from the same model family, because when the two disagree and the author concedes, the agreement that follows measures only the author's willingness to concede. The engine now says so on every single audit, in the read
string, until someone who is not the author has adjudicated the set.
That is why the badge is no longer a QWK. ** 0/258 graded up is a safety property that does not depend on the gold being perfectly calibrated** β and correcting the gold
downwardonly made it a stronger claim, because it lowered the bar the grader had to not exceed. It still never did.
One genuine disagreement (g_054
) is deliberately left in, because the reviewer read both readings and judged the gold's defensible. An instrument with no disagreement left in it measures nothing.
The gold set is public β gold/assessor-gold.jsonl, 86 items,
86% adversarial:
fluent-but-empty,
terse-but-correct,
confident-and-wrong,
right-answer-wrong-reason,
paraphrase,
partial-credit boundary, and β new in v1.1 β
right-answer-wrong-method,
slip-vs-conceptual,
fluent-wrong-step,
terse-but-correct-solution. Every corrected item carries a
disputed
record with its original grade, so the correction is auditable rather than laundered. Run it yourself: /coach audit
. Dispute an itemβ drop it in
gold/local-gold.jsonl
and it overrides ours (the audit will say it did).What would actually fix this: one human, who is not us, adjudicating 86 items β and the two categories where the author and the grader now disagree in every run (right-answer-wrong-method
, procedure-partial-boundary
) are where that human would earn their keep first. That is the highest-value contribution anyone could make to this repository, and until it happens the engine will keep saying so out loud. Since v1.4 there is a procedure for doing it β a 10-anchor calibration gate, then QWK and ordinal Krippendorff's Ξ± with a bootstrap CI, against thresholds fixed before anyone reads the file: ** docs/ADJUDICATION.md**, scored by
engram.py adjudication-stats
. One external rater corroboratesthe authored gold; replacing it would take two who agree with each other, and the engine keeps saying that too.
One more thing the literature insists on, and the engine enforces: high consistency is not correctness. A judge has been measured at testβretest 0.992 with a position bias of 0.192 β perfectly reproducible and systematically wrong (docs/07 Β§3). Engram's assessor is prompted to be a skeptic, so it is self-consistent by construction β precisely the profile that failure mode wears. So the engine refuses to certify on consistency: above 0.95 testβretest it demands the leniency bias be strictly under the ceiling, fewer than three runs cannot pass at all, and three identical runs are flagged as measuring nothing.
The evidence base of learning science is built on undergraduates, word pairs, and 20-minute retention intervals. Almost nothing tests self-directed adults, on hard conceptual material, at 30β90 day horizons, with blind-graded free recall.
That is not a gap anyone chose. It is a gap because, until roughly 2026, grading free recall at scale was impossible β you needed a human to read every answer.
Engram produces exactly that data as a byproduct of being useful, on hundreds of machines, with a measured grader behind every verdict. And the open question is sitting right there: Kestin et al. (Harvard, Scientific Reports, 2025) found an AI tutor built on this exact dialogue grammar produced
~2Γ the learning gains of an active-learning classroom, in less timeβ measured on an
immediate post-test.
Nobody has ever measured whether AI-tutoring gains survive to thirty days.
python3 scripts/engram.py export --contributor "@you" # writes a FILE. Sends nothing.
Then read the file. It is short, it is yours, and nothing has left your machine.
| leaves | never leaves |
|---|---|
| grades, ratings, confidence | your productions β every word you wrote |
| timings, stability, intervals, retrievability | probes, claims, rubrics |
kind , node_kind , error_class , artifact , arm , stratum |
|
| goals, interests, misconception text | |
grader and its measured QWK |
|
| topic names and node ids β hashed, not carried |
Four things make that a promise rather than a hope:
The payload is a WHITELIST. Every field is constructed by name. There isno code pathby which a production could arrive β not*"we remembered to delete it."*A blacklist is a promise you must keep every release; a whitelist is one you keep by construction.The, so the promise is verifiable by the person making it, not merely asserted at them.stripped
list ships INSIDE the fileAn unaudited grader cannot contribute.export
refusesβ a refusal, not a warning.A finding aggregated from unaudited oracles is not a finding; it is noise with a schema.v0.7 gates v1.0.**The engine has no network code. Not "none by default" βnone. Apermanent selftest parses the engine's own AST(not a grep β the first draft found the wordcurl
in itsown comment) and fails the build if anyone ever addsimport socket
to make one thing convenient.export
writes a file and stops; theagent posts, viagh
, only on an explicit yes.
And it is ATTRIBUTED β we are not going to lie to you about that. gh
posts from your account. A "salted anonymous hash" riding inside a signed envelope would be theatre the moment the envelope is signed. You cannot have one-keystroke upload and anonymity; pick one, and say which out loud. Attribution is also the stronger science: a retention study lives on longitudinal linkage β following the same learner across months is the question β so attributed n=100 beats anonymous n=500.
This is not telemetry. It is a consenting, named, informed participant in an open study β which is what every good study has always had. Withdrawal is: it's a GitHub post, delete it. That is the entire mechanism, deliberately.
Read the whole thing before you decide: CONTRIBUTING-DATA.md.
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.
Is this a memory plugin for my agent? No β the other direction, and this is the most common mix-up. Agent-memory tools (memory MCPs, context managers, "give Claude persistent memory" plugins) store knowledge for the agent. Engram uses the agent to install knowledge in you: it tutors, blind-grades your free recall, and schedules reviews against your measured forgetting curve. If you want your agent to remember things, you want a different tool. If you want to still know things a month after the chat, you want this one.
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).
Math and STEM specifically?
Yes, and since v1.1 with a layer built for the half of STEM that is doing: the architect marks skill-type nodes as procedure
, which swaps in worked-example acquisition and solve-a-fresh-variant reviews, step-graded with execution-checked arithmetic (a dropped sign is priced as a slip, not a forgotten idea; a right answer over a wrong method is capped β the answer is not the knowledge). It is not a "math mode": the same kind fires on a git workflow or a conjugation drill, concepts still run the Socratic grammar, and a topic with no procedure nodes behaves exactly as before. Theory and the adversarial verification behind it: docs/11-the-procedure-gap.md.
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
(oroff
, orstatus
).
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.
CLI reference β scripts/engram.py
, the deterministic core
The model never does calendar math; this does:
| Command | Purpose |
|---|---|
| `add-topic --file F [--replace | --extend]` |
| ingest a concept DAG Β· re-author one Β· add an arc (new nodes only; every existing schedule, receipt and retirement untouched) | |
next --topic T [--frontier-of N] |
|
| next frontier concept Β· the unreceipted prerequisites of a node, for an adaptive pretest that credits nothing | |
init / doctor [--fix] / path |
|
| create state Β· diagnose problems and name their repairs Β· print state location | |
topics / topic-status --topic T |
|
| list topics Β· mastery map with progress bar | |
adherence |
|
the binding constraint: of concepts taught and scheduled, how many you came back for (loop_closure ) Β· return cadence Β· the full funnel |
|
retention |
|
the north star: recall at 7 / 30 / 90 days after encoding β reported with its unmeasured denominator (the concepts that came due and were never reviewed; unknown, not absent) |
|
decay --topic T |
|
| what is dying right now, and what N minutes would save β real FSRS numbers, both arms over the same window | |
commit --cue β¦ --action β¦ |
|
| your if-then plan, in your words. Stored, shown back at the moment it names (v1.3 β from v0.6 to v1.2 it was stored and displayed by nothing), renewable, never enforced | |
next --topic T / due |
|
| next frontier concept Β· due review queue (interleaved) | |
due --cap N |
|
a capped session, ranked by expected retention saved per minute rather than most-overdue-first β with order_basis stating in the payload that it is model-derived (--limit keeps the old shape and order) |
|
retire --topic T [--node N] |
|
take something off your list β out of every queue, counted in every denominator it leaves, reversible with --restore |
|
rate / receipt --file F |
|
| apply one rating Β· apply assessor receipt batch | |
| `stash add | list |
| crash-safe queue of answers awaiting grading | |
model / misconception |
|
| open learner model Β· error catalog | |
propose / adaptations |
|
| at most 3 engine-justified adaptations, each with its evidence and grade (read-only) Β· the append-only ledger of every change, why, and that it is reversible (Article 12) | |
| `experiment start | assign |
n-of-1 trials done properly: randomized (seeded, reproducible) Β· stratified (kills the material-vs-medium confound) Β· pre-registered Β· powered (15/arm; the floor moves with the metric β 8 for transfer, 10 for slip-share) Β· and the engine computes the verdict β --verdict is refused |
|
edit-node --topic T --node N --file F |
|
repair ONE nodeβs grading contract in place β probe , rubric , transfer_probe (by file, the shell-safe channel; inline flags for hand use). Schedules, receipts and registrations are untouched; the node records that its contract moved and how many receipts predate it |
|
| `focus on | off |
| toggle the ADHD Focus profile (Sprint default, growth every review, always-on amnesty) | |
| `visuals eager | threshold |
| the explorables dial: every high-affordance concept Β· portal concepts only (default) Β· none | |
| `artifact set | clear |
| register a built explorable on its node (validated; powers regeneration tracking + the medium comparison) | |
gold |
|
| the 86-item adversarial gold set, answers stripped by construction β shaped exactly like a real settle payload, so the audit grades the real assessor | |
assessor-audit --file F |
|
| grade the grader. QWK (headline) Β· raw agreement (never quoted alone) Β· signed leniency bias Β· testβretest Β· confusion matrix Β· per-case-type breakdown | |
adjudication-stats --file F |
|
| score an external human's adjudication of the gold set: anchor calibration gate, QWK, ordinal Krippendorff's Ξ± with a bootstrap CI, signed direction β thresholds fixed in advance ( | |
grader-health [--grader-context S] |
|
the latest audit's verdict β and it EXPIRES (v1.4): a grader swap voids the badge, because a swapped model grades measurably more lenient. stats embeds it, and stamps grader_unvalidated on every retention figure until it passes |
|
transfer [--topic T] |
|
the mature concepts ready for the harder question β the transfer_probe the architect wrote and nothing ever asked. /review serves it automatically |
|
capstone --topic T |
|
materialize the build as a real NODE in the DAG (idempotent). New topics get one from add-topic ; it requires every concept, so it cannot be silently skipped |
|
stats / report |
|
telemetry JSON (incl. modality β explorable vs dialogue retention) Β· self-contained HTML dashboard |
|
refit |
|
| fit the schedule to your measured memory: the interval multiplier (β₯50 reviews), then your own FSRS parameters β S0 at 64 usable reviews, the full vector at 400, and a fit that does not beat your current one is refused | |
export [--topic T] |
|
| a text-stripped, attributed receipt bundle written to a file. Whitelist-constructed β there is no code path by which a production could leave. Refuses if your grader is unaudited | |
session-start / log-session |
|
| ambient nudge (hook) Β· session telemetry | |
selftest |
|
| 302 checks over the FSRS math, state machine, adherence/retention arithmetic, the grader-audit statistics, and every hardened boundary |
Troubleshooting & updating
- Anything weird β
python3 scripts/engram.py doctor
(checks state files, paths, python, quarantined files). - Update:
claude plugin marketplace update engram && claude plugin update engram@engram
, then restart or/reload-plugins
. - Skills resolve the plugin root via
${CLAUDE_PLUGIN_ROOT}
(or${CODEX_PLUGIN_ROOT}
on Codex); for a dev clone outside the plugin cache, setENGRAM_ROOT=/path/to/engram
. - Corrupt a state file by hand? It's quarantined to a
.corrupt.<date>
sibling (never silently discarded) anddoctor
will point at it β your other topics keep working.
Repository layout & design lineage
.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, subagent spawning)
agents/ engram-curriculum-architect Β· engram-assessor Β· engram-artifact-smith (Claude Code)
codex/agents/ *.toml ports of the three subagents (Codex)
hooks/ SessionStart re-anchor (Claude Code/Codex) Β· pre_llm_call port (Hermes) β self-resolving; silent when nothing is due
hooks/engram-due/ HOOK.md + handler.js (OpenClaw hook pack β same nudge, same silence)
scripts/engram.py deterministic core: FSRS-4.5, state, receipts, stats, dashboard, selftest
docs/ theory Β· prior art Β· architecture Β· roadmap
INSTALL-CODEX.md Β· INSTALL-HERMES.md Β· INSTALL-OPENCLAW.md per-platform glue, at the repo root
One codebase, many agents: skills/
and scripts/engram.py
are shared verbatim; each platform gets its own thin glue (manifest, subagent format, or hook adapter). See INSTALL-CODEX.md Β· INSTALL-HERMES.md.
Separation of powers, enforced by construction: the tutor teaches but never grades; the assessor grades from a fresh context without seeing the lesson; the coach adapts only from receipts; and engram.py
β never the model β computes every date and stability value. Verification patterns (oracle-driven loops, receipts, re-anchoring) inherited from claude-code-production-grade-plugin, transposed from software verification to learning verification.
| Doc | Contents |
|---|---|
docs/02-prior-art.mddocs/03-architecture.mddocs/04-roadmap.mddocs/05-affective-layers.mddocs/06-visual-encoding.mddocs/07-the-measured-loop.mdThe frontier audit: why "learning rate" is the wrong vector, what actually determines whether you come back, whether an LLM grader can be trusted, and which memory neuroscience is actionable vs. decorationdocs/08-vision.mdThe vision: the one number Engram exists to move, which appealing metrics are traps, and the final state β tutor β instrument β commons. Includes the exhibit: the founder's own memory decaying on scheduledocs/09-target-architecture.mdThe target engine: schemas, the nine new commands, the invariants that must never break, and the order of operationsdocs/10-roadmap-to-1.0.mdThe road to 1.0: v0.6 β v1.0 as executable work orders β why / what / done / selftests / risk, each shippable by someone who has never seen the repodocs/11-the-procedure-gap.mdThe procedure gap (v1.1's theory): Engram was braced for the conceptual half of math & STEM and blind to the procedural half β Pillars 16β17 (the example ladder; the problem as the probe), adversarially verified by three refute-first passes that corrected five claims and inverted one design rule before code shippeddocs/13-the-adaptive-instrument.mdThe v2.0 evidence audit: a live probe of the shipped engine plus seven refute-first research passes (successive relearning Β· the FSRS ecosystem Β· LLM-grader validity 2025β26 Β· adherence Β· retrieval formats Β· review ordering Β· adaptivity) β and a kill list as long as the survivor listdocs/14-roadmap-to-2.0.mdThe road to 2.0: v1.3 β v2.0 as executable work orders, each marked shipped with what the build corrected in itdocs/15-target-architecture-2.0.mdThe schema authority: every field, payload and signature the roadmap names, the self-heal table, and the invariants v2.0 addsdocs/ADJUDICATION.mdThe contributor kit: how to adjudicate the gold set as an outside human, and the statistics that make your work countabledocs/12-procedure-layer-work-order.mdThe procedure layer's build: architecture + work orders (WO-1β¦WO-8), the compatibility doctrine (no breaking changes, no domain mode β Engram stays general), and the pre-answered numbers audit forby_kind
Four 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.
β 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.effortminingβ 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.idiolectβ 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.production-gradeβ a minimal comms protocol for Claude: a per-turn hook makes replies answer-first, pick-list-driven, and calm, without touching the work.less
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 Β·