open-context-engine

Open Context Engine

ローカル。セマンティック。瞬時。
あらゆるコードベースを、AI が検索できるナレッジベースに変えます。

---

Open Context Engine（OCE）は、コードベース全体をインデックス化してベクトル化し、セマンティック検索、キーワード検索、Model Context Protocol（MCP）を通じて LLM に提供する、ローカルファーストの高性能な検索エンジンです。クラウドは不要です。コードがマシンの外に出ることもありません。

コーディングアシスタントの構築、PR レビューの自動化、自分のコードについて自然言語で質問することなど、どのような用途でも、OCE は AI に確かな根拠を提供します。

📘 ドキュメント、ベンチマーク、ガイド： opencontextengine.com — Claude Code と Cursor の MCP セットアップ、エージェント型ワークフローガイド、実測済みの検索ベンチマーク。

✨ 特長

特長	説明
🧠 AST を考慮したチャンク分割	Tree-sitter を使用して、単純な行数ではなく、関数、クラス、メソッドなどの意味的な境界に沿ってコードを分割します。TypeScript、JavaScript、Python、Go、Rust、Java、C#、C、C++、Ruby、PHP、Kotlin、Swift に対応しています。
🔍 ハイブリッド検索	Reciprocal Rank Fusion により、高密度ベクトル類似度（コサイン）と BM25 キーワード検索を融合し、意味的に関連性が高く、語彙的にも正確な結果を提供します。
⚡ ローカル SQLite ＋ ベクトル	sqlite-vec を使ってすべてをローカルの SQLite データベースに保存します。外部ベクトル DB も、ネットワーク遅延も、サブスクリプション料金も不要です。
🏠 完全ローカルの埋め込み	デフォルトでは、プロセス内の ONNX 埋め込みを使用します。API キーもサーバーも不要で、モデルはディスクにキャッシュされます。Ollama にも対応しており、最高のコード検索を実現するアップグレード先として Voyage を利用できます。
🔗 シンボルの展開	検索結果の識別子を自動的に解決し、スニペット内で参照されている関数、クラス、型の定義を取り込みます。
🎯 オプションの再ランキング	Voyage または Cohere の再ランキング機能を組み込み、複雑なクエリの結果品質を高められます。
🕸️ コードグラフ	Tree-sitter の AST 解析により、インポート、呼び出し、定義のエッジをクエリ可能なグラフに抽出します。検索上位の結果はグラフに沿って展開され、呼び出し元と呼び出し先も一緒に取得されます。
🔭 Trace	ブラウザー、ターミナル、デスクトップにおけるエージェントのワークスペースです。モデルのコンテキストに含まれる内容を示すエビデンスレール（順位付け、ピン留め、除外が可能）、チェックポイントへの巻き戻し、影響範囲スコア付きの承認、監視可能なサブエージェント、確認して反映できる、分離された git worktree での並列セッションを備えています。
🤖 エージェントハーネス	コードベース検索、ファイル編集、シェル実行、ウェブ検索に対応する、ツールを使用するエージェントです。並列の読み取り専用ツール実行、ツール呼び出し前後のフック、トークン使用量の計測、セッションのエクスポート／インポート、モデルルーティング、セッション間メモリーも備えています。
🔌 MCP ネイティブ	Model Context Protocol を通じて、stdio または Streamable HTTP（ベアラー認証付きの共有エンドポイント）で検索、ファイル、シンボルのツールを公開します。Claude Desktop、Cursor、その他すべての MCP 対応クライアントで利用できます。
🧰 VS Code 拡張機能	インデックスに基づいたサイドバーチャット、ファイルごとの差分表示と元に戻す／やり直しが可能なエージェント編集、保存時のライブ再インデックス、インデックスの健全性パネルを備えています。プラットフォームごとに配布され、1.103 以降のすべての VS Code で、単一の Node-API SQLite バインディングが動作します。
🛡️ ポリシー制御	ワークスペースまたは組織ごとに、エンジンが実行できる操作を固定できます。シェル、編集、ウェブ検索の無効化、コマンド許可リストの固定、ローカルのみの埋め込みの強制、パスの除外が可能です。組織が署名したポリシーロックは、ローカルで緩和できません。
🧾 改ざん検知可能な監査ログ	すべてのエージェント実行、ツール呼び出し、MCP 呼び出しをハッシュチェーンでつないだ JSONL として記録します。oce audit --verify により、改ざん、削除、並べ替えを検出できます。
👥 チームでのインデックス同期	CI でインデックスを一度作成してアーティファクト（S3／HTTP／共有ドライブ）として公開し、チームメンバーは oce pull-index で取得します。再埋め込みされるのは各メンバーのローカル差分のみです。コンテンツハッシュによる埋め込みキャッシュにより、同一のコードに対して二重に課金されることはありません。
🚀 並列インデックス作成	大規模なリポジトリでは、ワーカースレッドによる解析／チャンク分割プールが自動的に起動します。oce bench で、ご自身の環境での処理性能を測定できます。
🛟 機能を縮退させても停止しない	お使いのプラットフォームで sqlite-vec をビルドできない場合も、エンジンはクラッシュせず、キーワードのみ（BM25）で動作します。インデックス作成と検索は引き続き利用でき、どの画面でも現在のモードを確認できます。
📏 推測ではなく、実測で評価	このリポジトリ自身と外部コードベースの、コミット済みの正解データセットに対して、両方の検索モードで検索品質を評価します。クエリの形状に応じて BM25 と意味検索の重みを調整する 適応型融合により、ここでの ハイブリッド recall@10 は 0.943、キーワードのみでは 0.886 です。以前はハイブリッド検索が下回っていた Flask では **同等の性能（0.926）**を実現しています。ランキングの変更は、変更前後の差分とともにリリースされます。コーディングエージェント自体も評価対象です。oce eval-agent で、検証スクリプトによって採点されるエンドツーエンドのタスクを実行できます。

