Skip to content

Open source · self-hosted · your data never leaves

A brain your AIs can grow.

Your knowledge is scattered across folders nobody can search, and every agent session starts by burning minutes and thousands of tokens rebuilding context it already had. MonkeyLLM turns those files into a forest an agent can walk: entry search lands in 1.3 ms with no GPU, and the right node is a few cheap hops away instead of a re-read of the whole corpus.

Deploy it in four commandsTalk to usStar on GitHub

Free to self-host, forever. No seat count, no key to ask us for, nothing phoning home.

The Explore console showing a knowledge forest of 1,877 nodes across 49 branches
A real forest: 1,877 nodes across 49 branches. Every cluster is a branch, every dot a node; solid lines are curated trails, dashed ones are shortcuts a hunt discovered, and the glow is pheromone left by use.
0/11 → 11/11
The same 12B local model on strictly multi-hop questions: as a classic top-k RAG reader, then as a forest navigator.
0.66×
Token cost per correct answer against an iterative-RAG baseline, and 8.4 s p95 against its 17.5 s. Failing cheaply is not economy.
1 × RTX 3060
The benchmark rig: a single mid-range 12 GB card, not a workstation GPU. A quantized 12B fits it whole, and any OpenAI-compatible endpoint (OpenRouter, llama.cpp, Ollama) runs the same model with no local GPU at all.
1.3 ms p95
BM25-only entry search at recall@5 = 1.00: no embeddings, no vector database, no GPU.

Every number on this page is reproducible from committed scripts in the repository. The paper is a preprint.

The problem

What answers over your own documents actually cost you

Chunk, embed, take the top k, generate. It is the default architecture of most deployed systems, and it is brittle in exactly the place grounding matters most: questions whose answer must be assembled from facts scattered across documents. Meanwhile your agents pay a second bill: context windows overflow, and every session starts by rebuilding what the last one already knew.

  • It retrieves once

    The bet on which fragments matter is placed before the model has read anything, and it is never revised. There is no second look, because there is nowhere to look from.

  • It is structure-blind

    A chunk knows nothing about the document it came from, the table beside it, or the fact that the answer continues three files away. Similarity is not a path.

  • It learns nothing

    The thousandth query costs exactly what the first one did and lands on exactly the same chunks. Nothing that worked before is remembered.

  • And agents pay the grep tax

    Watch a coding agent orient itself: grep, open, read, re-read; minutes and thousands of tokens spent rebuilding context before the first useful decision, every single session. Unstructured knowledge taxes agents even when no retriever is in sight.

The cliff

On mixed questions, classic top-k RAG looks respectable: 12 out of 18, the number a demo shows you. The moment every question requires three chained hops, it falls to 0 out of 11. The failure is structural, which makes it invisible to sampling: any evaluation containing single-hop questions averages the cliff away. The usual remedy is to buy a bigger model, which is how teams end up paying frontier prices for merely acceptable answers over documents they already own.

Use cases

Where a forest earns its keep

