Alcove

你的 AI Agent 不了解你的项目。Alcove 来解决这个问题。

→ 快速开始

English · 한국어 · 日本語 · 简体中文 · Español · हिन्दी · Português · Deutsch · Français · Русский

Alcove 是一个 HTTP API 服务，可让 AI 编码 Agent 按需访问你的私有项目文档——通过 BM25 + 向量混合搜索 实现精准检索，通过 tree-sitter 代码索引 帮助 Agent 理解代码库结构，并通过 策略强制执行 确保文档一致性。不会造成上下文膨胀，不会将文档泄露到公开仓库，也不必为每个 Agent 单独配置每个项目。

演示

Claude、Codex — 搜索 · 切换项目 · 全局搜索 · 验证和生成。一处配置即可。

CLI 演示

alcove search · 切换项目 · --scope global · alcove validate

## 问题所在

你的 AI Agent 每次会话都从零开始。

它不了解你的架构，也会忽略你已做出的决策所规定的约束。每次会话，它都会让你重复解释同样的事情。

上下文窗口是瓶颈。每个 token 都要花费金钱和注意力。每次运行都把 10 份架构文档加载到上下文中，会浪费 50K+ 个 token，而且 Anthropic 自己的文档也警告说，臃肿的配置文件会让 Agent 忽略你的实际指令。

所以你只能在三个糟糕的选项中做选择：

把所有内容塞进 Agent 配置——每次运行都会将每个文件加载到上下文中。10 份文档 = 上下文臃肿 = 响应更慢、更贵、更不准确。

复制粘贴到每次聊天中——偶尔管用，但无法扩展到多个会话。

干脆不管——你的 Agent 会凭空编造你已经记录的需求，忽略你已做出的决策所规定的约束，而你每周一早上都要重新解释同样的架构。

现在把情况扩展到 5 个项目和 3 个 Agent。每次切换，你都会丢失上下文。

Alcove 如何解决这个问题

Alcove 不会注入你的文档。Agent 会在需要时搜索所需内容。

~/projects/my-app $ claude "/alcove how is auth implemented?"

  → Alcove detects project: my-app
  → BM25 search: "auth" → ARCHITECTURE.md (score: 0.94), DECISIONS.md (score: 0.71)
  → Agent gets the 2 most relevant docs, not all 12

~/projects/my-api $ codex "/alcove review the API design"

  → Alcove detects project: my-api
  → Same doc structure, same access pattern
  → Different project, zero reconfiguration

随时切换 Agent，随时切换项目。文档层始终保持标准化。

为什么选择 Alcove

Alcove 为你的 Agent 提供能够跨会话保留的记忆。

Agent 不会将你的文档加载到上下文中。**它们会在需要时搜索所需内容。**架构文档、设计决策、运行手册、约束——全部集中在一处，可搜索，而且绝不会出现在你的公开仓库中。

Agent 配置用于定义 Agent 的行为。Alcove 用于管理项目知识。

Agent config files                ← agent rules, coding conventions, recurring corrections
~/.alcove/docs/my-app/
  ARCHITECTURE.md                ← tech stack, data model, system design
  DECISIONS.md                   ← why X was chosen over Y
  DEBT.md                        ← known issues, workarounds
  ...                            ← agent searches here when it needs context

没有文档层	使用 Alcove
Agent 配置中的文档会在每次运行时使上下文臃肿	混合搜索（BM25 + RAG）——Agent 仅提取所需内容，并按相关性排序
Agent 只能查看文本文档，看不到代码结构	Tree-sitter 代码索引——Agent 能理解 12 种语言中的模块、函数和类型
内部文档散落在 Notion、Google Docs 和本地文件中	一个 doc-repo，按项目整理
每个 AI Agent 都要单独配置文档访问权限	只需一次设置，所有 Agent 共享同一访问权限
切换项目意味着要重新解释上下文	自动检测当前工作目录（CWD），即时切换项目
Agent 搜索会返回随机匹配行	结果按相关性排序——最佳匹配优先，每个文件仅返回一个结果
“搜索我所有关于 OAuth 的笔记”——无法实现	通过一次查询即可全局搜索所有项目
敏感文档存放在项目仓库中	私密文档保存在你的设备上，绝不会出现在公开仓库中
每个项目和团队成员的文档结构都不同	policy.toml 在所有项目中强制执行统一标准
无法检查文档是否完整	validate 可发现缺失文件、空模板和缺失章节
过时文档中的失效链接或 WIP 标记无人察觉	lint 会自动检测失效链接、孤立文件和过时标记
Obsidian 或其他工具中的笔记彼此孤立	promote 只需一条命令，就能将任何笔记加入你的 doc-repo