🚀 クイックスタート

1. インストール

npm install -g @dhaxor/open-context     # Node 22+

2. モデルを選ぶ — 無料オプションもあります

oce setup

oce setup は、すでに利用できるもの（実行中の Ollama、環境内のキー）を確認し、モデルを使えるようにする方法をすべて一覧表示します。無料のものが先に表示されます。

-p	費用
ollama	無料、ローカル	お使いのマシン上で実行されます。キーも利用上限もなく、オフラインでも動作します。
google	無料枠	Gemini — 最も充実した無料枠です。キーは aistudio.google.com/apikey で取得できます
groq	無料枠	非常に高速です。キーは console.groq.com/keys で取得できます
cerebras	無料枠	キーは cloud.cerebras.ai で取得できます
openrouter	無料モデル	:free で終わるモデルは無料です。キーは openrouter.ai/keys で取得できます
openai, anthropic	有料

oce setup -p google で選択を記録すると、その後は oce trace をすぐに使えます。

すぐに使えるハイブリッド検索 — キーもアカウントも不要です。 最初のインデックス作成ではローカルの MiniLM を使って埋め込みを行うため（プロセス内、デバイス上で完結し、データが外部に送信されることはありません）、すぐにセマンティック検索とキーワード検索を利用できます。コード検索の精度を最大限に高めたい場合は、Voyage キーで埋め込みモデルをアップグレードできます — oce setup --embeddings voyage — すると、インデックスがそのモデルで再構築されます。アップグレードを希望しない場合も、ローカルモデルで十分に機能します。

3. Trace を開く

oce trace      # the workspace, in your browser
oce            # the same thing, in your terminal

どちらも起動時に現在のディレクトリをインデックス化し、1 つの会話を継続します — Trace の特徴については、以下の Trace をご覧ください。

4. またはコマンドラインから検索する

oce index                                        # full index (incremental afterwards: --incremental)
oce search "how does the auth middleware work?"

🔭 Trace

Trace はエージェントのワークスペースです。すべてのコーディングエージェントは「何をしたか」を表示します。Trace は「何を把握していたか」も表示します — OCE が管理するのはチャットのループだけでなく、検索だからです。

