HeurAMS "潜进" (Heuristic Auxiliary Memorizing Scheduler) is an auxiliary memorizing scheduler based on heuristic algorithms and cognitive science theories, designed to help users memorize and plan learning more efficiently.
It is also an open, elegant, and extensible spaced repetition scheduler experiment platform, intended to help researchers conduct investigations, experiments, and research on cutting-edge memory algorithms more efficiently.

Detailed Introduction | Screenshots

Quick Start

Installation

Install from Package Manager

HeurAMS (package name heurams) is in early development and not yet available on PyPI.
However, you can install stable and development versions from the repository using pip, which requires a Python environment (Python 3.12.13 or later recommended).

Install from the stable master branch with optional dependencies for user experience (recommended):

pip install --upgrade 'heurams[basic] @ https://git.pluv27.top/pluv/HeurAMS/archive/master.zip'

Install from the more recent, roughly stable dev branch with optional dependencies (if you want cutting-edge improvements):

pip install --force-reinstall --no-deps 'heurams[basic] @ https://git.pluv27.top/pluv/HeurAMS/archive/dev.zip'

Install the general audio module for desktop computers (based on playsound3):
(Not applicable for termux environments; termux has built-in audio support)

pip install --upgrade 'heurams[audio-playsound] @ https://git.pluv27.top/pluv/HeurAMS/archive/master.zip'

You can also install from specific branches like refactor/... to test particular changes.

Dependency Group Reference

Install from Source

We provide two source installation methods: native Python and uv.
See the Contributing Guide - Setting up Development Environment for details.

Usage

Run heurams in your terminal, and you will see help information:

~ $ heurams
Usage: heurams [OPTIONS] COMMAND [ARGS]...

  HeurAMS 0.5.1 - Heuristic Auxiliary Memorizing Scheduler

Options:
  -v, --version  Show the version and exit.
  -h, --help     Show this message and exit.

Commands:
  help     Show this help message
  tui      Launch the built-in basic user interface (TUI)
  version  Print version information

Start the basic user interface by typing heurams tui:

~ $ heurams tui
Welcome to the basic user interface!
Loading config and context... Done! (2ms)
Loading UI framework... Done! (89ms)
Loading UI layout... Done! (56ms)
Component directory: <package directory>
Working directory: <working directory, ./data folder will be created here>
Pre-work total: 147ms

(Your terminal will now display the TUI)

Check the version with heurams -v:

~ $ heurams -v
HeurAMS 0.5.1 stable (fulcrum/支点), Linux

Frequently Asked Questions (FAQ)

See FAQ.

Project Architecture

See Architecture Overview.

Contributing

Contributions are welcome!
See the Contributing Guide.
For AI-assisted development guidelines, see AGENTS.md.

Project Identity

HeurAMS project identity assets are located in ./src/heurams/assets/art/ directory:

Colors: #1660A5 (Ocean Blue) #545F70 (Blue Gray) #FFFFFF (Monochrome Light Icon White) #1A1A1A (Monochrome Dark Icon Deep Black) #2f2f35 (Text Color).

License

Project

This project is open source under the AGPL-3.0 license, with an additional exemption clause for local API calls, making it more permissive than the standard AGPL-3.0.

See the LICENSE file in the root directory.

Third-Party Code

The project embeds or directly uses the following third-party code or its derivatives (possibly with modifications) in src/heurams/vendor/ or other locations:

SM.js

Upstream version: commit 6e3bb4a (upstream discontinued as of Feb 4, 2015)
Usage: Rewritten from CoffeeScript to Python with indirect reference, maintaining the same mathematical principles; improved logic, performance, and standardized API
Location: src/heurams/kernel/algorithms/sm15m.py
Original project: SM.js
Original license: MIT License

This project benefits from their selfless and excellent work.