快速开始

必需步骤：安装后运行一次 alcove setup，以配置文档根目录并启用完整功能。插件会自动启动 API 服务，但在运行 setup 之前，Alcove 无法搜索或索引文档。

使用 Obsidian？ 请参阅生态系统一节，了解文档结构和知识库配置。

Claude Code

/plugin marketplace add epicsagas/plugins
/plugin install alcove@epicsagas

自动安装二进制文件，并在下次会话启动时启动 API 服务。

alcove setup   # run once after plugin install

使用 claude plugin update alcove@epicsagas 更新。

Codex

codex plugin marketplace add epicsagas/plugins
codex plugin add alcove@epicsagas

自动安装技能并启动 API 服务（插件会自动启用）。立即可用，无需其他步骤。

使用 codex plugin marketplace upgrade && codex plugin add alcove@epicsagas 更新。

Antigravity（Gemini CLI）

agy plugin install https://github.com/epicsagas/alcove

自动安装插件（API 服务、技能、钩子），并在下次会话启动时运行。

alcove setup   # run once after plugin install

Grok Build (xAI)

grok plugin marketplace add epicsagas/plugins
grok plugin install alcove@epicsagas --trust

自动安装二进制文件，并在下次会话启动时启动 API 服务。

alcove setup   # run once after plugin install

macOS（仅限 Apple Silicon）

brew install epicsagas/tap/alcove

没有 Homebrew？使用安装脚本：

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/alcove/releases/latest/download/alcove-installer.sh | sh

Linux（x86_64）

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/epicsagas/alcove/releases/latest/download/alcove-installer.sh | sh

Windows（x86_64 / ARM64）

目前尚未发布预构建的 Windows 二进制文件。请从源代码构建：

cargo install alcove --features full-cross

通过 Rust 工具链

cargo binstall alcove   # pre-built binary, includes hybrid search
cargo install alcove --features full-macos   # build from source (macOS)
cargo install alcove --features full-cross   # build from source (Linux/Windows)

注意：cargo binstall 会下载包含混合搜索（向量 + BM25）的预构建二进制文件。从源代码构建时，必须使用 --features full-macos 或 --features full-cross 才能支持混合搜索。不启用这些功能时，只能使用 BM25（关键词）搜索。

首次设置（必需）

通过上述任一方式安装后，请运行：

alcove setup
alcove --version
alcove doctor

setup 会通过交互方式引导你完成所有设置：

1. 文档所在位置
2. 要跟踪的文档类别
3. 首选的图表格式
4. 用于混合搜索的嵌入模型
5. 后台服务 — 避免每次会话启动时冷启动（macOS 登录项）
6. 要配置的 AI Agent（技能文件 — Claude Code 和 Codex 由其插件系统处理）

随时重新运行 alcove setup 更改设置。它会记住你之前的选择。

可选依赖项

工具	用途	安装
pdftotext (poppler)	完整提取 PDF 文本 — 搜索 PDF 时必需	macOS：brew install poppler · Debian/Ubuntu：apt install poppler-utils · Fedora：dnf install poppler-utils · Windows：适用于 Windows 的 poppler

如果没有 pdftotext，Alcove 会回退到内置的 PDF 解析器，该解析器可能无法处理某些文件。运行 alcove doctor 检查设置。

故障排除

Agent 找不到 Alcove 工具 重新运行 alcove setup — 它会为所有已配置的 Agent 重新配置 API 服务。然后启动新的 Agent 会话（更改会在下次会话启动时生效）。

搜索没有返回结果 索引可能尚未构建。运行 alcove index 构建索引，然后重试。

后台服务返回 403 Unauthorized 你的 shell 中未设置 ALCOVE_TOKEN。运行 alcove token 打印令牌，然后将 export ALCOVE_TOKEN="..." 添加到 shell 配置文件并重新加载。

alcove doctor 报告问题 按照 doctor 输出的建议操作 — 它会检查二进制文件位置、API 服务状态、索引状态，以及 pdftotext 等可选依赖项。

