Alcove

AI エージェントはあなたのプロジェクトを把握していません。Alcove がそれを解決します。

→ クイックスタート

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

Alcove は、AI コーディングエージェントがプライベートなプロジェクトドキュメントに必要なときにアクセスできる HTTP API サーバーです。高精度な検索を実現する BM25 とベクトルのハイブリッド検索、エージェントがコードベースの構造を理解できる tree-sitter によるコードインデックス作成、ドキュメントの一貫性を保つ ポリシー適用を備えています。コンテキストの肥大化も、公開リポジトリへのドキュメント流出も、エージェントごとのプロジェクト設定も不要です。

デモ

Claude、Codex — 検索 · プロジェクト切り替え · グローバル検索 · 検証と生成。セットアップは一度だけ。

CLI のデモ

alcove search · プロジェクト切り替え · --scope global · alcove validate

## 課題

AI エージェントは、セッションを開始するたびにゼロから始まります。

アーキテクチャを把握していません。すでに決定した内容の制約を無視します。毎回同じことを説明させられます。

ボトルネックはコンテキストウィンドウです。すべてのトークンにコストと注意力がかかります。アーキテクチャ文書を10件コンテキストに読み込むと、実行のたびに50K以上のトークンが無駄になります。さらに、Anthropicの公式ドキュメントも、設定ファイルが肥大化するとエージェントが実際の指示を無視するようになると警告しています。

そのため、選べるのは次のような望ましくない方法ばかりです。

すべてをエージェント設定に詰め込む — 実行のたびにすべてのファイルがコンテキストに読み込まれます。文書10件＝コンテキストの肥大化＝応答の遅延、高コスト、精度の低下につながります。

毎回のチャットにコピー＆ペーストする — 一度なら使えますが、複数のセッションには対応できません。

何もしない — エージェントはすでに文書化した要件を作り上げ、すでに決定した内容の制約を無視し、毎週月曜の朝に同じアーキテクチャを説明し直すことになります。

これを5つのプロジェクトと3つのエージェントに広げて考えてみてください。切り替えるたびに、コンテキストが失われます。

Alcoveによる解決方法

Alcoveは文書を注入しません。エージェントは必要なときに、必要な情報を検索します。

~/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

エージェントはいつでも切り替えられます。プロジェクトもいつでも切り替えられます。ドキュメント層は標準化されたままです。

Alcoveを選ぶ理由

Alcoveを使うと、セッションをまたいで維持される記憶をエージェントに持たせることができます。

エージェントは文書をコンテキストに読み込みません。**必要なときに、必要な情報を検索します。**アーキテクチャ文書、設計上の決定、ランブック、制約など、すべてを一か所にまとめて検索可能にし、公開リポジトリには置かずに管理できます。

エージェント設定はエージェントの動作を定めるものです。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を使う場合
エージェント設定に文書を入れると、実行のたびにコンテキストが肥大化する	ハイブリッド検索（BM25 + RAG）により、エージェントは関連度順に、必要な情報だけを取得する
エージェントが参照できるのはテキスト文書だけで、コード構造は見えない	Tree-sitterによるコードインデックス作成により、エージェントは12の言語にわたってモジュール、関数、型を理解できる
内部文書がNotion、Google Docs、ローカルファイルに散在している	プロジェクトごとに構成された単一のドキュメントリポジトリ
AI エージェントごとに文書アクセスを個別設定する	一度設定すれば、すべてのエージェントで同じアクセスを共有できる
プロジェクトを切り替えるたびにコンテキストを説明し直す必要がある	CWDの自動検出により、プロジェクトを即座に切り替えられる
エージェントの検索結果に一致する行が無作為に表示される	関連度順の結果 — 最適な一致が先頭に表示され、ファイルごとに1件
「OAuthに関するメモをすべて検索する」ことはできない	1回のクエリで全プロジェクトを横断検索できる
機密文書がプロジェクトリポジトリに置かれている	非公開の文書はマシン上に保存され、公開リポジトリには置かれない
プロジェクトやチームメンバーごとに文書構造が異なる	policy.tomlで全プロジェクトにわたる標準を適用できる
文書がそろっているか確認する方法がない	validateで不足ファイル、空のテンプレート、不足セクションを検出できる
リンク切れやWIPマーカーのある古い文書が見過ごされる	lintでリンク切れ、孤立ファイル、古いマーカーを自動検出できる
Obsidianなどのツールのメモが分散したままになる	promoteで、あらゆるメモを1つのコマンドでドキュメントリポジトリに取り込める

