https://github.com/vforvitorio/marginalia
Kindle Scribe handwritten notebooks -> Obsidian Markdown, with OCR and human review.
https://github.com/vforvitorio/marginalia
e-ink fastapi handwriting-recognition kindle-scribe local-llm markdown note-taking obsidian ocr ollama pkm react vision-language-model
Last synced: about 8 hours ago
JSON representation
Kindle Scribe handwritten notebooks -> Obsidian Markdown, with OCR and human review.
- Host: GitHub
- URL: https://github.com/vforvitorio/marginalia
- Owner: VforVitorio
- License: mit
- Created: 2026-06-21T20:47:40.000Z (10 days ago)
- Default Branch: main
- Last Pushed: 2026-06-27T14:31:31.000Z (4 days ago)
- Last Synced: 2026-06-28T01:32:10.126Z (4 days ago)
- Topics: e-ink, fastapi, handwriting-recognition, kindle-scribe, local-llm, markdown, note-taking, obsidian, ocr, ollama, pkm, react, vision-language-model
- Language: TypeScript
- Homepage: https://vforvitorio.github.io/marginalia/
- Size: 16 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# marginalia
Turn the notebooks you write by hand on your Kindle Scribe into Markdown you can actually use in Obsidian.
You write by hand on the Scribe, export the notebook as a PDF, and marginalia does the boring part: it runs OCR over your handwriting, lets you fix whatever the OCR got wrong, and drops the result into your vault — keeping the folder structure you already use on the device.
The name comes from *marginalia*, the notes people used to scribble in the margins of manuscripts. Same idea: getting handwritten thought to survive the jump to digital.
Import a Scribe PDF → OCR the handwriting (even math, as KaTeX) → review side-by-side → export to your Obsidian vault. full-quality video
## Kindle Scribe only (for now)
This is built for the Kindle Scribe and nothing else. No reMarkable, no Apple Notes, no Samsung Notes. If you use another device, marginalia won't help you yet — and there are tools that already do this well for those (Scrybble for reMarkable, for instance).
It's not laziness about portability: export quirks differ enough between devices that "support everything" usually ends up as "support nothing well." Scribe first.
## What it does (MVP)
- Local OCR with Qwen3-VL (2B or 4B) through Ollama or LM Studio. Runs on an 8 GB GPU.
- Cloud OCR when you want it — Claude (through your subscription, no API key) or Gemini (free tier). Good for the pages the local model chokes on.
- A review screen: your original page on one side, the transcription on the other. Fix the mistakes before anything touches your vault.
- Folder structure carries over. Your Scribe folders become folders and wikilinks in Obsidian — your call.
- Everything's a button. Switching models, pulling a new one, local vs cloud, exporting — no terminal once it's running.
## Stack
| Layer | Tech |
|---|---|
| Backend | Python 3.12 + uv, FastAPI, PyMuPDF, Ollama/LM Studio, Claude Agent SDK, Gemini |
| Frontend | Vite + React + Tailwind + GSAP |
| OCR | Qwen3-VL (local) or Claude/Gemini Vision (cloud) |
| Export | Jinja2 + Markdown with frontmatter |
## Getting started
### Install (one command — no Node required)
```bash
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/VforVitorio/marginalia/main/scripts/install.sh | bash
# Windows (PowerShell)
irm https://raw.githubusercontent.com/VforVitorio/marginalia/main/scripts/install.ps1 | iex
```
The installer sets up `uv` (which brings its own Python), clones marginalia, downloads the prebuilt frontend from the latest release, and launches the app on http://localhost:8000. You only need **git + a shell**. For **local OCR** also install Ollama or LM Studio; for **cloud OCR** use a Claude or Gemini account. Relaunch any time with `uv run marginalia` (from the install folder, default `~/marginalia`). The vault path and almost everything else is set from the UI — `providers.toml` is just the starting point and where API keys live.
### From source (development — needs Node 20+)
```bash
git clone https://github.com/VforVitorio/marginalia.git
cd marginalia
cp providers.example.toml providers.toml
scripts/run.sh # macOS/Linux (Windows: scripts\run.ps1) — builds the UI from source, then runs
```
For frontend work, run the API and the Vite dev server separately: `npm run dev` in `frontend/` serves the UI on `:5173` and proxies `/api` to the backend.
## How it works
1. Export from the Scribe: Notebooks → hold the cover → Export/Share → PDF. Save it to your synced folder or drop it straight into the app.
2. Import: drag the PDF in, or point marginalia at your synced folder and pick from what's there.
3. Pick a backend: local for privacy, cloud for the hard pages. One click.
4. Review: page by page, fix what the OCR misread. A normal notebook takes a couple of minutes.
5. Export: choose how it lands in Obsidian (mirror folders, wikilinks), hit export.
## Customizing the OCR system prompt
Transcription quality depends on two things: the **model you pick** and the **instructions it gets**. The OCR runs with a system prompt tuned for Obsidian — LaTeX math (`$…$` inline, `$$…$$` blocks), callouts, checkboxes, tables, headings: the rich Markdown Obsidian actually renders. If you want to steer it (your own conventions, a different structure), it lives in one place:
- `backend/marginalia/ocr/prompts.py` → `system_prompt()` — the full instructions.
- `backend/marginalia/ocr/prompts.py` → `handwriting_prompt()` — the short per-page instruction.
Edit, restart the backend, done.
## Status
The MVP works end-to-end — import a Scribe PDF, OCR it (local or cloud), review side-by-side, export to your vault (that's the demo above). What's left before the first tagged release is polish: frontend linting, mobile/responsive tuning, a one-command install, and an end-to-end verification pass. Architecture and conventions live in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) and [CLAUDE.md](CLAUDE.md).
## Trademarks
Kindle and Kindle Scribe are trademarks of Amazon. Obsidian is a trademark of Obsidian Foundry. marginalia is not affiliated with, endorsed by, or sponsored by either — the names are here so you know what works with what.
## License
MIT. Use it, fork it, sell it, whatever — just keep the notice. No warranty. See [LICENSE](LICENSE).
## Contributing
PRs welcome, Scribe-only. Issues about other devices will be closed — not out of spite, just scope. Fork, branch, follow the conventions in [CLAUDE.md](CLAUDE.md), open a PR.
## Roadmap (later, maybe)
- One-command install (and maybe a packaged build)
- Process multiple notebooks at once
- Pull in Kindle highlights (`My Clippings.txt`)
- Custom export templates
- Full-text search across exports
- Scheduled pull from Drive
- Other devices — someday, not soon
## FAQ
**Why not just use the Scribe's built-in "Convert to text"?** Amazon's conversion emails you a flat `.txt`. marginalia drops the result straight into Obsidian — your Scribe folder structure mirrored, optional wikilinks, real Markdown (headings, tables, callouts, KaTeX math) — and lets you fix the OCR before it ever touches your vault. It can also run fully local, so nothing leaves your machine.
**Does it work with reMarkable, iPad, etc.?** Not yet, and not for the MVP. This is for the Kindle Scribe. If you use another device, there are better tools for it (Scrybble for reMarkable, Apple Importer for Apple Notes).
**Do I need an API key?** For local OCR (Ollama), no. For cloud, you either use your Claude subscription (no API key) or a free Gemini key from AI Studio.
**Does it run on Mac/Windows/Linux?** Yes — pure-Python backend, web frontend. Run on Windows, macOS, and Linux.
**What if the OCR is bad?** That's what the review is for: you see the original image and the text, and you edit it before exporting. If it's still bad, run that page through a cloud backend (Claude or Gemini) — they hold up better on messy handwriting.
## Contact
Issues for bugs and (Scribe-only) feature requests. Discussions for workflows and ideas. No Discord yet — maybe when there's a reason for one.