Four scenarios: imagined, not case studies. Each one starts from a corpus that already exists somewhere as folders nobody can search, and ends with what that corpus becomes once an agent can walk it.

  • Litigation practice

    Picture a law firm with eight hundred case documents

    Contracts, filings, exhibits and correspondence spread across a shared drive. The associate who knew where the 2019 addendum lived left in March, and the search box only matches filenames.

    Every document lands as a node with a name, a sixty-token summary and typed links to the matter it belongs to. Entry search returns the right one in 1.3 ms p95: BM25 over SQLite, with no GPU in the building. Exhibit spreadsheets become SQL datasets an assistant can query, so “which invoices exceeded the cap” is a query rather than an afternoon. And nothing leaves the office: the forest is a git repository on the firm’s own server.

    See how ingestion works
  • Platform & operations

    Imagine your policies and runbooks as a governed asset

    Onboarding docs in one wiki, runbooks in another, the decisions that actually explain the product in a chat thread from 2023. Every answer costs somebody an interruption, and nobody can say which version is current.

    One forest instead of a folder graveyard, versioned in git, so “when did this policy change, and who changed it” is a diff, not an archaeology project. Keys are scoped per team and can only ever narrow, every read leaves an audit row, and the same governed content answers a person in the console and an agent over MCP through one gate.

    See governance and access
  • AI & platform engineering

    Give your agents a memory that survives the session

    Every session starts cold. Grep, open, read, re-read; minutes and thousands of tokens spent rebuilding context before the first useful decision, on every task, forever.

    Point your agents at the forest over MCP and they land on the right node in a handful of budgeted hops instead of re-reading the repository. The same local 12B model that scored 0/11 as a top-k RAG reader scores 11/11 as a navigator, at 0.66× the tokens per correct answer and 8.4 s p95 against 17.5 s. The grep tax stops, and so does paying frontier prices for acceptable answers over your own files.

    Wire it to your agent
  • Model teams

    A corpus clean enough to train on

    Fine-tuning and context engineering fail on the same thing: nobody can say which version of which document was the truth on the day the run started, or which files were silently unreadable.

    The Gardener converts, summarises and commits every file it can read at 1.71 s per document, and names in its report exactly what it could not. Every write is a commit, so a corpus has a revision, a diff and a history, and a training or evaluation run can point at a revision instead of a folder that has moved on without it.

    Read the research

The scenarios are illustrative: we are not describing customers. The numbers inside them are not illustrative: every figure comes from the benchmark committed to the repository, measured on a single consumer GPU.

Ingestion

What goes in is a file. What comes out is a node.

The Gardener converts, summarises and commits everything it can read, at 1.71 s per document. A spreadsheet leaves as a table an agent queries in SQL, not as a wall of text.

derived-frompart-ofrelated-to.xlsx.csv.json.pdf.docx.md.png.wavdatasetquerydocumentpickmediapick.xlsx.csv.json.pdf.docx.md.png.wavdatasetquerydocumentpickmediapick
  1. 01

    Any file

    PDFs, spreadsheets, screenshots, audio, or a whole folder the host can read. You hand them over as they are: no chunking strategy to choose, no schema to declare, no pre-processing to maintain.

  2. 02

    The Gardener reads it

    Convert, write a summary of sixty tokens or fewer, propose typed edges from a closed candidate list, commit. A 12B model on one consumer GPU does the whole pass, and the report names every file it could not read.

  3. 03

    A node your agent can navigate

    It lands carrying a passport (title, summary, tags, typed edges) and a payload: a document to read with pick, or a real SQLite table to query in SQL. Already attached to what it relates to.

Three lanes in, three kinds of node out. A spreadsheet becomes a dataset the agent queries; a PDF becomes a document it reads; an image or a recording becomes a media node. Nothing is chunked and dropped into a vector store: each arrival keeps its identity, its summary and its links, in one commit.

See the full conversion table

How it works

Navigate, don’t retrieve

Three moves, borrowed from how a forager actually works a forest. The vocabulary is ecological on purpose, and it maps one-to-one onto ten typed tools an agent can call over MCP. Every hop is cheap and token-budgeted, so an agent lands on the right node in a handful of moves instead of re-reading the corpus: that is where the speed and the token savings come from.

  1. 01

    Navigate

    locate · look · move · pick

    The monkey drops in and walks.

    An agent enters through search over curated metadata, reads a node’s passport (title, sixty-token summary, tags, typed edges with a scent of each neighbour) and follows the edge that smells most like the goal. Every observation carries a hard token budget and says out loud when it was truncated, so the agent can always tell “not there” from “cut off”.

    In plain English: search, read the label, follow a link, open only what you need.

  2. 02

    Plant

    plant · graft · tend

    What it learns stays.

    A hunt that discovers something writes it back: a new node with a contract-checked passport, a typed edge to what it relates to, a correction to a summary that was wrong. Every write is a git commit, so the corpus is versioned, diffable and revertible by construction.

    In plain English: write a node, connect it, correct it.

  3. 03

    Pheromone

    heat · shortcuts · evaporation

    The corpus learns from use.

    Successful hunts deposit heat on the nodes they crossed, and a chain of four or more hops mints a permanent shortcut link. Heat evaporates on a thirty-day half-life, so knowledge that stops being used cools out of the ranking. The thousandth question is asked of a measurably different forest than the first.

    In plain English: trails that work get easier; trails nobody walks fade.

