Contextful

Contextful

⚠️ まだ初期アルファ版です。API、機能、連携は安定していません。破壊的変更が予想されます。フィードバックやコントリビューションをぜひお寄せください！

エージェント型 AI のためのローカルコンテキスト管理＋検索エンジン＋メモリ。

Contextful は、エージェント向けのランタイムコンテキストレイヤー兼ローカル検索エンジンです。プロジェクトのコンテキストをすばやく検索、圧縮、引用、記憶するための統一された方法を提供します。

CLI ファーストのツールとして、MCP ランタイムブリッジと生成されるエージェント向け指示を備え、Codex、Claude Code、Cursor、Windsurf、GitHub Copilot、VS Code、Cline、Roo Code、Continue、Zed とシームレスに連携します。

エージェントに毎回40個のファイルを読ませる代わりに、Contextful はプロジェクトを一度インデックス化し、順位付けされ、出典が示され、トークン予算内に収まるコンテキストパックを返します。

なぜ必要なのか？

コンテキストは、エージェント型 AI にとって常にボトルネックでした。大きなコンテキストウィンドウを持つモデル（たとえば100万トークン）は、次のような課題があります。

1. コストが高く、はるかに多くの計算リソースと処理時間が必要です。
2. コンテキストウィンドウが埋まるにつれて、重要な情報を見失いやすくなります。
3. ほとんどのプロジェクトには数百万行のコードがありますが、エージェントが各コンテキストウィンドウに収められるトークン数には限りがあります。

現在の解決策は、エージェントに読み込むファイルを推測させ、セッションのたびにファイルを読むためのトークンコストを支払うことです。これは遅く、コストがかかり、情報も失われやすくなります。

さらに、エージェントにはセッションをまたいで学びを保存・共有する方法がありません。起動するたびにすべてを忘れ、同じコンテキストを再び読み直す必要があります。

効率的なナレッジ検索を可能にしてコンテキストウィンドウを小さく保つため、Contextful の開発を始めました。プロジェクトをインデックス化し、順位付けされ、出典が示され、トークン予算内に収まるコンテキストパックを返すことで、次のことが可能になります。

• トークン使用効率が100倍に向上： 同じファイルを読み直すためにトークンを消費するのをやめられます。
• ツール呼び出しを削減： 1つのコンテキストパックで、数十回に及ぶ grep、glob、ファイル読み込みの呼び出しを置き換えられます。
• セッション間でコンテキストを失わない： エージェントは、証拠に裏付けられたメモリ台帳にセッションでの学びを保存できます。
• 共有可能なプロジェクトナレッジ： 学びとコンテキストパックは、コンテキストの圧縮後や将来のセッションでも保持されます。

主な機能

1. コンテキスト管理

デフォルトのローカルストアは SQLite で、FTS ベースの検索と型付きグラフテーブルを備えています。V1 には次の機能が含まれます。

• デフォルトのローカルストアとしての SQLite。
• FTS5 による語彙検索／BM25 検索。
• 型付きグラフテーブル：nodes、edges、node_props、edge_props。
• よく使われるグラフ関係向けのホット隣接キャッシュ。
• Code2Vec 風の二次再ランキングシグナルを参考にした、決定論的な構造フィンガープリント。

次のストレージ拡張では、sqlite-vec、LanceDB、ローカル HNSW によるセマンティックベクトルと、より大規模なリポジトリ向けの Roaring ビットマップまたは CSR 配列による圧縮隣接リストを、オプションで利用できるようにする予定です。

2. 検索エンジン

Contextful はクエリを分析して意図を分類し、語彙検索、シンボル、ドキュメント、グラフ関係、メモリのヒットを組み合わせて、適切な証拠を取得します。目標は、エージェント向けの Google レベルのプロジェクト検索です。「認証のオンボーディングに役立つリソース」のような曖昧なクエリでも、適切なコード、ドキュメント、過去の学びにたどり着けるようにします。

3. メモリ台帳

