CodeCortex Context Engine

🧠 CodeCortex Context Engine

AI コーディングエージェント向けのオープンソースコンテキストインテリジェンス基盤

リポジトリをマッピング · シンボルを解決 · タスクに応じた証拠を取得 · 影響を推定 · ガードレール付きで編集

⭐ CodeCortex にスターを付ける · ❤️ プロジェクトを支援する · ドキュメント · 最新リリース · コントリビュート

🇬🇧 English · 🇮🇷 فارسی

コーディングエージェントにコードベースをたどらせる前に、地図を渡しましょう。

CodeCortex Context Engine

コードベースをたどるよう求める前に、エージェントに地図を渡しましょう。

ノイズを減らし、エビデンスを増やし、変更を検査可能に。

🇮🇷 ペルシャ語

CodeCortex を一言で表すと

CodeCortex は、ソフトウェアリポジトリを質問ごとのエビデンスシステムに変換します。これにより、コーディングエージェントは推測ではなく、地図と根拠に基づいて作業できます。

CodeCortex は、エージェントとコードベースの間に位置します。リポジトリの構造、シンボル、関係、Git 履歴、オーナーシップ、アーキテクチャ、チームの判断、影響範囲、検証から、持続的なインテリジェンスレイヤーを構築します。そしてタスクごとに、モデルに毎回リポジトリの半分を開いて同じ事実をゼロから再構築させるのではなく、役に立つ最小限のエビデンスパッケージを返すよう努めます。

このプロジェクトは、また別のチャットボットではありません。モデルプロバイダーでもありません。エージェントを間違いなく動作させると主張するものでもありません。CodeCortex はコンテキストのインフラストラクチャです。つまり、エージェントの推論に入力される情報の質を向上させるものです。

基本ルール：まずエビデンスを見つけ、その後で確信度に応じて発言します。

چرا اصلاً به چنین چیزی نیاز داریم؟

مدل قوی می‌تواند کد بخواند. مسئله سخت مهندسی این است که بداند کدام کد ارزش توجه دارد، چه چیزی به آن وصل است، چه چیزی عوض شده، کجا ambiguity داریم، مالک آن بخش کیست و اگر تغییر اشتباه باشد چه چیزی می‌شکند.

بدون موتور کانتکست، جریان معمولاً این شکلی می‌شود:

جست‌وجوی اسم فایل
→ باز کردن فایل‌های زیاد
→ کشف دوباره معماری
→ حدس زدن مالکیت سیمبل
→ حدس referenceها
→ بررسی دستی Git
→ حدس blast radius
→ مصرف کانتکست زیاد
→ ویرایش
→ کشف یک dependency پنهان در مرحله بعد

CodeCortex جریان را عوض می‌کند:

تسک
→ تشخیص intent
→ جمع‌آوری evidence ریپو
→ rank کردن برای همین تسک
→ حفظ provenance و uncertainty
→ جا دادن evidence داخل context budget
→ ارائه از یک سطح واحد به ایجنت
→ validation تغییر پیشنهادی

هدف کانتکست بیشتر نیست.

هدف evidence مفیدتر به ازای هر توکن است.

معماری سیستم

استریم زنده Evidence

flowchart LR
    A[AI Coding Agent] --> G[CodeCortex Gateway]
    G --> R[Adaptive Router]

    R --> REP[Repository Intelligence]
    R --> SYM[Symbol Intelligence]
    R --> RET[Hybrid Retrieval]
    R --> GIT[Git + PR Intelligence]
    R --> MEM[Project + Team Memory]
    R --> ARC[Architecture + Drift]
    R --> IMP[Impact + Validation]

    REP --> E[Evidence Surface]
    SYM --> E
    RET --> E
    GIT --> E
    MEM --> E
    ARC --> E
    IMP --> E

    E --> C[Context Pipeline]
    C --> B[Rank + Dedup + Slice + Budget]
    B --> G
    G --> A

