knowing

English · 简体中文 · Русский · हिन्दी · العربية

---

自己適応型のコードインテリジェンスエンジンです。グラフの密度を自ら観察し、検索戦略を自動調整します。38 種類のエッジタイプ、28 個の MCP ツール、263 個の同値クラス、暗号学的証明を備えています。規模が大きくなるほど賢くなり、性能が落ちることはありません。

---

メモ

公開済みの研究に基づいて構築： ソフトウェア関係性インテリジェンスのための計算プリミティブとしてのコンテンツアドレス指定（DOI: 10.5281/zenodo.20342255）

アーキテクチャ図には、サービス A がサービス B を呼び出すとあります。それを証明できますか？

knowing ならできます。 抽出したコードの関係性からコンテンツアドレス指定されたグラフを構築し、Git コミットに紐づく Merkle ツリーとしてスナップショットを作成し、オフラインで検証できる暗号学的証明を生成します。エージェントは、順位付けされたコンテキストを得るために利用します。セキュリティチームは監査に利用します。プラットフォームチームは、コードと本番環境のトレースを比較するために利用します。

使うたびに改善されます。コードが変更されると、古くなった知識は自動的に失効します。

brew install blackwell-systems/tap/knowing

{ "mcpServers": { "knowing": { "command": "knowing", "args": ["mcp", "--watch"] } } }

これだけです。MCP サーバーは初回起動時にリポジトリを自動でインデックス化します。モデルのダウンロードも API キーも不要です。エージェントは、順位付けされたコンテキスト、影響範囲、テスト範囲、そしてアクティブなセッション中に結果を改善する暗黙的なノイズの降格を利用できるようになります。

動作を確認する： エージェントに次のように尋ねてください：「context_for_task ツールを使って、コード内に存在すると分かっているものに関連するシンボルを探してください。」 コードベースから、スコアとファイルパス付きで順位付けされたシンボルが表示されるはずです。結果が空の場合は、リポジトリのインデックス化がまだ進行中です（初回起動時は 10～30 秒かかります）。結果が無関係に見える場合は、トラブルシューティングを参照してください。

AI エージェントを使っていませんか？ 下のCLI の使い方に進んでください。

やりたいこと...	こちらから開始
AI エージェントにグラフで順位付けされたコンテキストを提供する	MCP のセットアップ
CLI からグラフを探索する	CLI の使い方
検索の仕組みを理解する	概要
暗号学的証明を使って監査する	監査とコンプライアンス

---

3つの機能、1つのアーキテクチャ

knowingは、1つの基盤（コンテンツアドレス方式のグラフと階層型Merkleツリー）上に構築された3つの製品です。

1. AIエージェント向けコンテキストエンジン 1回の呼び出しで、タスクに最も関連性の高いシンボルを、グラフ中心性、新しさ、学習済みの有用性に基づいて順位付けし、トークン予算内に収まるようにまとめて返します。キーワード検索で見つからない場合も、263のフレームワーク同値クラスが語彙の違いを橋渡しします。ツール呼び出しを47％削減。トークンを84％削減。フィードバックにより結果が向上します。

2. コンプライアンス向け監査プリミティブ グラフの各状態は、gitコミットに紐付いたMerkleルートです。knowing proveは、ある関係が存在したことを示す暗号学的証明を生成します。knowing verifyは、オフラインでその証明を検証します。knowing fsckは、グラフ全体を98msで検証します。サプライチェーン検出では、認証情報へのアクセス、プロセスの起動、ネットワークへの流出を示すエッジを抽出し、構造的に疑わしいコードにフラグを立てます。

3. 学習するノイズ降格 エージェントに返されたものの使用されなかったシンボルは、今後のクエリで降格されます。コードが変更されると、フィードバックは自動的に期限切れになります（パッケージのMerkleルートで検証）。アクティブなセッション中に、システムの精度が高まります。knowingはこの特性を中心に構築されています。

これらは個別の機能ではありません。 コンテンツアドレス方式がもたらす構造上の帰結です。コンテキストをキャッシュ可能にするのと同じハッシュが、その証明も可能にし、古さを検出するのと同じMerkleルートが、古いフィードバックも期限切れにします。

---

回答できること

エージェント向け：

• 「この関数を変更します。何が壊れますか？」（呼び出し元、テスト、ルート、リポジトリを横断した影響範囲）
• 「このタスク向けに50,000トークン分のコンテキストをください。」（grep検索ではなく、グラフに基づく順位付け）
• 「どのテストを実行すべきですか？」（呼び出しグラフのトラバーサル、精度98％）

