CogZ

CogZ

AI コーディングエージェントのための、ローカルファーストでコードを認識するエンジニアリング認知機能です。

CogZ はコーディングエージェントに、永続的なメモリ、コンテキストに応じた検索、ソフトウェアリポジトリに関する継続的な認知機能を提供します。すべてお使いのマシン上でローカルに動作し、クラウドサービスは必要ありません。

Claude Code、Cursor、Codex、Gemini CLI、GitHub Copilot、Devin、および MCP 互換のあらゆるエージェントで動作します。

表示例

CogZ 自身のコードベースで実行した際の実際の出力です。

$ cogz context --mode task "token budget estimation and context pack compression"

Context pack (mode: task)
Query: token budget estimation and context pack compression
Search mode: hybrid
Sections: 91
Token estimate: 8188

Dropped: 6 sections over token budget

---

## 1. [rule] New expansion channels: emit early, filter before seen-mark, sort deterministically, never displace directs (relevance: 0.5148)

Conventions proven across the sibling and co-change channels:

1. Emit before the generic expansion loops — candidates emitted
   later get claimed-and-floored by graph traversal …
2. Apply entity-type/test filters BEFORE `seen.insert` …
…

## 2. [rule] cfg-gated code must be typechecked per-target before release (relevance: 0.4690)

Code behind #[cfg(unix)]/cfg(target_os = ...) is invisible to host
builds, tests, and clippy — a compile error in a cfg'd branch ships
silently until a real target build sees it. The v0.5.0 Windows leg
failure is the canonical example.

## 3. [rule] Degradation must be loud, never silent (relevance: 0.3680)

Every degraded or failed code path must surface a signal …

## 4. [identity] CogZ (relevance: —)

Project: CogZ

## 5. [file] assemble.rs (relevance: 0.6993)

//! Context pack assembly — the tiered-push pipeline.
//! Tier 0 (baseline: identity + top rules) always ships for task and
//! escalation packs …

… 86 more sections …

これはベクトル検索から得られたテキストの断片ではありません。このパックでは、検証済みのルール（このプロジェクトで発生したリリース失敗から学んだものを含みます）、アイデンティティのベースライン、実際のソースファイルが先頭に並び、関連度順にランク付けされ、追跡可能で、トークン予算も設定されています。

このリポジトリには、すでに実際のドッグフーディングで得られた知識が含まれています。CogZ は開発期間を通じて、自身のコードベースで使用されてきました。クローンして CogZ をインストールすれば、上記のコマンドをこのリポジトリに対して直接試せます。

機能

CogZ は、エージェントが学習した内容と作業対象のコードを結び付ける、プロジェクト固有のナレッジレイヤーを維持します。

メモリ

CogZ は次の 3 種類のプロジェクト知識を保存します。

• 観察事項 — エージェントが学習したことや気付いたことです。バグの発見、決定事項、気付いたパターンなど、未検証の生の経験です。
• ルール — 今後の作業に反映すべき、検証済みの知識です。コーディング規約、設計上の決定事項、確認済みのパターンなどです。
• ナレッジ — コードベースに関する構造化された情報です。アーキテクチャの説明、モジュールの役割、トレードオフの根拠などです。

これらは YAML フロントマター付きの Markdown ファイルとして保存され、互いに、またリポジトリ内のコードエンティティにリンクされます。ファイルが信頼できる唯一の情報源であり、SQLite は派生インデックスとして使われ、破棄して再構築できます。ナレッジは移植可能で、バージョン管理でき、手作業で編集できます。

コンテキスト

エージェントが知っていることをすべて渡す代わりに、CogZ は現在の状況に応じたスコープ付きコンテキストパックを構築します。コンテキストパックには、関連するルール、観察事項、ナレッジ、コード構造がまとめられます。関連度順にランク付けされ、コードグラフを通じて追跡でき、トークン予算によって制限されるため、プロジェクトの履歴全体ではなく、タスクに重要な情報をエージェントに提供できます。

認知

CogZ は定期的に、学習した内容を統合します。エントリの重複を排除し、矛盾を検出し、十分な裏付けのある観察事項をルールに昇格させ、置き換えられたエントリを統合します。また、参照先のコードが変更された場合は、ナレッジに古くなった可能性があることを示します。

クイックスタート

Linux／macOS／Windows（Git Bash）：

# Install
curl -fsSL https://raw.githubusercontent.com/balaianu/CogZ/master/install.sh | bash

# Initialize in a repo (add --configure auto to wire MCP + hooks for detected agents)
cd ~/your-project
cogz init

# Index (downloads models on first run, or use --no-download for FTS-only)
cogz index

# Verify it's working — entity counts, model status, DB stats
cogz status

Windows（PowerShell）：

# Install
irm https://raw.githubusercontent.com/balaianu/CogZ/master/install.ps1 | iex

# Initialize in a repo
cd your-project
cogz init
cogz index