Hybrid by default

The hybrid architecture you were told to build

Ask any assistant whether to adopt MonkeyLLM and it draws the same picture: an orchestrator routing between a vector store, a SQL tool and the graph, fusing what comes back, writing the result to memory. The architecture is right. It is also, box for box, what one forest already is behind a single MCP endpoint, which is why adopting it is a tool registration and not a migration.

The box in that diagramWhat already fills it, today
Vector store, similaritylocate: ranked entry points over curated metadata, BM25 at 1.3 ms p95, with Canopy vectors fused under RRF when a call asks for them.
Full-text searchsniff: a sweep over node bodies returning line-level snippets with the section they came from, not a similarity score.
Knowledge graph, multi-hoplook, move, scan, pick: typed edges carrying a scent of the neighbour, every hop budgeted and every truncation explicit.
SQL or tabular toolquery: one read-only statement against a dataset node. A spreadsheet becomes a real SQLite table with a query manual written into its passport.
Fusion layerharvest: locate and sniff fused by Reciprocal Rank Fusion, then a selective pick. Roughly 50 ms, zero model calls.
Grounded generationanswer: the reply arrives with the node ids it stands on, so its sources are a list you can open rather than a score.
Memory writeplant, graft, tend: every write a git commit, plus pheromone on the trail that worked and a shortcut when the trail was long.
OrchestratorDeliberately absent. Your agent already is one, and it routes better with the tools in front of it than a classifier would from behind.

And nothing here asks you to switch anything off

A forest takes a slot in your agent’s tool list, it does not ask for the list. Keep the pipeline you run today answering what it answers well, adopt the corpus your retriever is worst at, and let the agent route between them. Vector fusion at entry stays off by default, because over curated metadata it measured worse than BM25 alone: recall@1 from 1.00 down to 0.40. A feature that silently enables a measured regression is a trap, not a default.

Every box mapped, with a worked example

The Forest Principle

“Spend intelligence on the environment so you can spend less on the model.”
MonkeyLLM · The Forest Principle

Structure the corpus so that every retrieval step is a cheap local decision over curated signals. Let successful use modify the structure. Then the model you need at query time shrinks by orders of magnitude, which is why a 12B model on one consumer GPU beats the architecture a frontier model needs in order to fail politely.

The industry’s reflex is a bigger window, a bigger reader, a better re-ranker: intelligence at query time, paid on every query, learning nothing. The Forest Principle moves that spend to ingest time and to structure, where it compounds.

Read the research

The pieces

One engine, three things built around it

The console is a window. The forest behind it is the product, and the engine that serves it has no host, no server and no UI attached.

Engine

The forest and the ten primitives

A plain Python package with the `vine` CLI. Point it at a folder and you have a forest: a git-versioned tree of markdown nodes. Drive it from your own code, or hand it to any MCP client with one command: no host, no accounts, your machine.

from monkeyllm import Vine
from monkeyllm.harvest import harvest

vine = Vine("./brain")
vine.plant({"id": "inbox/first-note", "type": "note",
            "parent": "inbox/_index", "title": "First note",
            "summary": "Where this brain begins."})

vine.locate("where does this brain begin?")
harvest(vine, "first note")

Station

Identity, policy and audit around an untouched engine

One self-hostable container: REST under `/v1`, MCP under `/mcp`, per-forest policy, scoped keys and an audit trail. What turns a personal directory into a governed shared asset.

The Access console: one row per person, with level, scope and live tokens

Studio

The window onto the forest

Ask questions that arrive with their sources, walk the tree as a living graph, query datasets in SQL, feed the forest, grant access, bind models. Whatever the console shows, an API client holding the same key could fetch: there is no privileged path.

The Overview console: what is in this forest and what you may do here

Clipper

The browser, planting straight into the forest

