<p align="center"><a href="docs/design/BRIEF.md"><img src="docs/design/assets/logo/themes/prax-mark-bindery.svg" width="128" alt="The prax mark: a praxinoscope in elevation, printed in three passes in block, key and one colour facet"></a></p>

prax

prax is a self-hosted library for the papers, web pages, manuals and notes one person reads. Its search matches words and meaning at once, its graph records what the documents say about each other, and an AI agent can search and read it through the same interface its owner uses. Everything lives in one SQLite file and a folder of originals, on your own machines, with models you choose.

pip install -e ".[serve,work]"
export PRAX_DATA_DIR=~/prax-data
prax serve                                  # http://127.0.0.1:8000/ui/

prax add paper.pdf
prax add https://example.org/article
prax search feedback delay networks
prax ask --answer why do FDNs colour the tail

An empty store works from the first command. A new document is archived as it arrives, and prax work --watch, run on the machine with the models, does the rest: its text, title, graph links and vectors. To keep the parts running, list them under run: in prax.yaml and run prax up --install, which starts them at login on Windows, Linux or macOS. Setting up the Zotero import and the browser extension is in docs/howto.md.

Why I built it

My reading was spread over a Zotero library, an external disk I called zoetrope, a NAS and a year of browser tabs. I could only find a paper again if I remembered where I had put it. I wanted one place that keeps the originals and reads them closely enough to answer "which of my papers says this, and where". An agent working with me should be able to search it without being handed whole PDFs. I built prax with Claude Code over a few weeks in 2026. I decided what it should do and measured whether it did, and the log of that work is in docs/log.md. It is shaped by one library and one set of machines, and it is published so the design and the measurements can be read and reused.

One question, followed through

Say I want to know why a feedback delay network colours the tail of a reverb. A search from the shell returns documents, each with the passage that matched (the brackets mark the matched words) and where in the document it sits:

$ prax search feedback delay networks colour the tail
 …
 3. The Role of Modal Excitation in Colorless Reverberation             doc 9577
    [Feedback] [delay] [networks] (FDNs) are a computationally efficient
    structure for artificial reverberation…
     text · page 1 · THE ROLE OF MODAL EXCITATION IN COLORLESS R…
 4. Allpass Feedback Delay Networks                                    doc 13371
    …arbitrary connection of [delay] lines, namely [feedback] [delay] [networks]
    (FDNs). We present…

prax ask --answer goes further when there is a model on the host. It searches again with words of its own, reads on in the documents that looked promising and drops what does not help. Then it writes an answer whose citations point at the passages it kept. The trail of those steps is shown under the answer, so you can see why a source was used.

