contextweaver

ContextWeaver

🧵 AI エージェントのために織り上げられたコードベースコンテキストエンジン

AI エージェント向けセマンティックコード検索 — ハイブリッド検索 • グラフ展開 • トークンを考慮したパッキング

日本語 · 簡体字中国語

---

ContextWeaver は、AI コーディングアシスタント向けに特化して構築されたセマンティック検索エンジンです。ハイブリッド検索（ベクトル＋字句検索）、インテリジェントなコンテキスト展開、トークンを考慮したパッキングを組み合わせ、正確で関連性が高く、コンテキストが完全なコードスニペットを LLM に提供します。

✨ 主な機能

🔍 ハイブリッド検索エンジン

• ベクトル検索：類似度を通じた深い意味理解
• 字句検索（FTS）：関数名、クラス名、その他の技術用語を完全一致で検索
• RRF 融合（Reciprocal Rank Fusion）：複数の再現チャネルをインテリジェントに統合

🧠 AST セマンティック分割

• Tree-sitter 解析：TypeScript、JavaScript、Python、Go、Java、Rust、C、C++、C# などに対応
• デュアルテキスト戦略：表示用の displayCode と埋め込み用の vectorText
• ギャップを考慮した結合：意味的整合性を保ちながら、コードのギャップをインテリジェントに処理
• パンくずリストの挿入：ベクトルテキストに階層パスを含め、再現率を向上
• UTF-16 文字領域の正規化：メタデータの書き込み前に SourceAdapter.toCharOffset でオフセットを統一し、マルチバイト文字の切り出しエラーを防止（v1.4.0+）

📊 3 段階のコンテキスト展開

• E1 隣接展開：同一ファイル内の隣接チャンクを展開し、ブロックの完全性を保持
• E2 パンくずリストの補完：同じクラス／関数配下の兄弟メソッドを取得し、構造の理解を支援
• E3 インポート解決：ファイルをまたぐ依存関係を追跡（切り替え可能）

🎯 スマート TopK カットオフ

• アンカーと下限値：動的しきい値と絶対下限値による二重の保護
• デルタガード：Top1 が外れ値となるケースでの誤判定を防止
• セーフハーバー：最初の N 件の結果では下限値のみを確認し、基本的な再現率を保証

🔌 MCP ネイティブ対応

• MCP サーバーモード：1 つのコマンドで Model Context Protocol サーバーを起動
• 複数のツール粒度（v1.5.0+）：中核となるセマンティック検索に加え、構造の参照、シンボルの参照、シンボル定義、統計情報の専用ツールを追加
• 意図と用語の分離：LLM に適した API 設計
• 自動インデックス作成：最初のクエリで自動的にインデックスを作成し、増分更新を透過的に実行

⚡ クエリーキャッシュとファイル監視（v1.5.0+）

• クエリーキャッシュ（QueryCache）：プロジェクトごとのプロセス内 LRU キャッシュ（デフォルトは50エントリー）です。キャッシュにヒットすると、ベクトル検索／再ランキング／拡張のパイプライン全体をスキップします。
• キャッシュの自動無効化：キャッシュキーは normalized query + projectId + index version + search-config fingerprint で構成されるため、インデックスの更新後や設定の変更後に自動的に無効化されます。古い結果が返されることはありません。
• 監視モード：contextweaver watch はファイルシステムを監視し、インクリメンタルインデックス作成を自動的に開始します。デバウンス（デフォルトは500ms）とスキャンの重複排除（同時スキャンなし）にも対応しています。

📈 統計と可観測性（v1.5.0+）

• 3つのメトリクスグループ：インデックス作成プロセス、検索の品質／動作、健全性／整合性
• 2つのアクセス方法：contextweaver stats CLI（--json 対応）と MCP の stats ツール
• 整合性診断：異常なマイグレーション状態、pending_marks の滞留、ベクトル行の欠落などを自動検出し、修正方法を提案します。