プラットフォームチーム向け：

• 「このルートは本番環境で使われていますか？」（静的解析＋OTelランタイムトレース）
• 「特定のスナップショット時点で、サービスグラフはどのような状態でしたか？」（スナップショットチェーン。各ルートはgitコミットに紐付け）

セキュリティチーム向け：

• 「このコミットでサービスAがサービスBを呼び出すことを証明してください。」（Merkle証明。オフラインで検証可能）
• 「この依存関係が存在しないことを証明してください。」（ソート済みリーフによる不在証明）
• 「コンプライアンスレポートを生成してください。」（knowing audit -proofs、1つのコマンド）
• 「このパッケージは認証情報を読み取り、プロセスを起動しますか？」（knowing audit-supply-chain --scan-all）

---

数値

項目	結果
システム横断検索	P@10=0.330、コールドスタート（302タスク、17リポジトリ、8言語）
競合との比較	codegraph（19K stars）の3.79倍、GitNexusの6.00倍、Gortexの6.35倍、grepの22.0倍
同値クラス	手作業でキュレーションした277個＋使用状況から学習したクラス。語彙とシンボルを橋渡し（P@10が+57％）
ノイズ降格	クラスターごとの暗黙的フィードバック：R@10 +5.2％、MRR +12.6％（Django、5ラウンド）
削減されるツール呼び出し	47％削減（1回のコンテキスト呼び出しで、繰り返しのgrep+readを代替）
トークン削減	84％削減（GCFワイヤ形式）
同一クエリの再実行速度	93倍高速（Merkleキー付きサブグラフキャッシュ）
Merkle差分	エッジ数100Kの場合、エッジ全件スキャンより517倍高速
テスト範囲	精度98％、再現率82％
グラフ整合性チェック	98ms（24,936エッジ）
証明の生成	生成72us、検証1.2us
フィードバックの期限切れ	コード変更時に100％期限切れ、オーバーヘッド11％
インデックス作成のスループット	16リポジトリ（8言語）を約60秒で処理
言語カバレッジ	16/16リポジトリで合格（Go、Python、TS、Rust、Java、C#、Ruby、multi）
エッジの種類	38種類（サプライチェーン関連のreads_env、executes_processを含む）

すべてのベンチマークは再現可能です。システム横断ベンチマーク（P@10=0.330）では、正確なコミットに固定した17のリポジトリと、コーパスマニフェスト、およびゼロから完全に再現するためのセットアップスクリプトを使用します。プロトコルの詳細はMETHODOLOGY.mdを参照してください。

---

クイックスタート

方法A：MCP サーバー（AIエージェントに推奨）

# 1. Install
brew install blackwell-systems/tap/knowing
# Or: npm install -g @blackwell-systems/knowing
# Or: pip install knowing
# Or: go install github.com/blackwell-systems/knowing/cmd/knowing@latest

# 2. Add to your agent config (.mcp.json, Claude Code settings, etc.)
#    See "MCP Integration" below for the config block.
#    The server auto-indexes your repo on first launch. Done.

方法B：CLIの使用（自分でグラフを調べる）

# 1. Install (same as above)
brew install blackwell-systems/tap/knowing

# 2. Index your repo
knowing add .

# 3. Verify the index worked
knowing stats
# You should see node and edge counts. A healthy TypeScript repo with 50K LOC
# typically produces 2K-10K nodes and 5K-30K edges. If you see very few edges,
# the extractors may not have found your code (check language support below).

# 4. Get context for a task
knowing context -task "refactor auth middleware" -format gcf

# 5. Check graph integrity
knowing fsck

セットアップを確認する

インデックス作成後、次のコマンドを実行して、すべてが正常に動作していることを確認します。

# Show node/edge counts, repos, snapshots
knowing stats

# Search for a symbol you know exists in your code
knowing query "MyKnownFunction"

# Check graph integrity (should report 0 errors)
knowing fsck

# If results seem wrong, check if the graph is stale
knowing stale

knowing stats でノードがゼロ、またはエッジが非常に少ないと表示される場合は、下記の トラブルシューティングを参照してください。

その他の CLI コマンド

# Find affected tests
knowing test-scope -files internal/auth/middleware.go

# Explain why a symbol ranked where it did
knowing why -task "refactor auth" -symbol "SessionHandler"

# Prove a relationship exists (cryptographic Merkle proof)
knowing prove -source "AuthService" -target "SessionStore"

