Context Atlas

Context Atlas は、ソフトウェアプロジェクトのためのローカルファーストで、エビデンスに基づいたメモリレイヤーです。Git 履歴、リポジトリ構造、マニフェスト、プロジェクトドキュメント、および人間によるレビュー済みの説明を、次のものに変換します:

• 新規参入者に優しいプロジェクト概要;

• 探索可能なコンポーネントと依存関係のマップ;

• プロジェクトがどのように変化したかの時系列記録;

• コンポーネントと決定のエビデンスにリンクされた説明; および

• コーディングエージェントが変更を加える前に読むことができる、境界のあるコンテキストパック;

• 人間の同意を得て明示的に選択されたドキュメントと会話の要約; および

• 信頼されたホスト向けの、バージョン管理された拡張機能とプロバイダー出口の安全契約。

このリポジトリには、動作する実験的な 0.1.0 アルファリリース候補のソースが含まれています: Node.js CLI、ローカル Web ダッシュボード、TypeScript ライブラリ、stdio MCP サーバー、および Codex プラグインバンドル。生成されたプラグインランタイム、ローカル動作ゲート、最新のローカルパッケージ候補、および以下で説明するクリーンなインストール済みパッケージのスモークテストは、現在のワークツリーで検証されています。ホストされたワークフローと GitHub リリースは検証されていません。0.1.0 は未公開のままであり、より広範な本番計画は docs/ で明示的に追跡されています。

存在理由

長いコーディングセッションは、流れを見失います。チャット履歴は圧縮され、エージェントは変更され、文書化されていない決定は消え、生成された要約は静かに古くなったり間違ったりする可能性があります。Context Atlas は、観察された事実、文書化された主張、推論、提案、および人間が承認した説明の間の厳密な境界を維持しながら、単一のチャットの外に永続的な高レベルのマップを保持します。

flowchart LR
  A["Git history"] --> I["Evidence-first ingestion"]
  B["Repository structure"] --> I
  C["README, ADRs, manifests"] --> I
  I --> D["Local SQLite knowledge graph"]
  I --> L["Hash-chained audit ledger"]
  D --> O["Overview and orientation"]
  D --> M["Mind map and timeline"]
  D --> P["Task-bounded context pack"]
  O --> H["Developer"]
  M --> H
  P --> X["Coding agent through MCP"]
  R["Human review"] --> D

Related MCP server: koragraph

クイックスタート

要件: Git と Node.js 24 以降。

git clone https://github.com/moelomda/context-atlas.git
cd context-atlas
npm.cmd ci
npm.cmd run build
node dist/cli.js init C:\path\to\your\git-repository --name "My Project"
node dist/cli.js serve --repo C:\path\to\your\git-repository

http://127.0.0.1:4242 を開きます。サーバーは、認証されていない非ループバックホストを意図的に拒否します。

最初のハンドオフには、次のシーケンスを使用します:

node dist/cli.js overview --repo C:\path\to\repo
node dist/cli.js health --repo C:\path\to\repo
node dist/cli.js timeline --repo C:\path\to\repo
node dist/cli.js pack "add subscription retry handling" --json --repo C:\path\to\repo
node dist/cli.js proposals pending --repo C:\path\to\repo

生成されたナラティブ提案は、自動的に真実として受け入れられません。それらのエビデンスを確認し、特定の提案を明示的に承認または拒否します:

node dist/cli.js approve <proposal-id> --actor human:alice --note "Reviewed against ADR-0001 and current code" --repo C:\path\to\repo
node dist/cli.js reject <proposal-id> --actor human:alice --note "Superseded by the current architecture" --repo C:\path\to\repo

ループバックダッシュボードは、エビデンスの準備状況、競合のグループ化、レビュー履歴、および明示的な承認/拒否の確認を備えた、人間による提案レビューワークスペースも提供します。ブラウザの変更には、完全に同一オリジンのリクエストとインメモリセッショントークンが必要です。これらはエージェント機能ではありません。

1 つの外部テキスト/Markdown ドキュメントまたは 1 つの会話要約は、ダッシュボードの Add source ワークフローまたは CLI を通じて追加できます。プレビューは読み取り専用で、正確なバイト、オリジン、目的、権限、機密性、および帰属する人間のアクターをバインドします。適用には、新しいプランとリテラル IMPORT が必要です。機密性の高いインポートは、本文を省略しながら、メタデータと来歴を保持します。インポートされたマテリアルは信頼されていないエビデンスのままであり、クレームを自動的に承認したり、概要を書き換えたりすることはありません。

