From Reading Rut to Reading System

Building an LLM-powered book companion.

The Spark

Last year, stuck in a reading rut, I picked up Michiko Aoyama's What You Are Looking For Is in the Library. It's a quiet book. Five people in Tokyo, each struggling with something, each finding their way to a community library where a librarian named Sayuri Komachi hands them exactly the book they didn't know they needed.

The magic isn't in the recommendations themselves. It's in how Komachi sees people. She doesn't ask "what genre do you like?" She observes. She listens to what they're struggling with. Then she hands them a book, sometimes unexpected, sometimes oblique, and it unlocks something.

I wanted that. Not the mystical intuition, but the process: someone understanding why I'm reading right now, what I'm avoiding, what I actually need versus what I think I want.

So I built it myself. Karpathy's line keeps coming back to me: agency > intelligence. The willingness to just start, to build the thing you wish existed, matters more than having all the answers first.

Three Problems, One System

Reading intentionally requires solving three distinct problems:

Finding serendipity systematically. Most recommendation systems optimize for "you liked X, here's more X." But growth happens in the adjacent possible. Books that surprise you yet feel right.

Building your own syllabus. I've always wanted to be a lifelong learner. Not in the vague aspirational sense, but practically. Seeing people online who read systematically across domains, who build knowledge deliberately over years, made me want that structure for myself.

Each domain has a different why. This year: classic literature to understand craft, deep fiction to rebuild my attention span, neuroscience for habit-building, and applied ML/System design books for engineering depth. A good reading system should understand the motivation, not just the topic.

Digesting what you read. Books aren't complete when you finish them. The reflection: what did this change in me? What craft did I learn? What do I want next? That's what transforms reading from consumption into growth.

The Design: Four Stages

I broke Komachi's intuition into components:

Stage 1: The Interviewer

Not "what books do you like?" but "what brings you here today?"

The goal is understanding the person deeply, beyond their immediate ask. The interview covers five areas: intention, current reading, interests and dislikes, habits, and pitfalls. One question at a time. No compound questions. The output is a reading profile that captures why, not just what.

The prompt philosophy: sound human, stay adaptive, prefer specifics over labels. "What's the pacing you enjoy?" beats "do you like fast or slow books?"

Stage 2: The Context Builder

This is where explicit preferences become latent features.

Someone says "I like mysteries." Not useful. The context builder infers: slow-burn atmospheric tension, unreliable narrators, prose that rewards attention. It extracts moods, pacing preferences, how adventurous they're feeling, when they read, and what to avoid.

The output is a compact JSON profile the recommender can actually use.

Stage 3: The Syllabus Builder

Matching books to the reader's current moment. Not "best books" but "best books for you right now."

The prompt explicitly counteracts LLM recommendation biases:

• Popularity bias: A lesser-known book with perfect fit > famous book with weak match
• Position bias: Don't favor candidates listed first
• Generic explanations: "Compelling characters" is weak. "The slow-burn character study aligns with your preference for introspective pacing" is useful.

Motivation match gets highest weight. Then mood alignment, pacing compatibility, thematic resonance.

Avoidance signals are hard constraints, not preferences.

Stage 4: The Reflection Partner

The back of Pachinko has reading group questions. I'd always skipped them. But the format stuck with me. Structured prompts for reflection. What if finishing a book always invited that kind of pondering?

The reflection captures: one-sentence distillation, craft lessons noticed, personal insights. And crucially: what are you hungry for next? More of this? Ready for a challenge? Need a palette cleanser?

That last question closes the loop. Your post-read appetite feeds back into recommendations.

The Build

Stack

Python with typer for CLI, pydantic for validation, rich for terminal output, and the Anthropic SDK. All data stored locally in JSON. Human-readable, version-controllable, portable.

Why MCP?

I chose to build this as an MCP server. The reasoning:

Ecosystem integration. The reading companion lives wherever Claude lives. No context switching to a separate app. You're in a conversation about something else, mention you finished a book, and the reflection tools are just there. Reading practice becomes ambient rather than ceremonial.

Shareability. A CLI app requires cloning a repo, installing dependencies, configuring API keys. An MCP server can be shared as a config snippet. Lower friction means people might actually try it.