用法

CLI 搜索

直接从终端搜索文档。默认情况下，它会搜索所有项目（全局范围）。

# Basic search (global scope)
alcove search "authentication"

# Limit search to the current project (auto-detected via CWD)
alcove search "auth flow" --scope project

# Force grep mode (exact substring match)
alcove search "TODO" --mode grep

# Force ranked mode (BM25/Hybrid)
alcove search "data model" --mode ranked

# Adjust result limit
alcove search "deployment" --limit 5

编码 Agent（HTTP API）

AI 编码 Agent 通过本地 HTTP API 使用 Alcove。每个会话中，URL 和认证令牌会通过 alcove api env 解析一次：

eval $(alcove api env)
# sets ALCOVE_URL=http://127.0.0.1:<port>
# sets ALCOVE_TOKEN=<token>  (only if configured)

Agent 可以通过 verify 或 rag status 参数验证连接；该操作会检查守护进程、解析 URL，并自动调用 /health。通常你无需自行调用这些参数；当你询问有关项目的问题时，Agent 会调用它们。

端点	方法	描述
/health	GET	健康检查 — 验证 API 服务是否正在运行
/search?q=...	GET	搜索文档（查询参数）
/v1/search	POST	使用 JSON 请求体搜索（支持 scope、limit、mode）
/projects	GET	列出 doc-repo 中的所有项目
/projects	POST	根据模板初始化新项目
/projects/{name}/docs	GET	列出项目的文档及其大小和分类
/projects/{name}/audit	GET	审查文档健康状况（缺失、过时、位置不当）
/projects/{name}/validate	GET	根据 policy.toml 验证文档
/projects/{name}/config	PUT	更新 alcove.toml 中的项目设置
/docs/{path}	GET	读取指定的文档文件（查询参数：project、offset、limit）
/index	POST	更新搜索索引（增量式，所有项目）
/projects/{name}/index	POST	更新搜索索引（单个项目）
/changes	GET	检查自上次索引以来更改的文件（查询参数：auto_rebuild）
/lint	GET	检查文档 — 链接失效、孤立文档、过时标记（查询参数：project）
/vaults	GET	列出所有知识库库
/vaults/search?q=...	GET	搜索知识库库（查询参数：vault、limit）
/vaults/backup	POST	对知识库状态创建 Git 快照
/promote	POST	将文件导入 doc-repo
/index-code	POST	使用 tree-sitter 为源代码编制索引
/mcp	POST	为全部 16 个 MCP 工具提供 JSON-RPC 代理（旧版）

注意：仍可使用 MCP — 如果你更喜欢基于 stdio 的访问方式，请参阅 registry/mcp.json 进行手动设置。

API 调用示例：

# Health check
curl http://localhost:58301/health

# Search docs
curl "http://localhost:58301/search?q=authentication+flow"

# Advanced search with JSON body
curl -X POST http://localhost:58301/v1/search \
  -H "Content-Type: application/json" \
  -d '{"query": "api endpoint", "scope": "global", "limit": 5}'

Agent 交互示例：

用户：“/alcove 如何添加新的 API 端点？” Agent：（调用 POST /v1/search，参数为 query="add api endpoint"） Agent：（通过 GET /docs/{path}?project=... 读取最相关的文档） Agent：“根据 ARCHITECTURE.md，你需要……”

---

工作原理

flowchart LR
    subgraph Projects["Your projects"]
        A1["my-app/\n  src/ ..."]
        A2["my-api/\n  src/ ..."]
    end

    subgraph Docs["Your private docs (one repo)"]
        D1["my-app/\n  PRD.md\n  ARCH.md"]
        D2["my-api/\n  PRD.md\n  ..."]
        P1["policy.toml"]
    end

    subgraph Agents["Any AI agent"]
        AG["Claude Code · Cursor\nCodex · Copilot\n+4 more"]
    end

    subgraph API["Alcove HTTP API server"]
        T["search · get_file\noverview · audit\ninit · validate"]
    end

    A1 -- "CWD detected" --> D1
    A2 -- "CWD detected" --> D2
    Agents -- "HTTP :58301" --> API
    API -- "scoped access" --> Docs

你的文档按项目分别存放在独立目录（DOCS_ROOT）中。Alcove 在该目录中管理文档，并通过 HTTP 在端口 58301 上向任何 AI Agent 提供文档。

