carrel README

The project's README from github.com/FengZhenfei/carrel. As one markdown file: README.md.

Carrel

English | 中文

tests License: MIT

Ontology-Augmented Generation for AI agents.

Carrel is a self-hosted knowledge base for AI agents. It automates document parsing, indexing, and retrieval, with optional knowledge graphs. Agents use its API to retrieve source passages, images, and related facts, then generate their own answers.

Use it to give an agent access to a collection of product documents, research, contracts, meeting notes, or other files that change over time. A web console manages knowledge bases, models, and processing tasks. A bundled search skill connects agents such as Claude Code and Codex to the retrieval service.

Features · Quick start · Agent integration · Documentation

Features

How it works

flowchart LR
    D[Document folders] --> P[Parse and chunk]
    P --> I[Vector and keyword indexes]
    P --> G[Optional knowledge graphs]
    I --> R[Retrieval API]
    G --> R
    R --> A[AI agent]
    A -->|Follow-up queries| R

Carrel uses MinerU and native parsers for ingestion, Qdrant for vectors, OpenSearch for keywords, and Neo4j for graph queries. SQLite tracks files and tasks. Model services can run locally or through compatible hosted endpoints. See Architecture for the pipeline and retrieval design.

Requirements

Platform Deployment
Linux with NVIDIA GPU GPU parsing and optional local model services; systemd scheduling
Linux without GPU CPU parsing; connect to model services on another host or a provider
macOS with Docker Desktop CPU containers and native Python services; arrange scheduling separately
Windows Use WSL2; native Windows deployment is not supported

Quick start

1. Deploy the services

git clone https://github.com/FengZhenfei/carrel.git
cd carrel
./deploy.sh

The script detects the host, starts the infrastructure, installs the Python app, and creates configuration files. On Linux with user systemd available, it also enables services and scheduled tasks. Other hosts receive manual startup commands. First startup downloads the parser models.

2. Configure model endpoints

Edit config/knowledge-base.env to set the embedding and vision model URLs, model names, and API keys. The initial URLs point to local model servers; starting those servers requires the optional local model setup below.

To use the bundled local models, prepare their weights and deploy with ./deploy.sh --with-local-models. See Model configuration and the local model setup. Restart running application services after changing their environment settings.

3. Add documents

Open the console at http://127.0.0.1:9800. Put documents in runtime/mirror/<folder>/, then enable that folder in the console. Each enabled folder becomes a knowledge base; scheduled tasks process its files.

For a knowledge graph, register a chat model in the console, select it in the knowledge-base settings, and enable graph building. Check service health and task progress in the console before making your first query.

Agent integration

Install the bundled carrel-search skill in your agent, or call the API directly:

curl -sS http://127.0.0.1:9810/search \
  -H 'Content-Type: application/json' \
  -d '{"question": "What are the delivery and acceptance requirements?", "top_k": 8}'

If you set KB_SEARCH_TOKEN, add an Authorization: Bearer … header. For a remote agent, configure CARREL_SEARCH_BASE_URL and CARREL_SEARCH_TOKEN in its environment.

Responses include source passages and, when available, graph evidence and image information. Agents can request more context, inspect images, and follow relationships before answering. See Retrieval and API for authentication, response status, and citations.

Documentation

Guide Contents
Configuration Model endpoints, folders, per-base settings, and access control
Architecture Parsing, graph construction, retrieval, and code layout
Retrieval and API Agent setup, endpoints, evidence status, and evaluation
Operations and development Console, CLI, scheduling, troubleshooting, and tests
Docker Compose Infrastructure, model weights, and container settings
systemd Linux services and timers

Data and access

The console binds to localhost by default. For LAN access, set both KB_WEB_HOST and KB_WEB_TOKEN. Configure KB_SEARCH_TOKEN before using protected search endpoints remotely. The stores and model servers listen on loopback only, which keeps other machines out but not web pages opened in a browser on the same host, so avoid browsing the web there.

Documents and images are sent to the model endpoints you configure. Local endpoints keep model processing within your own infrastructure. See Access and data handling.

License

Carrel is licensed under MIT. Dependencies and model weights have their own licenses; see Third-party notices. Original-resolution PDF image retrieval uses an optional dependency installed with ./deploy.sh --with-pdf-images; without it, retrieval uses cached images.

carrel (FengZhenfei/carrel)

sqlite
Searching Database…

312 ·GitHub
Carrel
What is this?Carrel is a self-hosted knowledge base for AI agents. It automates document parsing, indexing, and retrieval, with optional knowledge graphs, so an agent can pull source passages, images, and facts from your documents and answer from them.
Is this a Python library I import, or a self-hosted service I run?It's a self-hosted service: you deploy its infrastructure (Qdrant, OpenSearch, Neo4j) with Docker, run a Python app, and manage it through a web console and API rather than importing it as a library.
How do I deploy it and get documents indexed?Run the deploy script, which detects your host, starts the infrastructure, installs the Python app, and creates config files; then edit config/knowledge-base.env for model endpoints and drop files into runtime/mirror/ to be enabled as a knowledge base.
What do I need installed before deploying?Python 3.12+ and Docker 25+ with Compose v2, plus a text embedding endpoint, a vision-language endpoint for image descriptions, and a chat model if you want knowledge-graph construction enabled.
Can I run this natively on Windows?No, native Windows deployment isn't supported — you need to use WSL2 instead.
Where do my documents and data actually go?Documents and images are sent to whichever model endpoints you configure; pointing it at local model endpoints keeps that processing inside your own infrastructure instead of a third party.
Do I need an NVIDIA GPU to run it?Only if you want to run the optional local model stack with GPU acceleration; CPU-based parsing is supported as well.
What's the bundled carrel-search skill for?It's a ready-made skill that lets coding agents like Claude Code and Codex call Carrel's retrieval API directly, so you don't have to build the integration yourself.
What powers the retrieval pipeline under the hood?MinerU and native parsers handle document ingestion, Qdrant stores vectors, OpenSearch handles keyword search, Neo4j serves graph queries, and SQLite tracks files and tasks.
What do the knowledge graphs actually capture?They extract entity types, relationships, and facts from your documents, keeping track of sources, time information, and conflict indicators between facts.
What file types can it parse?PDF, Word, PowerPoint, spreadsheets, images, HTML, Markdown, and source code, each with processing suited to that format.
What are similar projects?m_flow, semantica, LightRAG, zilan, utopia, serviette, memvid, ragflow
Which topics is it in?document-parsing, hybrid-search, neo4j, self-hosted-ai, retrieval-augmented-generation, codex-skill, knowledge-graph, claude-code-skill, vector-database, semantic-search, knowledge-base, rag
Creator
FengZhenfei
Size
3.8 MB
Stars
312
Updated
CommitOct 15Releasev0.2.0Oct 04
Age
22d
Commits · 90 Days