JimmyWesley/MonkeyLLM

MonkeyLLM

面向 AI 智能体的知识引擎：一种查询数据的新方式。 你的文档会变成一个由 git 版本控制的 markdown 知识图谱，智能体通过 MCP 在其上导航：经过整理的摘要、带类型的边、带引用的答案、对你的电子表格执行 SQL，没有任何内容被切分成匿名片段。

这个仓库不是一个应用程序。知识存在于一片森林中：一棵由 git 版本控制的 markdown 节点树，每个节点都携带一份经过整理、带有气味线索的护照。AI 不会拿到一份检索转储。它会导航：通过搜索进入，沿着带类型的边前进，只读取它需要的那一个节点，并把它学到的东西种下来。成功的搜寻会留下信息素并铸造快捷链接，因此语料库本身会从使用中学习。

一片真实的森林：49 个分支上的 1,877 个节点。每个簇都是一个分支，每个点都是一个节点；实线是经过整理的路径，虚线是某次搜寻发现的快捷链接，而光晕是使用留下的信息素。

让我们把它写下来的那个数字：在一个每个问题都需要 ≥3 次链式跳转的基准上，同一个 12B 本地模型作为经典 top-k RAG 阅读器得分为 0 / 11，而作为森林导航器得分为 11 / 11（100%），每个正确答案的 token 成本是迭代式 RAG 基线的 0.66×，并且运行在单张消费级 GPU 上。如果你的第一反应是“我需要测试这是否真的适用于我的场景”，很好。每个数字都可以通过已提交的脚本复现，整个设计都写在论文中。

这个仓库中的其他一切都存在于那个引擎周围。你在截图中看到的 Studio 控制台不是产品。它是管理层：人们观察、治理和教授引擎所服务内容的那扇窗口。

规范就是真相：最新的 docs/monkeyllm-spec-v.md 是规范性的；代码遵循它，而不是反过来。

引擎，就在你自己的代码中

这个引擎是一个普通的 Python 包（Apache-2.0），没有附带宿主、服务器或 UI。把它指向一个文件夹，你就拥有了一片森林；在你自己的 Python 中操作它：

pip install monkeyllm                           # the monkeyllm package + vine CLIbash
vine init --forest ./brain --title "My brain"   # 一片空的森林，git 以及一切

直接从源码安装，无需等待发布：
pip install "git+https://github.com/JimmyWesley/MonkeyLLM.git"。需要 Python
3.11+；G 部分的文件转换器是一个额外组件
（pip install "monkeyllm[ingest]"），贡献者还需要下面进一步说明的可编辑安装。
python
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

智能体使用的每一个原语都依托同一个对象（locate、look、
move、pick、scan、sniff、query、plant、graft、tend），每一个
都有 token 预算，每一次截断都显式可见。园丁（vine adopt /
vine sync）将现有的文档树镜像为一片森林，而护林员（vine ranger）则
长期维护它的健康。

而且同一片森林可以直接从 CLI 向任何智能体说 MCP：
bash
vine serve --forest ./brain                    # stdio MCP server
vine serve --forest ./brain --transport http   # or over HTTP

Claude Code，或任何支持 MCP 的运行时，随后便掌握了这片森林的工具：
没有主机，没有账户，你的机器，你的生态系统。

你喂给它的任何东西都变得可导航

你不需要为引擎准备你的文件。你只需把它们交出去，园丁会转换、
总结并提交每一个文件，无论它是从命令行（vine adopt）、从
控制台，还是从你的浏览器运行，都走同一条流水线：

| 你放入的内容 | 它变成什么 |
|---|---|
| .md、.markdown、.txt | 一个 note；文本本身就已经是正文 |
| .docx | 一个 document：标题和段落转为 markdown |
| .pdf | 一个 document，通过一行转换器钩子，使用你信任的任何 CLI 提取器（方法） |
| .csv | 一个数据集：一张真正的 SQLite 表，用只读 SQL 查询 |
| .json | 当它是扁平表时是一个数据集，否则是一个持有 JSON 的 document |
| .xlsx、.xls | 每个工作表一个数据集，并推断类型 |
| .db、.sqlite、.sqlite3 | 整体采用：数据库本身成为载荷，并附带生成的查询手册和样本行 |
| .png、.jpg、.jpeg、.gif、.webp | 一个 media 节点；在绑定了 vision 模型的 Station 上，它还会获得一段可被搜索找到的文字描述 |
| .mp3、.wav、.m4a、.ogg、.flac | 一个携带其护照的 media 节点 |
| 其他任何内容 | 在报告中按名称列为 unsupported，这样你就能确切看到哪些内容没有落地 |

表格文件不再是文档：电子表格变成智能体用 SQL 查询的表，其护照中写有 ## Query manual 和示例行，这样模型在提问之前就知道存在哪些表和列。它们意味着什么，是机器唯一无法推断的东西，所以由人在 ## Notes 部分中写下来，该部分随数据集在任何被读取的地方一起传递。

.docx、.xlsx 和 .xls 需要可选的 ingest 附加项
（pip install -e ".[ingest]"）。PDF 需要转换器钩子，因为一个好的
提取器是重量级（通常是 copyleft）依赖，本项目不会
强加给你：在 _meta/gardener.yaml 中指定工具，它就会加入
流水线。表中的其他所有内容开箱即用。

从 Ingest 控制台将文件发送到森林中

拖入文件、镜像主机可读取的整个文件夹，或就地编写文档：每一个都会带着精心整理的护照到达，而一批就是一个你可以观看的任务。没有任何内容被分块后遗忘。每个文档都会变成一个带有名称、摘要和边的节点。

以及从浏览器