حقیقت اجرایی همچنان سورس فعلی، کانفیگ و تست است. Graph، memory، semantic retrieval، architecture inference و summary برای فهم بهتر هستند؛ جای source truth را نمی‌گیرند.

نقشه قابلیت‌های فعلی

دکترین CodeCortex

این‌ها slogan نیستند؛ قانون مهندسی‌اند.

Doctrine 01 — First evidence, then confidence

解決済みシンボル、セマンティックマッチ、推論されたエッジ、メモリー、Git の観測結果は、同じ品質ではありません。CodeCortex は、それらをすべて同じ確実性で提示してはいけません。

正確な証拠          → 正確に提示する
強い推論            → provenance を保持する
曖昧な推論          → 他の候補も保持する
証拠がない          → missing と報告する
証拠が古い          → stale と報告する

Doctrine 02 — 必要十分な、最小のコンテキスト

最適なコンテキストパッケージは、収まる最大のものではありません。最適なパッケージは、そのタスクに必要なソース、関係、履歴、検証を備えた、最小のパッケージです。

Doctrine 03 — Source はあくまで Source

メモリーは理由を説明できます。Git は履歴を示します。グラフは関係を示します。検索は関連の可能性を示します。しかし、実行時の動作を決めるのは、現在のソース、設定、テスト、再現可能な成果物です。

Doctrine 04 — 曖昧さそのものが情報です

2 つのシンボルが有力なターゲットであれば、その曖昧さは重要です。アーキテクチャが推論によるものであれば、欠落シグナルは重要です。任意のインテグレーションが利用できない場合、成功を捏造するより unavailable と示すほうが適切です。

Doctrine 05 — すべての変更には Blast Radius があります

小さな diff が高リスクの場合もあれば、大きな diff が機械的な変更の場合もあります。問うべきなのは、どのシンボルが変更されたか、何がそれに依存しているか、どのテストがその経路をカバーしているか、担当者は誰か、そしてどの証拠に基づいてリスクを判断したかです。

Doctrine 06 — Local-first は信頼に関する判断です

コアのインテリジェンスはローカルで動作します。ネットワーク境界、認証情報、リモートツール、クォータ、ポリシー、データ転送は、すべて明示されている必要があります。

Doctrine 07 — 再現性は魅力的な数値より重要です

仕様、リビジョン、環境、測定結果、成果物が揃っていないベンチマークは、強い証拠にはなりません。

Doctrine 08 — Scale は明示的な Coordination によって実現します

Worker には、ID、機能、リース、失敗、再試行、状態があります。共有メモリーには、同期と競合があります。リモートツールには、認証とポリシーがあります。

クイックスタート

インストール

CodeCortex は Python 3.11、3.12、3.13 をサポートしています。

python -m pip install --upgrade codecortex-context-engine

オプションのパーサー：

python -m pip install "codecortex-context-engine[parsers]"

オプションのローカルセマンティック埋め込み：

python -m pip install "codecortex-context-engine[semantic]"

リポジトリ内で始める

cortex init .
cortex index
cortex doctor

cortex architecture
cortex semantic "authentication and session lifecycle"
cortex impact AuthService
cortex symbol-history src/auth.py 10 80

cortex mcp --path .

30 秒でわかるメンタルモデル

          ┌────────────────────────────┐
          │       Coding Agent         │
          └─────────────┬──────────────┘
                        │ task
          ┌─────────────▼──────────────┐
          │        CodeCortex          │
          │ map · symbols · history    │
          │ graph · retrieval · memory │
          │ impact · architecture      │
          │ validation · policy        │
          └─────────────┬──────────────┘
                        │ 限定された証拠
          ┌─────────────▼──────────────┐
          │       Coding Agent         │
          │  より良いマップを使って推論する │
          └────────────────────────────┘

エージェントは引き続き自分で推論します。CodeCortex が改善するのは、エージェントが推論に使うものです。

タスクの流れ