API 端点

端点	方法	作用
/health	GET	健康检查 — 验证 API 服务是否正在运行
/search?q=...	GET	搜索文档（查询参数）
/v1/search	POST	使用 JSON 请求体搜索（scope、limit、mode）
/projects	GET	列出所有项目
/projects	POST	初始化新项目
/projects/{name}/docs	GET	列出项目的文档
/projects/{name}/audit	GET	审查文档健康状况
/projects/{name}/validate	GET	根据策略验证文档
/projects/{name}/config	PUT	更新项目设置
/docs/{path}	GET	读取文档文件
/rebuild	POST	重建搜索索引
/changes	GET	检查更改的文件
/lint	GET	检查文档
/vaults	GET	列出知识库库
/vaults/search?q=...	GET	搜索知识库库
/vaults/backup	POST	备份知识库
/promote	POST	将文件导入 doc-repo
/index-code	POST	为代码结构编制索引
/mcp	POST	JSON-RPC 代理（旧版 MCP）

注意：仍可手动设置 MCP — 基于 stdio 的访问方式请参阅 registry/mcp.json。

CLI

alcove              Start API server (agents call this)
alcove setup        Interactive setup — re-run anytime to reconfigure
alcove doctor       Check the health of your alcove installation
alcove validate     Validate docs against policy (--format json, --exit-code)
alcove lint         Semantic lint — broken links, orphans, stale markers (--format json)
alcove promote      Bring a file from an external vault into your doc-repo
alcove index        Update the search index (incremental — only changed files)
alcove rebuild      Rebuild the search index from scratch (use after schema changes)
alcove search       Search docs from the terminal
alcove bench        Search quality benchmark [--corpus] (precision, latency, regression detection)
alcove index-code   Generate code structure index from source [--language LANG] [--source PATH]
alcove token        Print the bearer token (for background server auth)
alcove uninstall    Remove skills, config, and legacy files

alcove mcp <CMD>      Manage background API server lifecycle (start, stop, status, enable, disable)

alcove vault create   Create a new knowledge base vault
alcove vault link     Link an external directory as a vault (e.g., Obsidian)
alcove vault list     List all vaults with document counts
alcove vault remove   Remove a vault (symlinks: remove link only)
alcove vault add      Add a document to a vault
alcove vault index    Build search index for vaults
alcove vault rebuild  Rebuild vault search index from scratch

代码索引

使用 tree-sitter 解析源文件并生成 CODE_INDEX.md，这是代码库的模块级 Markdown 摘要，可与 Tantivy 搜索流水线集成。

# Index the current project's source (auto-detects all languages)
alcove index-code --source ./src

# Monorepo: index a directory with multiple languages at once
alcove index-code --source ./

# Restrict to a single language (useful when only one language should be indexed)
alcove index-code --source ./src --language typescript
alcove index-code --source ./src --language rust

支持的语言：

语言	功能标志	文件扩展名
Rust	lang-rust	.rs
Python	lang-python	.py、.pyi
TypeScript	lang-typescript	.ts、.tsx
JavaScript	lang-javascript	.js、.jsx、.mjs
Go	lang-go	.go
Java	lang-java	.java
Kotlin	lang-kotlin	.kt、.kts
C	lang-c	.c、.h
C++	lang-cpp	.cpp、.cc、.cxx、.hpp、.hxx、.h
Swift	lang-swift	.swift
Ruby	lang-ruby	.rb
C#	lang-csharp	.cs

官方二进制文件启用了全部 12 种解析器（lang-all 功能）。未指定 --language 标志时，会自动索引所有可识别的扩展名，适用于大型单体仓库。

--language 标志接受规范名称和常见别名：ts → TypeScript、cpp → C++、csharp → C#、py → Python、js → JavaScript、kt → Kotlin、rb → Ruby。

代码检查

# Lint the current project (auto-detected from CWD)
alcove lint

# Lint a specific project by name
alcove lint --project my-app

# Machine-readable output for CI
alcove lint --format json

代码检查会检查以下四项：

检查项	检查内容
broken-link	指向不存在文件的 [[wikilinks]] 和 [text](path)
orphan	没有其他文档链接到的文件
stale-marker	WIP / TODO / FIXME / DRAFT / DEPRECATED 标记
stale-date	过时 2 年或更久的年份提及（例如“截至 2022 年”）