$plan = node dist/cli.js source-import-preview C:\path\to\notes.md --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo | ConvertFrom-Json
node dist/cli.js source-import C:\path\to\notes.md --plan $plan.planId --confirm IMPORT --type document --origin "Architecture workshop" --authority documented --sensitivity normal --purpose "Preserve retry decisions" --actor human:alice --repo C:\path\to\repo

意味のあるコミットの後に sync を実行します。ヘルスレポートは、リポジトリが最後にインデックスされたコミットを超えて移動したときに明確に警告します。

新しいリポジトリは、8,000 トークンのコンテキストパック予算で開始されます。既存のリポジトリは、オペレーターが変更するまで、.context-atlas/config.json に既に保存されている値(レガシーの 4,000 トークンのデフォルトを含む)を保持します。pack --budget N は、1 つのリクエストに対してリポジトリのデフォルトを引き続き上書きします。

抽出に影響する構成または .atlasignore ポリシーの変更後も、同期が必要です。Context Atlas は、コンテンツが同期およびレビューされたときにガイダンス依存関係の透かしを記録します。その境界を変更すると、以前にレビューされたクレームは未確定になります。透かし追跡の前に作成されたクレームは、フェイルクローズされ、同期と新しい人間のレビューが必要であり、静かに祖父条項として扱われることはありません。

Codex プラグインと MCP

プラグインソースバンドルは plugin/context-atlas/ にあります。パッケージ化またはインストールする前に、このプロジェクトをビルドして検証してください: ビルドは、自己完結型の MCP ランタイムを plugin/context-atlas/runtime/server.mjs に埋め込みます。したがって、検証されたコピーされたマーケットプレイスインストールは、このソースツリーに依存しません。ラッパーは、ローカルソース開発用に dist/mcp/server.js フォールバックを保持します。

MCP サーバーは、13 の読み取り専用ツールを公開します:

• 現在のナビゲーション: atlas_overview、atlas_context_pack、atlas_explain、atlas_history、atlas_health、atlas_search、および atlas_evidence。

• 時間的知識: atlas_assertions、atlas_assertion_history、および atlas_assertion_evolution。

• 保存済みパックの検査: atlas_pack_history、atlas_pack_snapshot、および atlas_pack_diff。

• 同期、提案の作成、提案の決定、パックの保存/更新、および保持の適用は、MCP を通じて意図的に利用できません。提案の決定には、CLI または保護されたループバックダッシュボードを通じて明示的な人間が必要です。他の変更は、人間が操作する CLI ワークフローのままです。

• atlas_context_pack は、既存の人間が作成した CLI オーバーライドの ID を消費できます。オーバーライドを作成または変更することはできず、オーバーライドされた重大な調査結果は、構造化された結果とそのテキストの処分の両方で目立つままです。

すべてのツールは、絶対的な repo パスを受け入れます。直接の MCP クライアントは、node <absolute-project-path>/dist/mcp/server.js を実行し、CONTEXT_ATLAS_REPO を初期化されたリポジトリに設定することもできます。

バージョン管理された HTTP および MCP 読み取りは、応答を組み立てる前後に、ナレッジデータベース、ライブ Git/ワークツリー、台帳、同期、およびガイダンスポリシーの境界を比較します。同時変更は、古いデータに新しい透かしを添付する代わりに、再試行可能なスナップショットエラーで拒否されます。保存済みパックの履歴と差分ツールは、短いテキストポインターを持つ 1 つのコンパクトな構造化ペイロードを返し、すべての MCP ツール結果には 2,500,000 文字のフェイルクローズ上限があります。

信頼されたインプロセス拡張機能は、公開された context-atlas/extensions エクスポートを使用できます。その 6 つのバージョン管理されたポートは、抽出器、分析器、プロバイダー、リダクター、エクスポーター、およびバリデーターをカバーします。マニフェストと入力/出力はスキーマチェックされ、安全でない出力はアトミックに失敗し、インストールされた拡張コードは明示的に信頼された実行可能コードとして扱われます。コアライブラリは、プロバイダー許可リスト、リダクション/ブロックポリシー、トークン/コスト予算、資格情報の間接化、永続的な試行レシート、失効、および自動再試行なしを備えた、正確なバイトの出口プレビュー/同意/承認ゲートウェイも公開します。このアルファでは、CLI、Web ダッシュボード、または MCP サーバーによってリモートプロバイダーは有効になっていません。

