Skip to content
Back to search

carrel

Ontology-Augmented Generation for AI agents.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/FengZhenfei/carrel with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/FengZhenfei/carrel'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fengzhenfei--carrel/badge.svg)](/listings/fengzhenfei--carrel)

HTML

<a href="/listings/fengzhenfei--carrel"><img src="/api/listings/fengzhenfei--carrel/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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](docs/configuration.md#model-endpoints) and the [local model setup](deployment/compose/README.md#local-model-servers-profile-local-models). 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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 200 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Carrel
  2. English | [中文](README.zh-CN.md)
  3. [![tests](https://github.com/FengZhenfei/carrel/actions/workflows/tests.yml/badge.svg)](https://github.com/FengZhenfei/carrel/actions/workflows/tests.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  4. **Ontology-Augmented Generation for AI agents.**
  5. Carrel is a self-hosted knowledge base for AI agents. It automates document
  6. parsing, indexing, and retrieval, with optional knowledge graphs. Agents use
  7. its API to retrieve source passages, images, and related facts, then generate
  8. their own answers.
  9. Use it to give an agent access to a collection of product documents, research,
  10. contracts, meeting notes, or other files that change over time. A web console
  11. manages knowledge bases, models, and processing tasks. A bundled
  12. [search skill](skills/carrel-search/SKILL.md) connects agents such as Claude
  13. Code and Codex to the retrieval service.
  14. **[0.4.1 general retrieval benchmarks and codebase capabilities](docs/evaluations/retrieval-0.4.1.md)** · [Full 0.4.0 capability evaluation](docs/evaluations/capability-evaluations-0.4.0.md)
  15. [Features](#features) · [Evaluation](#capability-evaluation) · [Design](#design) · [Quick start](#quick-start) · [Agent integration](#agent-integration) · [Documentation](#documentation)
  16. ## Features
  17. [0.4.3 changes and upgrade steps](docs/releases/0.4.3.md) — Consistent document publication, version-bound evidence, document and section time context, table parsing repairs, and bundled code grammars.
  18. - **Document parsing:** PDF, Word, PowerPoint, spreadsheets, images, HTML,
  19. Markdown, notebooks, source code, and workflow files, with processing suited
  20. to each format. [Format details](docs/architecture.md#ingestion).
  21. - **Automatic updates:** scan for file changes, update indexes, and maintain
  22. enabled knowledge graphs through scheduled tasks.
  23. - **Hybrid retrieval:** combine vector, keyword, graph, and visual search,
  24. with automatic knowledge-base selection and optional text/image reranking
  25. with rank fusion.
  26. - **Knowledge graphs:** extract entity types, relationships, and facts from
  27. your documents; retain sources, time information, and conflict indicators,
  28. compare graph versions, and apply reviewed, evidence-scoped corrections.
  29. - **Agent access:** search through an API, fetch surrounding text or original
  30. images, and follow graph relationships when more evidence is needed.
  31. - **Web console:** configure processing, inspect chunks and graphs, track
  32. tasks, and manage services. Available in English and Chinese.
  33. ## Capability evaluation
  34. Across 275 text queries, 0.4.1 reached **93.45%** evidence Hit@5 and **0.8141** MRR@10. In a separate study of 24 code questions, Haiku answered **13** completely from the first response and **23** with Skill follow-up. [0.4.1 evaluation](docs/evaluations/retrieval-0.4.1.md)
  35. The full 0.4.0 evaluation also covers graph rebuild stability, time-scoped evidence, conflicts and ontology governance. [Full 0.4.0 technical report](docs/evaluations/capability-evaluations-0.4.0.md)
  36. ## How it works
  37. ```mermaid
  38. flowchart LR
  39. D[Document folders] --> P[Parse and chunk]
  40. P --> I[Vector and keyword indexes]
  41. P --> G[Optional knowledge graphs]
  42. I --> R[Retrieval API]
  43. G --> R
  44. R --> A[AI agent]
  45. A -->|Follow-up queries| R
  46. ```
  47. Carrel uses MinerU and native parsers for ingestion. Standard uses Qdrant,
  48. OpenSearch and Neo4j; Light uses embedded LanceDB and DuckDB. SQLite tracks files
  49. and tasks in both editions. Model services run independently, locally or through
  50. compatible hosted endpoints.
  51. See [Architecture](docs/architecture.md) for the pipeline and retrieval design.
  52. ## Design
  53. Carrel provides general knowledge storage, retrieval, and evidence interfaces.
  54. Entities, relationships, and facts retain sources, time information, and
  55. conflicts so agents can check and use them alongside the original documents.
  56. Default retrieval retains historical and future source claims. An explicit
  57. time query selects the relevant evidence; reviewed corrections record which
  58. sources and identities the decision applies to.
  59. **The Agent Loop plugin is in development and not yet implemented.** It is
  60. intended to use these interfaces to continuously learn an enterprise ontology,
  61. seek clarification from relevant people, and maintain correction rules.
  62. Routine graph updates merge new and changed content incrementally. Configured
  63. time or change thresholds trigger full rebuilds, balancing update cost with
  64. overall consistency. Parsing, indexing, and graph construction are maintained
  65. separately: rebuilding a graph can reuse parsed content and chunks while
  66. preserving RAG indexes.
  67. ## Requirements
  68. - Docker with Compose v2. Python and background scheduling run inside the application container.
  69. - A text embedding endpoint; a vision-language endpoint for image descriptions;
  70. and a chat model for knowledge graph construction, if enabled.
  71. - An NVIDIA GPU and NVIDIA Container Toolkit for GPU parsing. CPU parsing is
  72. also supported. Resource needs depend on the parser and collection size.
  73. | Platform | Deployment |
  74. |---|---|
  75. | Linux with NVIDIA GPU | GPU parsing with NVIDIA Container Toolkit; container scheduling |
  76. | Linux without GPU | CPU parsing; connect to model services on another host or a provider |
  77. | macOS with Docker Desktop | CPU parsing and application containers, including scheduling |
  78. | Windows | Use WSL2; native Windows deployment is not supported |
  79. [Example setup](docs/example-setup.md) describes the author's installation
  80. on an NVIDIA DGX Spark and some lighter alternatives.
  81. ## Quick start
  82. ### 1. Deploy the services
  83. ```bash
  84. git clone https://github.com/FengZhenfei/carrel.git
  85. cd carrel
  86. ./deploy.sh --standard --build
  87. # Or use embedded storage:
  88. # ./deploy.sh --light --build
  89. ```
  90. The optional script prepares Compose configuration and starts the application,
  91. background scheduler and selected dependencies. You can also use Compose directly.
  92. First startup downloads MinerU parser assets. See [Container deployment](deployment/compose/README.md).
  93. ### 2. Configure model endpoints
  94. Choose **Standard** for Qdrant, OpenSearch and Neo4j, or **Light** for embedded
  95. LanceDB and DuckDB. The edition is fixed for that deployment directory. Both
  96. include MinerU; Light has no database containers. See [Storage editions](docs/storage.md).
  97. In **System settings**, configure LLM, Embedding and Reranker endpoints, model IDs
  98. and API keys. Register a vision-capable LLM and select it as the **Multimodal model**
  99. for each knowledge base. Images, charts and table review share that selection.
  100. Models can run on your own machines or hosted platforms. Carrel does not start
  101. these model services or download their weights. See [Model configuration](docs/configuration.md#model-endpoints).
  102. ### 3. Add documents
  103. Open the console at **http://127.0.0.1:9800**. Put documents in
  104. `data/runtime/mirror/<folder>/`, then enable that folder in the console. Each
  105. enabled folder becomes a knowledge base; scheduled tasks process its files.
  106. For a knowledge graph, register a chat model with its **Max Input** in the console, select it in the
  107. knowledge-base settings, and enable graph building. Check service health and
  108. task progress in the console before making your first query.
  109. ## Agent integration
  110. Install the bundled [carrel-search skill](skills/carrel-search/SKILL.md)
  111. in your agent, or call the API directly:
  112. The first container start creates `KB_SEARCH_TOKEN` in
  113. `data/config/knowledge-base.env`. Set `CARREL_SEARCH_TOKEN` to that value:
  114. ```bash
  115. export CARREL_SEARCH_TOKEN='your search token'
  116. curl -sS http://127.0.0.1:9810/search \
  117. -H "Authorization: Bearer $CARREL_SEARCH_TOKEN" \
  118. -H 'Content-Type: application/json' \
  119. -d '{"question": "What are the delivery and acceptance requirements?", "top_k": 8}'
  120. ```
  121. For a remote agent,
  122. configure `CARREL_SEARCH_BASE_URL` and `CARREL_SEARCH_TOKEN` in its environment.
  123. Responses include source passages and, when available, graph evidence and
  124. image information. Agents can request more context, inspect images, and
  125. follow relationships before answering. See [Retrieval and API](docs/retrieval.md)
  126. for authentication, response status, and citations.
  127. ## Documentation
  128. | Guide | Contents |
  129. |---|---|
  130. | [Configuration](docs/configuration.md) | Model endpoints, folders, per-base settings, and access control |
  131. | [Architecture](docs/architecture.md) | Parsing, graph construction, retrieval, and code layout |
  132. | [Retrieval and API](docs/retrieval.md) | Agent setup, endpoints, evidence status, and evaluation |
  133. | [Retrieval and codebase evaluation (0.4.1)](docs/evaluations/retrieval-0.4.1.md) | Document retrieval, page-image location, Skill follow-up and cross-file code analysis |
  134. | [Capability evaluation (0.4.0)](docs/evaluations/capability-evaluations-0.4.0.md) | Full technical report: retrieval, answers, temporal evidence, conflicts, ontology, rebuild stability, latency, and token usage |
  135. | [Operations and development](docs/operations.md) | Console, CLI, scheduling, troubleshooting, and tests |
  136. | [Test scope](docs/testing.md) | Shared regression contracts, deployment-specific checks, and live evaluations |
  137. | [Example setup](docs/example-setup.md) | The author's installation on a DGX Spark, a Mac that syncs the documents, and lighter alternatives |
  138. | [Docker Compose](deployment/compose/README.md) | Infrastructure, model weights, and container settings |
  139. | [Container deployment](deployment/compose/README.md) | Images, scheduling, persistent data and updates |
  140. | [systemd](deployment/systemd/README.md) | Native/source installation |
  141. ## Data and access
  142. The console binds to localhost by default. For LAN access, set both
  143. `KB_WEB_HOST` and `KB_WEB_TOKEN`. Configure `KB_SEARCH_TOKEN` before using
  144. protected search endpoints remotely. The stores and model servers listen on
  145. loopback only, which keeps other machines out but not web pages opened in a
  146. browser on the same host, so avoid browsing the web there.
  147. Documents and images are sent to the model endpoints you configure. Local
  148. endpoints keep model processing within your own infrastructure.
  149. See [Access and data handling](docs/configuration.md#access-and-data-handling).
  150. ## License
  151. Carrel is licensed under [MIT](LICENSE). Dependencies and model weights have
  152. their own licenses; see [Third-party notices](NOTICE.md). Original-resolution
  153. PDF image retrieval uses an optional dependency installed with
  154. `./deploy.sh --with-pdf-images`; without it, retrieval uses cached images.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.