提升

# Copy a note from Obsidian into your doc-repo (auto-routes to matching project)
alcove promote ~/my-brain/Projects/auth-notes.md

# Route to a specific project
alcove promote ~/my-brain/Projects/auth-notes.md --project my-app

# Move instead of copy
alcove promote ~/my-brain/Projects/auth-notes.md --mv

没有匹配项目的文件会放入 inbox/，以供人工审核。

基准测试

使用内置 IR 指标和回归检测来衡量并跟踪搜索质量。

隔离语料库模式（--corpus）使用自包含的测试数据集（19 篇合成文档、25 个查询）执行快速、可复现的 CI 基准测试，无需真实文档，60 秒内即可完成。

# Run against the built-in eval corpus (recommended for CI)
alcove bench --corpus --baseline benches/corpus/baseline.json

# Update the corpus baseline after intentional changes
alcove bench --corpus --save-baseline benches/corpus/baseline.json

# Run against your real docs (50 queries across 10 categories)
alcove bench --metrics precision

# Save as baseline for future comparison
alcove bench --output json --save-baseline benches/baseline.json

# Compare against baseline — detect regressions in CI
alcove bench --baseline benches/baseline.json

# Markdown report
alcove bench --output markdown --output-file bench-report.md

指标	衡量内容
Precision@K	前 K 条结果中相关结果所占比例
Recall@K	前 K 条结果中找到的相关文档所占比例
NDCG@K	按位置折损计算的排序质量
MAP@K	跨查询的平均准确率均值
MRR	首个相关结果的倒数排名
分块准确率	检索到的分块是否位于正确的章节中

回归阈值：准确率 >5%、延迟 >20%、吞吐量 >15%。达到半数阈值时会发出警告。

后台服务

运行持久后台服务，可消除每次新 Agent 会话的冷启动延迟。alcove setup 默认会启用此功能（macOS 登录项）。

alcove mcp enable --now     # Enable and start (persists across reboots)
alcove mcp stop / start / restart / status
alcove mcp disable          # Disable and remove login item

后台服务运行时，stdio 进程会作为轻量代理，将请求转发给已预热的服务，而不是在每次会话中加载搜索引擎。启动时，stdio 进程会检查 GET /health，并自动进入代理模式。

注意：偏好基于 stdio 访问的用户仍可使用 MCP。手动配置 MCP，请参见 registry/mcp.json。

搜索

Alcove 会自动选择最佳搜索策略。搜索索引存在时，它会使用 BM25 排序搜索（由 tantivy 提供支持），返回按相关性评分的结果；索引不存在时，则会回退到 grep。你无需操心。

混合搜索（RAG）

Alcove 支持混合搜索，将 BM25 与向量相似度搜索（由 fastembed 提供支持）相结合。

运行 alcove setup 时，你可以选择嵌入模型并立即下载。你也可以手动管理模型：

# Set and download an embedding model
alcove model set ArcticEmbedXS
alcove model download

# Check model status
alcove model status

选择模型

模型	磁盘占用	维度	上下文长度	语言	最适合	峰值 RAM
ArcticEmbedXS（默认）	90 MB	384	512	多语言	默认首选——兼顾大小与质量	~400 MB
ArcticEmbedXSQ	90 MB	384	512	多语言	量化版本，下载体积更小	~400 MB
MultilingualE5Small	470 MB	384	512	100+ 种语言	韩语和中日韩文字支持最佳	~1.2 GB
BGEM3	600 MB	1024	8192	100+ 种语言	高级选择——Dense+Sparse+ColBERT	~2 GB
ArcticEmbedMLong	430 MB	768	8192	多语言	长文档	~1.5 GB
JinaEmbeddingsV2BaseCode	550 MB	768	8192	代码+英语	针对代码优化	~1.5 GB

默认模型为 ArcticEmbedXS（90 MB，支持多语言）。对于大多数项目，它在体积和质量之间实现了最佳平衡。

嵌入模型由 fastembed-rs（ONNX Runtime）提供，并完全在本地运行。要使用其他模型，请在 config.toml 中设置：

[embedding]
model = "BGEM3"    # any Variable name from the model docs