# Verify offline (no database needed)
knowing verify proof.json

# Check if the graph is stale (CI gate: exits 1 if stale)
knowing stale

# Supply chain audit (scan all files for suspicious patterns)
knowing audit-supply-chain --scan-all

# Remove a repo (evicts all data: nodes, edges, snapshots, feedback)
knowing remove ./path/to/repo

すべてのコマンドのリファレンスについては、CLI リファレンスを参照してください。

MCP 統合

MCP サーバーをエージェントに追加します。設定はどこでも同じで、ファイルパスだけが異なります。

エージェント	設定ファイル
Claude Code	.mcp.json（プロジェクトルート）または ~/.claude/mcp.json（グローバル）
Cursor	.cursor/mcp.json
Windsurf	~/.codeium/windsurf/mcp_config.json
VS Code（Copilot、Continue、Cline、Roo）	.vscode/mcp.json
Zed	~/.config/zed/settings.json の "context_servers" の下
Codex（OpenAI）	codex.json または --mcp-config フラグ
JetBrains	Settings > Tools > MCP Servers

{
  "mcpServers": {
    "knowing": {
      "command": "knowing",
      "args": ["mcp", "--watch"],
      "transport": "stdio"
    }
  }
}

--watch フラグを指定すると、ファイルの変更時にインデックスを再作成します。エージェントは常に最新のデータをクエリできます。手動で knowing index を実行したり、データベースパスを指定したりする必要はありません。MCP サーバーは初回起動時に Git リポジトリを自動でインデックス化し、今後のセッションに備えてレジストリに登録します。

エンベディングはデフォルトで無効です（コールドスタートのベンチマークで中立であることを確認済み）。実験する場合は、--embeddings を指定して有効にしてください。グラフ構造と同値クラスが検索品質を支えます。

エージェントが利用できる機能： 主要なツールは context_for_task です。エージェントがタスクの説明とともにこのツールを呼び出すと、knowing は関連性の高いコードシンボルを順位付けし、トークン予算に収まる形で返します。これにより、grep と読み取りを繰り返すループを置き換えられます。ほかにも、blast_radius（これを変更すると何が壊れますか？）、test_scope（どのテストを実行すべきですか？）、explain_symbol（なぜこの順位になったのですか？）などの便利なツールがあります。全 28 個のツールについては、MCP ツールリファレンスを参照してください。

動作を確認する：

1. エージェントとのセッションを開始します
2. 次のように質問します：「context_for_task ツールを使って、コード内の特定のものに関連するシンボルを見つけてください」
3. コードベースから、スコアとファイルパスを伴う順位付けされたシンボルが表示されます

結果が空の場合は、リポジトリのインデックス作成がまだ進行中の可能性があります（初回起動時は 10～30 秒かかります）。結果が無関係に思える場合は、タスクの説明に具体的なシンボル名を使ってください（「認証コードを探して」ではなく、「AuthMiddleware ハンドラーを探して」など）。CLI からも確認できます：

knowing stats          # should show nodes and edges
knowing query "MyFunc" # should find symbols you recognize

HTTP トランスポートを使う場合（複数エージェント、デーモンモード）：

knowing serve -addr :8100 .

{
  "mcpServers": {
    "knowing": {
      "url": "http://localhost:8100",
      "transport": "streamable-http"
    }
  }
}

---

これが機能する理由

Git はファイルをバージョン管理します。knowing はコードの理解をバージョン管理します。

システム全体は、コンテンツアドレス可能な識別という 1 つの考え方に基づいて構築されています。すべてのシンボル、関係、スナップショットは SHA-256 でハッシュ化されます。この選択により、次の機能が追加コストなしで実現します。

• 古さの検出を追加コストなしで実現。 ファイルの変更 = 新しいハッシュ = スキャンせずに古いエッジを特定できます。
• キャッシュを追加コストなしで実現。 同じパッケージルート = 同じ結果。変更のないクエリでは 93 倍高速になります。
• 整合性を追加コストなしで実現。 保存されているすべてのハッシュとスナップショットチェーンの連続性を検証できます。98 ミリ秒です。
• 履歴を追加コストなしで実現。 各スナップショットは Git コミットに紐づく Merkle ルートです。チェーンをたどれます。
• フィードバックの有効期限を追加コストなしで実現。 フィードバックにはパッケージの Merkle ルートが保存されます。コードの変更 = ルートの変更 = 古いフィードバックは表示されなくなります。
• 証明を追加コストなしで実現。 リーフからルートまでの Merkle パスは、自己完結した暗号学的証明です。

	Git	knowing