コンテキストパック契約

コンテキストパックスキーマ v2 は、常に同じ 15 の必須セクションを表します: アイデンティティ/権限、警告、目標、コンポーネント、インターフェース、規約、決定、制約、リスク、最近の変更、テスト、競合、未知、エビデンス、および除外。セクションは明示的に present、none、または unknown にできます。空の知識領域は黙って省略されません。

選択はアイテム全体です。境界のあるセレクターユニバースに受け入れられたすべての重要なエンティティ、アクティブな関係、主張、またはイベントは、そのエビデンスクロージャとともに完全にレンダリングされるか、正確な理由を持つ重要な除外としてリストされます。周囲の非重要なレコードは、集計数として報告されます。関係は、現在の使用状況、理由、権限、信頼性、およびエビデンス検証メタデータを保持し、未検証のトポロジは確定したガイダンスとして提示されません。ハード予算は、Markdown 本文だけでなく、コンパクトな JSON オブジェクト全体に適用され、MCP アダプターはツール結果エンベロープ用のスペースも予約します。現在の見積もりは、開示された文字数を 4 で割った近似値であり、プロバイダートークナイザーではありません。500 トークンという低いリクエストも入力として受け入れられますが、必須のエンベロープが収まらない場合、生成は計算された最小値で拒否されます。

pack-save は、検証されたパックを不変のコンテンツアドレス指定スナップショットとして保存します。pack-history、pack-diff、および pack-refresh は、境界のある履歴、構造比較、および現在の状態に対する再構築ワークフローを提供します。スナップショットは .context-atlas/packs/ の下に保存されます。ストアは、履歴を黙って削除する代わりに、257 番目の個別のスナップショットを拒否します。更新は、元のタスクとトークン予算を保持し、以前の安全オーバーライドを継承せず、リポジトリ ID または不安定なリポジトリ/ポリシーの変更を拒否します。履歴読み取りは、要求された表示制限を適用する前に保持されたセットを検証するため、256 アイテムの境界は安全上限であり、大規模な履歴パフォーマンスの資格ではありません。

現在のガイダンスが提示またはパックされる前に、ローカルファイル、到達可能な Git コミット、リポジトリスナップショット、およびコンポーネントスナップショットのロケーターは、正規パス、ポリシー、および SHA-256 ダイジェストに対して再検証されます。不明な外部ロケーターの種類は、未検証として報告されます。検証済みのエビデンスにアップグレードされません。概要、グラフ、検索、説明、主張、API、MCP、パック、およびダッシュボードのパスは、現在の使用状況/理由/権限/エビデンスメタデータを保持するか、未確定のレビュー済み散文を保留します。

記録されるもの

Context Atlas は、ローカル状態を <repository>/.context-atlas/ の下に保存します:

• config.json: スキャンと鮮度ポリシー;

• atlas.db: エビデンス、エンティティ、バージョン、関係、イベント、および提案;

• ledger.ndjson: 記録されたアクションをカバーする追加専用のハッシュチェーン;

• backups/: 検証された SQLite バックアップとポータブルなナレッジスナップショット;

• exports/: チェックサム付きのポータブル JSON エクスポート; および

• packs/: 無視される不変のコンテキストパックスナップショット。ハード 256 アイテム容量。

完全な生の差分と完全なファイル本文は保持されません。Context Atlas は、ナビゲーションに必要な境界のあるサニタイズされたドキュメント抽出とリポジトリメタデータを保持します。シークレットのような値と、.env、資格情報、秘密鍵、証明書などの機密パスは保留されます。リポジトリ固有の除外を .atlasignore に追加します。その順序付けられた glob ルールは ! 否定をサポートします。

初期化により、.context-atlas/.gitignore が作成され、データベース、エクスポート、バックアップ、パック、およびアップグレード前の完全な移行スナップショットが誤ってコミットされないようにします。レガシーストレージが移行スナップショットまたはパックを書き込む前に、Context Atlas は、オペレーターのルールを置き換えることなく、欠落している派生データルールを安全に追加します。共有されたレビュー可能なプロジェクトメモリが必要な場合は、.context-atlas/config.json、.context-atlas/ledger.ndjson、および .context-atlas/.gitignore をコミットします。無視されたデータベースマテリアルはローカルに保持するか、検証されたバックアップワークフローを通じてのみ転送します。