如需查看支持的 40 多种模型的完整列表，以及其维度、上下文长度和语言覆盖范围，请参阅 EMBEDDING_MODELS.md。

模型下载并就绪后，Alcove 会自动在 CLI 搜索和基于 Agent 的 MCP 工具中使用混合搜索。这对于多语言项目和复杂的语义查询尤其有效。

# Search the current project (auto-detected from CWD)
alcove search "authentication flow"

# Force grep mode if you want exact substring matching
alcove search "FR-023" --mode grep

API 服务启动时会自动在后台构建索引，并在检测到文件更改时重新构建。无需 cron 作业，也无需手动操作。

Agent 的使用方式： Agent 只需使用查询调用 search_project_docs。其余工作都由 Alcove 处理——排序、去重（每个文件仅返回一个结果）、跨项目搜索和回退。Agent 无需选择搜索模式。

索引生命周期

了解何时运行 alcove index 与 alcove rebuild：

命令	功能	适用场景
alcove index	增量更新——仅处理新增或已更改的文件	默认操作：添加或编辑文档后运行
alcove rebuild	完整重建——删除并重新创建所有索引数据	更换嵌入模型后，或索引损坏后

首次设置：

# Step 1: BM25 search is ready immediately after setup
alcove index            # builds full-text index (no model needed)

# Step 2: Enable Hybrid Search (optional)
alcove model set ArcticEmbedXS
alcove model download   # ~90 MB download

# Step 3: Build vector index for all existing docs
alcove rebuild          # one-time full rebuild with embeddings
                        # ⚠ peak RAM = model size + corpus vectors (see note below)

# After this: incremental updates just work
alcove index            # fast — only re-embeds changed files

切换模型：

alcove model set BGEM3                     # change model
alcove rebuild                            # required: vectors are model-specific

重建期间的内存占用： 峰值 RAM 因模型而异——请参阅上方表格中的“峰值 RAM”列。较大的模型（BGEM3、ArcticEmbedMLong）在重建期间可能会使用 1.5–2 GB。重建完成后，常态内存占用会降至约 50–200 MB，具体取决于你的 [memory] 配置。降低 max_hnsw_cache 并缩短 model_unload_secs，还可以进一步降低常态内存占用。

全局搜索

每一项架构决策、每一本运行手册、每一条项目笔记——都能一次性跨所有项目搜索。

# Search across ALL projects
alcove search "rate limiting patterns" --scope global
alcove search "OAuth token refresh" --scope global

Agent 也可以在 search_project_docs 中使用 scope: "global" 执行相同操作。一次查询，搜索每个项目。

项目检测

默认情况下，Alcove 会根据终端的工作目录（CWD）检测当前项目。你可以使用 MCP_PROJECT_NAME 环境变量覆盖此设置：

MCP_PROJECT_NAME=my-api alcove

当 CWD 与文档仓库中的项目名称不匹配时，这会很有用。

文档规范

在文档仓库中使用 policy.toml 定义团队范围的文档标准：

[policy]
enforce = "strict"    # strict | warn

[[policy.required]]
name = "PRD.md"
aliases = ["prd.md", "product-requirements.md"]

[[policy.required]]
name = "ARCHITECTURE.md"

  [[policy.required.sections]]
  heading = "## Overview"
  required = true

  [[policy.required.sections]]
  heading = "## Components"
  required = true
  min_items = 2

策略文件按以下优先级解析：项目（<project>/.alcove/policy.toml）> 团队（DOCS_ROOT/.alcove/policy.toml）> 内置默认值（来自你的 config.toml 核心文件）。这样既能确保所有项目的文档质量一致，也允许针对各个项目进行覆盖。

文档分类

Alcove 将文档分为以下等级：

分类	存放位置	示例
doc-repo-required	Alcove（私有）	PRD、架构、决策、约定
doc-repo-supplementary	Alcove（私有）	部署、入门指南、测试、运行手册
reference	Alcove 的 reports/ 文件夹	审计报告、基准测试、分析
project-repo	你的 GitHub 仓库（公开）	README、CHANGELOG、CONTRIBUTING、SECURITY、CODE_OF_CONDUCT、LICENSE、QUICKSTART

audit 工具会扫描你的 doc-repo 和本地项目目录，然后建议操作，例如从私有 PRD 生成公开 README，或将放错位置的报告移回 Alcove。

配置