• エビデンスレール。 現在モデルのコンテキストウィンドウに含まれている内容を表示します。取得したすべてのチャンク、その統合スコアによる順位、チャンクを取り込んだグラフのエッジ（「search.ts から呼び出し」）、さらに検索／ファイル／履歴／システムに分かれた予算メーターが含まれます。チャンクを固定するとコンパクション後も残り、削除すると次のリクエストから実際に除外されます。
• スピナーではなく検索結果を表示 — retrieved 5 · top 0.94 · graph +2 · 251ms。
• チェックポイントの軸。 監査ログと同じハッシュチェーン上に、ターンごとのチェックポイントをタイムラインで表示します。クリックすると巻き戻しが行われ、会話とエージェントが変更したファイルがロールバックされます。ただし、その後に手動編集したファイルには影響しません。
• 影響範囲を示す承認フロー。 すべての編集とシェルコマンドは、y / a（常に許可）/ n の入力を待ちます。その際、差分、リスクスコア、そのファイルを呼び出すインデックス済みの箇所数を表示します。
• 動作を確認できるサブエージェント。 委任した調査は、何分も応答が途絶えるのではなく、独立した折りたたみ可能なブロックにストリーミング表示されます。
• 並列セッション。 git リポジトリでは、新しいセッションごとに専用のワークツリーとブランチが作成されるため、エージェント同士が同じチェックアウトを編集することはありません。セッションの差分を確認し、完了したら取り込み（コミット + --no-ff マージ）ます。セッションを閉じても、未コミットの作業が破棄されることはありません。
• コンポーザー。 @path でファイルをコンテキストに固定（インデックスを使ったあいまい検索に対応）、!command で同じ承認フローを通してシェルコマンドを実行し、それ以外は /command で操作できます。ブラウザーとターミナルで同じように使えます。

oce trace は 127.0.0.1 のみにバインドされ、起動するたびに新しいアクセストークンを生成します。便利なフラグ：--port、--no-open、--headless（API のみ）、--no-parallel。

ターミナルでの利用

oce を引数なしで実行すると、同じワークスペースがターミナルで全画面表示されます。エビデンスレール（幅が 100 列以上の場合、または Ctrl+R）、チェックポイントのガター、承認フローも同じです。Esc または Ctrl+C で実行を中断し、Ctrl+C を 2 回押すか /exit を入力すると終了します。パイプ、--print、および機能の限られたターミナルでは、従来の 1 行ずつの REPL に切り替わります。oce --classic で従来の REPL を明示的に起動することもできます。

デスクトップアプリとして

desktop/ は Trace を Electron シェルでラップし、デスクトップ通知 （承認待ちがある場合、バックグラウンドでターンが完了した場合、または 何かが失敗した場合のみ）、アプリケーションメニュー、trace:// ディープリンクを追加します。現在はソースをチェックアウトしてビルドします。詳細は desktop/README.md を参照してください。

従来の REPL

oce --classic はスタイル付きの出力をストリーミングし、各ツール呼び出しをライブスピナーと所要時間とともに表示します。また、ファイル編集やシェルコマンドの実行前には、差分／コマンドのプレビューを表示し、承認を求めます（y／always／n）。Ctrl+C を押すと、セッションを終了せずに現在の実行を中断できます。

承認モード（他の主要なコーディング CLI と同様）：

• デフォルト（suggest）— 編集とシェルコマンドのたびに、最初に確認します
• --auto-edit — ファイル編集は自動で適用されますが、シェルは引き続き確認を求めます
• --full-auto — 確認を求めません（コンテナー／CI 向け）

セッション中に /mode で切り替えられます。インタラクティブセッションでは、承認を前提として編集ツールとシェルツールを使用できます。非インタラクティブな --print モードでは、引き続き --allow-edits／--allow-shell で明示的に有効にする必要があります。

スラッシュコマンド： /help /reset /compact /plan /diff /usage /tools /mode /sessions /resume /exit。

セッションは .open-context/sessions/ に自動で保存されます。 oce --continue はワークスペース内の直近の会話を再開し、oce --resume <id> は指定した会話を復元します（/sessions で一覧を表示できます）。

ハーネスの機能：

• プランの追跡 — エージェントは複数ステップの作業向けに、進行中のステップチェックリストを管理し、作業の様子に合わせて表示します。
• サブエージェントへの委任 — 広範な調査は、スコープを限定した読み取り専用の子エージェントが実行するため、大量の中間出力でメインコンテキストがあふれることはありません。
• 要約によるコンパクション — 履歴が長くなると、古いターンは破棄されずにモデルによってコンテキストノートへ要約されるため、判断やファイルパスが保持されます。/compact で強制実行できます。
• 環境の把握 — プラットフォーム、git のブランチ／状態、日付、インデックスの統計情報がシステムプロンプトに注入されます。
• コストと並列処理 — 各ターンの最後に統計行（ステップ数、ツール呼び出し数、トークン使用量、経過時間）が表示されます。ターン内の読み取り専用ツール呼び出しは並列で実行されますが、編集またはシェル呼び出しを含むターンは常に順序どおりに実行されます。
• --route は各クエリをコストに適したモデル階層に送信します。--memory はセッションをまたいでコードベースに関する知見を記憶します。--audit は改ざん検知可能な監査ログに実行内容を記録します。

