What Caelune does
Caelune builds searchable indexes from knowledge you already keep on your own computer. It combines exact-text retrieval, structural signals, semantic vector search, optional reranking, and source-aware context assembly.
The desktop app manages data roots, Runtime components, models, knowledge-base builds, live watch, queries, and result review. The optional MCP server exposes the same retrieval core to MCP-capable AI clients through two read-only tools.
Search local Markdown, PDF, and other documents, review source-linked results directly, or provide selected evidence to AI.
Choose your path
Interface preview
The Query Console keeps input, scope, retrieval settings, and live query state together. Results and Details uses a separate page for source-labelled hits, snippet review, full-context selection, and page filtering.
Download
Open the latest release and choose the package that matches your use case:
| Package label | Use it for |
|---|
WIN-EXE | Normal Windows desktop use: configure, build, watch, search, and review results |
MCP-...-win64.zip | Manual stdio setup for an MCP client |
.mcpb | MCP Registry or MCPB-aware clients |
The MCP package does not build or modify knowledge bases. Build the index with the Windows desktop app first.
Highlights
- Local-first storage — indexes, configuration, models, logs, and Runtime payloads stay under the active local data root.
- Markdown and Logseq awareness — understands Markdown content plus common Logseq properties, block references, and embeds.
- Hybrid retrieval — combines SQLite FTS5, structure-aware scoring, LanceDB vector search,
BAAI/bge-m3, and optional BAAI/bge-reranker-v2-m3.
- PDF and Tika extensions — maintains separate extension indexes and returns unified results with explicit source labels. The Tika catalog exposes 1,290 format entries; real compatibility still depends on the source file and parser.
- Event-driven live watch — reacts to real file changes, waits for the configurable quiet period, and performs incremental updates in disposable worker processes.
- Visible query stages — preparing, lexical recall, semantic recall, fusion, reranking, finalization, and context packing remain visible in the Query Console.
- Resource-aware execution — Auto mode prefers a usable NVIDIA CUDA path and falls back safely when Windows Commit, physical memory, or GPU memory is insufficient.
- Read-only MCP access — MCP clients can inspect readiness and search, but cannot build indexes, delete data, or change configuration.
Privacy boundary
Caelune is local-first, not a promise that every possible workflow is permanently offline.
- Source files are read for indexing; normal build and source-removal operations do not delete or rewrite the original notes or documents.
- Network access is needed only for user-initiated downloads such as Runtime components, models, Java, or Tika.
- Retrieved text leaves the app only when you copy it, export it, or explicitly let an MCP client request it.
- Third-party AI clients and anything you paste into them remain subject to their own privacy policies.
Keep backups of important source material and review retrieved context before using it in high-stakes work.
Quick start
- Download the release asset whose name contains
WIN-EXE.
- Extract the archive and launch
Caelune.exe.
- Wait for the automatic Runtime detection to finish.
- Choose the local data root and add one or more Markdown knowledge-base directories.
- Install or repair the CPU/CUDA Runtime and local models from the Runtime page when prompted.
- Run a full build once.
- Search from the Query Console. Enable live watch if you want later edits to enter the index automatically.
Detailed instructions: Getting Started.
Practical requirements
- 64-bit Windows
- Enough disk space for the application, external Runtime, local models, and indexes
- Internet access for the initial Runtime/model downloads unless the payloads are installed manually
- CPU execution is supported; a compatible NVIDIA GPU and driver are optional
- Windows automatic paging-file management is recommended for large knowledge bases and local AI models
The Runtime and models are external sidecars so healthy components can be reused across application versions. See Runtime and Models.
Retrieval flow
flowchart LR
A["Markdown / PDF / Tika sources"] --> B["Local parsing and indexes"]
B --> C["FTS5 lexical recall"]
B --> D["LanceDB semantic recall"]
C --> E["Fusion and filters"]
D --> E
E --> F["Optional reranking"]
F --> G["Results and context pack"]
G --> H["Clipboard or read-only MCP"]
MCP in one minute
- Build at least one knowledge base with the desktop app.
- Download the MCP ZIP for manual
stdio configuration, or use the Registry/MCPB package.
- Point a compatible client at
Caelune-MCP.exe.
- Let the client call:
omniclip.status to inspect readiness and active retrieval modeomniclip.search to retrieve source-labelled results
Some clients do not accept local stdio servers directly and may require a local proxy. See the MCP Integration Wiki and MCP_SETUP.md.
Documentation
User guides
Project references
Development
# Desktop GUI
.\scripts\run_gui.ps1
# CLI status and query
.\scripts\run.ps1 status
.\scripts\run.ps1 query "your question"
# Build Windows packages
.\scripts\build_exe.ps1
# MCP self-check from source
python launcher_mcp.py --mcp-selfcheck
Developer orientation and architecture links live in Development and Architecture.
License and third-party software
Caelune is released under the MIT License. It relies on open-source projects including PySide6, SQLite, LanceDB, Apache Arrow, PyTorch, sentence-transformers, Transformers, BGE models, PyPDF, Apache Tika, Eclipse Temurin, watchdog, PyInstaller, and the Model Context Protocol SDK.
See THIRD_PARTY_NOTICES.md for the repository-level legal and distribution notices.
Caelune and its retrieval results are provided without warranty. Verify important results, maintain backups, and do not use retrieved context or downstream AI output as the sole basis for medical, legal, financial, safety-critical, or other high-stakes decisions.
