Ctx Sys

🚀 ctx-sys

AIコーディングアシスタント向けのローカルハイブリッドRAGです。コードベースをインデックス化し、セマンティック検索、キーワード検索、グラフ検索を組み合わせて検索し、AIアシスタントに深いプロジェクト理解能力を与えます。すべてOllamaを使ってローカルで実行されます。

🚀 クイックスタート

1. インストール

# ctx-sysをインストール
npm install -g ctx-sys

# Ollamaをインストールして起動（エンベディング用）
# macOS: brew install ollama
# Linux: curl -fsSL https://ollama.com/install.sh | sh
ollama serve &
ollama pull mxbai-embed-large:latest

2. プロジェクトのインデックス化

cd your-project
ctx-sys init
ctx-sys index

このコマンドで、tree-sitterを使ってコードを解析し、Ollamaでエンベディングを生成し、Markdownドキュメントをインデックス化します。

3. 検索

# セマンティック + キーワードのハイブリッド検索
ctx-sys search "how does authentication work"

# ソース展開付きのコンテキスト取得
ctx-sys context "error handling in the API layer"

# HyDEを使った概念検索の改善
ctx-sys search "database connection pooling" --hyde

4. AIアシスタントへの接続

ctx-sysをMCPサーバーとして追加します。Claude Desktop の場合は、~/Library/Application Support/Claude/claude_desktop_config.json に以下を追加します。

{
  "mcpServers": {
    "ctx-sys": {
      "command": "ctx-sys",
      "args": ["serve"]
    }
  }
}

Claude Code の場合は、MCP設定に以下を追加します。

{
  "mcpServers": {
    "ctx-sys": {
      "command": "ctx-sys",
      "args": ["serve"]
    }
  }
}

これで、AIアシスタントはコードベースの検索、リレーションシップグラフのクエリ、会話メモリの管理など、12のアクションベースのツールにアクセスできるようになります。

✨ 主な機能

• ハイブリッドRAG — ベクトル検索、キーワード/FTS5、グラフトラバーサルを相互ランク融合で組み合わせます。
• ローカルファースト — コードは決してマシンを離れません。Ollamaがエンベディングと要約を処理します。
• コード認識 — tree-sitter AST解析により、関数、クラス、インポート、およびそれらの関係を抽出します。
• 任意のMCPクライアントと互換性 — Claude Desktop、Claude Code、Cursor、またはMCP互換のツールと連携します。

📦 インストールガイド

npm install -g ctx-sys

💻 使用例

基本的な使用法

# セマンティック + キーワードのハイブリッド検索
ctx-sys search "how does authentication work"

高度な使用法

# HyDEを使った概念検索の改善
ctx-sys search "database connection pooling" --hyde

📚 ドキュメント

CLIリファレンス

コアコマンド

ctx-sys init [directory]          # プロジェクト設定の初期化
ctx-sys index [directory]         # コード + ドキュメント + エンベディングのインデックス化
ctx-sys search <query>            # ハイブリッド検索（セマンティック + キーワード）
ctx-sys context <query>           # 展開付きのコンテキスト取得
ctx-sys status [directory]        # プロジェクト情報とヘルスチェック
ctx-sys serve                     # MCPサーバーの起動
ctx-sys watch [directory]         # ファイルの監視と自動再インデックス化

主要なフラグ

# インデックス化
ctx-sys index --no-doc            # ドキュメントのインデックス化をスキップ
ctx-sys index --no-embed          # エンベディングの生成をスキップ
ctx-sys index --force             # すべてを最初から再インデックス化

# 検索
ctx-sys search "query" --hyde     # 概念クエリにHyDEを使用
ctx-sys search "query" --limit 20 # 結果の件数を制御
ctx-sys search "query" --no-semantic  # キーワードのみの検索

# コンテキスト
ctx-sys context "query" --max-tokens 8000  # トークン予算
ctx-sys context "query" --no-expand        # コンテキストの展開をスキップ
ctx-sys context "query" --hyde             # HyDE強化検索

# ステータス
ctx-sys status --check            # 完全なヘルス診断

サブコマンド

# エンティティ管理
ctx-sys entity list               # インデックス化されたエンティティの一覧表示
ctx-sys entity stats              # タイプの内訳
ctx-sys entity get <id>           # エンティティの詳細

# リレーションシップグラフ
ctx-sys graph query <entity>      # 関係のトラバース
ctx-sys graph stats               # グラフの統計情報

# エンベディング
ctx-sys embed run                 # エンベディングの生成/更新
ctx-sys embed status              # カバレッジレポート

# 要約
ctx-sys summarize run             # LLM要約の生成
ctx-sys summarize status          # カバレッジレポート

# セッションとメモリ
ctx-sys session list              # 会話セッションの一覧
ctx-sys session messages [id]     # セッションメッセージの表示

# 知識ベース
ctx-sys kb create <name>          # 共有可能な.ctx-kbとしてパッケージ化
ctx-sys kb install <file>         # 知識ベースのインストール

# デバッグ
ctx-sys debug health              # システムのヘルスチェック
ctx-sys debug inspect             # データベーステーブルの確認
ctx-sys debug export <file>       # プロジェクトデータのエクスポート

MCPツール

MCPサーバーとして接続すると、ctx-sysは12のアクションベースのツールを公開します。

設定

プロジェクト設定 (.ctx-sys/config.yaml)

project:
  name: my-project

indexing:
  ignore:
    - node_modules
    - dist
    - .git

embeddings:
  provider: ollama
  model: mxbai-embed-large:latest

summarization:
  provider: ollama
  model: qwen3:0.6b

hyde:
  model: gemma3:12b

グローバル設定 (~/.ctx-sys/config.yaml)

database:
  path: ~/.ctx-sys/ctx-sys.db

providers:
  ollama:
    base_url: http://localhost:11434
  openai:
    api_key: ${OPENAI_API_KEY}  # オプションのクラウドフォールバック

サポートされる言語

ドキュメント（Markdown、HTML、YAML、JSON、TOML、PDF、CSV、XML、平文）もセマンティックチャンキングでインデックス化されます。

🔧 技術詳細

ctx-sysはすべてのデータを単一のSQLiteデータベースに格納します。

• エンティティ — コードシンボル、ドキュメントセクション、会話メッセージ
• 関係 — CONTAINS、IMPORTS、CALLS、EXTENDS、IMPLEMENTS（ASTから自動抽出）
• ベクトル — sqlite-vecを使ったエンベディングによる高速KNN検索
• FTS5 — BM25ランキングによる全文検索
• セッション — 決定追跡付きの会話履歴

検索では、4つの検索戦略（ベクトル、FTS、グラフ、ヒューリスティック再ランキング）を相互ランク融合で組み合わせます。高度な機能には、HyDEクエリ拡張、クエリ分解、検索ゲーティング、スマートコンテキスト拡張が含まれます。

ソースからのビルド

git clone https://github.com/davidfranz/ctx-sys.git
cd ctx-sys
npm install
npm run build
npm link    # ctx-sysをグローバルに使用可能にする

コントリビューション

コントリビューションを歓迎します。アーキテクチャの詳細については ホワイトペーパー を、完全なドキュメントについては ウェブサイト を参照してください。

📄 ライセンス

MIT