🛡️ クラッシュに強いデータアーキテクチャ（v1.4.0+）

• コンテンツの唯一の情報源：LanceDB にはベクトルと位置特定用メタデータのみを保存し、コンテンツは files.content から読み戻します。これにより、インデックスサイズを30～50%削減します。
• ストア間のトランザクション補償：LanceDB → FTS+outbox → SQLite mark の3段階で書き込み、失敗時には自動的にロールバックまたは再実行します。
• マイグレーション状態マシン：pending/done/aborted を永続化し、クラッシュからの復旧時に自動的に再構築します。
• プロセス間の相互排他：アドバイザリロックにより、MCP サーバーと CLI が同時に LanceDB のマイグレーションを開始するのを防ぎます。
• chunk_id の重複排除：書き込み前に削除することで、再試行時の行の重複を防ぎます。

📦 クイックスタート

要件

• Node.js >= 20
• pnpm（推奨）または npm

インストール

# Global install
npm install -g @chiway/contextweaver

# Or with pnpm
pnpm add -g @chiway/contextweaver

設定の初期化

# Create the config file (~/.contextweaver/.env)
contextweaver init
# Or the short alias
cw init

~/.contextweaver/.env を編集し、API キーを入力します。

# Embedding API config (required)
EMBEDDINGS_API_KEY=your-api-key-here
EMBEDDINGS_BASE_URL=https://api.siliconflow.cn/v1/embeddings
EMBEDDINGS_MODEL=BAAI/bge-m3
EMBEDDINGS_MAX_CONCURRENCY=10
EMBEDDINGS_DIMENSIONS=1024

# Reranker config (required)
RERANK_API_KEY=your-api-key-here
RERANK_BASE_URL=https://api.siliconflow.cn/v1/rerank
RERANK_MODEL=BAAI/bge-reranker-v2-m3
RERANK_TOP_N=20

# Search parameters (optional, override built-in defaults)
CW_SEARCH_WVEC=0.6
CW_SEARCH_WLEX=0.4
CW_SEARCH_RERANK_TOP_N=10
CW_SEARCH_MAX_TOTAL_CHARS=48000
CW_SEARCH_VECTOR_TOP_K=80
CW_SEARCH_SMART_MAX_K=8
CW_SEARCH_IMPORT_FILES_PER_SEED=3

# Ignore patterns (optional, comma-separated)
# IGNORE_PATTERNS=.venv,node_modules

コードベースのインデックス作成

# Run from the codebase root
contextweaver index

# Specify a path
contextweaver index /path/to/your/project

# Force a full re-index
contextweaver index --force

監視モード（v1.5.0+）

# Watch for file changes and auto-index incrementally (Ctrl+C to stop)
contextweaver watch

# Specify a path and debounce window (ms)
contextweaver watch /path/to/project --debounce 800

watch は起動時にインクリメンタルスキャンを1回実行してから、ファイルシステムのイベントを監視します。変更があると、デバウンス期間内に重複排除されたスキャンが開始され、無視ルールで除外されたパスによってスキャンが開始されることはありません。

ローカル検索

# Semantic search
cw search --information-request "How is the user authentication flow implemented?"

# With exact terms
cw search --information-request "Database connection logic" --technical-terms "DatabasePool,Connection"

構造の参照とシンボル検索（v1.5.0+）

以下のコマンドは MCP ツールに対応する CLI で、Embedding API のコストはかかりません。

# List indexed files (supports glob / language / count filters)
contextweaver list-files --glob "src/**/*.ts" --language typescript --max-results 100

# Look up a symbol definition
contextweaver definition SearchService --hint-path src/search

# Look up symbol references
contextweaver references handleStats --exclude-definition

統計（v1.5.0+）

# Human-readable stats report
contextweaver stats

# JSON output (for scripting)
contextweaver stats --json

# Specify a project path
contextweaver stats --path /path/to/project