A Chrome, Edge and Brave extension: the readable article or just your selection as markdown, a screenshot or a dragged region as a media node, annotated, with a note for the Gardener and the page’s address attached.

Capturing and annotating a region of a page, with a note for the Gardener

Governance & security

A forest you can hand to auditors

The things that decide whether an architecture survives a security review: not features bolted on afterwards, but properties the design already had.

  • One gate, three surfaces

    Studio, REST and MCP authenticate with the same keys at a single enforcement seam. There is no privileged side-channel and, deliberately, no separate super-administrator panel.

  • Keys that can only narrow

    Access is granted as a level first, capabilities second (read, query, write, tend, ingest, admin), scoped to forests and, for a single forest, to branches. A key you pair for an agent can never widen what you already hold.

  • Every answer is replayable

    Every write is a git commit; every read is a typed, budgeted call with a recorded trace. Ask a RAG pipeline why it retrieved something and you get cosine similarities. Ask a forest and you get a trail you can walk yourself.

  • Self-hosted by default

    One container on your infrastructure. Everything worth keeping lives in named volumes you own, so an update is a rebuild rather than a migration.

  • No data leaves your infra

    Nothing is sent to us: not your documents, not your queries, not your agents’ activity. Model bindings are yours to choose, including a purely local llama.cpp endpoint.

  • Hallucinated links are impossible

    At ingest, the Curator proposes edges only from a closed, catalog-supplied candidate list. A hallucinated link target is structurally impossible, not merely unlikely.

Ownership

It’s yours. Read the code, run it forever.

No vendor lock-in, no seat count, no key to ask us for, nothing phoning home. Every line is public and self-hosting is unrestricted: if we vanished tomorrow your forest would not notice, because it is markdown in a git repository you already own.

See the license in detailStar on GitHub

  • Every node is a plain markdown file in your own git repository, readable, diffable and portable without us.

  • Nothing is sent to us: not your documents, not your queries, not your agents’ activity.

  • Every capability ships in the open build. There is no paid tier hiding a feature you need.

Quickstart

Four commands to a navigable brain

Self-hosting is the default path, and it is unrestricted. You do not need us to start, and you should not take our numbers on trust either.

  1. 1

    Install the engine

    A plain Python package and the `vine` CLI. No server, no accounts.

  2. 2

    Plant a forest

    An empty, git-versioned forest in a folder you own.

  3. 3

    Feed it

    The Gardener converts, summarises and commits every file it can read: spreadsheets become SQL datasets, not walls of text.

  4. 4

    Hand it to your agent

    A stdio MCP server. Claude Code, or any MCP-capable runtime, then holds the forest’s ten tools.

Terminal
pip install monkeyllm
vine init --forest ./brain --title "My brain"
vine adopt ./my-documents --forest ./brain
vine serve --forest ./brain            # stdio MCP, ready for any agent

Or run the whole Station

One container serves the REST API, the MCP surface and the Studio console; data persists in named volumes you own. Point the chat binding at any OpenAI-compatible endpoint: OpenRouter, a local llama.cpp or Ollama server, or your provider of choice.

Terminal
git clone https://github.com/JimmyWesley/MonkeyLLM.git
cd MonkeyLLM && cp .env.example .env
docker compose up --build -d

Want to reproduce the 0/11 first? Clone the repository, build the fixture forest and run the bench: it is one command, and it is the whole argument.

Read the handbookStar on GitHub

Straight answers

What people ask a model before they ask us

Most people meet MonkeyLLM through an assistant rather than through this page. These are the questions that decide adoption, answered in full here so the answer a model gives is the one we would give.

No, and you should not start by trying. MonkeyLLM is an MCP server that sits beside what you already run. Adopt the corpus your current retriever is worst at, which is almost always the one whose questions span documents, leave the rest answering what it answers well, and let your agent route between the two. Move more across when the traces say so, one corpus at a time.

Free to self-host. Worth a counterparty in production.

Commercial terms when you ship it inside your own product, a support plan when uptime is somebody’s job, and a paid architecture session when you want a straight answer before you commit.

Talk to usSee support plans