Clipper（apps/clipper/）是一个 Chrome/Edge/Brave 扩展，可将你正在阅读的页面变成一片森林：可读文章或仅你的选择内容作为 markdown，截图或拖拽区域作为 media 节点。拖拽区域，通过其手柄调整，进行标注（箭头、方框、笔、文本标签），并为 Gardener 留下备注，可输入或口述。剪辑落地时会附带页面地址，因此始终可以追溯回来。

一键：剪辑、捕获、编写，或向森林提问。
拖拽一个区域，标注它，留下备注，然后捕获。

它持有自己的一对配对密钥，绝不是你的密码，而 Station
在 /clipper.zip 提供构建产物，并在控制台自己的侧栏中提供：一个只能缩小你访问权限的密钥是自助的，所以获取该扩展也是如此。

快速开始（开发）
bash
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

管理层（Station + Studio）
当森林必须是一个共享的、受治理的资产，而非个人目录时，Station（规范 Part J）以身份、按森林策略、审计和模型绑定包裹未改动的引擎，在 /v1 下提供 REST 服务，在 /mcp 下提供 MCP 服务。它还提供 Studio，即 Web 控制台：

提出自带来源的问题，将树作为活的图来遍历，用 SQL 查询数据集，通过上传和浏览器 Clipper 喂养森林，授予限定范围的访问权限，并将让森林成为其持久记忆的技能交给自己的 AI。控制台是引擎的可能性变得可见的地方，但无论它显示什么，持有相同密钥的 API 客户端也能获取：不存在特权路径。

文档

The MonkeyLLM Handbook：安装它，首次登录，使用和喂养森林，通过 MCP 连接你自己的 AI（包括 Studio 生成的 Claude Code 技能），并治理部署。提供英语、葡萄牙语和西班牙语版本，附有截图。

论文

MonkeyLLM: Stigmergic Navigation of Knowledge Forests，用小型语言模型的智能体觅食取代检索增强生成。森林、气味契约、十个有预算的原语、信息素经济，以及 Forest Principle（把智能花在环境上，这样你就能在模型上花得更少），每个基准数字都可以从本仓库复现。

路线图

引擎、Station、Studio 和 Clipper 已构建并经过测量；以下阶段是接下来的工作。完整计划及各阶段的退出标准见 docs/monkeyllm-roadmap.md；工作待办列表见 tasks/。

| 下一步 | 含义 | 当前状态 |
|---|---|---|
| Monkey Bench，正式版 | 发布完整基准运行及其轨迹，对照 top-k 和迭代式 RAG 基线 | 4 项退出标准中已满足 3 项；第四项重新以每正确 token 数（0.66×）衡量 |
| 收敛曲线 | 证明随着森林被使用，到达答案所需的跳数下降*：信息素经济开始见效，也是论文的标志性图表 | 测量过一次；标准尚未满足，而发现（地板效应、信息素串扰）本身就是结果 |
| The Troop | 带评判者的并行觅食者：目前是准确率放大器，还不是速度放大器 | 两组均为 8/8 准确率；墙钟时间标准需要更深的语料库 |
| 摄取时的实体和类型化边 | Gardener 提取人物、地点和关系，超越当前的摘要和 related-to 提议 | 已设计（Part G），需要规范升级 |
| Station 加固 | OIDC 登录、按主体配额 | Part J 的其余部分今天发布 |
| 发表 | 论文以 DOI 存入（Zenodo / arXiv） | 已撰写；存入待定 |
| 阶段 3：更快的核心（有条件） | 在相同契约背后用 Rust 实现 Catalog + Canopy，仅当遥测证明瓶颈时 | 有意未启动；SLM 目前主导成本 |

项目对自身坚持的规则：在前一阶段通过其退出标准之前，不启动任何阶段；在没有证明其合理性的测量之前，不进行任何优化。 基准是裁判，而非直觉，这就是为什么未通过的标准被写在上方，而不是被悄悄丢弃。

布局

| 路径 | 其中内容 |
|---|---|
| src/monkeyllm/ | 引擎：vine CLI、10 个原语、harvest、Gardener（摄取）、Ranger（维护）、catalog、Canopy |
| apps/station/ | 可部署主机：REST /v1、MCP /mcp，为 Studio 提供服务 |
| apps/studio/ | Web 控制台（React/Vite，构建进 Station 镜像） |
| apps/clipper/ | 浏览器扩展：将你正在阅读的页面剪藏进森林 |
| paper/ | 论文：设计、词汇、基准、作者身份 |
| forests/ | 生成的森林（除 forests/scripts/ 外被 gitignore）；重新构建，绝不编辑 |
| bench/ | Monkey Bench：分块器、RAG 基线、运行器 |
| scripts/ | 基础设施 + 测量（本地模型、bench、策展指标） |
| docs/ | 规范、手册（docs/guide/）和设计笔记 |
| tasks/ | 待办事项，每个任务一个文件 |

运行整个环境（Docker）

一个容器同时服务前端和后端；数据持久化在命名卷中：
bash
cp .env.example .env   # fill in what you use
docker compose up --build -d

完整演练见 deploy/README.md，包括 Dokploy 和可选的本地 llama.cpp 推理。

许可证

两个许可证，沿架构已经划定的界线拆分：

- 引擎（src/monkeyllm/、规范、基准、工具）：
Apache-2.0。MCP 契约旨在传播。
- 主机（apps/station/、apps/studio/、apps/clipper/）：
AGPL-3.0-only。自托管免费且
不受限制；将其作为托管服务提供意味着开放你的技术栈。

完整地图、商业选项以及贡献的 DCO 要求见 LICENSING.md。