エージェントは学び、決定事項、プロジェクトに役立つ事実を保存できますが、単なる「これを覚えておいて」というメモとして保存するわけではありません。すべてのメモリには、ファイル、シンボル、コミット、過去のコンテキストパックを参照する証拠参照が必要です。証拠が変更されると、Contextful はそのメモリを古いものとしてマークします。

4. コンテキストを活用した実行

Contextful は、MCP サーバー、ローカルインデクサー、小規模な CLI です。

• MCP サーバー： エージェント向けインターフェースです。
• ローカルデーモン／ウォッチャー： インデックス作成、再構築、鮮度管理、将来のベンチマークを担います。
• CLI（cxf）： 人間によるセットアップ、インデックス作成、検索、メモリへの書き込み、ローカルでのスモークテストに使用します。

MCP は、ツール、リソース、プロンプトを標準化しているため、適切なインターフェースです。エージェントがコンテキストを要求すると、Contextful は簡潔な根拠を返します。

インストール

npx @inferensys/contextful init --workspace .
npx @inferensys/contextful search "where is user auth handled" --workspace . --budget 2000

MCP サーバーとして実行します。

npx @inferensys/contextful server

CLI

主なバイナリは cxf です。読みやすい別名として contextful も用意されています。

cxf init --workspace <path>
cxf index --workspace <path> [--watch]
cxf daemon --workspace <path>
cxf search "<query>" --workspace <path> --budget 2000 --json
cxf memory add --workspace <path> --claim <text> --evidence <ref>
cxf server

MCP の主要なツール

エージェント向けの機能は最小限に保ちます。

• context_pack(query, budget, scope) - 最も重要なツールです。ランダムなファイルを40個読み込ませる代わりに、順位付けされ、引用付きで、トークン予算に収まるコンテキストのまとまりを返します。
• search_code(query, mode, filters) - コード、ドキュメント、シンボル、メモリを強力に検索します。
• trace_path(from, to, edge_types) - ファイル、シンボル、モジュール、設定をまたいでグラフをたどります。
• impact_analysis(symbol_or_file) - 逆依存関係と、関連する可能性の高いテストを返します。
• why_changed(symbol_or_file) - 現在の根拠と Git の履歴を返します。
• recall_memory(query, scope) - セッションで得た知見と、プロジェクトに関する永続的な教訓を検索します。
• write_lesson(claim, evidence_refs, scope) - 根拠に裏付けられたメモリを保存します。

MCP クライアントのセットアップ

MCP 対応のコーディングツールで、次の stdio サーバーコマンドを使用します。

{
  "mcpServers": {
    "contextful": {
      "command": "npx",
      "args": ["-y", "@inferensys/contextful", "server"]
    }
  }
}

Codex：

codex mcp add contextful -- npx -y @inferensys/contextful server

CLI を優先するエージェントのワークフロー

各ワークスペースで一度だけ cxf init を実行します。プロジェクトのインデックスを作成し、.contextful/AGENT_INSTRUCTIONS.md に簡潔なスキル形式のガイドを書き込みます。このガイドでは、エージェントが context_pack を呼び出すタイミング、範囲を絞って追加検索するタイミング、メモリへの書き込みが許可されるタイミングを説明します。

人間がエージェントと同じ根拠のまとまりをテストする場合は、cxf search を使用します。

cxf search "how does auth load user profiles?" --workspace . --budget 2000

MCP サーバーは引き続きエージェント向けインターフェースとして機能します。CLI はセットアップ、確認、再現可能なローカルテストに使用します。

プライバシー

V1 はローカル環境のみで動作します。外部の埋め込み API を呼び出したり、ソースコードをアップロードしたり、ソースファイルを編集したり、コードを自動修正したり、対象のワークスペース内に依存関係をインストールしたりすることはありません。

根拠参照

メモリへの書き込みには、検索結果またはコンテキストのまとまりから返された根拠参照が必要です。

• file:src/auth.ts:10-40
• symbol:src/auth.ts#AuthService:12
• pack:ctx_...

無効または古い根拠は拒否されるか、古いものとしてマークされます。