スクリプトや CI 向けの非インタラクティブな使用方法：

oce --print "where is the auth middleware defined?"           # one answer, then exit
oce --print "list the exported symbols in src/core" --json     # {answer, stats, toolCalls}

プログラム API もこれらすべてに対応しています。defaultAgentTools({ context }) は、includeEdits／shell／plan／delegate を渡さない限り読み取り専用のままです。また、ContextAgent は hooks（ここに PermissionManager を組み込めます）、compaction、environmentProvider を受け取ります。

5. MCP 経由で Claude / Cursor に接続する

oce mcp --workspace ./my-project

# Or serve a shared HTTP endpoint (e.g. one index for the whole team):
oce mcp --workspace ./my-project --http --port 8940 --auth-token "$TOKEN"

MCP サーバーは起動時にワークスペースのインデックスを作成し、その後は変更を監視するため、手動で再インデックスしなくてもインデックスが最新の状態に保たれます。監視を無効にするには --no-watch を渡してください。（MCP のハンドシェイクはインデックス作成の開始前に確立されるため、大規模なリポジトリの初回インデックス作成中もクライアントは接続できます。）

HTTP モードでは、サーバーは MCP の Streamable HTTP トランスポートを使用し、デフォルトでループバックにバインドされ、GET /health に応答します。また、--auth-token（または OCE_MCP_AUTH_TOKEN）が設定されている場合は、すべてのリクエストで Authorization: Bearer <token> が必要です。

次に、MCP 設定に追加します：

{
  "mcpServers": {
    "open-context": {
      "command": "oce",
      "args": ["mcp", "--workspace", "/path/to/project"]
    }
  }
}

6. または、VS Code 拡張機能を使用する

extension/ フォルダーには、同じエンジンを基盤とする、VS Code での完全な使用環境が含まれています。インデックスに基づくサイドバーのチャット（ストリーミング、Markdown、コードブロックのコピー／挿入／適用）、ファイルごとの差分表示／元に戻す／やり直しと、ターンごとの「すべて元に戻す」に対応したエージェントによる編集、クイック検索 （Ctrl+Shift+K）、保存時の自動インデックス作成、検索結果のデバッグに使えるインデックスの健全性パネルを備えています。各プラットフォーム用パッケージには Node-API SQLite バインディングが含まれており、VS Code 1.103 以降のすべてのバージョンとリモートホスト（SSH、WSL、Codespaces）で動作します。サポート対象の一覧は extension/PUBLISHING.md を参照するか、独自の VSIX をビルドしてください。

cd extension && npm ci --ignore-scripts
npm run package -- linux-x64   # → ../artifacts/open-context-linux-x64-<version>.vsix

📖 使用ガイド

CLI リファレンス

oce <command> [options]

Commands:
  index <workspace>      Index a codebase
  search <query>         Search the indexed codebase
  watch                  Index, then keep the index live as files change
  mcp                    Start MCP server (stdio, or --http for a shared endpoint)
  agent                  Start interactive agent (auto-indexes on startup)
  eval                   Score retrieval quality against a labeled query set
  push-index <dest>      Publish the index as a team artifact (Team)
  pull-index <src>       Install a team index, re-embed only local changes (Team)
  bench                  Benchmark parse/chunk throughput on this workspace
  policy                 Show the effective policy (user + workspace + org lock)
  audit                  Inspect / verify the tamper-evident audit log
  activate <key>         Activate a Team/Enterprise license
  license / deactivate   Show or remove the active license

Options:
  -w, --workspace <path>   Project root (default: cwd)
  -p, --provider <name>    Embedding provider: voyage | openai | ollama | local
  -m, --model <model>      Embedding model name
  --api-key <key>          API key (falls back to env vars)
  --store-path <path>      Custom store directory (default: .open-context/)
  --max-file-size <bytes>  Skip files larger than this
  --chunk-size <lines>     Lines per chunk (default: 80)
  --chunk-overlap <lines>  Overlap between chunks (default: 15)

プログラム API

import { OpenContext, ContextAgent, defaultAgentTools } from "@dhaxor/open-context";

// 1. Create and index
const ctx = await OpenContext.create({
  workspaceRoot: "./my-project",
  embedding: {
    provider: "voyage",
    model: "voyage-code-3",
    dimension: 1024,
    apiKey: process.env.VOYAGE_API_KEY,
    batchSize: 32,
  },
});

await ctx.indexWorkspace();

