https://github.com/tobocop2/lilbee
Local, offline experimental knowledge base. Index documents and code, search or ask questions — from the terminal or any AI agent. Built on Ollama + LanceDB + Kreuzberg + tree-sitter.
https://github.com/tobocop2/lilbee
cli code-search embeddings knowledge-base kreuzberg lancedb llm local-llm mcp model-context-protocol offline ollama python rag tree-sitter vector-search
Last synced: 12 days ago
JSON representation
Local, offline experimental knowledge base. Index documents and code, search or ask questions — from the terminal or any AI agent. Built on Ollama + LanceDB + Kreuzberg + tree-sitter.
- Host: GitHub
- URL: https://github.com/tobocop2/lilbee
- Owner: tobocop2
- License: mit
- Created: 2026-03-05T06:13:52.000Z (24 days ago)
- Default Branch: main
- Last Pushed: 2026-03-11T07:15:59.000Z (18 days ago)
- Last Synced: 2026-03-11T18:08:12.008Z (18 days ago)
- Topics: cli, code-search, embeddings, knowledge-base, kreuzberg, lancedb, llm, local-llm, mcp, model-context-protocol, offline, ollama, python, rag, tree-sitter, vector-search
- Language: Python
- Homepage:
- Size: 21.8 MB
- Stars: 4
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# lilbee
> Beta — feedback and bug reports welcome. [Open an issue](https://github.com/tobocop2/lilbee/issues).
> Chat with your documents locally using Ollama — or plug into AI agents as a retrieval backend via MCP. Indexes PDFs (including scanned via vision OCR), Office docs, spreadsheets, images, and code with a git-like per-project model. Powered by [Kreuzberg] for text extraction, [Ollama] for embeddings and chat, and [LanceDB] for vector storage.
---
- [Why lilbee](#why-lilbee)
- [Demos](#demos)
- [Install](#install)
- [Quick start](#quick-start) · [Full usage guide](docs/usage.md)
- [Agent integration](#agent-integration)
- [HTTP Server](#http-server) · [API reference](https://tobocop2.github.io/lilbee/api/)
- [Interactive chat](#interactive-chat)
- [Supported formats](#supported-formats)
---
## Why lilbee
lilbee indexes documents and code into a searchable local knowledge base. Use it standalone — search, ask questions, chat — or plug it into AI coding agents as a retrieval backend via MCP.
Most tools like this only handle code. lilbee handles PDFs, Word docs, spreadsheets, images (OCR) — and code too, with AST-aware chunking.
- **Standalone knowledge base** — add documents, search, ask questions, or chat interactively with model switching and slash commands
- **AI agent backend** — MCP server and JSON CLI so coding agents can search your indexed docs as context
- **Per-project databases** — `lilbee init` creates a `.lilbee/` directory (like `.git/`) so each project gets its own isolated index
- **Documents and code alike** — PDFs, Office docs, spreadsheets, images, ebooks, and [150+ code languages](https://github.com/Goldziher/tree-sitter-language-pack) via tree-sitter
- **Open-source** — runs with [Ollama] and LanceDB, no cloud APIs or Docker required
Add files (`lilbee add`), then search or ask questions. Once indexed, `search` works without Ollama — agents use their own LLM to reason over the retrieved chunks.
## Demos
> Click the ▶ arrows below to expand each demo.
AI agent — lilbee search vs web search (detailed analysis)
[opencode] + [minimax-m2.5-free][opencode], single prompt, no follow-ups. The [Godot 4.4 XML class reference][godot-docs] (917 files) is indexed in lilbee. The baseline uses [Exa AI][exa] code search instead.
**⚠️ Caution:** minimax-m2.5-free is a cloud model — retrieved chunks are sent to an external API. Use a local model if your documents are private.
| | API hallucinations | Lines |
|---|---|---|
| **With lilbee** ([code](demos/godot-with-lilbee/level_generator.gd) · [config](demos/godot-with-lilbee/)) | 0 | 261 |
| **Without lilbee** ([code](demos/godot-without-lilbee/level_generator.gd) · [config](demos/godot-without-lilbee/)) | 4 (~22% error rate) | 213 |
With lilbee — all Godot API calls match the class reference
Without lilbee — 4 hallucinated APIs (details)
If you spot issues with these benchmarks, please [open an issue](https://github.com/tobocop2/lilbee/issues).
### Vision OCR
Scanned PDF → searchable knowledge base
A scanned 1998 Star Wars: X-Wing Collector's Edition manual indexed with vision OCR ([LightOnOCR-2][lightonocr]), then queried in lilbee's interactive chat (`qwen3-coder:30b`, fully local). Three questions about dev team credits, energy management, and starfighter speeds — all answered from the OCR'd content.
See [benchmarks, test documents, and sample output](docs/benchmarks/vision-ocr.md) for model comparisons.
One-shot question from OCR'd content
The scanned Star Wars: X-Wing Collector's Edition guide, queried with a single `lilbee ask` command — no interactive chat needed.
### Standalone
Interactive local offline chat
> [!NOTE]
> Entirely local on a 2021 M1 Pro with 32 GB RAM.
Model switching via tab completion, then a Q&A grounded in an indexed PDF.
Code index and search
Add a codebase and search with natural language. Tree-sitter provides AST-aware chunking.
JSON output
Structured JSON output for agents and scripts.
## Hardware requirements
When used standalone, lilbee runs entirely on your machine — chat with your documents privately, no cloud required.
| Resource | Minimum | Recommended |
|----------|---------|-------------|
| **RAM** | 8 GB | 16–32 GB |
| **GPU / Accelerator** | — | Apple Metal (M-series), NVIDIA GPU (6+ GB VRAM) |
| **Disk** | 2 GB (models + data) | 10+ GB if using multiple models |
| **CPU** | Any modern x86_64 / ARM64 | — |
Ollama handles inference and uses Metal on macOS or CUDA on Linux/Windows. Without a GPU, models fall back to CPU — usable for embedding but slow for chat.
## Install
### Prerequisites
- Python 3.11+
- [Ollama] — the embedding model (`nomic-embed-text`) is auto-pulled on first sync. If no chat model is installed, lilbee prompts you to pick and download one.
- **Optional** (for scanned PDF/image OCR): [Tesseract](https://github.com/tesseract-ocr/tesseract) (`brew install tesseract` / `apt install tesseract-ocr`) or an Ollama vision model (recommended for better quality — see [vision OCR](docs/usage.md#vision-models))
> **First-time download:** If you're new to Ollama, expect the first run to take a while — models are large files that need to be downloaded once. For example, `qwen3:8b` is ~5 GB and the embedding model `nomic-embed-text` is ~274 MB. After the initial download, models are cached locally and load in seconds. You can check what you have installed with `ollama list`.
### Install
```bash
pip install lilbee # or: uv tool install lilbee
```
### Development (run from source)
```bash
git clone https://github.com/tobocop2/lilbee && cd lilbee
uv sync
uv run lilbee
```
## Quick start
See the [usage guide](docs/usage.md).
## Agent integration
lilbee can serve as a local retrieval backend for AI coding agents via MCP or JSON CLI. See [docs/agent-integration.md](docs/agent-integration.md) for setup and usage.
## HTTP Server
lilbee includes a REST API server for programmatic access:
```bash
lilbee serve # start on localhost:7433
lilbee serve --host 0.0.0.0 --port 8080
```
Endpoints include `/api/search`, `/api/ask`, `/api/chat` (with streaming SSE variants), `/api/sync`, `/api/add`, and `/api/models`. When the server is running, interactive API docs are available at `/schema/redoc`. See the [API reference](https://tobocop2.github.io/lilbee/api/) for the full OpenAPI schema.
## Interactive chat
Running `lilbee` or `lilbee chat` enters an interactive REPL with conversation history, streaming responses, and slash commands:
| Command | Description |
|---------|-------------|
| `/status` | Show indexed documents and config |
| `/add [path]` | Add a file or directory (tab-completes paths) |
| `/model [name]` | Switch chat model — no args opens a curated picker; with a name, switches directly or prompts to download if not installed (tab-completes installed models) |
| `/vision [name\|off]` | Switch vision OCR model — no args opens a curated picker; with a name, prompts to download if not installed; `off` disables (tab-completes catalog models) |
| `/settings` | Show all current configuration values |
| `/set ` | Change a setting (e.g. `/set temperature 0.7`) |
| `/version` | Show lilbee version |
| `/reset` | Delete all documents and data (asks for confirmation) |
| `/help` | Show available commands |
| `/quit` | Exit chat |
Slash commands and paths tab-complete. A spinner shows while waiting for the first token from the LLM. Background sync progress appears in the toolbar without interrupting the conversation.
## Supported formats
Text extraction powered by [Kreuzberg], code chunking by [tree-sitter]. Structured formats (XML, JSON, CSV) get embedding-friendly preprocessing. This list is not exhaustive — Kreuzberg supports additional formats beyond what's listed here.
| Format | Extensions | Requires |
|--------|-----------|----------|
| PDF | `.pdf` | — |
| Scanned PDF | `.pdf` (no extractable text) | [Tesseract](https://github.com/tesseract-ocr/tesseract) (auto, plain text) or [Ollama] vision model (recommended — preserves tables, headings, and layout as markdown) |
| Office | `.docx`, `.xlsx`, `.pptx` | — |
| eBook | `.epub` | — |
| Images (OCR) | `.png`, `.jpg`, `.jpeg`, `.tiff`, `.bmp`, `.webp` | [Tesseract](https://github.com/tesseract-ocr/tesseract) |
| Data | `.csv`, `.tsv` | — |
| Structured | `.xml`, `.json`, `.jsonl`, `.yaml`, `.yml` | — |
| Text | `.md`, `.txt`, `.html`, `.rst` | — |
| Code | `.py`, `.js`, `.ts`, `.go`, `.rs`, `.java` and [150+ more](https://github.com/Goldziher/tree-sitter-language-pack) via tree-sitter (AST-aware chunking) | — |
See the [usage guide](docs/usage.md#ocr) for OCR setup and [model benchmarks](docs/benchmarks/vision-ocr.md).
## License
MIT
[Ollama]: https://ollama.com
[opencode]: https://opencode.ai
[Kreuzberg]: https://github.com/Goldziher/kreuzberg
[tree-sitter]: https://tree-sitter.github.io/tree-sitter/
[LanceDB]: https://lancedb.com
[godot-docs]: https://github.com/godotengine/godot/tree/4.4-stable/doc/classes
[tml]: https://github.com/godotengine/godot/blob/4.4-stable/doc/classes/TileMapLayer.xml
[asg2d]: https://github.com/godotengine/godot/blob/4.4-stable/doc/classes/AStarGrid2D.xml
[nr2d]: https://github.com/godotengine/godot/blob/4.4-stable/doc/classes/NavigationRegion2D.xml
[ns2d]: https://github.com/godotengine/godot/blob/4.4-stable/doc/classes/NavigationServer2D.xml
[exa]: https://exa.ai
[lightonocr]: https://ollama.com/maternion/LightOnOCR-2