MCP サーバーの起動

# Launch the MCP server (for use by Claude and other AI assistants)
contextweaver mcp

インデックス管理（v1.4.0+）

# Show LanceDB migration state
contextweaver migrate

# Clear the aborted state: wipe LanceDB and trigger a full rebuild
# Triggered when: the Indexer refuses to write after sampling validation fails;
# run this, then index again.
contextweaver migrate --reset

# Specify a project path
contextweaver migrate --path /path/to/project

🔧 MCP 連携

Claude Desktop の設定

以下を Claude Desktop の設定ファイルに追加します。

{
  "mcpServers": {
    "contextweaver": {
      "command": "contextweaver",
      "args": ["mcp"]
    }
  }
}

MCP ツールの概要（v1.5.0+）

ContextWeaver は、「まずセマンティック検索、次に構造の参照」という階層型設計に基づいて、5つの MCP ツールを提供します。

ツール	用途	Embedding コスト
codebase-retrieval	主要ツール：セマンティック検索と完全一致検索のハイブリッド検索	はい
list-files	インデックス化されたファイル構造（パス／言語／サイズ）の一覧表示	いいえ
find-references	シンボルへのテキスト参照をヒューリスティックに検索	いいえ
get-symbol-definition	シンボルの定義と思われるブロックを検索	いいえ
stats	インデックス／検索／健全性の統計	いいえ

codebase-retrieval のパラメーター

Parameter	Type	Required	Description
repo_path	string	✅	リポジトリルートの絶対パス
information_request	string	✅	自然言語で記述した意味的な意図
technical_terms	string[]	❌	正確な技術用語（クラス名／関数名など）
mode	string	❌	検索プロファイル：quick、balanced、deep
include_globs	string[]	❌	検索後に適用する、許可するファイルの glob パターン
exclude_globs	string[]	❌	検索後に適用する、除外するファイルの glob パターン
language	string[]	❌	検索後に適用する、許可する言語
max_total_chars	number	❌	1 回の呼び出しで出力できる最大文字数
max_files	number	❌	パッキング後に返すファイルの最大数
max_segments_per_file	number	❌	ファイルごとに返す、連続していないセグメントの最大数
return_debug	boolean	❌	構造化出力にデバッグメタデータを含めるかどうか
low_confidence_behavior	string	❌	信頼度が低い場合の処理：return_top1、return_empty、return_with_warning
output_format	string	❌	応答形式：markdown、json、both

list-files のパラメーター

Parameter	Type	Required	Description
repo_path	string	✅	リポジトリルートの絶対パス
glob	string	❌	パスを絞り込む glob パターン
language	string	❌	言語フィルター（files.language と照合）
max_results	number	❌	返すファイルの最大数（デフォルトは 200）

find-references のパラメーター

Parameter	Type	Required	Description
repo_path	string	✅	リポジトリルートの絶対パス
symbol	string	✅	正確なシンボル名
exclude_definition	boolean	❌	パンくずの末尾がシンボル名と一致するチャンクを除外するかどうか
max_results	number	❌	返す参照の最大数（デフォルトは 50）

get-symbol-definition のパラメーター

Parameter	Type	Required	Description
repo_path	string	✅	リポジトリルートの絶対パス
symbol	string	✅	解決する正確なシンボル名
hint_path	string	❌	同名の定義を区別するための優先パス
max_results	number	❌	返す定義の最大数（デフォルトは 3）

注：find-references と get-symbol-definition は、インデックス化されたチャンクを対象とするヒューリスティックなテキスト検索であり、コンパイラー精度のナビゲーションではありません。テキスト全体を網羅的に検索するには、MCP の外部で grep を使用してください。

設計思想

• 意図と用語の分離：information_request は「何をするか」を記述し、technical_terms は「何と呼ばれているか」で絞り込みます。
• 同一ファイル内のコンテキストを優先：同一ファイル内のコンテキストはデフォルトで提供され、ファイルをまたいだ調査はエージェントが開始します。
• エージェントの判断に委ねる：ツールは場所を特定するだけです。ファイルをまたいだ調査は、エージェントが必要に応じて行います。

