bkb — Books Knowledge Base Manager

Turn your reading reflections into a personal, connected knowledge base.

bkb is a small CLI plus an agent pipeline for building a "second brain" out of the books you read. After a reading session you journal a raw reflection — in your own language, in your own words. An AI agent (via Claude Code Skills) translates it if needed, synthesizes it into concepts while preserving your voice, and — this is where it's most useful — notices when a concept from one book echoes or contradicts one from another.

bkb itself stays deliberately thin: it tracks what's pending and what's been processed. It never writes your reflections or your concepts for you; the agent does that, with your approval at every step.

How it works

journal  →  translate  →  synthesize concepts  →  connect across books

1. Journal. After a reading session, write (or transcribe) a raw reflection into books/<book>/journal/YYYY-MM-DD-N.<lang>.md.
2. Translate. If you journal in a language other than the KB's working language, the agent translates it, preserving your reflective, informal tone.
3. Synthesize. The agent proposes book-level concept files, grounded in your journal entries, keeping your own phrasing and doubts rather than a textbook restatement. You approve before anything is written.
4. Connect. Once you have concepts across a few books, the agent looks for genuine cross-book connections — the same idea appearing in two authors, in tension or in agreement — and proposes a cross-book concept file. You approve before anything is written.

bkb init scaffolds every new knowledge base with an AGENTS.md (the full pipeline spec), a CLAUDE.md, and .claude/skills/{translate,synthesize,connect}/SKILL.md — the agent reads these to know how to run each phase. bkb itself only exposes list (what's pending, as JSON) and complete (mark it done) for each phase; see AGENTS.md in a scaffolded KB for the full command reference.

A note on language choices

Right now the KB's working language is hardcoded to English, and journal entries can be in whatever language you name in the filename. That's not a general design principle — it's just my own setup: Spanish is my mother tongue, so reflections and thoughts flow more naturally in it right after a reading session, but I mostly read in English, so that's the language I want my synthesized concepts in. If your setup is different, letting bkb init ask for your preferred journal and KB languages is on the roadmap below.

Installation

Requires uv and Python 3.14+.

uv tool install git+https://github.com/rmunoz/bkb.git

To update:

uv tool upgrade bkb --reinstall

You'll also want an AI coding agent that supports Skills and AGENTS.md (e.g. Claude Code) — bkb handles the bookkeeping, the agent does the reading, translating, and synthesizing.

Usage

1. Initialize a knowledge base

$ bkb init philosophy-kb
Describe the domain and goals of this knowledge base (optional): Self-study in philosophy, starting from the Greeks, tracking how different thinkers' arguments connect and challenge each other over time.
Initialized knowledge base at /Users/you/philosophy-kb

This creates:

philosophy-kb/
├── AGENTS.md
├── CLAUDE.md
├── README.md
├── .claude/skills/{translate,synthesize,connect}/SKILL.md
├── books/
│   └── books.yaml
└── concepts/            # cross-book concepts land here

2. Add a book

$ cd philosophy-kb
$ bkb books add
Title: Meditations
Subtitle:
...

This creates books/meditations/{journal,concepts}/.

3. Journal after each reading session

Drop a reflection at books/meditations/journal/2026-07-08-1.es.md (name it in whatever language you think in) with frontmatter:

---
processed: false
---

<your raw reflection>

4. Run the pipeline with an AI agent

Open the knowledge base directory with a Skills-capable agent and ask it to translate, synthesize, or connect. The agent runs bkb translate list / bkb synthesize list / bkb connect list to see what's pending, does the actual reading and writing itself, shows you the result, and runs bkb translate complete / bkb synthesize complete once you've approved it.

Example workflow: self-studying philosophy

Sara is working through the history of philosophy on her own, starting with Plato and moving forward. After each reading session she records a short voice reflection in Spanish — her honest reaction, what confused her, what she's unsure she believes yet. bkb translate turns it into English without smoothing over her uncertainty; bkb synthesize turns a handful of entries on Meditations into a concept file on Cartesian doubt, grounded entirely in her own reflections and phrased the way she actually thinks about it — she reviews and approves it before it's written.

Months later, after she's also read the Nicomachean Ethics and Beyond Good and Evil, she runs bkb connect. The agent notices that her own notes on "the good life" show up independently in both books' concept files — with Aristotle and Nietzsche pulling in different directions — and proposes a cross-book concept file laying out the tension. That's the connection she wouldn't have made on her own, months and several books apart: not a generic "these philosophers disagree" summary, but one grounded in what she actually wrote at the time.

Roadmap

• Reading timeline — static HTML per book showing how the reader's notes evolved from the first entry to the last.
• Book concept graph — static HTML site per book visualizing its concepts and their relationships (inspired by Google's Open Knowledge Format).
• Global concept graph — the same, across the whole knowledge base.
• Audio ingestion — integrate Whisper so bkb can transcribe voice reflections itself.
• Podcast generation — turn a book's (or chapter's) concepts into an audio recap for review on the go.
• AI-generated quizzes — challenge the reader on synthesized concepts to reinforce retention.
• Configurable languages — let bkb init ask for the preferred journal and KB working languages, instead of the current hardcoded Spanish-notes/English-KB assumption tailored to my own use.

Under consideration:

• Spaced-repetition export (e.g. an Anki-compatible deck) generated from concept files, for longer-horizon retention than one-off quizzes.
• Semantic search across journals and concepts — "ask your knowledge base."
• Socratic dialogue mode — an agent-led session of follow-up questions that probes whether understanding actually holds up, rather than testing recall.
• bkb status — a quick per-book dashboard of what's pending translation or synthesis.

Inspiration

bkb isn't a faithful implementation of either of these, but it wouldn't exist without them: Andrej Karpathy's idea of an LLM-maintained personal wiki — journaling raw thoughts and letting an LLM continuously synthesize and refine them into structured knowledge — shaped the journal → synthesize pipeline, and Google's Open Knowledge Format shaped how concepts and their connections are meant to be structured and (eventually) rendered.