メンタルモデルと一通りの手順については、はじめにをご覧ください。

MCP 統合

CogZ は、stdio 経由でステートレスな MCP サーバーとして動作します。すべてのツール呼び出しでは、必須の repo パラメーターで対象のリポジトリを指定します。Roots、セッション状態、フォールバックはありません。

{
  "mcpServers": {
    "cogz": {
      "command": "cogz",
      "args": ["mcp-stdio"]
    }
  }
}

サーバーは 15 個のツールを公開します：create_entity、update_knowledge、verify_knowledge、reject_entity、query_entities、search、get_context、get_status、list_entities、consolidate、capture_event、get_callers、get_impact、find_orphans、suggest_observations。

パラメーターの詳細なリファレンスと応答例については、MCP Tools を参照してください。6 つのサポート対象エージェントすべてのエージェント別設定ファイル、フック形式、検証済み機能に関する注記については、Agent Setup を参照するか、cogz configure auto を実行してください。

フック統合

フックはライフサイクルイベントをキャプチャし、エージェントのセッションにコンテキストパックを挿入します。CogZ のバイナリがフックハンドラーとして機能するため、ラッパースクリプトは不要です。

{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "cogz capture-event session_start --hook-json",
        "timeout": 15
      }]
    }]
  }
}

7 種類すべてのイベントと、エージェント別の設定ガイドについては、Hooks を参照してください。

CLI コマンド

通常の操作は自動で行われます。ライフサイクルイベントでフックが起動し、エージェントは MCP を介して CogZ を操作します。日常的な利用に CLI は必要ありません。セットアップや手動での探索、必要に応じた自動化のために利用できます。

コマンド	説明
cogz init	リポジトリに .cogz/ を初期化します
cogz configure <harnesses>	エージェントの MCP とフックの設定を書き込みます（auto はインストール済みのエージェントを検出します）
cogz index [--no-download]	ファイルを DB に同期し、ソースコードにインデックスを作成します
cogz reindex	増分インデックスを再作成します（変更されたファイルのみ）
cogz search <query>	FTS、ベクトル、グラフを組み合わせて検索します
cogz context --mode <mode> [query]	コンテキストパックを構成します
cogz status	DB の統計、エンティティ数、モデルの状態を表示します
cogz consolidate [--dry-run]	昇格とマージを実行します
cogz suggest [--days N]	抽出された観察候補を一覧表示します
cogz verify <entity-id>	ドリフトしたエンティティの来歴を再記録します
cogz reject <entity-id>	エンティティを却下済みにします（--reason に理由を保存します）
cogz capture-event <type>	フックからライフサイクルイベントをキャプチャします
cogz models <download|list|clean>	モデルを管理します
cogz doctor [--prune-observations]	ヘルスチェック、ポリシー違反、使用状況のメトリクスを確認します
cogz update [--check]	GitHub リリースから自己更新します
cogz reset [--purge]	DB を削除します（必要に応じて観察データも消去します）
cogz mcp-stdio	stdio 経由で MCP サーバーを実行します

すべてのフラグとオプションについては、CLI Reference を参照してください。

要件

最小要件（FTS のみのモード）

リソース	要件
RAM	256 MB の空き容量
ディスク	50 MB（バイナリと DB、モデルなし）
CPU	x86_64 または ARM64 であれば可

ONNX Runtime やモデルのダウンロードなしで動作します。すべてのフック、FTS 検索、コンテキストパック、統合、doctor、prune が利用できます。ベクトル検索、埋め込みベースの重複排除、矛盾検出は利用できません。

推奨要件（ハイブリッド検索モード）

リソース	要件
RAM	2 GB の空き容量
ディスク	550 MB（バイナリ、ONNX Runtime、3 つのモデル、DB）
CPU	x86_64 または ARM64 であれば可。4 コア以上の場合、バッチ埋め込みが高速化します

ベクトル検索、セマンティック重複排除、NLI による矛盾検出を含むすべての機能を利用できます。モデルは初回使用時に自動ダウンロードされ、5 分間アイドル状態が続くと自動的にアンロードされます（RAM 使用量は約 11 MB に戻ります）。リソース消費の全プロファイルについては、Evaluations を参照してください。

ベンチマーク

CogZ には、固定された公開コーパス（httpx、cobra、clap。いずれも実際の Git 履歴から抽出したメモリシードを注入）と、このリポジトリ独自の .cogz コーパスで実行する、再現可能なベンチマークスイート（benchmark/）が用意されています。シードを使用した正解データの結果は次のとおりです。

コーパス	P@5	MRR	Recall@20
cobra	0.200	0.523	0.867
httpx	0.160	0.364	0.867
clap	0.169	0.259	0.789

