Open Review Assistant

A privacy-first adaptive review engine for learners and coding agents. It keeps prompts, answers, schedules, and review history in a local SQLite database and exposes the same small workflow through a command-line interface and an MCP server.

This repository is a clean public core extracted from a larger personal study system. It contains no real learner records, exam questions, private notes, or production databases. The demo content is synthetic.

Why this project exists

Many review tools combine content, scheduling, and user data in a hosted service. Open Review Assistant keeps the durable state on your machine, uses a deterministic scheduling policy, and makes every schedule transition auditable. An agent can select a due item, present it without exposing the stored answer, then record a score after the learner responds.

Features

• Local SQLite storage with foreign keys and integrity checks.
• Deterministic due-item selection and spaced-review scheduling.
• Answer-safe retrieval: next omits the stored answer by default.
• Immutable review events recording previous and next intervals.
• JSON output for scripts and agents.
• Dependency-free Python core.
• MCP tools over standard input/output.
• Synthetic demo data and unit tests.

Quick start

Python 3.10 or newer is required.

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e .

open-review --database review.sqlite3 init
open-review --database review.sqlite3 seed-demo
open-review --database review.sqlite3 next

After answering the returned prompt, grade the item from 0 to 5:

open-review --database review.sqlite3 grade ITEM_ID 4
open-review --database review.sqlite3 stats

All commands support --json. The database path is explicit so a test database cannot silently replace a real one.

CLI

open-review init
open-review add --title TITLE --prompt PROMPT --answer ANSWER [--tags TAG ...]
open-review next [--tag TAG] [--show-answer]
open-review grade ITEM_ID SCORE
open-review stats
open-review seed-demo

Scores follow a compact, transparent scale:

Score	Meaning	Scheduling effect
0	No recall	Restart tomorrow
1	Incorrect	Restart tomorrow
2	Hard	Shorten the current interval
3	Correct with effort	Grow the interval conservatively
4	Correct	Grow using the current ease factor
5	Easy	Grow faster and raise the ease factor

MCP server

Run the stdio server with:

open-review-mcp --database /absolute/path/to/review.sqlite3

It exposes four tools:

• review_add_item
• review_next
• review_grade
• review_stats

Example Codex configuration:

[mcp_servers.open_review]
command = "open-review-mcp"
args = ["--database", "/absolute/path/to/review.sqlite3"]

The server implements the MCP initialization, tool-listing, and tool-call subset needed for this workflow. Transport is newline-delimited JSON-RPC over stdio, and logs are never written to stdout.

Privacy model

• No network calls, telemetry, accounts, or cloud synchronization.
• Database files and journals are ignored by Git.
• Answers are not returned by next unless explicitly requested.
• The public repository uses only synthetic examples.

Local-first is not the same as encrypted. Protect the device and database file according to the sensitivity of your material. See SECURITY.md.

Roadmap

This public core is extracted from a larger system that is used and improved continuously. Planned public milestones include:

• Provider-agnostic AI generation of question variants that test the same knowledge from different angles without copying private source material.
• Source-linked web and semantic review to check generated items for factual correctness, knowledge coverage, ambiguity, and unintended answer leakage.
• Reproducible evaluation fixtures for variant quality, prompt injection, and answer-safety regressions.
• Expanded MCP tools for orchestrating generation, verification, review, and weak-point analysis while keeping durable learner data local.

These capabilities will be added behind explicit interfaces so the scheduling core remains inspectable, offline-capable, and independent of any single model provider.

Development

PYTHONPATH=src python3 -m unittest discover -s tests -v

Contributions are welcome. Please read CONTRIBUTING.md.