アーキテクチャ概要

KnowledgePulse は二層アーキテクチャ上に構築された AI ナレッジ共有プロトコルです。プロトコルレイヤーはナレッジの構造化、検索、ガバナンスを定義し、インフラストラクチャレイヤーはプロトコルを実装する具体的なランタイムコンポーネントを提供します。

プロトコルスタック

プロトコルは5つのレイヤーで構成され、各レイヤーはその下のレイヤーの上に構築されます：

┌─────────────────────────────────────────┐
│            5. ガバナンス                │
│   ライセンス、帰属、監査証跡           │
├─────────────────────────────────────────┤
│            4. プライバシー              │
│   スコーピング、リダクション、GDPR 準拠│
├─────────────────────────────────────────┤
│            3. ディスカバリー            │
│   検索、スコアリング、ベクトル検索     │
├─────────────────────────────────────────┤
│            2. KnowledgeUnit             │
│   JSON-LD スキーマ、型、バージョニング │
├─────────────────────────────────────────┤
│            1. SKILL.md                  │
│   エージェント機能宣言フォーマット     │
└─────────────────────────────────────────┘

レイヤー 1 -- SKILL.md はエージェントが機能、入出力、制約を宣言するための標準ファイルフォーマットを定義します。他のレイヤーが参照する基盤的な契約です。

レイヤー 2 -- KnowledgeUnit は3つのナレッジタイプ（トレース、パターン、SOP）の JSON-LD スキーマとスキーマの進化を規定するバージョニングルールを規定します。

レイヤー 3 -- ディスカバリー はナレッジユニットのインデックス化、検索、関連性スコアリング、取得（ベクトルベースの類似検索を含む）を扱います。

レイヤー 4 -- プライバシー はスコーピングルール、フィールドレベルのリダクション、データエクスポートや忘れられる権利などの GDPR 要件のオペレーションを処理します。

レイヤー 5 -- ガバナンス はライセンス、帰属チェーン、エージェント間のナレッジフローを追跡する監査証跡を扱います。

コンポーネント概要

4つのランタイムコンポーネントがプロトコルスタックを実装します：

コンポーネント	パッケージ	役割
SDK	@knowledgepulse/sdk	コアライブラリ --- 型、キャプチャ、取得、スコアリング、SKILL.md パース、マイグレーション
レジストリ	registry/	Hono REST API サーバー --- ナレッジユニットの格納、認証、レート制限
MCP サーバー	@knowledgepulse/mcp	Model Context Protocol サーバー --- 6つの MCP ツール、デュアルモードレジストリブリッジ
CLI	@knowledgepulse/cli	コマンドラインインターフェース --- 検索、インストール、バリデーション、コントリビュート、認証、セキュリティ

SDK

SDK（packages/sdk）は他のすべてのコンポーネントが依存するコアライブラリです。Zod スキーマから生成された TypeScript 型、ナレッジユニットのキャプチャと取得のための関数、関連性スコアリング、SKILL.md のパースとサニタイズ、スキーマバージョンアップグレードのためのチェーン可能なマイグレーション関数を提供します。

レジストリ

レジストリ（registry/）は Hono ベースの REST API サーバーで、ナレッジユニットの中央ストアとして機能します。Bearer トークンによる認証、ティアベースのレート制限を処理し、ナレッジユニットの CRUD エンドポイントを公開します。

MCP サーバー

MCP サーバー（packages/mcp-server）は Model Context Protocol を通じて KnowledgePulse の機能を公開し、MCP 互換のあらゆる AI クライアントからアクセス可能にします。デュアルモードで動作します：

• スタンドアロンモード -- 独自のインメモリストアで動作します。
• プロキシモード -- KP_REGISTRY_URL 環境変数を介してリモートレジストリにブリッジします。

CLI

CLI（packages/cli）は、開発者やエージェントがプロトコルとやり取りするためのコマンドラインインターフェースを提供します。ナレッジの検索、SKILL.md ファイルのインストール、スキーマのバリデーション、ナレッジユニットのコントリビュート、認証の管理を行えます。

モノレポ構造

knowledgepulse/
├── packages/
│   ├── sdk/            # @knowledgepulse/sdk — 型、キャプチャ、取得、スコアリング、マイグレーション
│   ├── mcp-server/     # @knowledgepulse/mcp — 6つの MCP ツール、デュアルモードレジストリブリッジ
│   ├── cli/            # @knowledgepulse/cli — 検索、インストール、バリデーション、コントリビュート、認証
│   └── sop-studio/     # プレースホルダー（フェーズ 3）
├── registry/           # Hono REST API サーバー（インメモリストア、認証、レート制限）
├── specs/              # codegen.ts、validate-consistency.ts、skill-md-extension.md
├── examples/           # basic-sdk-usage、mcp-client-example、langraph-integration
└── website/            # Docusaurus ドキュメントサイト

ストレージモデル

フェーズ 1 では、非同期 Promise<T> インターフェースの背後にインメモリ Map<> ストアを使用しています。この設計は意図的なもので、非同期インターフェース境界によりストレージバックエンドを永続化データベース（PostgreSQL、SQLite など）にコンシューマーコードの変更なしで置き換えられます。ベクトルキャッシュは HNSW ではなくブルートフォースリニアスキャンを使用しており、こちらもインターフェースを通じて交換可能です。

技術スタック

テクノロジー	用途
Bun	JavaScript/TypeScript ランタイムおよびパッケージマネージャー
Hono	レジストリと MCP サーバー用の軽量 HTTP フレームワーク
Zod v3	スキーマ定義とバリデーション（コード生成に zod-to-json-schema を使用）
tsup	SDK のビルドツール（ESM + CJS + TypeScript 宣言）
Biome	リンターおよびフォーマッター
@modelcontextprotocol/sdk	MCP プロトコル実装
bun test	テストランナー（15ファイル、319テスト）