クイックスタート

必須：インストール後に一度 alcove setup を実行し、文書のルートを設定してすべての機能を有効にしてください。プラグインはAPIサーバーを自動で起動しますが、setup を実行するまではAlcoveで文書を検索・インデックス化できません。

Obsidianをお使いですか？ 文書構造とVaultの設定については、エコシステムセクションをご覧ください。

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 エージェント（スキルファイル — 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 を実行してください。

トラブルシューティング

エージェントが Alcove ツールを見つけられない alcove setup をもう一度実行してください。設定済みのすべてのエージェントについて、API サーバーが再設定されます。その後、新しいエージェントセッションを開始してください（変更は次のセッション開始時に反映されます）。

検索結果が返されない まだインデックスが作成されていない可能性があります。alcove index を実行してインデックスを作成し、もう一度お試しください。

バックグラウンドサーバーから 403 Unauthorized が返される シェルで ALCOVE_TOKEN が設定されていません。alcove token を実行してトークンを表示し、シェルのプロファイルに export ALCOVE_TOKEN="..." を追加してから、再読み込みしてください。

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

コーディングエージェント（HTTP API）

AI コーディングエージェントは、ローカル 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)

エージェントは、verify または rag status 引数を使って接続を確認できます。これらはデーモンを確認し、URL を解決して、/health を自動的に呼び出します。通常、これらを自分で呼び出す必要はありません。プロジェクトについて質問すると、エージェントが呼び出します。

エンドポイント	メソッド	説明
/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	ドキュメントを lint します — リンク切れ、孤立ファイル、古い状態を示すマーカー（クエリ：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 ベースのアクセスを希望する場合は、手動で MCP をセットアップする方法について 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}'

エージェントとのやり取りの例：

ユーザー：「/alcove 新しい API エンドポイントを追加するにはどうすればよいですか？」 エージェント：（query="add api endpoint" を指定して POST /v1/search を呼び出します） エージェント：（GET /docs/{path}?project=... で最も関連性の高いドキュメントを読み取ります） エージェント：「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 はそこでドキュメントを管理し、ポート 58301 上の HTTP 経由で任意の AI エージェントに提供します。

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	ドキュメントを lint します
/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

リントでは、次の 4 項目をチェックします：

チェック項目	検出する内容
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%。しきい値の半分で警告が表示されます。

バックグラウンドサーバー

常駐型のバックグラウンドサーバーを実行すると、新しいエージェントセッションごとのコールドスタートによるレイテンシをなくせます。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以上の言語	韓国語／CJK のサポートに最適	約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 検索とエージェントベースの 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 ジョブも手動作業も必要ありません。

エージェントでの動作： エージェントはクエリを指定して search_project_docs を呼び出すだけです。ランキング、重複排除（ファイルごとに1件の結果）、プロジェクト横断検索、フォールバックはすべて Alcove が処理します。エージェントが検索モードを選ぶ必要はありません。

インデックスのライフサイクル

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を使用する場合があります。再構築が完了すると、通常時の使用量は [memory] の設定に応じて約50～200 MBに減少します。max_hnsw_cache を小さくし、model_unload_secs を短くすると、通常時の使用量をさらに減らせます。

グローバル検索

すべてのアーキテクチャ決定、すべてのランブック、すべてのプロジェクトメモを、一度にすべてのプロジェクトから検索できます。

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

エージェントも search_project_docs で scope: "global" を指定すれば、同じ検索ができます。1つのクエリで、すべてのプロジェクトを検索します。

プロジェクトの検出

デフォルトでは、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

対応エージェント

エージェント	アクセス	スキル
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 環境変数で上書きすることもできます。

言語	コード
英語	en
韓国語	ko
簡体字中国語	zh-CN
日本語	ja
スペイン語	es
ヒンディー語	hi
ポルトガル語（ブラジル）	pt-BR
ドイツ語	de
フランス語	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 プラグイン	claude plugin update epicsagas/alcove

alcove --version

アンインストール

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

ナレッジベースのボルト

プロジェクトのドキュメントに加え、Alcove は調査メモ、参考資料、LLM が検索できるように整理されたナレッジを保存するための、独立したナレッジベースのボルトに対応しています。

# 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="*")

ボルトはプロジェクトのドキュメントから完全に分離されています。インデックス、キャッシュ、検索はそれぞれ独立しています。コーディングエージェントによるプロジェクトドキュメントの検索が、ボルトの利用によって影響を受けることはありません。

