How it works

imprnt is plain markdown files on your computer. No database, no cloud, no app to log into. You talk to your assistant, and it drives imprnt underneath.

A model costs money every time it thinks, and it forgets everything between sessions. So imprnt gives it one job, the one that needs real understanding, and keeps it out of the parsing, the sorting and the searching. Which side a step lands on comes down to how often it runs.

write path Spend the model once runs once per note

you Hand over a source a transcript, a doc, a stray fact

model · paid It reads and sorts summary, tags, links, folder

result Clean notes one source can fan out into several

↓ filing writes in

the vault plain markdown files on your disk

↓ every search reads out

read path Search with cheap local code runs thousands of times

you Ask in plain words any question, all day long

code · free Code ranks every note counting, no model, no server

model It reads the top hits a handful of notes, then answers

When you write: the model works

Hand over a transcript or a document, and imprnt runs one pass of four steps: the model reads it, decides what it is, writes the summary, and picks the tags.

1. 1
   Copy code

   The source goes into raw/ untouched, hashed, with the obvious structure pulled out. Free.

2. 2
   Understand model the only paid step

   For each thing in the source: pick its type and folder, write a one-line summary, pull out the decisions and actions, and tag it with the words you will search for later, even if the source never used them. A dense source fans out into several small notes.

3. 3
   File code

   Look up people by name and alias, flag anything unresolved for review, and write the note without ever overwriting an existing one. Merging a renamed person into their old note is the model's call, made back in step 2.

4. 4
   Tidy code

   check rebuilds the index and flags broken links, topic and event notes that link to no person, organization, or thing, and any note with no tags. It never blocks and never silently drops anything.

Where a note lands follows the rules in Vault layout, and the model pays that cost exactly once per source.

Edits are cheap, originals are forever

renamed

Carl, Engineer → Boris, Director, right everywhere

one edit, old name kept as an alias

contradicted

the old date → the new date, the stale one still traceable

old line stamped superseded, never overwritten

One edit fixes a fact everywhere it appears. A rename is looked up by alias, so the correction lands in the existing note and "Carl" stays in the aliases for old references. Every other note points at that person by their permanent file ID, so one fix carries the new name and role across every meeting and project.

A contradiction never overwrites. The next pass flags it for review and stamps the stale line superseded, so a reader can see which fact won.

Your raw sources are kept forever, one untouched snapshot per source under raw/. To change how notes are structured, re-run the model over the originals: you pay the model once more and get the new layout across the whole vault, so you are never stuck in an old format. Any claim traces back to its snapshot.

When you read: plain code works

Ranking is arithmetic, so no model touches it. recall scores every note with BM25, a formula from the 1990s, pure arithmetic, no server. Three things set the score:

how often Repeats count

says your word 4 times says it once

Your search words are counted in every note.

how rare Rare words weigh more

"osteopath" "meeting"

A rare word narrows the search more than a common one.

where it sits Title beats body

in the title in the body

The same word counts more in a note's title than in its text.

The model only turns your question into search words at the start and reads the few best notes at the end. Nothing AI-made sits under the search: no embeddings, no vectors (numeric codes a model would have to compute for every note). recall hands back the top 15.

Three things sit on top of BM25, all on by default, each fixing a blind spot with more arithmetic:

• Stemming folds English inflections, so a note about swimming answers a search for swim, and policies answers policy. Any word not ending in a Latin letter is left alone, so Russian, Greek and CJK are untouched.
• Coverage rewards matching more distinct words from your query, because BM25 adds up its score per word and a note repeating one word could outrank a note that matched three.
• Proximity rewards your words appearing near each other, because BM25 discards positions entirely: double charge side by side scores the same as two hundred words apart.

Together they lift retrieval (the right note in first position) from 19.7% to 24.9% on the LoCoMo benchmark, at no measurable cost: 157 ms before, 134 ms after, on a real 308-note vault. Turn any of them off with --no-stem, --no-coverage or --no-proximity.

9 in 10 ~97% right note ranked first in the top five the assistant reads

Measured across the two example vaults and 39 everyday questions. A small test, and the number will move. Run bun run eval to check it yourself.

The eval/ folder holds the queries and the runner.

The whole loop, step by step

Step	Who	Why
Copy the source, hash it, log it code	code	mechanical, exact, free
Read messy prose to find its shape model	model	nothing to parse, it takes reading
Pick the type, write the summary, pull decisions model	model	needs real understanding, the conscious work
Assign tags, set the kind, wire the links model	model	judgment about meaning, paid once
File the note in its folder code	code	once the type is decided, writing is mechanical
Rebuild the index from every summary code	code	a plain read over the note headers
Rank notes for a search code	code	fast, free, clear, over thousands of notes
Turn a question into search words, read the top hits model	model	it is the interface, with the question in hand

Why no search server

Every tool call the model makes costs tokens, the units AI work is billed in, whatever the wires look like. The two levers are payload size and caching.

Payload size

live server the model re-fetches and re-reads on every read

imprnt code does the heavy scan, the model gets a tight result

Caching

live server a round-trip on every read, and whatever it caches is the vendor's choice, not yours

imprnt one batched sync caches locally, every read after is free

A live server answering search queries breaks both levers, so there is no query layer over the vault. A plugin’s sync is fine: one batched call that caches locally.

Core plus plugins

Always present: the core, meaning the vault plus ingest, recall and check. Everything else is an optional plugin you add or delete with one command, under one rule: the core never depends on a plugin. The how is in How plugins work, the why in Design decisions.