配置位于 ~/.config/alcove/config.toml：

docs_root = "/Users/you/documents"

[core]
files = ["PRD.md", "ARCHITECTURE.md", "PROGRESS.md", "DECISIONS.md", "CONVENTIONS.md", "SECRETS_MAP.md", "DEBT.md"]

[team]
files = ["ENV_SETUP.md", "ONBOARDING.md", "DEPLOYMENT.md", "TESTING.md", ...]

[public]
files = ["README.md", "CHANGELOG.md", "CONTRIBUTING.md", "SECURITY.md", ...]

[diagram]
format = "mermaid"

[server]
host = "127.0.0.1"          # bind address (0.0.0.0 for all interfaces)
port = 57384                  # listen port
token = "alcove-a3f7b2..."   # auto-generated bearer token

[memory]
reader_ttl_secs   = 300   # evict idle IndexReader after N seconds (0 = never)
max_cached_readers = 1    # max concurrent IndexReader instances in RAM
model_unload_secs  = 600  # unload embedding model after N seconds of inactivity (0 = never)
max_hnsw_cache     = 3    # max HNSW graphs held in memory simultaneously

以上设置均可通过 alcove setup 交互式完成。你也可以直接编辑该文件。

内存使用说明： 初次建立索引或完整重建时，Alcove 会加载嵌入模型（约 235–500 MB），并在构建 HNSW 图的过程中将所有文档向量保存在 RAM 中——峰值用量随语料库大小而变化，且此操作无法避免。上述 [memory] 设置控制的是索引完成后的稳定状态 RAM 用量。

文件列表完全可自定义——你可以向任意类别添加文件名，也可以在类别间移动文件，以符合团队的工作流：

[core]
files = ["PRD.md", "ARCHITECTURE.md", "DECISIONS.md", "MY_SPEC.md"]  # added custom doc

[public]
files = ["README.md", "CHANGELOG.md", "PRD.md"]  # PRD exposed as public for this project

支持的 Agent

Agent	访问方式	技能
Claude Code	~/.claude.json	~/.claude/skills/alcove/
Cursor	~/.cursor/mcp.json	~/.cursor/skills/alcove/
Claude Desktop	平台配置	—
Cline（VS Code）	VS Code globalStorage	~/.cline/skills/alcove/
OpenCode	~/.config/opencode/opencode.json	~/.opencode/skills/alcove/
Codex	~/.codex/config.toml	~/.codex/skills/alcove/
Copilot CLI	~/.copilot/mcp-config.json	~/.copilot/skills/alcove/
Antigravity	agy plugin install	—
Grok Build	grok plugin install	—

/alcove                          Summarize current project docs and status
/alcove search auth flow         Search docs for a specific topic
/alcove what conventions apply?  Ask a doc question directly

支持的语言

CLI 会自动检测系统区域设置。你也可以通过 ALCOVE_LANG 环境变量覆盖该设置。

语言	代码
English	en
한국어	ko
简体中文	zh-CN
日本語	ja
Español	es
हिन्दी	hi
Português (Brasil)	pt-BR
Deutsch	de
Français	fr
Русский	ru

# Override language
ALCOVE_LANG=ko alcove setup

更新

方式	命令
Homebrew	brew upgrade alcove
curl 安装程序	重新运行上方的安装脚本
cargo binstall	cargo binstall alcove@latest
cargo install	cargo install alcove@latest --features full-macos
Claude Code Plugin	claude plugin update epicsagas/alcove

alcove --version

卸载

alcove uninstall          # remove skills & config
cargo uninstall alcove    # remove binary

知识库 Vault

除项目文档外，Alcove 还支持独立的知识库 Vault，用于存储研究笔记、参考资料和经过整理的知识，供大模型搜索。

# Create a vault for AI research notes
alcove vault create ai-research

# Link an existing Obsidian vault (no copying — indexes in place)
alcove vault link my-obsidian ~/Obsidian/research

# Add a document
alcove vault add ai-research ~/Downloads/transformer-survey.md

# Build the vault search index
alcove vault index

# List all vaults
alcove vault list
#   areas (8 docs) → (linked)
#   resources (71 docs) → (linked)
#   zettelkasten (17 docs) → (linked)

# Search from CLI
alcove search "attention mechanism" --vault ai-research

# Agents search via MCP
search_vault(query="attention mechanism", vault="ai-research")

