Read, reflect, and build a record of how you think.
让阅读留下自己的思考。
Native iOS · Local-first · Bring your own AI key
The idea · Features · Status · Build · Architecture · Contributing · License
Elsepage is an open-source iOS EPUB reader and personal thinking companion. Read a passage, write or speak what it brings to mind, and invite an AI response grounded in your reading and past reflections. Over time, those entries become a personal archive of ideas, questions, and changes in perspective.
Your original reflection is saved locally before an AI reply is requested. AI feedback, summaries, and personal memory are derived records; your own words remain the foundation.
The interface is primarily Chinese. ReadLoop is the engineering name used by the Swift package and Xcode project.
| Area | Current implementation |
|---|---|
| EPUB reading | Readium-based reader, reading position restoration, themes, highlights, notes, search, and user-initiated passage help. |
| Reflection | Text and voice input after reading, local save, follow-up discussion, and retry for a missing Agent reply. |
| Voice | On-device zh-CN recognition, editable partial transcripts, optional saved audio with playback, and separate BYOK text polish. Recognition requires an available on-device model. |
| Grounded feedback | Reading-session context, book evidence retrieval, links to cited passages, and connections to past reflections. |
| Personal Brain | Thoughts, questions, and memories with source evidence, revisions, editing, and deletion. |
| Data control | Local book/data storage, export, and deletion controls. App API keys are stored in Keychain. |
- Reading and saving text reflections work without a model connection.
- AI features use your own provider configuration and key. Provider presets include OpenAI, DeepSeek, Anthropic, and Gemini through their respective adapters; custom OpenAI-compatible endpoints are supported.
- Chat, optional embedding, and reranking requests go directly to configured providers. Requests can contain relevant book excerpts, reflections, and personal context. Those providers' policies apply to the data they receive.
- Elsepage has no proprietary backend or required Elsepage account. The current Chat adapters use non-streaming HTTP responses.
- The Agent stays quiet during reading unless you invoke it. See the product requirements for the full product invariants and accepted implementation deviations.
Under active development. The reading → reflection → saved response → journal flow and the Personal Brain domain are implemented. Implementation does not imply that every device, provider, or failure path has passed acceptance.
Current verification and release gaps are recorded in:
- DEBUG test loop: available device scenarios and their limits; full application E2E automation is still incomplete.
- Launch readiness: release work and outstanding acceptance items.
- Provider verification matrix: live provider checks requiring real keys.
Test counts and completion percentages are intentionally not fixed in this README. Check the results for the commit you are reviewing.
| Tool | Requirement |
|---|---|
| macOS / Swift | Swift 6; portable package targets declare macOS 14+. |
| Xcode | Xcode 16+ with the iOS 18 SDK for the iOS App target. |
| XcodeGen | Install with brew install xcodegen. |
| Dependencies | GRDB 7.11.1 and Readium 3.11.0, pinned in Package.swift and project.yml. Initial dependency resolution needs network access. |
git clone https://github.com/freecodetiger/Elsepage.git
cd Elsepage
swift testswift test runs the four package test targets. It does not compile App/ or run the Readium iOS integration tests. It may rewrite Package.resolved; record its state before testing and preserve existing changes when reviewing dependency-pin differences.
For a human developer building the iOS App:
xcodegen generate
open ReadLoop.xcodeprojSelect your signing team, resolve packages, and run the ReadLoop scheme. Keep personal signing settings out of shared commits. Configure a provider in the App to try AI feedback; a real API key is not needed for the portable test suite.
See the development guide for environment details and the contribution guide for verification responsibilities.
EPUB → Readium → reading session → locally saved reflection
↓
context planning and validation
↓
retrieval, ranking, and context assembly
↓
bounded Agent execution → saved reply
↓
journal and Brain maintenance
| Code | Responsibility |
|---|---|
| App/ | SwiftUI screens, dependency assembly, Readium integration, and DEBUG diagnostics. |
| ReaderCore / ReadingSessionCore | Reading locations, annotations, and sessions. |
| ReflectionCore / BrainCore | Original reflections, journal records, thoughts, questions, and memories. |
| RetrievalCore | Book indexing, lexical/semantic retrieval, optional reranking, bounded evidence expansion, and reading-boundary checks. |
| ContextRouting / ContextEngineering | Model-proposed context needs, deterministic policy, candidate ranking, and context budgets. |
| ReaderAgent / AgentRuntime | Product workflow and bounded model-call execution. |
| ModelProviders / Persistence | BYOK adapters, Keychain secret storage, and GRDB persistence. |
| SpeechCore / AppInfrastructure | Speech recognition, file handling, and shared App services. |
| BenchCore | Agent evaluation and regression comparison CLI. |
The Agent orchestrates routing, retrieval, replies, and derived records. Model calls run with explicit budgets; citations and proposed Brain changes are checked by code.
ARCHITECTURE.md is a historical Agent architecture snapshot. Use it with current source and the relevant feature specifications, rather than treating every old diagram or plan as current behavior.
Contributions are welcome: reproducible bugs, documentation, accessibility improvements, reader reliability, reflection UX, retrieval quality, and evidence-backed personal memory.
Start with CONTRIBUTING.md / 贡献指南. Issues and PRs may be written in Chinese or English.
- Open an issue for a bug or discuss a substantial feature before implementation. Small fixes can go straight to a PR.
- Work on a focused branch in your fork, or a repository branch if you have write access.
- Run checks appropriate to the change and state what was actually verified. Package tests, device scenarios, and manual acceptance have different coverage.
- Open a pull request targeting
main, describing the problem, resulting behavior, and validation evidence.
For priorities, follow the PRD:
Reflection Quality > Memory Quality > Reader Agent Quality > Habit Loop > Reader Feature Breadth
Contributions are provided under the project's GPL-3.0-only license. Preserve existing copyright notices and third-party license information.
- Development and repository map
- Product requirements and implementation deviations
- DEBUG verification workflow
- ReaderAgent Bench and regression requirements
- Release acceptance checklist
- Historical UI prototypes and brand assets
Copyright (C) 2026 freecodetiger and contributors.
Licensed under the unmodified GNU General Public License, version 3 (GPL-3.0-only), without additional exceptions or restrictions. Separately licensed files and third-party dependencies retain their respective licenses.