🏗️ アーキテクチャ

flowchart TB
    subgraph Interface["CLI / MCP Interface"]
        CLI[contextweaver CLI]
        MCP[MCP Server]
    end

    subgraph Search["SearchService"]
        QC[QueryCache<br/>LRU]
        VR[Vector Retrieval]
        LR[Lexical Retrieval]
        RRF[RRF Fusion + Rerank]
        QC -.cache hit.-> CP
        VR --> RRF
        LR --> RRF
    end

    subgraph Expand["Context Expansion"]
        GE[GraphExpander]
        CP[ContextPacker]
        GE --> CP
    end

    subgraph Storage["Storage Layer"]
        VS[(VectorStore<br/>LanceDB)]
        DB[(SQLite<br/>FTS5)]
    end

    subgraph Index["Indexing Pipeline"]
        CR[Crawler<br/>fdir] --> SS[SemanticSplitter<br/>Tree-sitter] --> IX[Indexer<br/>Batch Embedding]
    end

    Interface --> Search
    RRF --> GE
    Search <--> Storage
    Expand <--> Storage
    Index --> Storage

Core Modules

モジュール	役割
SearchService	ハイブリッド検索の中核：ベクトル／語彙検索による再現、RRF による統合、再ランク付けを調整します。QueryCache と連携します
QueryCache	プロジェクト単位のプロセス内 LRU キャッシュ（v1.5.0+）。キャッシュがヒットすると、検索パイプライン全体をスキップします
GraphExpander	コンテキスト拡張機能：E1／E2／E3 の 3 段階拡張戦略を実行します
ContextPacker	コンテキストパッカー：セグメントのマージとトークン予算の制御を行います
ChunkContentLoader	(path, start_index, end_index) に基づいて files.content をスライスします（v1.4.0+）
VectorStore	LanceDB アダプター。純粋なベクトル操作のみを提供します
Database (SQLite)	メタデータストレージ＋FTS5 全文インデックス＋統計カウンター。schema_version=3
Bootstrap	ストア間の初期化コーディネーター：pending_marks の再実行＋LanceDB スキーマの移行（v1.4.0+）
SemanticSplitter	AST セマンティックチャンカー（Tree-sitter）。書き込み時にオフセットを UTF-16 文字ドメインに正規化します
Watcher	ファイル監視コーディネーター（v1.5.0+）：デバウンス＋スキャンの重複排除＋除外フィルタリング
Stats	統計集計レイヤー（v1.5.0+）：インデックス／検索／ヘルスメトリクスを統合します

Data Architecture (v1.4.0+)

~/.contextweaver/<projectId>/
├── index.db                 # SQLite
│   ├── files                # File metadata + full content (content column, the only source for text slicing)
│   ├── files_fts            # External-content table, inverted index pointing to files
│   ├── chunks_fts           # Chunk-level inverted index, per-file wholesale replacement
│   ├── metadata             # schema_version / lancedb_migration_state / lock
│   ├── stats                # Cumulative index/search counters (v1.5.0+)
│   └── pending_marks        # Outbox: replayed when a vector_index_hash mark failed
└── vectors.lance/           # LanceDB chunks table (vectors + locating metadata only, no content)

主な不変条件：

• コンテンツの唯一の信頼できる情報源は files.content です。ChunkContentLoader は start_index/end_index を使ってスライスします（displayCode と同じ情報源です）
• LanceDB のすべてのオフセットフィールドは UTF-16 文字ドメインに属します。マルチバイトファイルが誤ってスライスされることはありません
• ストア間の書き込み順序：LanceDB →（FTS + outbox の単一トランザクション）→ SQLite マーク付け＋outbox のクリア
• LanceDB の移行状態 pending/done/aborted は永続化され、アドバイザリロックによるプロセス間の相互排他が行われます
• クエリーキャッシュキーはインデックスのバージョンと検索設定のフィンガープリントに紐付けられ、インデックスまたは設定が変更されると無効になります

