cerebrollm
Ask a question of your own Markdown documents and get an answer whose quote has been re-read in the source file, or exactly Not in the sources. Only the quote is checked, not the rest of the answer.
PyPI: cerebrollm 0.1.2 · Licence: MIT · Python 3.12 · Status: early research
Features · Quick start · How it works · Use it from an AI app (MCP) · Results · Docs · Product page
Figure: one question through cerebrollm, built from the three figures below. It leaves out indexing and error exits, which the figures under How it works show.
Why
For people who run local models, or let a cloud model read their documents, and need every answer traced to a file.
- A language model does not automatically read your current files. It answers from its training data and the context supplied to it.
- A model reads only what fits in its context window (the text it can take in at once, counted in tokens), and every token costs time. A real set of notes does not fit with each question.
- Retrieval (RAG: search the notes first, then hand the model only the matching passages) fixes both, but the model can still ignore or misquote the passages, and the answer still looks sourced. cerebrollm re-reads the cited file before it prints anything.
Evidence: with retrieval and a citation instruction, the small local model phi4 answered 47 of 60 questions right instead of 1 (model-graded, majority of 5 runs, eval/RESULTS.md).
Status: 0.1.2, early research.
The aim is at least 90% right outcomes (a right answer, or a correct Not in the sources.) with under 2% confidently wrong runs. No local model meets it yet.
Features
- Answers only with a quote it re-read in your file; otherwise prints
Not in the sources.One confirmed quote lets the whole answer through, and the rest of its text is not checked. - Runs on your machine: a PostgreSQL index, local models through Ollama and a local reranker (a second model that re-orders passages by how well they fit the question).
- Hybrid search: keyword and meaning (vector) search find 20 passages, and a reranker keeps the best 8.
- Trust rules: default search leaves drafts out, trusted and recent notes rank higher, and folders you mark are never indexed.
- An MCP server (MCP is the standard way AI apps call outside tools) with two read-only tools,
searchandverify, for AI apps such as Claude. - Measured results with raw run records in this repository; 100 records that quote private documents are withheld.
Quick start
Tested on Ubuntu 24.04, native or under WSL2 on Windows 11. macOS and native Windows are untested.
| You need | Why | Check |
|---|---|---|
| Python 3.12 | runs cerebrollm | python3.12 --version |
| Ollama | runs the embedding model and the answer model locally | curl http://127.0.0.1:11434/api/version answers |
| PostgreSQL 16 with pgvector | stores the index; step 2 installs it | /usr/lib/postgresql/16/bin/postgres --version prints 16.x |
| About 17 GB of disk | the two Ollama models take about 14.5 GB (research/model-study/STUDY-DONE.md), the optional reranker about 2.3 GB |
df -h ~ |
| Measured hardware: a GPU with 12 GB | all speeds and the default answer model gpt-oss:20b were measured on one 12 GB card; other hardware, and CPU only, are not measured |
nvidia-smi |
The commands below are the ones the author ran; the first index and ask on a fresh machine were not re-run while preparing this release.
- Clone the repository:
git clone https://github.com/sourav-patra/cerebrollm && cd cerebrollm. Check:ls engine/setuplistsroot-ubuntu.shanduser.sh. - Install the system packages once, with sudo:
sudo bash engine/setup/root-ubuntu.sh. Check:/usr/lib/postgresql/16/bin/postgres --versionprints a 16.x version. - Start Ollama, then create the virtual environment and the socket-only PostgreSQL cluster:
bash engine/setup/user.sh. It is safe to repeat. Check: the last line isUSER SETUP DONE. - Pull the models:
ollama pull qwen3-embedding:0.6bandollama pull gpt-oss:20b. Check:ollama listshows both. - Without the clone,
pip install cerebrollm(orpip install "cerebrollm[rerank]"for the reranker) gives the same commands; steps 2, 3 and 4 still apply, andengine/setup/user.shshows the PostgreSQL commands. Check:cerebrollm --helplists the commands.
First ask
-
Put your Markdown files in
~/cerebrollm-corpus/notes/. Check:ls ~/cerebrollm-corpus/noteslists them. -
Copy the configuration and add a rule for that folder. The shipped
engine/cerebrollm.tomlholds example rules and the rules for the public documentation folders the evaluation uses; a file that matches no rule is not indexed, so your folder needs the rule below.cp engine/cerebrollm.toml ~/cerebrollm.tomlAppend this to
~/cerebrollm.toml:[[rule]] root = "notes" glob = "notes/**/*.md" tier = "T2" status = "current"Then
export CEREBROLLM_CONFIG=~/cerebrollm.toml. Check:tail -6 ~/cerebrollm.tomlshows the rule. -
Build the index:
engine/bin/cerebrollm index. Check:engine/bin/cerebrollm statuslists chunks for tier T2. -
Ask:
engine/bin/cerebrollm ask "a question your notes answer". Check: the output is an answer followed by lines such asOK notes/guide.md. A question your notes do not answer printsNot in the sources. -
If the reranker is not downloaded the command stops with an error that names the folder. Download it as described next, or add
--no-rerank. Check: the sameaskprints an answer orNot in the sources.instead of the error.
After you edit notes, engine/bin/cerebrollm index --changed re-indexes only the files that changed.
The reranker
ask and the MCP rerank option load BAAI/bge-reranker-v2-m3 (Apache-2.0) from ~/.cerebrollm/models/bge-reranker-v2-m3. Nothing is downloaded at query time (HF_HUB_OFFLINE=1). Fetch it once, at the pinned revision, and check the hashes:
D=~/.cerebrollm/models/bge-reranker-v2-m3; mkdir -p $D && cd $D
R=953dc6f6f85a1b2dbfca4c34a2796e7dde08d41e
for f in config.json sentencepiece.bpe.model special_tokens_map.json tokenizer.json tokenizer_config.json model.safetensors; do
curl -L -O https://huggingface.co/BAAI/bge-reranker-v2-m3/resolve/$R/$f; done
sha256sum -c <path-to-clone>/eval/runs/retrieval/n7-evidence/bge-reranker-v2-m3.sha256
Check: sha256sum prints OK for six files. The download is about 2.3 GB (model.safetensors is 2,271,071,852 bytes in eval/runs/retrieval/n7-evidence/n7-hf-tree.json).
How it works
cerebrollm sits between you, your notes and local models. An AI app can also call it over MCP.
The passages it fetches go to that app and its model's provider.
Passages also leave your computer if you point the Ollama address in cerebrollm.toml away from loopback. cerebrollm does not prevent that.
Figure: who and what cerebrollm talks to. Arrows point from the caller; dashed lines reach a hosted model's provider. Solid lines stay local while Ollama uses its default loopback address (base_url), which cerebrollm does not enforce. It leaves out the AI app's own traffic to its provider, which cerebrollm does not see.
Inside, one program does the work.
It keeps an index of passages in PostgreSQL, calls Ollama for embeddings and answers, and loads a reranker from local files.
Figure: the parts of cerebrollm and what each link does, read against engine/cerebrollm/. It shows the default configuration with Ollama on loopback, and leaves out the configuration file and the secret scan that runs while indexing.
What cerebrollm ask does
Figure: the five steps of ask and its output gate, read against engine/cerebrollm/answer.py (function ask, gate decide). It leaves out indexing, the MCP server and the other commands.
- Search takes the top 20 passages with the default hybrid search (
cerebrollm search), which applies the status filter and the tier and recency boosts fromcerebrollm.toml. - Rerank scores those 20 with the cross-encoder
BAAI/bge-reranker-v2-m3(a model that reads the question and a passage together) and keeps 8.--no-rerankkeeps the first 8 of the search instead. - Generate sends the 8 passages, marked as data, to a local Ollama model (default
gpt-oss:20b, only models listed as allowed inengine/models.toml) and asks for one quoted line with its path. - Verify re-reads each cited file and checks that the quote is in it and that the file still has the sha256 recorded at indexing time.
- The gate prints the answer when at least one citation verified
OK, and prints exactlyNot in the sources.in every other case, including an empty answer and no search hits. A failure in search, rerank or generation prints an error on stderr and exits 2; it never prints an answer.
Other commands: index, search, verify, status and mcp (a read-only MCP server with the tools search and verify). engine/README.md documents each one.
Use it from an AI app (MCP)
Install the package into the cerebrollm environment first: ~/.cerebrollm/venv/bin/pip install "cerebrollm[rerank]". Check: ~/.cerebrollm/venv/bin/cerebrollm --help lists the commands.
From a clone without the package, use the absolute path of engine/bin/cerebrollm as the command instead.
Register cerebrollm mcp as a stdio server in your MCP host: the host starts the command and talks to it over standard input and output.
It offers two read-only tools, search and verify.
It wraps passages in <<<BEGIN RETRIEVED DATA>>> markers so a host can treat them as data.
A host that sends tool results to a cloud model sends your passages to that provider.
Nothing else leaves the machine except what you set up yourself. The Ollama address in cerebrollm.toml defaults to loopback and is not restricted to it.
Hosts that read a JSON server list take this entry; replace <you> with your user name:
{"mcpServers": {"cerebrollm": {
"command": "/home/<you>/.cerebrollm/venv/bin/cerebrollm",
"args": ["--config", "/home/<you>/cerebrollm.toml", "mcp"]}}}
Claude Code takes one command:
- On the same Linux machine:
claude mcp add --scope user cerebrollm -- ~/.cerebrollm/venv/bin/cerebrollm --config ~/cerebrollm.toml mcp. - On Windows with cerebrollm under WSL2:
claude mcp add --scope user cerebrollm -- wsl.exe -d Ubuntu-24.04 -e /home/<you>/.cerebrollm/venv/bin/cerebrollm --config /home/<you>/cerebrollm.toml mcp.
Check: claude mcp list shows cerebrollm as connected.
Results at a glance
Measured on one machine (Windows 11, WSL2 Ubuntu 24.04, RTX 4070 SUPER with 12 GB) with public documentation as the corpus.
The full tables, the v2 evaluation method and every limit are in docs/RESULTS.md.
| Question | Result | Source | State |
|---|---|---|---|
Does retrieval help a small local model? phi4, 60 questions |
without retrieval 1/60, with retrieval 47/60 | eval/RESULTS.md |
measured |
How often is gpt-oss:20b confidently wrong on 35 questions about recent releases? |
no retrieval 122 of 175 runs, plain search 17 of 175, cerebrollm ask 7 of 104 |
eval/RESULTS-v2.md |
measured |
Does ask meet the aim of at least 90% right outcomes with under 2% confidently wrong runs? |
not met by any local model; observed for Claude Sonnet 5.5 with plain search, but 35 items cannot show a rate under 2% | eval/RESULTS-v2.md |
measured |
| Does the top 8 hold a line that answers the question? 60 questions | default search 45/60, with the reranker 46/60 | eval/runs/retrieval/R-summary.md |
measured |
ask trades answers for safety: it removes most confidently wrong runs and says Not in the sources. more often, including on some questions the notes answer.
Only Markdown files are indexed. The gate checks that a quote exists in the file, not that it answers the question.
Docs
| To | Read |
|---|---|
| see every measured number, the evaluation method and all limits | docs/RESULTS.md |
| fix an install or indexing error | docs/TROUBLESHOOTING.md |
| use each command and its options | engine/README.md |
| find a file, or learn what was withheld from this repository | docs/REPOSITORY.md |
| read the locked design: PRD, TRD, LLD, POLICY | docs/LOCKS.md holds the hash of each (locked 2026-10-30); SECURITY.md, CONTRIBUTING.md, docs/DATA.md, docs/RELEASING.md and docs/GOVERNANCE.md come from the POLICY |
| know what data leaves the machine and how releases work | docs/DATA.md, docs/RELEASING.md, docs/GOVERNANCE.md |
| contribute or report a vulnerability | CONTRIBUTING.md, SECURITY.md (not a public issue) |
| see what changed | CHANGELOG.md |
| see how this README and its figures were checked | docs/README-CHECKS.md |
Licence
Code: MIT (LICENSE). Third-party text copied into eval/ and research/ is credited in NOTICE. Documents follow the "Writing docs" section of CONTRIBUTING.md.
Skipped or not checked: the first index and ask on a fresh machine, the reranker download, the Qwen3.6 context ladder, GLM-4.7-Flash (pulled, not measured), and the figures on the PyPI page, which does not resolve the relative image paths.
Metadata
Release files for cerebrollm 0.1.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| cerebrollm-0.1.2.tar.gz | 75.4 kB | With provenance | Details for cerebrollm-0.1.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| cerebrollm-0.1.2-py3-none-any.whl | Python 3 | none | any | Details for cerebrollm-0.1.2-py3-none-any.whl |
Total release size: 123.0 kB
Release files / cerebrollm-0.1.2.tar.gz
| Download URL | cerebrollm-0.1.2.tar.gz |
|---|---|
| Size | 75.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b9b49863c32c667f35937dc70c2f26d64dfbeced03472bff8bd1260d5217eca9
|
|
BLAKE2b-256 checksum How to use checksums |
83ae3b03b3c327420a7ab1b8991cef06a4fd78679dc0e7a4124adcaa9dcfa1f6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logRelease files / cerebrollm-0.1.2-py3-none-any.whl
| Download URL | cerebrollm-0.1.2-py3-none-any.whl |
|---|---|
| Size | 47.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6be8028050f5e4d9c7d2f68249db0e8784e259eade37d9dbf81265aa45532ca0
|
|
BLAKE2b-256 checksum How to use checksums |
9a805798c2eed8bc2b66e76850453dc6a49d03aa8317f97a619a0f8907b7a17b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logSecurity for cerebrollm 0.1.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for cerebrollm-0.1.2.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.