// 2. Search
const results = await ctx.search("authentication middleware flow");
console.log(results);

// 3. Agent with tools
const agent = new ContextAgent({
  provider: "openai",
  model: "gpt-4o",
  apiKey: process.env.OPENAI_API_KEY,
  tools: defaultAgentTools({ context: ctx, includeEdits: true }),
  // Optional harness features:
  maxParallelTools: 4,                       // read-only tool calls fan out concurrently
  hooks: {
    preToolCall: (tc) => tc.name === "remove-file"
      ? { behavior: "deny", reason: "deletions are reviewed manually" }
      : { behavior: "allow" },
    postToolCall: (_tc, result) => result.replaceAll(process.env.HOME!, "~"),
  },
});

const answer = await agent.run("How does the auth middleware work?");
console.log(answer);
console.log(agent.getLastRunStats());        // steps, tool calls, token usage, duration
const saved = agent.exportSession();          // persist; importSession(saved) restores

// 4. Cleanup
ctx.close();

MCP サーバーの統合

import { runMCPServer } from "@dhaxor/open-context";

await runMCPServer({
  workspaceRoot: "./my-project",
  embedding: { provider: "voyage", model: "voyage-code-3", dimension: 1024, batchSize: 32 },
});

公開される MCP ツール：

• codebase-retrieval — コードを自然言語で検索
• list-files — フィルターを使ってインデックス済みファイルを閲覧
• read-file — 行範囲を指定してファイルの内容を読み取り
• find-symbol-definition — 関数／クラス／型が定義されている場所を名前で完全一致検索
• find-symbol-references — 識別子がインデックス内で使用されているすべての箇所を検索
• index-status — チャンク数、ファイル数、検索モード、埋め込みモデル