機能	プロジェクトドキュメント	ボルト
用途	プロジェクトごとのドキュメント	汎用ナレッジベース
保存場所	~/.alcove/docs/	~/.alcove/vaults/
インデックス	共有プロジェクトインデックス	ボルトごとに独立したインデックス
キャッシュ	PROJECT_READER_CACHE	VAULT_READER_CACHE
検索	search_project_docs	search_vault
シンボリックリンク	なし	あり（外部ディレクトリへのリンク）

ボルトの設定

デフォルトでは、ボルトは ~/.alcove/vaults/ に保存されます。config.toml で変更できます。

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

config.toml の詳細については、設定セクションを参照してください。

エコシステム

obsidian-forge

Alcove は Obsidian の Vault 生成ツール兼自動化デーモンである obsidian-forge と自然に連携します。最適な連携を実現するには、alcove の docs_root を obsidian-forge のプロジェクトアーカイブに指定してください。

1. ドキュメントルートを設定する メインのドキュメントを obsidian-forge のプロジェクトディレクトリに直接、またはシンボリックリンク経由で指定します。

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

2. ナレッジエリアを Vault としてリンクする obsidian-forge の残り 3 つのカテゴリを、それぞれ独立した alcove Vault としてリンクします。これにより、~/.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

これで、エージェントは構造化されたアクセスが可能になります。

• search_project_docs：アーカイブされたプロジェクトのナレッジ（PRD など）を検索します。
• search_vault：より広範なナレッジエリアや調査メモを検索します。

~/.alcove/vaults/ のシンボリックリンクを確認すると、実際のストレージの対応関係を検証できます。

よくある質問

MCP ツールとして ripgrep を使うだけではだめですか？

ripgrep はファイル全体を返します。エージェントが「auth」を検索して平均 200 行のファイルを 5 つ見つけた場合、約 10K トークンがコンテキストに追加され、その大半は無関係な内容です。Alcove はドキュメントをチャンクに分割し、チャンクをランク付けして、最も関連性の高い箇所だけを返します。また、ripgrep ではできないセマンティック検索（ベクトル埋め込み）も提供します。「デプロイメントパイプラインはどのような構造か」というクエリは、DEPLOYMENT.md 内のどのキーワードにも一致しませんが、Alcove のベクトル検索なら見つけられます。

CLAUDE.md / AGENTS.md を置き換えるものですか？

いいえ。それぞれ役割が異なります。エージェント設定ファイル（CLAUDE.md、AGENTS.md）は、コミットのスタイル、言語の設定、安全上の制約などの行動ルールを定義します。Alcove は、アーキテクチャ上の決定事項、進捗状況、コーディング規約、コード構造などの組織のナレッジを管理します。エージェント設定は「エージェントがどのように行動すべきか」を定め、Alcove は「エージェントが何を知っておくべきか」を扱います。

なぜ Rust なのですか？

単一バイナリで、ランタイム依存関係がありません。Tantivy は BM25 の分野で最高クラスです。fastembed（ONNX Runtime）により、Python を使わずにローカルでベクトル埋め込みを利用できます。cargo install を実行するか curl を使うだけで、Docker、Node.js、virtualenv は不要です。

コンテキストウィンドウがさらに大きくなったらどうなりますか？

ウィンドウが大きくなっても、関連性の問題は解決しません。無関係なドキュメントで埋め尽くされた 200K トークンのウィンドウでも、エージェントの出力品質は低下します。Anthropic 自身のドキュメントでも、肥大化した設定ファイルによってエージェントが実際の指示を無視するようになると警告しています。目標はコンテキストを増やすことではなく、適切なタイミングで適切なコンテキストを提供することです。

ロードマップ

• 複数ユーザーによるリモートアクセス — LAN/VPN 経由でチームのドキュメントを共有します（ベアラートークン認証、レート制限はすでに実装済み）。必要なもの：書き込み API、並行インデックス処理の調整、プロジェクトのライフサイクル管理。

貢献

バグ報告、機能リクエスト、プルリクエストを歓迎します。議論を始めるには、GitHub で issue を作成してください。

謝辞

時間的有効性モデル（valid_until / last_verified による、クエリ実行時の期限切れデータの除外）は、@ajdelaguila による Data Olympus のライフサイクルスキーマを参考にしました（#37 での議論）。

ライセンス

Apache-2.0