alcove-search 0.5.0

Local-first document retrieval. Your data never leaves your disk.

Alcove is search infrastructure for documents you keep on your own machine. It ingests a local directory, extracts text, chunks it, writes a local index, and returns matching chunks through a CLI or local web/API server.

It is retrieval, not generation. Alcove does not summarize, answer questions, host models, or invent text. Search results are excerpts from the indexed corpus.

See it in 30 seconds · Why Alcove?

What ships today

Alcove v0.5.0 ships a working local pipeline:

• Recursive ingest for PDF, EPUB, HTML, Markdown, CSV, JSON, JSONL, DOCX, PPTX, RTF, ODT, XLSX, RST, TSV, and plain text.
• Local indexing with ChromaDB by default, with zvec available as an optional backend.
• A deterministic hash embedder by default, plus opt-in sentence-transformers and Ollama embedders for real semantic similarity.
• CLI search and a FastAPI web service with search, upload, health, collection-list, and browse endpoints.
• A machine-readable capabilities descriptor at /.well-known/alcove.json, /capabilities, and /api/capabilities for client discovery.
• A canonical client result schema at POST /api/search alongside the raw POST /query response.
• Semantic, keyword (BM25), and hybrid search modes.
• Named collection metadata and collection filtering.
• STDIO MCP retrieval tools for local index search and collection listing.
• Local signing helpers and index signing tooling for provenance checks.
• Python entry-point plugins for extractors, embedders, and vector backends.

The roadmap includes richer manifests, provenance workflows, streaming ingest, and more plugin categories. Those are not documented here as shipped behavior; see Roadmap for the pending-feature map.

How it works

Three stages. Each stage reads from local disk and writes to local disk, so it can be re-run independently.

data/raw/* -> data/processed/chunks.jsonl -> vector store -> query responses

Ingest discovers files recursively and extracts text with format-specific extractors.

Index embeds chunks and writes vectors plus metadata to a local vector store.

Query retrieves matching chunks through the CLI or local API/web UI.

See Architecture for module boundaries and extension points.

Quick start

pip install alcove-search[semantic]
alcove seed-demo
alcove serve

Open http://localhost:8000.

The [semantic] extra installs sentence-transformers. The first semantic run downloads all-MiniLM-L6-v2 once, then runs locally. For zero-download installs:

pip install alcove-search

The base package uses the hash embedder. It is deterministic, offline, and useful for smoke tests or operators who do not want ML in the pipeline. It is not a semantic search model.

Trust model

Local disk only for normal ingest, index, query, and serve operations. No telemetry. No account creation. ChromaDB's upstream telemetry is disabled.

Network use is explicit: alcove seed-demo fetches the public sample corpus, and sentence-transformers downloads its model on first use. After that, embedding runs locally.

Alcove does not require authentication. The local API is open to anyone who can reach the port, so keep it bound to 127.0.0.1 unless you put authentication in front of it. See Operations and Security.

Conductor workspaces

Alcove now ships a shared Conductor config:

• conductor.json bootstraps a workspace with ./scripts/bootstrap.sh and runs the local API on CONDUCTOR_PORT.
• .worktreeinclude copies local .env* files into new workspaces when present.
• runScriptMode stays concurrent because each workspace can bind its own port cleanly.

This repo is a good fit for normal workspace-local runs. Use Spotlight only if you intentionally want one heavyweight root-local stack to hot-swap tracked workspace changes.

Common commands

alcove ingest /path/to/files
alcove search "phrase to find" --mode hybrid --k 5
alcove collections
alcove status
alcove serve --host 127.0.0.1 --port 8000

Documentation

Why Alcove? · Architecture · Operations · Security · Desktop Packaging · Seed Corpus · Roadmap · Plugin Ideas · Accessibility

License

Apache 2.0