HeurAMS/README.md

潜进 (HeurAMS) - 启发式辅助记忆调度器

概述

"潜进" (HeurAMS: Heuristic Auxiliary Memorizing Scheduler, 启发式记忆辅助调度器) 是一种基于启发式算法与认知科学理论的辅助记忆调度器, 旨在帮助用户更高效地进行记忆工作与学习规划,
也是一种开放, 优雅, 易于扩展的间隔重复调度器实验平台, 旨在帮助研究者更高效地进行前沿记忆算法的研究.

项目结构

这个仓库是 "潜进" 的核心程序库在 python 语言下的实现
包含数据模型与框架, 并内置了基于 textual 框架的前端实现 (interface 子模块)
除了通过内置前端进行学习外, 开发者也能在 python 环境中导入 heurams 库或使用 RPC 与 heurams 程序库实例通讯, 使用框架构建其他辅助记忆功能前端或其他应用程序

Note

我们已经开始着手于基于 KDE 用户界面框架 Kirigami 的现代跨平台应用程序前端开发, 称作 "潜进K型 (HeurAMS-K)" 它通过 PyOtherSide 直接复用 python 内核, 现代化的 UI 支持 Windows, Linux, macOS, Android 和 Plasma Mobile 如果您善于开发 C++, QML, Qt 与 KDE 框架, 欢迎加入到 HeurAMS-K 项目的开发

特性

间隔重复调度器

许多出版物都广泛讨论了不同重复间隔对学习效果的影响. 特别是, 间隔效应被认为是一种普遍现象. 间隔效应是指, 如果重复的间隔是分散/稀疏的, 而不是集中重复, 那么学习任务的表现会更好. 因此, 有观点提出, 学习中使用的最佳重复间隔是最长的, 但不会导致遗忘的间隔.

• 软件开箱即用, 无需多加配置即可使用默认的 SM-2 算法进行学习
• 此外, 算法模块是 "潜进" 内核 (heurams.kernel) 中的一等公民, 内核天然支持插拔各型算法
• 无需安装繁杂的插件即可分单元集完成算法快速切换与调优, 研究者可以方便地修改算法模块以便捷地进行研究与测试
• 默认使用 SM-2 简单间隔重复算法, 此算法亦用作 Anki 闪卡记忆软件的默认闪卡调度器
• 还内置 NSP-0 筛选用非间隔重复算法以便快速筛选记忆内容, FSRS 先进间隔重复算法作为效率更高的调度器, 与 SM-15M (移植自 sm.js 项目) 复杂间隔重复算法(逆向工程)
• 算法模块可以标记记忆项目, 也可以动态规划每个记忆单元的记忆间隔时间表, 动态跟踪记忆反馈数据, 以优化长期记忆保留率与稳定性
• 得益于项目的模块化架构与单元集结构设计, 一个项目甚至可以与任意种算法共存并互通, 这对研究者及想探索/实验高效率方法的用户极其友好

多模态学习进程

与 Anki 的 SQLite .apkg 包不同, 我们坚持使用人类可读的文件夹组织单元集, 这带来了若干好处, 包括:

• 人类可读: 您可以用任意工具, 乃至一个记事本自由修改记忆载荷数据而无需打开软件
• 元数据配置: 配置自由度极高, 可以任意组合, 重造, 乃至创造新内容
• 测验, 算法与知识互相隔离: 一条知识不再是单一的闪卡, 不仅可以用若干不同的算法规划, 还可以用多种并行的谜题类型测验, 极大地提升您的学习效果和丰富度. 作为学习者, 您无需担忧概念复杂--仅需从云端下载单元集即可开箱即用上述特性!
• 多模态学习
  • 软件自身集成了文本转语音 (TTS) , 音频与语言模型 (LLM) 模块, 这些功能乃至功能本身都是可插拔, 可扩展, 可切换驱动的, 这为内容创建了极大的丰富度
  • 软件内置多种谜题类型, 包括选择题 (MCQ), 填空题 (Cloze) 与识别题 (Recognition), 您可在同一单元应用多种, 或是选择启用
  • 软件天然支持动态内容生成, 支持宏驱动的模板系统, 根据上下文乃至语言模型动态生成知识点的解析
  • 在间隔重复研究尚被 SuperMemo 系列独占的时代, Wozniak 就早已表示 "如果不能理解知识, 就无需记忆它". 今天, 我们依然相信理解是记忆的基石