バージョン管理するもの	ファイルの内容	コードの関係とその意味
保存単位	blob	node + edge + provenance + confidence
識別子	sha256(content)	sha256("node\0" + repo + package + name + kind)
スナップショット	blob のツリー	階層型 Merkle：repo -> package -> edge-type -> leaf
差分	変更された行	変更されたパッケージ、壊れたもの、新しいもの
履歴	コードがどう見えたか	コードベースが自らをどう理解していたか

---

動作の仕組み

+------------------------------------------------------------------+
|                         knowing daemon                            |
+----------------+------------------------+--------------------------+
|   Indexer      |     Graph Store        |      MCP Server          |
|                |                        |                          |
| 23 extractors  | Content-addressed      | 28 tools + 8 resources   |
| tree-sitter    | SQLite + Merkle tree   | stdio / HTTP (1.8s index)|
| LSP + SCIP     | 38 edge types          | GCF / GCB / JSON         |
| OTel traces    | Subgraph cache (93x)   | PackRoot dedup (99%)     |
|                | Embedding vector cache | Embedding re-ranker      |
|                | Community detection    | Supply chain audit       |
+----------------+------------------------+--------------------------+

2つのプレーンがあります。

• 実行： リポジトリをインデックス化し、シンボルと関係を抽出し、トレースを取り込み、スナップショットを保存します。
• インテリジェンス： 保存されたグラフから、影響範囲、コンテキストパック、テスト対象範囲、フィードバック、コミュニティを計算します。

この境界は重要です。インテリジェンス機能はグラフを読み取り、派生結果を生成します。グラフの事実を破損させることはありません。ランキングに誤りがあれば、推奨内容に誤りが生じますが、証明が無効になることはありません。

---

機能

言語と形式

言語／形式	抽出器	フレームワーク／パターンの検出
Go	tree-sitter + go/packages + SCIP	net/http、gin、echo、chi、gorilla/mux
TypeScript/JavaScript	tree-sitter	Express.js、Fastify、Hono、NestJS、Next.js
Python	tree-sitter	Flask、FastAPI、Django
Rust	tree-sitter	Actix、Axum、Rocket
Java	tree-sitter	Spring アノテーション
C#	tree-sitter	ASP.NET 属性
Protocol Buffers	tree-sitter	service、message、enum、RPC 宣言
Terraform (HCL)	tree-sitter	resource、data、module、variable 宣言
SQL	tree-sitter	テーブル、ビュー、関数、プロシージャ、外部キーのエッジ
Kubernetes YAML	yaml.v3	デプロイメント、サービス、ConfigMap、ラベルセレクターのエッジ
CloudFormation/SAM	yaml.v3	リソース、!Ref/!GetAtt/!Sub の相互参照
Docker Compose	yaml.v3	サービス、ポート、ネットワーク、depends_on のリンク
GitHub Actions	yaml.v3	ワークフロー、ジョブ、ステップ、アクション参照
Serverless Framework	yaml.v3	関数、イベント、リソース参照
CSS/SCSS	tree-sitter	セレクター、カスタムプロパティ、var() 依存関係
イベント／MQ パターン	複数言語	Kafka、NATS、SQS、RabbitMQ のパブリッシュ／サブスクライブ
OpenAPI/JSON Schema	json/yaml	エンドポイント、モデル、$ref の解決
Dockerfile	パーサー	FROM のベースイメージ、COPY --from のマルチステージ依存関係、EXPOSE のポート
Makefile	パーサー	ターゲット依存関係、include ディレクティブ、変数参照
Helm Charts	yaml.v3	チャートの依存関係、テンプレート参照、values の注入
GitLab CI	yaml.v3	ジョブの needs、extends テンプレート、include ファイル、アーティファクト
package.json (npm)	json	dependencies、devDependencies、peerDependencies、scripts
GraphQL	パーサー	型定義、フィールドの型参照、インターフェース実装
Ruby	tree-sitter	クラス、モジュール、メソッド定義、require のエッジ
.env ファイル	パーサー	環境変数宣言、ファイル間参照

すべての抽出器はマルチディスパッチによってファイルごとに実行され、結果が統合されます。Tree-sitter は信頼度 0.7（ast_inferred）でエッジを生成し、go/packages と SCIP は信頼度 0.95～1.0（ast_resolved、scip_resolved）で生成します。

MCP ツール

