MonkeyLLM

This repository is not an application. It is a knowledge engine: a new
way to query data.

Knowledge lives in a forest: a git-versioned tree of markdown nodes,
each carrying a curated, scent-bearing passport. An AI does not get handed
a retrieval dump. It navigates: drops in through search, follows typed
edges, reads exactly the node it needs, and plants what it learns.
Successful hunts deposit pheromone and mint shortcut links, so the corpus
itself learns from use.

_{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.}

The number that made us write it down: on a benchmark where every
question needs ≥3 chained hops, the same 12B local model scores
0 / 11 as a classic top-k RAG reader and 11 / 11 (100%) as a forest
navigator, at 0.58× the token cost per correct answer of an
iterative-RAG baseline, on a single consumer GPU. If your first reaction
is "I need to test whether this actually serves my case", good. Every
number is reproducible from committed scripts, and the whole design is
written down in the paper.

Everything else in this repository exists around that engine. The
Studio console you see in the screenshots is not the product. It is
the management layer: the window where people watch, govern and teach
what the engine serves.

The spec is the truth: the latest docs/monkeyllm-spec-v*.md is
normative; code follows it, never the other way around.

The engine, inside your own code

The engine is a plain Python package (Apache-2.0) with no host, no
server and no UI attached. Point it at a folder and you have a forest;
operate it from your own Python:

pip install monkeyllm                           # the monkeyllm package + vine CLI
vine init --forest ./brain --title "My brain"   # an empty forest, git and all

Straight from source, without waiting for a release:
pip install "git+https://github.com/JimmyWesley/MonkeyLLM.git". Python
3.11+; the file converters of Part G are an extra
(pip install "monkeyllm[ingest]"), and contributors want the editable
install further down.

from monkeyllm import Vine
from monkeyllm.harvest import harvest

vine = Vine("./brain")
vine.plant({"id": "inbox/_index", "type": "branch", "parent": "_index",
            "title": "Inbox", "summary": "Loose notes before they find a branch."})
vine.plant({"id": "inbox/first-note", "type": "note", "parent": "inbox/_index",
            "title": "First note", "summary": "Where this brain begins.",
            "body": "Planted from my own code."})

vine.locate("where does this brain begin?")   # ranked entry points, BM25, zero embeddings
harvest(vine, "first note")                   # one-shot retrieval: evidence + snippets, zero LLM

Every primitive an agent uses rides that same object (locate, look,
move, pick, scan, sniff, query, plant, graft, tend), each
token-budgeted, each truncation explicit. The Gardener (vine adopt /
vine sync) mirrors an existing document tree into a forest, and the
Ranger (vine ranger) keeps it healthy over time.

And the same forest speaks MCP to any agent, straight from the CLI:

vine serve --forest ./brain                    # stdio MCP server
vine serve --forest ./brain --transport http   # or over HTTP

Claude Code, or any MCP-capable runtime, then holds the forest's tools:
no host, no accounts, your machine, your ecosystem.

Anything you feed it becomes navigable

You do not prepare your files for the engine. You hand them over and the
Gardener converts, summarises and commits each one, through the same
pipeline whether it runs from the command line (vine adopt), from the
console, or from your browser:

Tabular files stop being documents: a spreadsheet becomes a table an
agent queries in SQL, with a ## Query manual and sample rows written
into its passport, so a model knows which tables and columns exist before
it asks. What they mean is the one thing a machine cannot infer, so a
person writes it in a ## Notes section that travels with the dataset
everywhere it is read.

.docx, .xlsx and .xls need the optional ingest extra
(pip install -e ".[ingest]"). PDFs need a converter hook, because a good
extractor is a heavyweight (often copyleft) dependency this project will
not force on you: name the tool in _meta/gardener.yaml and it joins the
pipeline. Everything else in the table works out of the box.

Drop files, mirror a whole folder the host can read, or write a document
in place: each one arrives with a curated passport, and a batch is a job
you can watch. Nothing is chunked and forgotten. Every document becomes a
node with a name, a summary and edges.

And from the browser

The Clipper (apps/clipper/) is a Chrome/Edge/Brave extension that
turns the page you are reading into a forest: the readable article or just
your selection as markdown, a screenshot or a dragged region as a media
node. Drag the region, adjust it by its handles, mark it up (arrow, box,
pen, text label) and leave a note for the Gardener, typed or dictated. The
clip lands with the page's address attached, so it can always be traced
back.

One click: clip, capture, write, or ask the forest.	Drag a region, annotate it, leave a note, then capture.

It holds a paired key of its own, never your password, and the Station
serves the build at /clipper.zip, offered on the console's own rail: a
key that can only narrow your access is self-service, so getting the
extension is too.

Quick start (development)

pip install -e ".[dev]" && pip install -e apps/station
python -m pytest -q
python forests/scripts/build_fixture.py
python -m monkeyllm.cli validate --forest forests/forest-fixture

The management layer (Station + Studio)

When a forest must be a shared, governed asset instead of a personal
directory, the Station (spec Part J) wraps the untouched engine with
identity, per-forest policy, audit and model bindings, serving REST under
/v1 and MCP under /mcp. It also serves the Studio, the web console:

Ask questions that arrive with their sources, walk the tree as a living
graph, query datasets in SQL, feed the forest from uploads and the browser
Clipper, grant scoped access, and hand your own AI the skill that makes
the forest its persistent memory. The console is where the engine's
possibilities become visible, but whatever it shows, an API client holding
the same key could fetch: there is no privileged path.

Documentation

The MonkeyLLM Handbook: install it, sign in
for the first time, use and feed the forest, connect your own AI over MCP
(including the Claude Code skill the Studio generates), and govern the
deployment. English, Português and Español, with screenshots.

The paper

MonkeyLLM: Stigmergic Navigation of Knowledge Forests,
replacing retrieval-augmented generation with agentic foraging by small
language models. The forest, the scent contract, the ten budgeted
primitives, the pheromone economy, and the Forest Principle (spend
intelligence on the environment so you can spend less on the model), with
every benchmark number reproducible from this repository.

Roadmap

The engine, the Station, the Studio and the Clipper are built and
measured; the phases below are what comes next. The full plan, with exit
criteria per phase, is docs/monkeyllm-roadmap.md;
the working backlog is tasks/.

The rule the project holds itself to: no phase starts before the
previous one passes its exit criteria, and no optimization happens
without a measurement that justifies it. The benchmark is the judge,
not intuition, which is why a criterion that did not pass is written down
above instead of quietly dropped.

Layout

Run the whole environment (Docker)

One container serves frontend and backend; data persists in named volumes:

cp .env.example .env   # fill in what you use
docker compose up --build -d

See deploy/README.md for the full walkthrough,
including Dokploy and optional local llama.cpp inference.

License

Two licenses, split along the line the architecture already draws:

• Engine (src/monkeyllm/, the spec, the benchmark, the tooling):
  Apache-2.0. The MCP contract is meant to spread.
• Host (apps/station/, apps/studio/, apps/clipper/):
  AGPL-3.0-only. Self-hosting is free and
  unrestricted; offering it as a managed service means opening your stack.

See LICENSING.md for the full map, the commercial option and
the DCO requirement for contributions.