# Search ALL vaults at once
search_vault(query="transformer", vault="*")

Vault 与项目文档完全隔离——索引、缓存和搜索均相互独立。编码 Agent 对项目文档的搜索绝不会受到 Vault 活动的影响。

功能	项目文档	Vault
用途	每个项目的文档	通用知识库
存储	~/.alcove/docs/	~/.alcove/vaults/
索引	共享的项目索引	每个 Vault 独立索引
缓存	PROJECT_READER_CACHE	VAULT_READER_CACHE
搜索	search_project_docs	search_vault
符号链接	否	是（链接外部目录）

Vault 配置

默认情况下，Vault 存储在 ~/.alcove/vaults/。你可以在 config.toml 中更改此设置：

[vaults]
root = "/path/to/your/vaults"

有关 config.toml 的更多详情，请参阅配置部分。

生态系统

obsidian-forge

Alcove 与 obsidian-forge（一个 Obsidian 知识库生成器和自动化守护进程）天然适配。为了获得最佳集成效果，Alcove 的 docs_root 应指向 obsidian-forge 项目归档目录。

1. 设置文档根目录 将主要文档指向 obsidian-forge 项目目录（直接指向或通过符号链接）：

# During alcove setup, set docs_root to:
~/Obsidian/SecondBrain/99-Archives/projects

2. 将知识领域链接为知识库 将 obsidian-forge 的其他三个类别链接为独立的 Alcove 知识库。这会在 ~/.alcove/vaults/ 中创建符号链接：

# Link obsidian-forge categories
alcove vault link areas ~/Obsidian/SecondBrain/02-Areas
alcove vault link resources ~/Obsidian/SecondBrain/03-Resources
alcove vault link zettelkasten ~/Obsidian/SecondBrain/10-Zettelkasten

现在，Agent 可以有条理地访问内容：

• search_project_docs：搜索已归档的项目知识（PRD 等）
• search_vault：搜索更广泛的知识领域和研究笔记。

你可以通过检查 ~/.alcove/vaults/ 中的符号链接，确认实际存储映射。

常见问题

为什么不直接将 ripgrep 用作 MCP 工具？

ripgrep 会返回整个文件。如果 Agent 搜索 “auth” 并命中 5 个文件，每个文件平均 200 行，那么就会向上下文注入约 10K 个 token，其中大部分都不相关。Alcove 会对文档分块、为文本块排序，并仅返回最相关的段落。它还提供 ripgrep 无法实现的语义搜索（向量嵌入）——例如，查询 “how is the deployment pipeline structured” 与 DEPLOYMENT.md 中的任何关键词都不匹配，但 Alcove 的向量搜索可以找到相关内容。

这能取代 CLAUDE.md / AGENTS.md 吗？

不能——它们的用途不同。Agent 配置文件（CLAUDE.md、AGENTS.md）定义行为规则：提交风格、语言偏好、安全限制。Alcove 管理组织知识：架构决策、进度跟踪、编码规范、代码结构。Agent 配置用于规定 Agent 应该如何行动。Alcove 用于规定 Agent 应该了解什么。

为什么使用 Rust？

单一二进制文件，无需运行时依赖。Tantivy 是一流的 BM25 实现。fastembed（ONNX Runtime）让我们无需 Python 即可在本地生成向量嵌入。只需运行一次 cargo install 或 curl——无需 Docker、Node.js 或 virtualenv。

上下文窗口越来越大怎么办？

更大的窗口无法解决相关性问题。即使是 200K-token 的窗口，如果填满不相关的文档，也会降低 Agent 的输出质量——Anthropic 自己的文档也警告说，臃肿的配置文件会导致 Agent 忽略实际指令。目标不是提供更多上下文，而是在正确的时间提供正确的上下文。

路线图

• 多用户远程访问 — 通过 LAN/VPN 共享团队文档（已实现 bearer token 身份验证和速率限制）。需要：写入 API、并发索引协调、项目生命周期管理。

参与贡献

欢迎提交错误报告、功能请求和拉取请求。请在 GitHub 上提出议题，开始讨论。

致谢

时间有效性模型（valid_until / last_verified，并在查询时排除已过期内容）参考了 @ajdelaguila 的 Data Olympus 生命周期架构（讨论见 #37）。

许可证

Apache-2.0