Knode: Grounded answers across your personal knowledge

Canonical MVP guide.

Picture the highlights from books you have read on Kindle, the travel scraps your family keeps in OneNote, a photo of a menu you loved, or a voice memo after a hard day. Knode is built around a simple idea: ask in normal language, and get answers that pull from your own saves and point back to them, so themes connect across reading, notes, and plans instead of sitting in separate apps.

The first version proves that on Windows with Kindle reading you export into a local corpus.jsonl, then index and Ask with sources, using Google Gemini. Down the road, the same pattern extends to more of your repositories and formats (notes, documents, images, audio, video, and transcripts), still grounded in what you chose to keep.

1. Product: intent, personas, scenarios, requirements, success

Elevator pitch

Knode is a Windows desktop assistant that answers natural-language questions about your own Kindle reading using highlights and notes you ingested into a local corpus.jsonl. Answers are retrieval-grounded: the model sees your passages first, then synthesizes with citations (book, location, quote). The wedge is personal, citation-backed recall, not generic web chat.

Repository policy: The GitHub repo ships source and docs only: no corpus.jsonl, no sample highlights. **/corpus.jsonl is gitignored at repo root. After clone or install, every user produces or selects their own corpus (see §4).

Problem

Highlights in Kindle Notebook are organized by book, but themes span books. Finding “what did I read about confidence?” across the library is slow; keyword search misses concepts. Users want their reading connected by topic without fabricated quotes.

Primary persona (MVP)

Alex, the returning reader

• Reads on Kindle, highlights actively, reviews in Notebook.
• Wants: “What have I read about X?” before journaling, prep, or decisions.
• Expects book-level references on claims and, when retrieval supports it, cross-book threads (same theme, contrast, progression).
• Accepts a practical ingestion path today: export / capture → structured file → app (see §4), while the product language still points at Notebook as source of truth.

Scenarios (as shipped + near term)

Functional requirements (MVP: implemented vs gap)

Non-goals (unchanged)

• Live Microsoft / Google / WhatsApp connectors in v1.
• Social, shared, or public corpora.
• Agents that act outside read → reason → answer (no calendar/email actions).

Success criteria (MVP)

2. Design: options, choice, reasoning (succinct)

What we wanted (official)

Programmatic, documented access to the same highlights the user sees in Kindle Notebook, ideally OAuth + REST (clear ToS, rate limits).

What we verified

• No published Kindle Notebook API for third-party highlight export.
• Login with Amazon is identity, not Notebook payloads.
• Amazon Data Portability Kindle-related scopes are not “export all Notebook highlight text” as of our review.

Conclusion: MVP must use user-mediated or session-based extraction, with legal/ToS review before any broad release.

Options considered (abbreviated)

Chosen path (MVP)

1. Spike: Option B: WebView2 (spike/webview-notebook) to prove login + readable capture from Notebook.
2. Normalize: Dedupe captures → parse_dump → corpus.jsonl (deterministic, no DOM at query time).
3. Ship: Knode reads JSONL, embeds with Gemini, stores vectors under %LocalAppData%\Knode\index\, answers with Gemini chat.

Reasoning: Single installer story, offline replay of parsing from text, and no dependency on Amazon DOM at RAG time, only at export time. Extension remains the upgrade if WebView login grows painful.

3. Architecture: layers, data flow, technologies

Deep dive (tiers, components, vector stores, Ask sequence): KNODE-ARCHITECTURE.md

Layered view (static summary)

Optional Python path (prototyping): same corpus.jsonl → ChromaDB + sentence-transformers + query_cli; OpenAI optional for synthesis only. See mvp/README.md.

4. Corpus, install, and first run

You need a local corpus.jsonl (one JSON object per line). It is not in git and not bundled in installers. Without a public Kindle Notebook API, a dev or power-user pipeline produces the JSONL contract the app expects.

Typical pipeline (this repo):

1. WebView spike: spike/webview-notebook/README.md (Notebook login, per-book capture to spike_extract.txt).
2. Dedupe: dedupe_spike_extract.py → spike_extract_deduped.txt.
3. Parse / validate: from mvp/, run parse_dump and validate_corpus (see mvp/README.md). Output: mvp/data/corpus.jsonl. validate_corpus exits 0 only when every row has a non-empty book_title; fix author gaps for best citations before indexing.
4. In Knode: browse to the JSONL, Build index; after corpus changes, use Force full re-embed if highlight ids shifted (see parse_dump and title hashing).

Fallback: Any tool that emits the same JSONL shape works; My Clippings.txt is valid if you convert to that shape.

Runbooks (read in this order):

1. KNODE-INSTALL.md. Installer, prerequisites (.NET 8 Desktop Runtime, WebView2), SmartScreen.
2. KNODE-FIRST-RUN.md. Corpus path, API key, Build index, first Ask, troubleshooting.

Also useful: security and keys SECURITY-AND-RELEASES.md; engineer-oriented tiers KNODE-ARCHITECTURE.md; diary JOURNEY.md. Product vision and future sources: §5.

5. Vision and future sources

This section is the public north star. It stays high level so contributors and readers share the same direction without publishing private details.

What we are building toward

The through-line is your material in, cited answers out: retrieval and reasoning stay anchored to snippets, files, or media you ingested, not the open web. Experiences stay goal-directed (scoped questions, cross-source synthesis) rather than an open-ended agent running your machine.

Scenario themes (illustrative, not a commitment list)

• Reading and big moments: Connect highlights across books before a career or life decision; surface themes and tensions you already captured.
• Family and travel notes: Patterns across itineraries, preferences, pace, and places (e.g. from notes or planners you control), with answers tied to those entries.
• Voice and text together: Questions over transcripts, memos, and typed notes in one personal corpus, once ingestion supports them.
• Video or talks plus reading: Relate something you saved from a clip or lecture to a passage you highlighted, with pointers to both.
• Cross-corpus bridges: Link ideas between unrelated repositories you own (for example, a theme in reading and a pattern in trip notes).
• Work knowledge: Recall across meeting notes, specs, or exports you choose to ingest, with provenance on each claim.

Technical building blocks for engineers stay in §3 and KNODE-ARCHITECTURE.md.

Private scenario notes (local only, not for GitHub)

Rich vignettes (real names, employers, trips, or exploratory copy) belong in a local-only markdown file, for example docs/VISION-SCENARIOS.local.md, and should not be committed. Filenames ending in .local.md are gitignored at repo root so you can iterate privately; keep the canonical guide to sanitized bullets here in §5.

Revision log