🏗️ アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│                        Open Context Engine                   │
├─────────────────────────────────────────────────────────────┤
│  CLI / API / MCP / Agent                                     │
├─────────────────────────────────────────────────────────────┤
│  HybridRetriever                                             │
│  ├── Vector Search (sqlite-vec)                              │
│  ├── BM25 Search (SQLite FTS5, porter-stemmed)               │
│  ├── Reciprocal Rank Fusion + symbol/editor/recency boosts   │
│  ├── Optional Re-ranking (Voyage / Cohere)                   │
│  └── Graph Expansion (callers/callees via code graph)        │
├─────────────────────────────────────────────────────────────┤
│  AstChunker + CodeChunker                                    │
│  ├── Tree-sitter parsers (TS, JS, Py, Go, Rust, Java, C#)   │
│  └── Boundary-aware fallback chunking                        │
├─────────────────────────────────────────────────────────────┤
│  Embedding Providers                                         │
│  ├── Voyage Code-3 (recommended)                             │
│  ├── OpenAI text-embedding-3-*                               │
│  └── Ollama (local, nomic-embed-text)                        │
├─────────────────────────────────────────────────────────────┤
│  SqliteStore                                                 │
│  ├── chunks (metadata)                                       │
│  ├── chunks_vec (vector index — skipped in keyword-only)     │
│  ├── chunks_fts (full-text index)                            │
│  ├── graph_edges (import/call/definition graph)              │
│  └── files (index state)                                     │
└─────────────────────────────────────────────────────────────┘

⚙️ 設定

埋め込みモデル

プロバイダー	モデル	次元数	最適な用途
Voyage	voyage-code-3	1024	⭐ コード検索（推奨）
OpenAI	text-embedding-3-large	3072	汎用
OpenAI	text-embedding-3-small	1536	速度とコスト
Ollama	nomic-embed-text	768	Ollama サーバーを使った完全ローカル実行
Local	jina-embeddings-v2-base-code	768	完全ローカル、プロセス内で実行、コード向けに調整済み — キーもサーバーも不要
Local	all-MiniLM-L6-v2	384	完全ローカル、プロセス内で実行、最小・最速

local プロバイダーにはオプションの @huggingface/transformers パッケージが必要です。モデルは ~/.open-context/models に一度ダウンロードされ（OCE_MODEL_DIR で変更可能）、以降はオフラインで実行されます。

エージェントの LLM

openai、anthropic、google（Gemini、ストリーミングとツールに対応）、ollama（完全ローカル — oce -p ollama --llm-model qwen2.5-coder:7b は API キー不要）、および custom（--llm-base-url を介して、OpenAI 互換の任意のエンドポイントを使用できます）。LLM に -p ollama、埋め込みに --embedding-provider local、さらに reranker: { provider: "local" } を指定すると、スタック全体がオフラインで動作します — インデックス作成、検索、再ランキング、エージェントをすべてオフラインで実行できます。

設定ファイル

永続設定は ~/.open-context/config.json（ユーザー）および <workspace>/.open-context/config.json（プロジェクト — コミットしてください）に保存されます。フラグと環境変数が常に優先されます。設定ファイルでは API キーが意図的に拒否されるため、環境変数を使用してください。

{
  "embedding": { "provider": "local", "model": "jina-embeddings-v2-base-code" },
  "llm": { "provider": "ollama", "model": "qwen2.5-coder:7b" },
  "search": { "topK": 20, "minScore": 0.15 },
  "chunkSize": 80
}

検索設定

{
  search: {
    topK: 15,              // Final results returned
    candidateK: 60,        // Candidates before fusion/rerank
    maxOutputLength: 80000,// Max chars in formatted output
    minScore: 0.0,         // Score floor
    bm25Weight: 1.0,       // Keyword search weight
    vectorWeight: 1.0,     // Semantic search weight
    rerank: true,          // Enable reranking if configured
    expandSymbols: true,   // Pull in referenced definitions
  }
}

再ランキング

{
  reranker: {
    provider: "voyage",    // or "cohere"
    model: "rerank-2",     // optional
    apiKey: "your-key",
  }
}

👥 チームインデックスの同期（Team）

CI またはリード担当者のマシンで一度インデックスを作成し、チーム全員が同じモノレポの埋め込みにそれぞれ費用をかける代わりに、その結果を取得できるようにします。

# CI / lead machine: refresh the index and publish it (any file path or
# HTTP(S) PUT endpoint — S3/GCS presigned URLs work as-is)
oce push-index https://artifacts.example.com/oce/main.db.gz --token "$TOKEN"

# Each teammate: install it, then only their local diff gets embedded
oce pull-index https://artifacts.example.com/oce/main.db.gz --token "$TOKEN"
# → Installed team index: 12,481 chunks, 1,904 files, built ... at commit ab12cd34
# → Reconciled: 3 file(s) re-embedded locally, 1,901 reused from the artifact

成果物はストアそのもの（ベクトル + FTS + コードグラフ + ファイルハッシュ）を gzip 圧縮したものです。そのため、調整は通常の増分インデックス作成として行われ、成果物とハッシュが異なるファイルだけが再度埋め込みされます。OCE のクラウドサービスは関与しません。成果物は、お客様が管理するストレージに保存されます。

さらに、マシン全体で共有される埋め込みキャッシュ（~/.open-context/embed-cache.db。CLI と拡張機能ではデフォルトで有効）は、コンテンツハッシュをキーとしてベクトルを保存します。同一のコードが、リポジトリ、ブランチ、ストアの再構築をまたいで二度埋め込まれることはありません。--no-embed-cache または openContext.embedding.cache.enabled で無効にできます。

🛡️ ポリシー制御

ポリシーファイルをコミットすると、すべての OCE のインターフェース（CLI、拡張機能、ライブラリ）でそのポリシーが適用されます。--allow-shell フラグで上書きすることはできず、マージでは常に最も制限の厳しい設定が優先されます。

// <workspace>/.open-context/policy.json (or ~/.open-context/policy.json for user-wide)
{
  "agent": {
    "shell": { "enabled": false },                  // or pin: { "allowlist": ["git", "npm"] }
    "edits": { "enabled": true },
    "webSearch": { "enabled": false }
  },
  "embedding": { "localOnly": true },               // only ollama/local providers may run
  "ignore": ["secrets/**", "*.pem"],                // never indexed, on top of .contextignore
  "audit": { "required": true }                     // force audit logging on
}

oce policy を実行すると、有効なマージ結果と各ルールの適用元が表示されます。Team+ プランをご利用の組織は、開発者が設定を緩めたり削除したりして回避できない Ed25519 署名付きの policy.lock（scripts/license-tool.mjs sign-policy で発行）も配布できます。

🧾 監査ログ

oce agent --audit（または openContext.agent.audit.enabled 設定）を有効にすると、すべての実行、ツール呼び出し、MCP 呼び出しが .open-context/audit/audit.jsonl に追記されます。各レコードは直前のレコードと SHA-256 でハッシュチェーンされるため、編集、削除、並べ替えを検出できます。

oce audit                 # recent events
oce audit --type tool-call --since 2026-07-01
oce audit --verify        # ✓ chain intact — or exactly where it was tampered

監査ログは Enterprise 機能です。また、"audit": { "required": true } を設定したワークスペース／組織のポリシーでも有効になります。

🛠️ 開発

git clone https://github.com/Dhaxor/open-context-engine.git
cd open-context-engine
npm install
npm run build
npm test

プロジェクト構成

src/
├── core/
│   ├── context.ts          # Main OpenContext class
│   ├── ast-chunker.ts      # Tree-sitter chunking
│   ├── chunker.ts          # Fallback line chunking
│   ├── embedder.ts         # Embedding providers
│   ├── retriever.ts        # Hybrid search + RRF + boosts
│   ├── reranker.ts         # Re-ranking providers
│   ├── sqlite-store.ts     # SQLite persistence (vec + FTS5 + graph)
│   ├── code-graph.ts       # Import/call/definition edge queries
│   ├── ast-graph-extractor.ts # Single-DFS AST edge extraction
│   ├── graph-expander.ts   # Graph-aware result expansion
│   ├── chunk-pool.ts       # Worker-thread parse/chunk pool (auto on big repos)
│   ├── policy.ts           # Workspace/org policy loading + enforcement
│   ├── audit.ts            # Tamper-evident (hash-chained) audit log
│   ├── license.ts          # Offline Ed25519 license gate
│   ├── search.ts           # Output formatting
│   ├── file-filter.ts      # Gitignore-aware file collection
│   └── file-watcher.ts     # Watch for changes
├── agent/
│   ├── agent.ts            # ContextAgent + tools
│   ├── providers.ts        # LLM callers (OpenAI, Anthropic)
│   ├── model-router.ts     # Cost-appropriate tier per query
│   ├── session-memory.ts   # Cross-session insight memory
│   ├── edit-tools.ts       # File editing tools
│   └── extra-tools.ts      # Shell + web search
├── eval/
│   └── runner.ts           # Retrieval-quality scoring (oce eval)
├── mcp/
│   └── server.ts           # MCP server implementation
└── cli/
    └── index.ts            # oce CLI entrypoint
extension/                  # VS Code extension (chat, edit review, health)

🧪 検索の仕組み

1. チャンク化：コードは Tree-sitter で解析され、関数、クラス、メソッドなどの意味単位に分割されます。未対応のファイルは、境界を考慮した行単位のチャンク化にフォールバックします。
2. 埋め込み：各チャンクは選択したプロバイダーを使用して埋め込まれます。Voyage Code-3 はコード向けに最適化されており、最高の検索品質を実現します。
3. インデックス作成：ベクトルは sqlite-vec に、テキストは FTS5 に、メタデータは SQLite テーブルに格納されます。すべてローカルで処理されます。
4. クエリ：自然言語のクエリが埋め込まれ、ベクトル類似度と BM25 を使って同時に検索されます。
5. 融合：結果は Reciprocal Rank Fusion で融合され、その後、シンボル名の一致、エディターのコンテキスト（アクティブなファイル、開いているタブ）、Git の新しさに基づいてスコアが引き上げられます。
6. 再ランキング（任意）：上位候補は専用の再ランカーで再採点され、精度が向上します。
7. グラフ拡張：上位の結果はコードグラフに沿って拡張され、呼び出し元、呼び出し先、参照されている定義も含まれるため、LLM が全体像を把握できます。

sqlite-vec 拡張機能をプラットフォーム上で読み込めない場合、手順 2 と 4 のベクトル処理は自動的にスキップされ、エンジンは**キーワードのみ（BM25）**で動作します。概念的な一致は見つけにくくなりますが、機能はすべて引き続き動作し、getStatus()、CLI、拡張機能のすべてでこのモードが表示されます。

📏 検索品質の測定

oce eval はラベル付きクエリセットに対してエンジンを評価します。ランキングの変更を推測ではなく測定できます。

# Score the engine against the bundled gold set for this repo
oce eval --cases eval/oce.eval.json

# Save a baseline, change a ranking knob, then compare
oce eval --cases eval/oce.eval.json --out baseline.json
# ...tweak weights / expansion / reranker...
oce eval --cases eval/oce.eval.json --baseline baseline.json

# Measure what symbol/graph expansion contributes
oce eval --cases eval/oce.eval.json --no-expand --baseline baseline.json

recall@k、MRR、nDCG@k、hit-rate、クエリごとのレイテンシーに加え、保存済みベースラインとのケースごとの差分（改善／悪化）をレポートします。メトリクスはファイル単位です。正解ファイルが返された一意のファイルの上位 k 件にランクインすると、そのケースは合格となります。

現在の数値は、このリポジトリにコミットされた 44 ケースの正解セット（eval/oce.eval.json）と、外部の 27 ケースの Flask セット（eval/external/flask.eval.json）で新たに測定したものです。ベースラインもそれぞれのセットとともにコミットされています。

正解セット	キーワードのみ（BM25）	ハイブリッド（voyage-code-3）	ハイブリッド（ローカル MiniLM、適応型フュージョン）
このリポジトリ — recall@10 / MRR / nDCG@10	0.886 / 0.676 / 0.716	0.943 / 0.759 / 0.792	0.932 / 0.691 / 0.743
Flask 3.1.2（外部）— recall@10 / MRR / nDCG@10	0.926 / 0.605 / 0.685	0.889 / 0.604 / 0.676	0.926 / 0.641 / 0.711

正直な見方が 2 つあります。どちらも重要です。

• クエリが意図を言い換えている場合、ハイブリッド方式の価値が発揮されます — このリポジトリのセットでは再現率が 6 ポイント向上しており、エージェントが実際に使用するモードです。
• 適応型フュージョンにより、定義を問うクエリのギャップが解消されました。 以前の均等重み RRF では、確信度の高い BM25 のヒットが、ベクトル検索で優先されたドキュメントやテストよりも下位になっていました（MiniLM ハイブリッドの Flask でのスコアは 0.852 で、キーワードのみの 0.926 に及びませんでした）。クエリはその形式に基づいて分類されるようになりました。識別子の表記、引用符で囲まれたコード、ファイルパスは BM25 を優先し、言い換えはセマンティック検索を優先します（src/core/query-profile.ts）。その結果、ローカル MiniLM ハイブリッドは Flask セットでキーワードのみと同等の 0.926 を達成しつつ、言い換えクエリではハイブリッド方式の優位性を維持しています。voyage の列は適応型フュージョン導入前の結果です（クエリ時のみの変更であり、コミット済みベースラインは均等重みの参照値のままです）。自分で再実行するには、oce eval --no-adaptive-fusion で以前の動作と A/B 比較できます。

このセクションで以前引用していた 6 月のベースライン（ハイブリッド 0.977）は、現在のエンジンでは再現できません（0.943）。ハーネスが実行のたびにドリフトを検出するため、気づかないままリリースされることはありません。

レポートには、生成に使用した検索モード（hybrid または keyword-only）が記録されます。ベースラインとの比較時にモードが一致しない場合は、明確に警告されます。

リポジトリをまたいだ検証： 同梱のセットで検証できるのは、このリポジトリでの検索だけです。eval/external/ には、OCE がこれまで扱ったことのないコードベース向けの正解セットが含まれています。最初のセットは Flask 3.1.2（Python、27 ケース、キーワードのみの recall@10 は 0.926）で、ベースラインと追加手順もコミットされています。eval/oce.eval.json で成果が出たランキング変更は、進歩とみなす前にこちらでも再実行してください。

ケースファイルは JSON 配列（または { cases: [...] }）です。

{ "id": "rrf-fusion", "query": "where is reciprocal rank fusion implemented", "expectedPaths": ["src/core/retriever.ts"] }

評価セットはインデックスに含めないでください。.contextignore にそのディレクトリを指定します。正解セットはクエリと回答を対応付けるため、インデックスに含めると、評価対象のランキングが汚染されます。

📦 要件

• Node.js 22 以降（22 と 24 LTS はコンパイラーなしでインストールできます。Node 20 はサポート終了で、SQLite バインディングのビルド済みバイナリも提供されなくなりました）
• チャットモデル — oce setup で無料の選択肢を確認できます（ローカルの Ollama、または Google、Groq、Cerebras、OpenRouter の無料枠のキー）
• 埋め込みは任意です。埋め込みなしの場合、検索はキーワードのみ（BM25）で動作します。セマンティックランキングには、Ollama（nomic-embed-text、無料かつローカル）、任意の @huggingface/transformers パッケージ（--provider local）、または Voyage／OpenAI のキーを使用します
• sqlite-vec のビルドがないプラットフォーム（例：win32-arm64、Alpine）でも、キーワードのみで動作します

📄 ライセンス

MIT © Gain

---

AI に自分のコードを本当に理解させたい開発者のために作られました。