安全モデル

Context Atlasはナビゲーション支援であり、ソフトウェアが正しいことの証明ではありません。現在のコードとテストは、ランタイムの動作に対して引き続き権威を持ちます。コンテキストパックがブロックされている場合は、リストされている重大なヘルスチェックを解決してください。例外的なpack-overrideワークフローでは、明示的な人間のアクター、根拠、短い有効期限が必要であり、結果のパックは視覚的にマークされたままです。

コマンド

完全なコマンドリストについては、node dist/cli.js helpを実行してください。主なワークフローは次のとおりです。

• 探索: overview、map、timeline、search、explain、evidence、assertions、assertion-history、assertion-evolution。

• エージェントの準備: pack <task> [--budget N] [--json]、pack-save <task>、pack-history、pack-diff <left> <right>、pack-refresh <snapshot>。

• メモリの維持: sync、proposals、propose、approve、reject。approve/rejectは、保護されたループバックダッシュボードで人間にも利用可能です。

• 選択した証拠の追加: source-import-preview <file> の後に source-import <file> --plan <id> --confirm IMPORT を実行します。ダッシュボードは、ブラウザで選択した1つのファイルまたは貼り付けた要約に対して、同じプレビュー/同意の境界を提供します。

• 監査: health、validate、recover-ledger、privacy、retention-preview、確認済みのretention-apply、およびretention-history（validateは重大な発見でコード2で終了します）。保持削除は対象のエクスポート/バックアップファイルに限定され、正確なプレビュープランID、human:アクター、根拠、および--confirm APPLYが必要です。

• 移植性: export、verify-export、import-preview、オールオアナッシングのimport、rebuild-verify、backup、verify-backup、restore --confirm RESTORE。

• 可視化: ループバック上のserve。

開発と検証

npm.cmd run build
npm.cmd test

現在のローカルワークツリーは、通常の動作スイート（122/122テスト、693,394 ms）とカバレッジ実行（122/122テスト、901,735 ms、行95.40%、関数96.07%、ブランチ76.81%）に合格しています。厳格なソース/テストTypeScriptコンパイル、JavaScript構文、JSON/YAML解析、リリースID検証、および報告された脆弱性がゼロのオンラインnpm auditも合格しました。これらはローカルWindowsの結果であり、クロスプラットフォームまたはホストされた結果ではありません。

最終的なローカルパフォーマンスパスでは、概要コントラクトから重複するリポジトリ/証拠作業も削除されました。9エンティティのフィクスチャでは、実際の/api/v1/overviewリクエストが約8〜12秒と58のGitサブプロセスから、1.48〜1.61秒と12のGitサブプロセスに減少し、前後のスナップショットチェックは維持されました。これは、大規模リポジトリのレイテンシ認定ではなく、焦点を絞った小規模フィクスチャの回帰結果です。

プラグインはこのソースから再生成されました。ソースとバンドルされたランタイムはそれぞれ同じ13の読み取り専用ツールを公開し、プラグインとスキルのバリデータは合格し、独立したランタイムとサードパーティ通知の再生成は決定論的なハッシュを生成し、実際の再生成されたランタイムはMCP回帰（1/1）に合格しました。固定されたActionlint 1.7.12を使用したワークフロー検査は、4つのワークフローすべてに合格しました。17のワークフローuses参照はすべてフルSHAで固定されており、解決および検証された7つの一意のコミットをカバーしています。これらのチェックは、GitHubホストのCI、CodeQL、依存関係レビュー、SBOM、または来歴ジョブの代わりにはなりません。

2026-08-23にレンダリングされたアプリ内ブラウザQAは、デスクトップビューポートに加えて390×844および320×720レイアウトをカバーし、概要と完全な外部ソースのプレビュー/同意フローを含みました。確認がプレビューまで非表示のままであることを検証し、ローカルインポートを完了し、レスポンシブリフローと最小幅のオーバーフローをチェックし、コンソールの警告やエラーがゼロで終了しました。この実行では、早期の確認表示と320pxの水平オーバーフローを発見して修正しました。更新されたWebスイートは6/6に合格しました。以前のナビゲーション、マップ、タイムライン、ヘルス、レビュー、検索、ブリーフィング、キーボード、Escape、フォーカスリターンのカバレッジはソーステストコントラクトの一部ですが、これはスクリーンリーダーの結果、WCAG準拠の主張、クロスブラウザマトリックス、または別のオペレーティングシステムでの証明ではありません。