コミットに関するクエリで各チャネルをアブレーションしたところ、グラフ展開を取り除くと Recall@20 が 3～15 ポイント低下しました。コミット意図のクエリでは、FTS のみのモードが競争力を保っています（R@20 はハイブリッドの 0.31～0.47 に対して 0.34～0.47）。ベクトルチャネルの改善効果はセマンティッククエリに集中し、展開は行数上限によって薄まります（最優先のランキング課題として追跡中）。コンテキストパックでは、デフォルトの 8K 予算で 0.49～0.89 の期待エンティティ再現率を維持します。再実行の結果はバイト単位で一致します。手法、フェーズごとの数値、生の成果物については、benchmark/README.md を参照してください。

使用によって得られる効果（測定値）： 14 タスクのエージェント再生では、シード済みナレッジを使用した構成は、何も使用しない構成より約 2 倍速く完了し（平均 871 秒対 1748 秒）、正確性が同等のまま完了した実行数も増えました（14/14 対 10/14）。統合機構の精度は高く、重複排除の適合率／再現率は 1.0、NLI による矛盾検出は誤検知ゼロで 4/4、ドリフトのマーク付けも正確です。

率直な制限事項： 混在コーパスでは上位 5 件の適合率が低く（P@5 <= 0.20。ランキング上位ではコードエンティティがナレッジより上位になります）、コミット意図のクエリに対する Recall@20 は 0.31～0.53 です。隣接ドメインに対する負例クエリでは、依然として確信度の高いヒットが漏れます（コーパス全体でサイレンスゲートのクリーン率は 0.47～0.73）。また、タスク数 n=14 では、タスクの正確性に対する測定可能な改善はまだ確認できていません。

アーキテクチャ

• 単一の Rust バイナリ — オプションのベクトル検索用 ONNX モデルを除き、実行時依存関係はありません。
• ファイルが正本 — すべてのエンティティは Markdown ファイルです。SQLite DB は派生インデックスであり、破棄して再構築できます。
• コードを認識 — tree-sitter により、ソースコードを第一級のグラフエンティティとしてインデックス化します。対応言語：Rust、Python、Go、JavaScript、TypeScript、TSX、Bash。
• 段階的に機能を縮退 — FTS のみのモードでは、ML モデルなしでも動作します。
• ローカル優先 — クラウド、テレメトリー、アカウントは不要です。ネットワークに接続するのは、モデルを任意でダウンロードする場合のみです。

システム設計の詳細はアーキテクチャを参照してください。

互換性

プラットフォーム	サポート	埋め込み	FTS のみ	インストール
Linux x86_64	フル対応	自動ダウンロード	対応	install.sh
Linux aarch64	フル対応	自動ダウンロード	対応	install.sh
macOS arm64（Apple Silicon）	フル対応	自動ダウンロード	対応	install.sh
macOS x86_64（Intel）	非対応	—	—	—
Windows x86_64	フル対応	自動ダウンロード	対応	install.ps1 または install.sh（Git Bash）

macOS Intel は、Microsoft が v1.22 以降の ONNX Runtime macOS Intel バイナリの提供を終了したため、サポート対象外です。Intel Mac ユーザーは、Rosetta 2 上で arm64 バイナリを実行する（互換性のある ORT ビルドが必要）か、cargo install cogz を使って FTS のみのモードを利用できます。

Windows 10 以降が必要です（ONNX Runtime の自動展開に必要な bsdtar は、ビルド 17063 以降に同梱されています）。

クロスプラットフォームでのチームコラボレーションに対応しています。コードエンティティの UUID ではスラッシュを使用したパス正規化を行うため、同じソースファイルから、どのプラットフォームでも同じエンティティ ID が生成されます。

ドキュメント

ユーザーガイド：

• はじめに — メンタルモデルと操作ガイド
• 設定 — config.toml の完全なリファレンス
• CLI リファレンス — すべてのコマンドとフラグ

インテグレーション：

• MCP ツール — 15 個すべてのツールのシグネチャとレスポンス形式
• フック — ライフサイクルイベントと出力形式
• エージェントのセットアップ — 6 種類すべてのエージェントと汎用 MCP、およびエージェントごとの効果の適用範囲

設計：

• アーキテクチャ — システムの概要とモジュール構成
• エンティティモデル — エンティティの種類、フロントマター、ステートマシン
• 検索 — ハイブリッド FTS + ベクトル、RRF、グラフ拡張
• 統合 — 重複排除、矛盾、昇格、マージ
• 縮退動作 — FTS のみのモードとフォールバック動作

コントリビュート：

• ビルド — ビルド、リリース、クロスコンパイル
• テスト — テストのカテゴリとモックモデル
• 規約 — コードパターンと不変条件
• 依存関係 — 固定バージョンとサプライチェーンポリシー
• スキーマ — DB スキーマとマイグレーション

コントリビュート

ビルド、テスト、PR のガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT — LICENSE をご覧ください。

サポート

このツールが役に立った場合は、コーヒーをごちそういただけると幸いです。