バグ調査

sequenceDiagram
    participant A as Agent
    participant C as CodeCortex
    participant R as Repository
    participant G as Graph
    participant H as Git/History
    participant V as Validation

    A->>C: Trace a failing behavior
    C->>R: locate source and symbols
    C->>G: resolve callers and dependencies
    C->>H: inspect recent change and ownership
    C->>V: identify tests and validation signals
    C-->>A: compact evidence package + impact

優れた調査では、次の点に答える必要があります。

1. 動作はどこに実装されていますか？
2. どの呼び出し元と参照が経路上にありますか？
3. 最近何が変更されましたか？
4. 仮説を否定する別の経路はありますか？
5. 説明が誤っている場合、どのテストが失敗するはずですか？
6. 最小限の安全な変更は何ですか？

Pull Request レビュー

diff
→ 変更されたファイル
→ 変更されたシンボル
→ 下流への影響
→ 影響を受けるテスト
→ 変更頻度 / 担当者
→ アーキテクチャ上の変化
→ リスクの証拠
→ レビュー用コンテキスト

PR のサイズはシグナルの 1 つにすぎません。

マルチリポジトリ

frontend repo ───────┐
backend repo ────────┼── フェデレーションされた証拠 ──→ タスクコンテキスト
contracts repo ──────┘

リポジトリの識別情報は保持されます。すべてが物理的に 1 つのコードベースであるかのように装うのではなく、証拠をフェデレーションします。

インテリジェンスのレベル

制御された編集

現在のセマンティック操作：

cortex edit rename src/auth.py AuthService SessionService
cortex edit replace src/auth.py AuthService/refresh --body-file ./replacement.txt
cortex edit insert-before src/auth.py AuthService --body-file ./imports.txt
cortex edit insert-after src/auth.py AuthService --body-file ./helper.txt

変更の原則：

必要な範囲を読み取る
→ 影響を把握する
→ 範囲を限定して変更する
→ 検証する

次のような方法ではありません：

あらゆる場所で置換する
→ テストが検出してくれることを願う

MCP：エージェントのための統一インターフェース

cortex mcp --path /path/to/repository

MCP は、リポジトリマップ、シンボル検索、参照、依存関係グラフ、影響分析、ハイブリッド検索、コンパクトなコンテキスト、アーキテクチャ、Git、PR、メモリ、ワークスペース、トレース、検証、統計を提供します。

分散処理

flowchart TB
    AG[AI Agents] --> GW[Remote MCP Gateway]
    GW --> AUTH[Authentication]
    AUTH --> POL[Tool Policy + Quotas]
    POL --> COORD[Coordinator]

    COORD --> IDX[Index Workers]
    COORD --> RET[Retrieval Workers]
    COORD --> CTX[Context Workers]

    IDX --> GRAPH[(Graph State)]
    RET --> VEC[(Persistent Vector Store)]
    CTX --> MEM[(Synchronized Team Memory)]

    COORD --> AUDIT[(Audit + Performance History)]

ワーカーは機能を通知し、作業にはリースが設定され、期限切れの作業は再キューに入れることができます。リモート操作では、認証、TLS、クォータ、ツールポリシー、組織／ワークスペースポリシー、監査の根拠を設定できます。

ダッシュボードは可観測性のためのものであり、認可のためのものではありません。

Observatory

cortex dashboard -p /path/to/repository

Observatory では、次の情報を表示できます：

バックエンドの健全性
ルーティングの分布
コンテキストの使用状況
エンジンのレイテンシ
グラフのホットスポット
タスクのトレース
アーキテクチャのドリフト
ベンチマークの履歴
プルリクエストのリスク

コンテキストエンジンは、自身のルーティング、根拠の出所、障害状態を説明できる必要があります。

مدل امنیت

Badge امنیتی evidence است، نه تضمین امنیت همه deploymentها. Threat model مخصوص محیط همچنان لازم است.

دکترین Quality، Release و Benchmark