機能とレンダリングされたUIの修正後、124ファイルのローカルパッケージ候補が再構築され、インベントリ、禁止ファイル、サイズ、SHA-1、SHA-512の検証に合格しました。クリーンな一時プロジェクトがそのアーカイブと依存関係をインストールし、選択した外部ソースをインポートし、ダッシュボード/APIと保護されたレビューAPIをロードし、公開拡張サブパスをインポートし、プライバシー、オーバーライド、MCPスモークに合格しました。スモークは完全な13ツールの読み取り専用インベントリを検証し、代表的なナビゲーション、pack-history、evidence、オーバーライド読み取りを実行しました。ドキュメントの編集により新しいアーカイブ候補が作成されるため、最終ハンドオフには最新のドキュメント後の再認定のみが記録されます。正確なアーカイブダイジェストとサイズは、この自己参照ドキュメントではなく、ローカルパックレポートに残ります。これはローカルアーティファクトの証拠であり、リモートリポジトリ、ホストされたチェック、署名済み/SBOMで証明されたアーティファクト、または公開されたプレリリースではありません。

ビルドはプロジェクトライセンスをプラグインにコピーし、自己完結型ランタイムに実際にバンドルされている依存関係からサードパーティ通知を生成し、リリースワークフローはランタイム/ライセンス/通知のドリフトを拒否するように定義されています。ローカルのランタイム/通知ドリフトとリリースIDチェックは、候補タグ入力、パッケージ、ロックファイル、プラグインマニフェスト、MCPアドバタイズバージョン、日付付きチェンジログ間のパリティを含めて合格します。最新のローカルパッケージスモークも合格しますが、これらの制御はホストされた実行や公開を証明するものではありません。実際のGitHubプレリリース用に選択された不変のコミットでも、同じゲートに合格する必要があります。

実装は現在、Nodeの組み込みSQLite APIを使用していますが、Node 24はまだ実験的とラベル付けしています。このアルファは、単一のローカルリポジトリと単一のライター向けに設計されています。ホストされたコラボレーション、IDEネイティブパネル、増分ファイルシステムウォッチ、プロバイダーストア/UI統合、よりリッチな言語セマンティック分析、大規模リポジトリのパフォーマンス作業はロードマップ項目のままです。保存されたパックのプライベートパス検出は、現在のリポジトリルートと認識可能なホストファイルシステムルートの広いセットをブロックしますが、フリーテキストはすべてのカスタムPOSIX絶対パスをAPIルートと完全に区別することはできません。保持は、記述子とIDチェックでパスレースを狭めますが、悪意のある同一ユーザーのディレクトリコンポーネントスワップに対するレースフリーの削除を主張するものではありません。

詳細な計画と証拠

• docs/PRODUCT_PLAN.md — ユーザー、ジョブ、スコープ、機能要件および非機能要件。

• docs/ARCHITECTURE.md — 時系列データモデル、信頼境界、取り込み、検索、およびデプロイ設計。

• docs/RISK_REGISTER.md — 障害モード、制御、テスト、および残留リスク。

• docs/IMPLEMENTATION_ROADMAP.md — プロトタイプから本番強化までのマイルストーン。

• docs/REQUIREMENTS_TRACEABILITY.md — 要件から制御・テストへのトレーサビリティ台帳。

• docs/IMPLEMENTATION_STATUS.md — このアルファ版が実装している内容と、計画済みの内容に関する正直な証拠。

コントリビューション、サポート、およびリリース

• 変更を提案または実装する前に、CONTRIBUTING.md をお読みください。信頼境界の不変条件と検証基準が文書化されています。

• 再現可能なバグ、製品リクエスト、およびドキュメントの問題については、構造化された GitHub issue フォームを使用してください。

• 脆弱性は SECURITY.md を使用して非公開で報告してください。公開 issue に認証情報、プロプライエタリなソース、または実際の .context-atlas/ ディレクトリを決して置かないでください。

• プロジェクトへの参加は CODE_OF_CONDUCT.md に従います。

• リリースの変更内容とメンテナー手順は、CHANGELOG.md および docs/RELEASING.md に記載されています。

ライセンス

MIT