📁 Project Structure

contextweaver/
├── src/
│   ├── index.ts              # CLI entry (init / index / watch / search / mcp / migrate / stats)
│   ├── config.ts             # Config management (environment variables)
│   ├── defaultEnv.ts         # Default .env template
│   ├── cli/
│   │   └── mirrorCommands.ts # CLI mirrors of MCP tools (list-files / definition / references)
│   ├── api/                  # External API wrappers
│   │   ├── embedding.ts      # Embedding API
│   │   └── reranker.ts       # Reranker API
│   ├── chunking/             # Semantic chunking
│   │   ├── SemanticSplitter.ts   # AST semantic chunker
│   │   ├── SourceAdapter.ts      # Source adapter (UTF-16/UTF-8 domain normalization)
│   │   ├── LanguageSpec.ts       # Language spec definitions
│   │   ├── ParserPool.ts         # Tree-sitter parser pool
│   │   └── types.ts              # Chunking type definitions
│   ├── scanner/              # File scanning
│   │   ├── index.ts          # Scan orchestration
│   │   ├── crawler.ts        # Filesystem traversal
│   │   ├── processor.ts      # File processing
│   │   ├── watcher.ts        # File-watch coordinator (v1.5.0+)
│   │   ├── filter.ts         # Filter rules
│   │   ├── hash.ts           # File hash
│   │   └── language.ts       # Language detection
│   ├── indexer/              # Indexer
│   │   └── index.ts          # Three-stage transaction (LanceDB → FTS+outbox → SQLite mark)
│   ├── vectorStore/          # Vector storage
│   │   └── index.ts          # LanceDB adapter (pure vector operations)
│   ├── db/                   # Database
│   │   ├── index.ts          # SQLite + FTS5 + pending_marks + migration state machine + stats counters
│   │   └── bootstrap.ts      # Cross-store init coordinator (v1.4.0+)
│   ├── search/               # Search service
│   │   ├── SearchService.ts      # Core search service (cache-integrated)
│   │   ├── QueryCache.ts         # Per-project LRU query cache (v1.5.0+)
│   │   ├── GraphExpander.ts      # Context expander
│   │   ├── ContextPacker.ts      # Context packer
│   │   ├── ChunkContentLoader.ts # Slices by (path, start_index, end_index) (v1.4.0+)
│   │   ├── fts.ts                # Full-text search (per-file wholesale replacement)
│   │   ├── config.ts             # Search default config + value bounds
│   │   ├── loadConfig.ts         # Env-var overrides + config fingerprint (v1.5.0+)
│   │   ├── types.ts              # Type definitions
│   │   ├── utils.ts              # Token-overlap scoring
│   │   └── resolvers/            # Multi-language import resolvers
│   │       ├── JsTsResolver.ts
│   │       ├── PythonResolver.ts
│   │       ├── GoResolver.ts
│   │       ├── JavaResolver.ts
│   │       ├── RustResolver.ts
│   │       ├── CppResolver.ts
│   │       └── CSharpResolver.ts
│   ├── stats/                # Statistics aggregation layer (v1.5.0+)
│   │   └── index.ts          # Aggregates and renders index/search/health metrics
│   ├── mcp/                  # MCP server
│   │   ├── server.ts         # MCP server implementation (registers 5 tools)
│   │   ├── main.ts           # MCP entry
│   │   └── tools/
│   │       ├── index.ts                 # Tool registry
│   │       ├── shared.ts                # Shared tool logic
│   │       ├── codebaseRetrieval.ts     # Code retrieval tool
│   │       ├── listFiles.ts             # File structure browsing (v1.5.0+)
│   │       ├── findReferences.ts        # Symbol reference lookup (v1.5.0+)
│   │       ├── getSymbolDefinition.ts   # Symbol definition lookup (v1.5.0+)
│   │       └── stats.ts                 # Statistics tool (v1.5.0+)
│   └── utils/                # Utilities
│       ├── logger.ts         # Logging system
│       ├── encoding.ts       # Encoding detection
│       └── lock.ts           # File lock
├── tests/                    # Unit + integration tests (28 test files, 156 test cases)
│   ├── chunking/             # SourceAdapter / chunking
│   ├── cli/                  # mirrorCommands
│   ├── db/                   # migration, outbox, advisory lock, index-version
│   ├── indexer/              # transaction compensation, GC, aborted guard
│   ├── integration/          # real LanceDB end-to-end
│   ├── mcp/                  # list-files / find-references / get-symbol-definition / shared / tool registry
│   ├── scanner/              # watcher / index-version
│   ├── search/               # FTS, ChunkContentLoader, Packer, cache, loadConfig
│   ├── stats/                # statistics aggregation
│   └── vectorStore/          # chunk_id de-duplication, sampling validation
├── package.json
└── tsconfig.json

