alcove

Purpose

Alcove solves the problem that AI coding agents do not understand project context. Agents start from scratch in every session, do not know the architecture, ignore existing decision constraints, and repeatedly ask for the same explanations. Stuffing all documentation into the agent configuration causes context bloat (10 documents may waste over 50K tokens), copy-pasting cannot scale across sessions, and leaving it unchecked causes agents to invent requirements out of thin air. Alcove lets agents actively search for the documentation they need when needed, rather than injecting documentation.

Main Capabilities

• On-demand retrieval: Agents search project documentation on demand, without loading documentation into context, saving tokens and attention.
• Hybrid search: BM25 (provided by tantivy) combined with vector similarity search (provided by fastembed), supporting CLI search and agent-based tools. The default model is ArcticEmbedXS (90 MB, multilingual).
• Code indexing: Parses source code with tree-sitter, generates module-level Markdown summaries CODE_INDEX.md, and connects to the Tantivy search pipeline. The official binary enables all 12 parsers (lang-all feature).
• Multi-project and global search: By default detects the current project based on the terminal working directory, and can also be overridden with MCP_PROJECT_NAME; supports global search across all projects (scope: "global").
• Documentation policy: Defines team documentation standards through policy.toml, with priority project > team > built-in defaults.
• Documentation validation and generation: lint checks four items; documentation is classified into different levels; the audit tool scans documentation repositories and local project directories and provides suggestions.
• Knowledge base Vault: A knowledge base independent of project documentation, used for research notes, reference materials, etc., with independent indexing, caching, and search that do not affect each other.
• Search quality measurement: Built-in IR metrics and regression detection, supporting isolated corpus mode (19 synthetic documents, 25 queries, completed within 60 seconds) for CI benchmarking. Regression thresholds are precision >5%, latency >20%, throughput >15%, with alerts at half the threshold.
• Background service: A persistent background service eliminates cold-start latency for each session; the stdio process acts as a lightweight proxy forwarding requests to the hot service.

Usage

After installationyou must run once alcove setup to configure the documentation root directory and enable full functionality; the plugin will automatically start the API server, but before setup is run, documents cannot be searched or indexed.

Installation channels: Claude plugin, Codex plugin, Antigravity (Gemini CLI), Grok Build (macOS Apple Silicon only).

On macOS without Homebrew, use the installation script; Windows currently has no prebuilt binaries released and must be built from source; it can also be installed through the Rust toolchain cargo install. Note: prebuilt binaries downloaded by cargo binstall include hybrid search; building from source requires --features full-macos or --features full-cross to support hybrid search, otherwise only BM25 keyword search is available.

setup interactive guidance contents: where documentation is stored, tracked documentation categories, preferred diagram format, embedding model for hybrid search, background service, AI agents to configure. setup can be rerun at any time, and it will remember previous choices.

Common CLI commands:alcove search, project switching,--scope global、alcove validate、alcove index、alcove rebuild、alcove doctor、alcove token、alcove api env.

Agents use Alcove through the local HTTP API (port 58301). Example: the agent calls POST /v1/search, then through GET /docs/{path}?project=... Read the most relevant documents. MCP is still available; for manual stdio setup, see registry/mcp.json.

Use cases

• Maintain a unified documentation layer in multi-project, multi-agent environments.
• Teams that need private documents to stay out of public repositories.
• Semantic retrieval for multilingual projects (the default model supports multiple languages).
• Code indexing for monorepos.
• Working with Obsidian: together with the obsidian-forge generator, point docs_root to the obsidian-forge project archive, and link the other three knowledge areas as separate vaults.

Limitations and known issues

• You must first run alcove setup, otherwise you cannot search or index.
• Windows prebuilt binaries are not yet released; you need to build them yourself.
• When building from source without the full feature, only BM25 keyword search is supported, with no vector hybrid search.
• Without pdftotext, it falls back to the built-in PDF parser, which may fail on some files.
• During the first index or a full rebuild, peak memory grows with corpus size; loading the embedding model takes about 235–500 MB, and large models (such as BGEM3, ArcticEmbedMLong) can reach 1.5–2 GB during rebuilds; after completion, steady state is about 50–200 MB.
• If the background service returns 403, you need to set ALCOVE_TOKEN.
• No search results may mean the index has not been built; you need to first run alcove index.

Additional notes

Alcove does not replace CLAUDE.md / AGENTS.md: the latter define behavioral rules (commit style, language preferences, security constraints), while Alcove manages organizational knowledge (architecture decisions, progress tracking, coding standards, code structure). Compared with using ripgrep directly as an MCP tool, Alcove chunks and ranks documents, returns only the most relevant passages, and provides vector semantic search that ripgrep does not have. For the list of supported languages and agents, and configuration options, see the official repository.