ツール	目的
index_repo、graph_query、repo_graph	グラフの構築と調査
cross_repo_callers、blast_radius、trace_dataflow、flow_between	影響と経路の把握
snapshot_diff、semantic_diff、pr_impact、stale_edges	グラフの状態を比較し、変更をレビュー
runtime_traffic、dead_routes、trace_stats	実行時に観測された関係の照会
context_for_task、context_for_files、context_for_pr、explain_symbol	エージェント向けにランキングされたコンテキスト
ownership、ownership_query、test_scope、communities、plan_turn、feedback	作業の割り当て、コードオーナー／作成者の照会、テストの選定、ランキングの改善
prove、prove_absent、fsck	暗号学的証明、不在証明、整合性検証
untrack_repo	リポジトリのすべてのデータ（ノード、エッジ、ファイル、スナップショット、フィードバック、タスクメモリー、グラフノート）を削除

MCP プロンプト：refactor_safely、review_pr、investigate_dead_code。

MCP リソース

ツールを呼び出さずにエージェントが状況を把握するための、8 つの読み取り専用リソースです。

リソース	返される内容
knowing://report	グラフのサイズ、主要な種類、ホットスポット数、スナップショットの経過時間
knowing://schema	ノードの種類、エッジの種類、来歴の階層、ハッシュ形式
knowing://stats	リポジトリ、種類、エッジの種類ごとの件数
knowing://repos	追跡対象の全リポジトリと件数、最終インデックス作成時刻
knowing://session	コンテキスト呼び出し数、提供したシンボル数、キャッシュヒット／ミス、稼働時間
knowing://index-health	正常／古い／破損の状態、整合性チェック
knowing://communities	凝集度と Merkle ルートを含むコミュニティ一覧
knowing://community/{id}	単一コミュニティの詳細（リソーステンプレート）

---

ワイヤーフォーマット

形式	用途	JSON との比較
GCF（Graph Compact Format）	LLM での利用：行指向、位置ベースのフィールド	トークン数を 84% 削減
GCB（Graph Compact Binary）	サービス間の転送とキャッシュ：varint、長さプレフィックス	バイト数を 74% 削減
JSON	人によるデバッグ、汎用コンシューマー	基準

GCF は | 区切りのフィールドとローカル ID（$1 -> $3）を使用し、完全修飾名の繰り返しを避けます。LLM で解析でき、同じトークン予算で 5 倍のグラフコンテキストを格納できます。セッション状態を利用した重複排除により、シンボルの繰り返しを 47% 削減します。

---

現在の制約

• 静的な影響範囲の追跡では calls エッジをたどります。それ以外のエッジの種類は、たどる対象ではなくコンテキストを提供します。
• ランタイムツールを使うには OpenTelemetry トレースの取り込みが必要です。トレースがない場合、観測結果はありません。
• LSP による拡充に対応する言語：Go、TypeScript、Python、Rust、Java、C#。プロジェクトのマーカーから自動検出します。それ以外は tree-sitter にフォールバックします。
• 埋め込みはデフォルトで無効です（コールドスタートのベンチマークでは中立であることを確認済み、セッション 23）。有効にするには --embeddings を指定してください。

---

ドキュメント

ドキュメント	内容
はじめに	仕組み、検索パイプラインの解説、5 分でできるチュートリアル
アーキテクチャ	システム設計、スキーマ、コンテンツアドレッシング、デーモンモデル
機能	実装済み機能一覧、エントリーポイント、制限事項
監査とコンプライアンス	Merkle 証明、fsck、スナップショットチェーン、CI ゲート
CLI リファレンス	コマンド、フラグ、例、トラブルシューティング
MCP ツール	ツールのスキーマ、パラメーター、戻り値の形式
エッジの種類	関係の意味と来歴
コンテキストのパッキング	RWR、HITS、ランキング、トークン予算
埋め込み再ランキング	ローカル推論、ベクターキャッシュ、レイテンシープロファイル
ランタイムトレース	OTel の取り込みとランタイムの信頼度
ワイヤーフォーマット	GCF、GCB、JSON の形式とベンチマーク
ロードマップ	完了した作業項目と次の優先事項
ベンチマーク	パフォーマンス契約付きの再現可能な価値ベンチマーク
研究	knowing の基盤となる論旨：計算プリミティブとしてのコンテンツアドレッシング（DOI: 10.5281/zenodo.20342255）
フック	Claude Code のフック連携

ライセンス

Apache-2.0 (c) 2026 Dayna Blackwell / Blackwell Systems。LICENSE と NOTICE を参照してください。