⚙️ Configuration Reference

Environment Variables

変数	必須	デフォルト	説明
EMBEDDINGS_API_KEY	✅	-	埋め込み API キー
EMBEDDINGS_BASE_URL	✅	-	埋め込み API の URL
EMBEDDINGS_MODEL	✅	-	埋め込みモデル名
EMBEDDINGS_MAX_CONCURRENCY	❌	10	埋め込み処理の並行数
EMBEDDINGS_DIMENSIONS	❌	1024	ベクトルの次元数
RERANK_API_KEY	✅	-	再ランカー API キー
RERANK_BASE_URL	✅	-	再ランカー API の URL
RERANK_MODEL	✅	-	再ランカーモデル名
RERANK_TOP_N	❌	20	再ランク付け後の返却件数
IGNORE_PATTERNS	❌	-	追加の除外パターン

Search Parameter Env Overrides (v1.5.0+)

以下の環境変数は組み込みのデフォルト値を上書きします。範囲外の値は、有効な範囲に自動的に収まるよう調整されます。wVec／wLex の一方のみが設定されている場合、もう一方は自動的に 1 - x に設定されます。

変数	デフォルト	範囲	説明
CW_SEARCH_WVEC	0.6	0–1	ベクトルの重み（統合段階）
CW_SEARCH_WLEX	0.4	0–1	語彙の重み（wVec を補完）
CW_SEARCH_RERANK_TOP_N	10	5–20	再ランク付け後に保持する結果数
CW_SEARCH_MAX_TOTAL_CHARS	48000	20000–80000	トークン予算（文字数、約 12k トークン）
CW_SEARCH_VECTOR_TOP_K	80	40–200	ベクトル検索の候補数
CW_SEARCH_SMART_MAX_K	8	5–15	Smart TopK の厳密な上限
CW_SEARCH_IMPORT_FILES_PER_SEED	3	0–5	シードごとに解決する E3 のインポートファイル数（0 にするとファイル間拡張を無効化）

Search Config Parameters (built-in defaults)

interface SearchConfig {
  // === Recall ===
  vectorTopK: number;        // Vector recall candidates (default 80)
  vectorTopM: number;        // Vectors kept after dedup (default 60)
  ftsTopKFiles: number;      // FTS recall file count (default 20)
  lexChunksPerFile: number;  // Lexical chunks per file (default 2)
  lexTotalChunks: number;    // Total lexical chunks (default 40)

  // === Fusion ===
  rrfK0: number;             // RRF smoothing constant (default 20)
  wVec: number;              // Vector weight (default 0.6)
  wLex: number;              // Lexical weight (default 0.4)
  fusedTopM: number;         // Candidates fed into rerank after fusion (default 60)