<table> <tr> <td width="50%"><a href="docs/images/search.png"><img src="docs/images/search.png" alt="Search results in the web UI, each hit marked with the side that found it"></a></td> <td width="50%"><a href="docs/images/ask.png"><img src="docs/images/ask.png" alt="An answer in the web UI with its cited passages beside it and the model's four steps of searching and reading under it"></a></td> </tr> <tr> <td>_{In the web UI each hit says whether keywords, vectors or the document's own summary found it.}</td> <td>_{Here the model searched again and read on before answering, and the trail under the answer shows each step.}</td> </tr> </table>

An agent asks the same library through the MCP server, and what comes back is sized for its context window. The same question asked by an agent, with three hits, is 1.8 KB of JSON. It opens with the region of the library the hits live in, and each hit carries a cite link that still finds the passage after the document is re-chunked:

{"doc_id": 270, "title": "Building the Erbe-Verb: Extending the Feedback Delay Network Reverb for Modular Synthesizer Use",
 "snippet": "…on a 4-[delay] [feedback] [delay] network [reverb] (FDN) as proposed by…",
 "heading": ["…", "2. BASIC DESIGN"], "page": 1, "published": "2015",
 "cite": "#doc/270?chunk=1757785&find=a+unitary+feedback+matrix"}

The agent can then ask how two things are connected. Asked for "feedback delay network" and "Schroeder reverberator", connect answers in 1.2 KB with one path of two steps through a paper on scattering delay networks, and each step quotes the sentence it rests on. One says the paper uses the Schroeder reverberator: "Starting with the Schroeder reverberator [3, 4], a wide variety of approaches for room acoustics simulation have been introduced…". The other says it uses feedback delay networks, on the strength of "…found that they perform better than Feedback Delay Networks (FDNs)". That is a generous reading, and because the quote comes with it, an agent or a person can see so and weigh it.

What it does

Reading figures with the words around them

Most PDF tools stop at the text. prax pulls each figure out, or renders the region above its caption when the figure was drawn with vector paths. A vision model then reads it together with the paragraphs that refer to it. That is why a plot comes back as "the frequency responses of the five learned CNN kernels against the ground truth filter" instead of "six stacked curves". The reading is a passage of the document, so you can search for a figure by what it shows, cite it, and an answer can use it. A scanned book with no text layer is read the same way, page by page.

<table> <tr> <td colspan="2"><a href="docs/images/vision-with-context.png"><img src="docs/images/vision-with-context.png" alt="A figure in the document view: the image, its caption, and the vision model's reading of it naming each step of the process"></a></td> </tr> <tr> <td colspan="2">_{The reading names the process the figure shows and its four steps, because the model was given the caption and the text that refers to it.}</td> </tr> <tr> <td width="50%"><a href="docs/images/image-recognition.png"><img src="docs/images/image-recognition.png" alt="A schematic as a document, described and transcribed by two vision models"></a></td> <td width="50%"><a href="docs/images/citations.png"><img src="docs/images/citations.png" alt="A paper's reference list in the document view: each entry a chunk of its own, and under it the library document it cites, matched by title with its score"></a></td> </tr> <tr> <td>_{A schematic read by two vision models; both readings are kept, each with the model that wrote it.}</td> <td>_{The entries of a paper's reference list are matched against the library, and the [12] in the text links to the paper it cites.}</td> </tr> </table>

A graph whose links say where they came from

A model reads each document against a small ontology: which paper uses which method, which manual belongs to which piece of gear, which recipe needs which ingredient. Every link it writes records the document, the sentence, the model, the batch it ran in and the ontology version. I wanted that because models misread papers, and a link I cannot trace to a sentence is one I cannot check. When a later reading disagrees, the old link is given an end date and kept. A database trigger refuses any attempt to delete a link or change what it says, so you can ask what the graph said on a given day. A whole batch from one model can be withdrawn without touching anyone else's work. A fact that states its own date ("she worked at the lab from 2019") keeps that date apart from the date prax learned it. Names are kept apart from things: apple the ingredient and Apple the company are two entities, and a merge of two names into one thing can be taken back.

<table> <tr> <td colspan="2"><a href="docs/images/graph.png"><img src="docs/images/graph.png" alt="A method's neighbourhood in the graph view, every link with its evidence and its source"></a></td> </tr> <tr> <td colspan="2">_{A method and its neighbours, where a link shows how sure the extraction was, which model wrote it, and the document and sentence it came from.}</td> </tr> </table>

Search

Keyword (SQLite FTS5) and vector search run over the passages and over a short description of each document. The four lists are merged per document, and you can filter them by kind of document or by subject. Acronyms the library defines ("feedback delay network (FDN)") are expanded on the keyword side. Each hit shows when its document was published, as precisely as the source says, so you can ask for only what appeared after a given year. A document that a newer one replaced is still found, a few places lower, with a note naming its replacement. The numbers, with their caveats, are further down.

Pages of your own

Notes, project logs and write-ups are Markdown pages with a revision history, and they are searched and read like any other document. A link from a page to a document becomes a link in the graph. If you put a question between two comment lines, prax answers it there with sources and answers again when new documents arrive. The second time, the model sees its earlier answer and is told what is new, so it revises. If you edit inside an answer, prax leaves that block alone. A daily briefing page lists what arrived and which answers changed.

<table> <tr> <td colspan="2"><a href="docs/images/ask-block.png"><img src="docs/images/ask-block.png" alt="A page of one's own notes with an ask block: the person's prose and links above, the answer below with the question on its rim, the documents the page links and cites beside it"></a></td> </tr> <tr> <td colspan="2">_{A page of notes with a standing question in it; the documents the page links and the ones the answer cites are listed beside it.}</td> </tr> </table>

And the rest

• Documents come from a Zotero library (read from a copy, never written to), a drop folder, and the browser extension. The extension sends the page you are reading as a self-contained snapshot, a paper as its PDF and a YouTube talk as its transcript and frames. prax import reads exports from GitHub stars, chat apps, bookmarks, Pocket, Raindrop and Medium, and prax sync sends a project's notes from its git working copy.
• PDFs are read by MuPDF with optional OCR, or by marker when you want the maths as LaTeX. HTML goes through trafilatura, and Word files, code and LaTeX sources have parsers of their own.
• Rules flag documents that look personal (a bank statement, a letter) and you decide. A token handed to an agent or another machine sees only the domains you give it and no personal documents. Because the filter sits in the store, search, the graph and answers all leave out the same documents.
• prax heal lists recurring damage (a placeholder entity, a page captured twice, a scan filed under its cover's title, figures not yet read) and prints the command that fixes each. A fix hides a wrong document with its history and deletes nothing.
• The UI has six themes, each four colours that change the page and the logo together (docs/design/BRIEF.md).

Ways in

The web UI at /ui/ has search and ask, a document with its context and figures, the graph, the review queue, your pages, the inbox and the jobs. The prax command covers the whole library from a shell, and it is how I use it most:

prax                              where things stand, what to type next
prax search granular synthesis    find documents
prax ask -