How BlackHole works

The usual failure mode for a notes app is taxonomy rot: if you don't categorize correctly on the way in, things get orphaned or misfiled and you can't find them later. BlackHole avoids that by separating two things people usually conflate. The folder is for your own browsing. Findability comes from the embedding index, the keyword index, and the knowledge graph, none of which look at the folder.

Extract clean text → repair encoding and detect language → write frontmatter (one model call, handed your existing tags and told to reuse before inventing) → pick a folder (one model call, constrained to folders that exist, returns a confidence) → link to related notes → write the file → embed into the index → update the graph. Indexing and graphing are incremental and never block the write. Every model call degrades to something reasonable with no key.

The filing step is confidence-gated. If the model clears 0.65 it files the note; if it doesn't, the note stays in your inbox where you can see it. So the worst case is “waiting in the inbox,” not “buried in the wrong folder.” And because links don't depend on the folder, a misfiled note still connects to the right things.

Lexical 0.45, vector 0.35, graph 0.12, tag 0.08. Lexical leads because an exact title match is almost always a real connection. Vector is close behind because it's the only channel that catches conceptual overlap with no shared words. Graph and tags are tie-breakers. A shortlist of 15 candidates gets one structured model call to decide placement (inline ≥0.65, related ≥0.55), and it still works without a model, just more bluntly. None of the channels reads the folder, so moving a note never breaks its links. The weights are a reasoned judgment call, not a tuned result.

Hybrid search (vector + BM25, fused with reciprocal-rank fusion) returns the top 12. That set expands one hop along wikilinks and backlinks into a working set capped at 60 notes. If those notes fit a 100k-token budget, it loads the whole notes, in order, not snippets. This is the Karpathy idea: chunked RAG fragments context, so if a coherent set fits the window, just load it. Only when the set overflows does it fall back to summaries, then to 1500-character excerpts. So chunking happens at query time and only on overflow. It never happens at intake, and most queries never trigger it.

Vectors miss exact terms and names; keyword search misses paraphrase. Running both covers the gaps. Reciprocal-rank fusion merges them on rank rather than raw score, so you don't have to calibrate a cosine similarity against a BM25 number. It also degrades cleanly: lose either index and the other still answers.

Everything already lives in one SQLite file (jobs, note metadata, keyword index, audit log). sqlite-vec puts the vectors in that same file: one store, one connection, no extra process, nothing to operate. For a desktop app that installs clean and runs offline, that's the right call. The tradeoff is that it does exact nearest-neighbor search, not approximate. Exact is great for a personal vault of tens of thousands of notes; for millions of documents you'd want an ANN index and probably a dedicated vector DB. We're the former, so we don't carry the weight of the latter.

The graph updates after each note and re-extracts fully overnight (deterministic, local, no model). A digest scheduler resurfaces notes each morning through four deterministic strategies (anniversaries, still-unread, buried gems, the current thread). A suggestion engine flags note pairs that share entities. All of it runs inside the app process on simple schedulers, no external cron.

In local and air-gapped mode, a process-wide guard patches socket.getaddrinfo (the name-resolution step every outbound call passes through) and blocks anything off the allowlist. A forgotten or future cloud call can't connect; it's blocked and logged. The Activity counter is the user-visible proof. In cloud mode, a redaction pass strips secrets (API keys, tokens, private keys) before any text is sent; PII is opt-in.