  // === Rerank ===
  rerankTopN: number;        // Results kept after rerank (default 10)
  maxRerankChars: number;    // Max chars per chunk sent to reranker (default 1000)
  maxBreadcrumbChars: number;// Max chars for breadcrumb context (default 250)
  headRatio: number;         // Head/tail ratio when truncating (default 0.67)

  // === Expansion ===
  neighborHops: number;      // E1 neighbor hops (default 2)
  breadcrumbExpandLimit: number;  // E2 breadcrumb completions (default 3)
  importFilesPerSeed: number;     // E3 import files per seed (default 3)
  chunksPerImportFile: number;    // E3 chunks per import file (default 3)

  // === ContextPacker ===
  maxSegmentsPerFile: number;     // Max non-contiguous segments per file (default 3)
  maxTotalChars: number;          // Token budget (chars, default 48000)

  // === Smart TopK ===
  enableSmartTopK: boolean;       // Enable smart cutoff (default true)
  smartTopScoreRatio: number;     // Dynamic threshold ratio (default 0.5)
  smartTopScoreDeltaAbs: number;  // Max absolute drop from Top1 (default 0.25)
  smartMinScore: number;          // Absolute floor (default 0.25)
  smartMinK: number;              // Safe Harbor count (default 2)
  smartMaxK: number;              // Hard upper bound (default 8)
}

🌍 多言語サポート

ContextWeaver は、Tree-sitter を使用した AST 解析を以下の言語でネイティブにサポートしています。

言語	AST 解析	インポート解決	拡張子
TypeScript	✅	✅	.ts、.tsx
JavaScript	✅	✅	.js、.jsx、.mjs、.cjs
Python	✅	✅	.py
Go	✅	✅	.go
Java	✅	✅	.java
Rust	✅	✅	.rs
C	✅	✅	.c、.h
C++	✅	✅	.cpp、.cc、.cxx、.hpp
C#	✅	✅	.cs

その他の言語では行ベースのチャンク分割にフォールバックし、通常どおりインデックス化や検索を行えます。

🔄 ワークフロー

インデックス作成のフロー

0. Bootstrap   → pending_marks replay + LanceDB schema migration (first launch)
1. Crawler     → traverse the filesystem, filter ignored items
2. Processor   → read file content, compute hash
3. Splitter    → AST parse, semantic chunking (offsets normalized to UTF-16 char domain)
4. Indexer     → batch embedding
5. Stages 4-6 pseudo-transaction:
   ├─ LanceDB write (pre-delete (path, hash) to avoid duplicates → add → clear old versions)
   ├─ FTS + outbox single SQLite transaction (rolls back LanceDB on failure)
   └─ SQLite mark + clear outbox single transaction (outbox kept on failure, replayed next launch)
6. Trailing GC → clean up LanceDB orphan chunks (time budget 5s)

検索のフロー

1. Query Parse     → parse the query, separate semantics from terms
2. Cache Lookup    → return immediately on hit (v1.5.0+, key includes index version + config fingerprint)
3. Hybrid Recall   → dual-channel vector + lexical recall
4. RRF Fusion      → Reciprocal Rank Fusion
5. Rerank          → cross-encoder reranking
6. Smart Cutoff    → intelligent score cutoff
7. Graph Expand    → neighbor/breadcrumb/import expansion
8. Context Pack    → segment merging, token budget
9. Cache Store     → write to cache (v1.5.0+)
10. Format Output  → format and return to the LLM

📊 パフォーマンス特性

• クエリキャッシュ：クエリが繰り返された場合、LRU キャッシュを利用し、想起／再ランキング／拡張のパイプライン全体をスキップします（v1.5.0+）
• インクリメンタルインデックス作成：変更されたファイルのみを処理するため、再インデックス作成が 10 倍以上高速です
• バッチ埋め込み：並行処理を制御しながらバッチサイズを適応的に調整します
• レート制限からの復旧：429 エラー時に自動でバックオフし、段階的に復旧します
• 接続プールの再利用：Tree-sitter パーサーをプールして再利用します
• ファイルインデックスのキャッシュ：GraphExpander 内のファイルパスインデックスを遅延読み込みします
• コストゼロのメタデータツール：list-files／find-references／get-symbol-definition は Embedding API を呼び出しません（v1.5.0+）