• 云同步与分享优化: 由于我们的记忆数据和单元集文件都是文本文件, 故可进行快速的增量同步而无需完整地上传所有文件, 并且设计天然支持分享内容的版本控制, 如果您想分享单文件, 我们也支持导出为压缩包或合并单文本文件以通过纯文本文件形式在 pastebin 等平台分享
• 性能提升: 得益于现代且支持分块的文件组织结构, 潜进能在保持高自由度的同时仅使用 python 就能达到敏捷且低占用的用户体验

实用用户界面

• 响应式 Textual 框架构建的跨平台 TUI 界面
• 支持触屏/鼠标/键盘多操作模式
• 简洁直观的复习流程设计

快速开始

从包管理器安装

潜进(heurams) 处于早期开发考虑, 尚未上架 PyPI, 但您可以用我们的基础设施安装稳定版和开发版本.

Caution

对于部分 Linux 发行版和 Android Termux 用户:
您需要先行安装 cmake 和 libzmq 才能正确安装项目的 zmq 依赖
例如在 termux 上先运行 pkg install cmake clang libzmq
项目功能本身不依赖它, 但需要该依赖用于启动可选的调试服务器

稳定版本

python -m pip install heurams[all] -i https://pypi.pluv27.top/root/stable/+simple/ # 安装全部可选依赖(推荐)

开发版本

python -m pip install heurams[all] -i https://pypi.pluv27.top/root/dev/+simple/ # 安装全部可选依赖(推荐)

依赖组说明

由于部分依赖只被少数功能需要, 所以我们把可选依赖分得比较细, 前面提供的命令会安装所有可选依赖, 以下是依赖组列表

• 基础依赖: (只能驱动程序库)
  • tabulate: 终端表格生成
  • toml: TOML 文件加载
  • transitions: 状态机依赖
• interface 依赖组: (基本用户界面依赖)
  • textual: 终端用户界面
  • psutil: 获取系统信息
• algo-fsrs 依赖组:
  • py-fsrs: FSRS 算法模块需要
• tts-edgetts 依赖组:
  • edge-tts：微软文本转语音
• misc-jieba 依赖组:
  • jieba: 中文智能分词所需
• llm-openai 依赖组:
  • openai: OpenAI API 所需
• audio-playsound 依赖组:
  • playsound: 通用音频播放
  • pygobject: playsound 依赖
• dev 依赖组:
  • zmq: 远程调试服务器所需
  • pytest: 测试所需
  • pytest-cov: 测试所需
• all 依赖组:
  • 包含以上所有依赖

从源码安装

我们提供原生 python 和 uv 两种安装方式.
详见贡献指南.

项目结构

详见架构说明.

参与项目

欢迎参与到项目协作中! 请参阅 CONTRIBUTING.md 了解贡献指南.

许可证

项目本身

本项目基于 AGPL-3.0 许可证开放源代码.
详见根目录下 LICENSE 文件.

第三方代码

项目在 src/heurams/vendor/ 目录下嵌入或在其他位置间接使用了以下第三方代码(可能有修改):

py-fsrs (open-spaced-repetition)

• 上游版本: 6.3.1
• 引用方式: vendor
• 位置: src/heurams/vendor/pyfsrs/
• 原项目: py-fsrs
• 原版权: Copyright (c) 2026 Open Spaced Repetition Contributors
• 原许可证: MIT License

SM.js (slaypni)

• 上游版本: commit 6e3bb4afaf484426deb4a9fa3bcffe42ac066b45 (2015年2月4日上游已停止维护)
• 引用方式: 将 coffeescript 重写为 python 并间接引用, 数学原理一致; 并对重写后代码进行逻辑, 性能与标准化 API 改进
• 位置: src/heurams/kernel/algorithms/sm15m*.py
• 原项目: SM.js
• 原版权: Copyright (c) 2014 Kazuaki Tanida
• 原许可证: MIT License

本项目受益于他们无私且优秀的工作.