Local · Private · Accurate

Your Private Second Brain for AI

An AI assistant that remembers your notes — finds the right one, answers only from it, shows the source, and says “I don’t know” instead of making things up.

01 Architecture

The system runs as a nine-stage pipeline. Select a node, press Play to step through each stage, or drag and zoom the diagram.

Loading interactive diagram…

02 What it does

Every AI assistant forgets your context. This system does not. It works in three steps:

Step 1

Index your notes

Your markdown notes are read and organised into a private search index — all on your own machine, nothing leaves it.

Step 2

Find the right note

When you ask a question, the system picks the few notes that are actually about it — not every note you own.

Step 3

Answer from your notes

The AI answers only from those notes and shows its source. If nothing matches well enough, it says “I don’t know”.

03 Why it matters

Costs less — it reads less

AI is billed per “token” (roughly, per word it reads). Most AI tools paste everything into the conversation. This system only sends the few notes that match your question.

Real example

You have 1,000 notes. You ask a question. Only the 3 most relevant notes are sent to the AI. That’s ~99% less text — cheaper and much faster answers.

Read more — how we reduce tokens
What“Embedding” turns text into a list of numbers that capture its meaning, so notes can be compared by meaning, not just keywords.
WhereUsed while indexing (step 1) and searching (step 2) to find only the relevant notes.
WhySo the AI never reads your whole vault — only the small relevant slice — cutting tokens by ~99%.

Notes are split into small chunks (about 200 words each) so the AI can retrieve exactly the piece it needs, and unchanged notes are skipped on re-index so we don’t re-process them again.

No more made-up answers

Generic AI can “hallucinate” — confidently invent answers when it doesn’t know. This system forces the AI to answer only from your notes and to show its source and a match score.

Real example

Before: “Your last project used a cloud database.” (invented)
After: “Your last project used a local database. Source: local-retrieval-pipeline.md · match 0.96.” (true, with proof)

Read more — how we stop hallucination
What“Similarity score” tells us how close a note is to your question — 1 means identical, 0 means unrelated.
WhereUsed in step 3 when deciding which notes the AI is allowed to answer from.
WhyIf no note scores above the threshold, the AI must abstain (“I don’t know”) instead of guessing.

Two rules enforce this: the system prompt says “answer only from the retrieved chunks and cite the source”, and a similarity threshold means low-confidence questions are refused rather than invented.

$$ \text{answer allowed} \iff \max_{d} \text{sim}(\text{query}, d) \ge \tau $$

Answers grounded in your real notes

Because answers are built from your own notes instead of the AI’s guesses, they match what you actually wrote — and we measure that accuracy so you can trust it.

Real example (measured on our demo vault)

The right note is the top result 75% of the time, and the right note is always found within the top 5 (100% recall).

Read more — how we measure accuracy
WhatWe test the system with real questions where we already know the correct note, then measure how often it finds it.
WhereRun python3 scripts/evaluate_retrieval.py to regenerate the numbers on your own notes.
WhyNumbers you can see beat promises — you can watch accuracy improve as you refine your notes.

04 How the machine works

Diagrams generated from the implementation. Click any image to zoom.

Architecture diagram
Write path: your notes get indexed. Read path: your question finds them.
Chunking illustration
Notes are cut into small overlapping pieces so the right part can be found.
Similarity threshold curve
The threshold separates trustworthy matches from noise.
Precision-recall curve
Precision‑recall curve from the evaluation run.

05 The simple math behind it

What each formula means, where it is used, and why.

Cosine similarity — “how similar are two notes?”
WhatA number from 0 to 1 saying how similar two pieces of text are. 1 = basically identical, 0 = unrelated.
WhereUsed in retrieval to rank which notes best match your question.
WhySo the AI only reads notes that are genuinely about what you asked.
$$ \text{sim}(\mathbf{a}, \mathbf{b}) = \frac{\mathbf{a} \cdot \mathbf{b}}{\|\mathbf{a}\| \cdot \|\mathbf{b}\|} $$
Reciprocal Rank Fusion (RRF) — “combine two ways of searching”
WhatA way to combine two rankings (keyword search + meaning search) into one better list.
WhereUsed in retrieval to fuse a keyword match with a semantic match.
WhyEach method catches things the other misses — together they’re more accurate.
$$ \text{RRF}(d) = \sum_{r \in \mathcal{R}} \frac{1}{k + \text{rank}_r(d)}, \quad k = 60 $$
MRR & NDCG — “did we find it quickly?”
WhatTwo scores that measure whether the right note appears near the top of the results.
WhereUsed in the evaluation step to grade retrieval quality.
WhyA note found at position 1 is more useful than one found at position 9 — these reward that.
$$ \text{MRR} = \frac{1}{|Q|} \sum_{q=1}^{|Q|} \frac{1}{\text{rank}_q}, \qquad \text{NDCG@k} = \frac{\text{DCG@k}}{\text{IDCG@k}} $$

06 Does it actually work?

We measured it on a small test set. Regenerate anytime with python3 scripts/evaluate_retrieval.py.

Loading evaluation results…