📈 統計と可観測性（v1.5.0+）

contextweaver stats は、次の 3 つのセクションを出力します。

• インデックス作成の処理状況：インデックス作成の累計実行回数、直近のインデックス作成時刻、前回実行のスナップショット（追加／変更／削除／変更なし／スキップ／エラー＋ベクトルインデックスの詳細）
• 検索品質／動作：クエリの累計数、キャッシュヒット率、実際の計算実行回数に加え、各段階（取得／再ランキング／拡張／パック）の平均レイテンシと、想起されたシード数の平均
• 健全性／整合性：ファイル数とコンテンツの合計サイズ、LanceDB のベクトル行数、埋め込みの次元数、インデックスのバージョン、移行状態、pending_marks、言語ごとの内訳

異常な移行状態、pending_marks の滞留、またはベクトル行の欠落が検出されると、対応する修正コマンドを含む診断警告がレポートに追加されます。--json の出力は StatsReport に対応しており、スクリプトや監視システムで利用できます。

🐛 ログとデバッグ

ログファイルの場所：~/.contextweaver/logs/app.YYYY-MM-DD.log

ログレベルを設定します。

# Enable debug logging
LOG_LEVEL=debug contextweaver search --information-request "..."

🚨 トラブルシューティング（v1.4.0+）

LanceDB の移行が停止する（aborted 状態）

症状：contextweaver index が「LanceDB is in the aborted state, refusing to write to prevent schema pollution.」というエラーを返します。

原因：v1.4.0 へのアップグレード中、サンプリングしたデータの 1% 超で、古い LanceDB インデックスの display_code が現在の files.content と異なっています（通常、チャンクオフセットに UTF-8 のバイト単位を使用していた古いインデックスで発生します）。

修正方法：

contextweaver migrate --reset   # Clear the LanceDB chunks table + reset state to done
contextweaver index             # Full rebuild (new schema)

先に contextweaver stats を実行して診断警告を確認し、現在の移行状態と pending_marks の滞留状況を確認することもできます。

プロセス間の移行競合

MCP サーバーが長時間稼働している状態で、別のターミナルから contextweaver index を実行すると、2 つのプロセス間で移行が競合します。v1.4.0 では、ゾンビ状態の判定しきい値を 10 分とするアドバイザリロックが導入されました。一方のプロセスが移行を完了する間、もう一方のプロセスは自動的に移行をスキップします。

ロックが停止した場合（kill -9 の実行後など）は、手動で解除してください。

sqlite3 ~/.contextweaver/<projectId>/index.db \
  "DELETE FROM metadata WHERE key = 'lancedb_migration_lock';"

重複した埋め込みの無駄な生成

v1.4.0 では pending_marks アウトボックスによりこの問題を解決します。FTS への書き込みは成功したものの、vector_index_hash マークの書き込みに失敗した場合、次回の起動時に自動的に再処理し、重複した埋め込みの生成を防ぎます。

検索結果に最近の変更が反映されない

インクリメンタルインデックス作成が実行されたことを確認してください（または自動で増分更新するには contextweaver watch を有効にしてください）。クエリキャッシュキーはインデックスのバージョンに紐づいているため、インデックス更新後は古いキャッシュエントリが自動的に無効になります。手動でクリアする必要はありません。

📄 ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。

🙏 Acknowledgements

• Tree-sitter - high-performance syntax parsing
• LanceDB - embedded vector database
• MCP - Model Context Protocol
• Source - Source repository

---

_{Made with ❤️ for AI-assisted coding}