Inspiration
I do most of my long-form reading on a Kindle, but I often want to stop at a sentence and ask a question, make a comment, or leave a thought for an AI reading companion.
Switching from the book to a separate chat app breaks the reading experience. It also removes the context: the AI sees my question, but not necessarily the exact passage that made me ask it.
I wanted something quieter and more asynchronous — less like opening a chatbot, and more like leaving a letter in the margin of a book.
That idea became Margin Mail.
What it does
Margin Mail is a local-first, Kindle-friendly reading system for asynchronous conversations with an AI reading companion.
A reader can:
- Import TXT books
- Open the reader from a Kindle browser over a private local network
- Read using a lightweight page-turning interface designed for an e-ink screen
- Leave a Quote, Note, or Question attached to a passage
- Return the AI reply to the original reading context, where it can be opened from the Kindle or desktop reader
Instead of requiring the reader to remain inside a chat window, Margin Mail lets the conversation happen inside the reading experience.
The result feels less like prompting an assistant and more like exchanging letters with a reading pen pal.
How we built it
Margin Mail began as a lightweight local text reader. For this project, I redesigned it as an asynchronous AI co-reading system that could work on both a Windows computer and a memory-constrained Kindle browser.
The system includes:
- A Python-based local Reading Room server
- A browser reader built with HTML, CSS, and JavaScript
- Local JSON storage for books, reading progress, annotations, and replies
- A restricted, token-authenticated Agent API
- A Node.js Local Companion that receives reading events
- Stable source anchors that connect questions and replies to their original passages
- A low-memory Kindle reading mode that avoids rendering an entire chapter at once
OpenAI Codex acts as the reading companion in the current prototype. It reads pending questions through the restricted Agent API and writes replies back to the Reading Room.
I designed the product concept, interaction flow, interface, safety boundaries, and real-device test cases. I used Codex as an implementation partner to build, debug, and iterate on the system. The private prototype also includes a local Windows notification bridge. The public Margin Mail demo currently focuses on the isolated Kindle-to-Agent reply workflow.
Challenges we ran into
The largest challenge was not the AI response itself — it was making the complete reading experience work reliably on a Kindle.
The first pagination implementation loaded an entire virtual chapter at once. One test chapter contained:
- 34 internal text chunks
- 2,159 paragraph elements
- 833 simultaneously laid-out visual pages
- An 18.9 MB web font
This worked on a desktop browser but exceeded the Kindle browser's available memory.
We redesigned the Kindle reader around a lightweight source window, system fonts, and incremental pagination. Only the text near the current page remains active in memory.
Another challenge was preserving text correctly across page boundaries. A visual page is temporary, but a question must remain attached to the same source sentence even after the font size, page layout, or screen orientation changes. We therefore store annotations using source chunk, paragraph, and character-offset anchors instead of permanent visual page numbers.
We also had to account for inconsistent EPUB structures, legacy annotations, unreliable touch selection on Kindle, local authentication, and safe communication between the reading server and the Agent.
Accomplishments that we're proud of
The complete asynchronous loop now works:
- A reader leaves a Question from the Kindle
- The local Agent API exposes it to the AI reading companion
- The AI writes a contextual reply
- The Reading Room emits a reply-ready event
- The Local Companion displays a Windows notification
- The reader returns to the original passage and opens the reply
We are especially proud that this is not only a desktop prototype. It has been tested through real reading sessions on a Kindle e-ink device.
The books and annotations remain local. The Agent receives access only through a narrowly scoped token-authenticated interface.
What we learned
We learned that designing for a constrained real device changes almost every technical decision.
A feature that appears inexpensive on a desktop — custom fonts, whole-chapter rendering, exact total-page calculation, or preloading every annotation — can become the dominant memory cost on an e-reader.
We also learned that AI-assisted building does not remove the need for product design or testing. The most important work was repeatedly observing the real experience, identifying where the interaction failed, defining precise safety and data requirements, and translating those observations into testable implementation rules.
What's next for Margin Mail
Next, we want to add:
- Profile-aware desktop notifications for the public demo workflow
- Offline book packs for airplane-mode Kindle reading
- An offline Question outbox that syncs when Wi-Fi returns
- Reading Journal export, combining passages, reader questions, and AI replies into Markdown and archival JSON
- Finished-book archiving and safe cleanup
- Improved EPUB chapter and table-of-contents handling
- A public, configurable open-source edition with generic assistant branding
- Reliable semantic EPUB import
- Markdown and HTML support
The long-term goal is a calm, local-first reading environment where an AI companion does not interrupt the book, but quietly meets the reader inside it.
Log in or sign up for Devpost to join the conversation.