Working Memory Jev · Passage

Passage helps educators inspect where instructional text may ask a learner to hold too many ideas or relationships at once. It runs on localhost and uses the real Jev API to propose active groups, source connections, and changes in demand as the passage unfolds.

This is an experimental teaching aid. Its slot estimates and confidence labels are not validated measurements of a student's memory or calibrated probabilities of overload. Research motivates the design; it does not validate the app's numerical predictions. See research and practical use.

Free for individuals and non-commercial use; ask first otherwise. Copyright © 2026 AustinAWay, under the Working Memory Jev License. Individuals, one-person organizations, and anyone using it non-commercially may use, modify, and share it. An organization with more than one employee, or any commercial use, needs written permission first: email austin.way@alpha.school with who you are and how you will use it. This is publicly readable source under custom terms, not an open-source license. See licensing and access.

• Reviews a whole passage, then individual sentences and smaller reading steps.
• Compares estimated demand with a selected 1–5 slot budget. Estimated demand itself can exceed five.
• Uses reading grade 1–12 (default 6), prior subject knowledge, the teaching goal, and visible/spoken presentation as context.
• Highlights source text, draws confirmed connections between exact source occurrences, and lets you inspect the proposed active groups.
• Reassesses what matters at each step instead of permanently accumulating every earlier mention.
• Shows average and peak estimates with categorical confidence, keeps usable estimates provisional when supplementary checks remain unresolved, and supports manual grouping review and export.

You need Python 3.12 (tested baseline), Node.js 22 with npm, and your own TypeSafe/Jev API key. The key is not included. Other Python versions satisfying >=3.12 may require dependency compatibility checks.

git clone https://github.com/AustinAWay/Working-Memory-Jev.git
cd Working-Memory-Jev
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.lock
cd web
npm ci
npm run build
cd ..
cp .env.example .env

Edit .env locally and replace the placeholder with your own key. Keep this file private; Git ignores it. Do not paste the key into frontend code, a browser field, an issue, or a command that will be saved in shell history.

.venv/bin/python run.py

Open http://127.0.0.1:8765. Keep the server window open; Control-C stops it. On macOS, Setup.command installs dependencies and Start.command launches the app. Windows commands, configuration precedence, and startup checks are in the setup guide.

The API key stays on the local server. Analysis sends the passage and learner context to TypeSafe; localhost does not mean offline inference. One Check can make many Jev requests. Jev answers are not deterministic, so each decision batch is sent PASSAGE_JEV_SAMPLES times (default 2, range 1 to 5) and the answers are averaged; set PASSAGE_JEV_SAMPLES=1 in .env to halve requests at the cost of noisier decisions. Provider pricing, quotas, and billing apply separately; the UI's cost estimate is not an invoice or a promise of free access.

1. Paste an English passage of up to 6,000 characters and choose the comparison budget.
2. Open Context. Describe the intended learning outcome and what the student has actually demonstrated they know. Grade level supplies a language assumption, not proof of subject knowledge.
3. Select Check. Start with the average, peak, and confidence, then inspect highlighted sentences and reading steps.
4. Select a step and a numbered slot to see its source words and proposed connections. Review overgrouped ideas, overly fragmented familiar actions, and conditions that should still be active.
5. Use Review grouping or Sentences → Words & connections → Edit grouping to correct assumptions. The map, scores, and exports update from the same current scenario.
6. Test the student's explanation and transfer to a new example independently. A lower displayed count does not establish better learning.

Changing the source or learner context requires a new analysis. Changing the comparison budget or reviewing grouping does not itself make another API call. More → Analysis details shows the model, prompt revision, actual request usage when available, and coverage warnings. Downloads include the passage and learner context; review them before sharing.

The local parser proposes reading steps and exact source occurrences. Jev makes bounded choices about familiarity, active/background status, grouping, and relationships. Proposed lines receive a separate source check. Relationship accounting asks whether a needed binding is already represented, independently needs a unit, or can be backgrounded. Further checks and one correction pass address unresolved accounting.

At each reading step, the current score counts primary Jev groups plus accepted extra relationship units. A line is not automatically an extra slot: it may already belong to a counted representation. Familiar component words alone do not prove that a relationship is familiar. Completed information can be released; a later reference can retrieve it again.

Average is the equal-weight mean across reading steps, not time spent reading. Peak is the largest available count. If a primary step cannot be assessed, the complete average is unavailable and a partial maximum is labeled Highest assessed. Valid primary estimates survive incomplete supplementary accounting as Provisional Jev estimates with Low confidence. Unknown accounting can change a result in either direction; it is not a guaranteed lower bound.

Confidence is Low, Moderate, or Unavailable, based on evidence and review rules. It is not an empirically calibrated percentage. Source highlighting can be exact even when the semantic judgment is wrong. The supported scope is English instructional prose; formulas, code, ambiguous references, implicit prerequisites, and incorrect learner assumptions can produce poor results.

Current versions: Jev jev-1.13.0; prompt passage-2026-09-21.2; frontend scoring relational-provisional-counts-v2. The architecture guide explains the full pipeline and the distinction between primary estimates and complete relationship accounting.

Historical reports preserve failed cases as well as successes. They are development evidence, not a benchmark of measured student overload.

.venv/bin/python -m pytest -q
cd web
npm test
npm run build

The normal tests use mocks and saved fixtures; they do not need a real API key or intentionally make paid provider calls. Live evaluation is separate and optional. Tests establish implementation behavior, not psychological accuracy.

Restart the server after backend changes. Rebuild the frontend and reload the page after frontend changes. Built assets, dependencies, caches, local configuration, and an exports/ directory are ignored by Git. Keep private exports outside the repository.

Please read contribution terms before submitting code. Dependencies retain their own licenses; see third-party notices.