Composability. MCP servers coexist cleanly. The reading companion works alongside other tools. Boundaries are clear.

The alternatives felt less right. A web app meant infrastructure overhead. A Claude Project with custom instructions lacks structured persistence. A pure CLI requires context-switching and makes sharing harder.

Process

Claude Code in plan mode became my collaborator. Map out the architecture before writing code, then execute phase by phase. The prompts went through several iterations. The interviewer especially needed tuning to avoid the "interviewer who talks too much" trap.

How It's Meant to Feel

I didn't want a reading tracker that demands daily check-ins. I wanted something closer to a knowledgeable friend who remembers everything.

While reading: Gentle check-ins when books come up naturally. "How are you finding it?" Not a survey. Just presence.

When finishing: A structured moment of reflection. The pause that turns finishing into having read.

When deciding what's next: This is where the system earns its keep. You're between books, that particular restlessness of not knowing what to read. The system knows your domains, your past reflections, your current appetite. It can say: "You've done three heavy literary novels in a row. Your last reflection said you wanted something lighter. Here's a suggestion from your neuroscience stack. Short, practical, a change of pace."

That's the Komachi moment. Not just "here's a good book" but "here's what you need right now."

What Surprised Me

Interview design is harder than it looks. More questions, less interest. Every extra question costs engagement. The UX research on conversational preference elicitation taught me that depth and engagement are in tension. The interviewer went through several iterations to find the minimum viable depth. Enough to understand the person, not so much that they disengage.

Building the system taught me to reason about recommendations. When you design a prompt that explains why a book fits, you internalize that reasoning. I started noticing the logic in my own choices. Why this, why now, what am I actually seeking?

Latent features changed how I think about preferences. Before: "I like literary fiction." Now: slow-burn pacing, unreliable narrators, themes of displacement. Designing the context builder forced me to articulate what I'd only felt.

Reflection is where the real reading happens. I underestimated this. The structured pause, the one sentence takeaway, craft lessons, what do I want next. It turns finishing into a small event. Discussions extend the book's life beyond the last page.

Stopping books is signal too. When I abandon a book midway and log it, that's data. Three dense nonfiction DNFs in a row tells me something. Maybe I need narrative. Maybe I need shorter. The system treats abandonment as information, not failure.

Research Threads

For those who want to dig deeper, here are the threads that shaped the design:

Conversational interviewing. UX research on preference elicitation reveals a core tension: depth vs. engagement. Compound questions kill clarity. More details often mean less user interest. The interviewer prompt went through iterations to find the balance. Enough to understand the person deeply, not so much that they disengage.

Latent feature extraction. The gap between "I like mysteries" and "I like slow-burn atmospheric tension with unreliable narrators" is the gap between useless and useful. See collaborative filtering literature on implicit vs. explicit feedback.

Context and memory. Building the context layer surfaced harder problems: how do you represent a reader's evolving state? What's the equivalent of "world memory" for a reading companion? This connects to broader research on personalization, user modeling, and long-term context in recommendation systems.

LLMs as recommenders. There's growing research on LLM recommendation systems and their biases: popularity, position, verbosity. The syllabus builder prompt draws on this work to counteract them.

Feedback loops. Reflection data flowing back to recommendations. Not just "what did you say you wanted?" but "what did you actually finish? what did you abandon? what appetite did you express afterward?"

Open Questions

The gap between stated and revealed preferences. If someone says they want "challenging literary fiction" but their reflections consistently show they enjoyed the comfort reads more, does the system notice? Should it gently push back, or adapt silently?

Social reading. This is currently a personal tool. But meaning-making from books often happens in discussion. Is there a version of this that's communal?

The limits of codification. Komachi's magic might be irreducible. She gives each visitor a handmade felt ornament. A sheep for one person. An airplane for another. Little talismans that mean something only to the recipient. Can structure capture that? Or does the attempt to systematize intuition necessarily lose something?

Coda

I can't make my system produce felt ornaments.

But the structured reflection is my version. The one-sentence distillation, the craft lessons, the "what do you want next." A small thing to carry forward from each book.

Maybe that's enough.

The code is available as an MCP server: github.com/aby0/reading-companion