commit دقیق
→ quality matrix
→ security checks
→ build
→ smoke test
→ checksum
→ SBOM
→ signature / attestation
→ release

Integrationای که credential ندارد باید skipped گزارش شود، نه success.

Benchmark:

python scripts/run_production_benchmark.py

Claim performance باید به spec بازتولیدپذیر، revision پین‌شده، environment، measured result و artifact وصل باشد. CodeCortex نباید token saving، speedup، task success یا accuracy ساختگی منتشر کند.

لایه Evidence Fusion

وضعیت: منتشر شده. implementation، test، benchmark، documentation و سوابق provenance همگی داخل ریپو هستند. هر سه لایه اختیاری‌اند: هسته CodeCortex بدون هیچ‌کدام از آن‌ها و بدون دسترسی شبکه کار می‌کند.

CodeCortex چند نوع evidence را با هم ترکیب می‌کند و برای هر نتیجه می‌گوید آن نتیجه چطور اثبات شده است. هر رکورد یک trust tier مشخص دارد — exact، near_exact، structural، inferred_high، inferred، weak — به‌همراه برچسب provenance. دو قاعده در خودِ کد اجرا می‌شوند، نه فقط در مستندات: هیچ evidence‌ای تا وقتی تازه نباشد نمی‌تواند ادعای exact کند، و evidence قدیمی هرگز بالاتر از evidence ساختاری تازه رتبه نمی‌گیرد.

مدل کامل، رفتار fallback و مرزهای امنیتی در docs/EVIDENCE_FUSION.md آمده است.

۱ — Precision Code Intelligence

لایه Precision Code Intelligence در صورت وجود evidence دقیق compiler/indexer-grade تفاوت این سطوح را تشخیص می‌دهد:

definition/reference دقیق
        با
relationship ساختاری
        با
candidate heuristic
        با
lexical coincidence

قابلیت‌های فعلی:

• definition دقیق؛
• reference دقیق؛
• implementation relationship؛
• occurrence سیمبل؛
• stale-index detection؛
• fusion گراف با provenance دقیق/استنباطی؛
• fallback به intelligence فعلی.

flowchart TB
    EX[Exact index/compiler evidence] --> F[Evidence Fusion]
    SEM[Language-aware semantic evidence] --> F
    AST[AST / structural evidence] --> F
    GR[Graph inference] --> F
    HEU[Heuristic resolution] --> F
    LEX[Lexical match] --> F
    F --> CTX[Task-ranked context]

سیستم باید فقط نداند چه پیدا کرده؛ باید بداند چقدر دقیق می‌داند.

۲ — Dependency Intelligence با آگاهی از نسخه

لایه Dependency Intelligence این اطلاعات را کنار هم قرار می‌دهد:

manifest
+ lockfile
+ نسخه declared
+ نسخه resolved
+ usage داخل repository
+ documentation مربوط به همان نسخه

سؤال‌هایی که این لایه پاسخ می‌دهد:

• نسخه واقعی resolveشده چیست؟
• API پیشنهادی برای همین نسخه معتبر است؟
• pattern فعلی قدیمی است؟
• migration guidance مرتبط چیست؟
• کدام file و symbol از dependency استفاده می‌کند؟

Documentation بیرونی باید optional، minimal-data، credential-aware، cacheشده و explicit باشد. Core باید offline هم کار کند. سورس ریپو نباید برای جواب dependency question به‌صورت پیش‌فرض از سیستم خارج شود.

۳ — Structural Search و Guarded Rewrite

لایه Structural Search و Guarded Rewrite برای patternهای syntax-aware:

callهایی با شکل old_api($X)
constructor با option قدیمی
handler با exception pattern خاص
همه usageهای ساختاری قبل از migration

جریان mutation:

flowchart LR
    Q[Migration request] --> S[Structural search]
    S --> M[Match set]
    M --> I[Impact analysis]
    I --> P[Rewrite preview]
    P --> A{Mutation allowed?}
    A -- No --> STOP[Preview only]
    A -- Yes --> W[Bounded rewrite]
    W --> R[Reindex]
    R --> V[Validation]
    V --> POST[Post-change impact]

Rewrite باید preview، bound، content-hash check، policy authorization، reindex و validation داشته باشد.

本当の目的：エビデンスの統合

将来のタスクの例：

このプロジェクトが使用しているバージョンに合わせて、認証ミドルウェアを正しい API に移行してください。

望ましいストリーム：

依存関係マニフェスト
→ 解決済みバージョン
→ 現在のミドルウェア
→ 正確なリファレンス
→ バージョンに対応したドキュメント
→ 構造上の出現箇所
→ 影響を受けるシンボルとテスト
→ ガード付き書き換えプレビュー
→ 変更ポリシー
→ 検証
→ 変更後の影響

中核となる価値は、3つの独立したツールではありません。中核となる価値は、ローカルコードの真実、正確な関係、依存関係のバージョン、構造パターン、履歴、検証を、1つのタスク向けのパッケージにまとめるコンテキストエンジンです。

現在の状態とフォールバック動作

利用プロファイル

CodeCortex ではないもの

設計原則

1. 境界を型付けする。
2. インテリジェンスは交換可能にする。
3. ローカル優先。
4. コンテキスト予算を明示する。
5. プロジェクトの状態をデフォルトにする。
6. 要約後も来歴情報を保持する。
7. 変更権限を分離する。
8. 分散状態を明示する。
9. 欠けているエビデンスを捏造しない。
10. リリース時の主張にはエビデンスを求める。

コマンド一覧

cortex init .
cortex index
cortex architecture
cortex architecture-drift
cortex semantic "authentication refresh"
cortex impact AuthService
cortex symbol-history src/auth.py 10 80
cortex pr main --head HEAD
cortex workspace-add backend ../backend
cortex workspace-search "payment service"
cortex definition src/auth.py 12 7
cortex references src/auth.py 12 7
cortex precision-status
cortex dependency next
cortex dependency-docs next "middleware authentication"
cortex structural-search --lang python --pattern 'old_api($X)'
cortex rewrite-preview --lang python --pattern 'old_api($X)' --replacement 'new_api($X)'
cortex rewrite-apply <preview-id>
cortex benchmark
cortex evidence-benchmark
cortex dashboard
cortex doctor
cortex mcp --path .

Docker

docker build --target core -t codecortex:core .
docker build --target full -t codecortex:full .
docker compose up dashboard

コンテナ化しても、適切な認証、TLS、ポリシー、シークレット管理、脅威モデルの代わりにはなりません。

プロジェクトの状態

CodeCortex は現在 アルファ版です。

公開インターフェースは今後も変更されるため、1.0 より前に破壊的変更が発生する可能性があります。このプロジェクトは、コード、テスト、CI、ドキュメント、再現可能な成果物が実際に示す内容に基づいて評価してください。

سناریوهای مهندسی

مشارکت در پروژه

Good First Issues · گزارش باگ · راهنمای مشارکت

مستندات

• Architecture
• Distributed
• Advanced Intelligence
• Evidence Fusion
• Integrations
• Quality
• Testing
• Release
• Licensing
• Security
• Contributing
• Governance
• Roadmap
• Cloud & Enterprise Early Access

سؤال‌های پرتکرار

نگهداری، مشارکت و License

CodeCortex توسط Behnam Jalali ساخته و نگهداری می‌شود.

python -m pip install -e ".[dev]"
ruff check .
mypy src/codecortex
pytest

بخش‌های متعلق به CodeCortex تحت Apache License 2.0 منتشر می‌شوند. اجزای ثالث تابع license و attribution ثبت‌شده در خود ریپو هستند.

فایل‌های LICENSE، NOTICE، SECURITY.md و CONTRIBUTING.md را ببینید.