GrayMatter

GrayMatter

検索範囲と貢献の証拠では、完全な一覧を見つける方法、再利用と書き込みの明示的な検証の違い、節約効果を捏造せずにレシートから判断、成果物、テストまでを報告する方法について説明しています。

GrayMatter Liteは、個人または1つのワークスペース向けの実用的なオープンソースのメモリ製品です。ローカル環境または管理下のインフラストラクチャで動作し、初回起動時から、サインイン、永続的なメモリの作成、MCP経由での検索、ポータブルなKnowledgePacksのインポートまたはエクスポート、ローカルまたはホスト型エージェントプロファイルへの接続という、便利な製品の一連の機能を利用できます。

期間限定の試用版でも、中身のないデモでもありません。Liteの範囲は、このリポジトリにある正規のThorAPI YAML（openapi/bundles）、./vaixビルダー、Spring/H2バックエンド、組み込みダッシュボード、MCP サーバー、スターターKnowledgePack、Docker定義、テスト、公開ドキュメントです。

ホスト型またはローカルのメモリを選択する

セットアップページから始めてください。 GrayMatter Cloudを標準の選択肢としておすすめします。valkyrlabs.comアカウントとネイティブプラグインのサインインを使って、ホスト型メモリに接続してください。テナントとアカウントの権限は、ホスト型サービスによって適用されます。

ローカルのGrayMatter Liteにはvalkyrlabs.comへのサインアップは必要ありません。ValorIDEのウェルカム画面でConnect Local GrayMatter Liteをクリックする（またはコマンドパレットからこのコマンドを実行する）と、Liteが起動します。求められた場合は、このソースフォルダーを選択してください。ValorIDEがLiteを起動し、ローカルアカウントとMCPメモリツールを検証します。Ollama、LM Studio、または独自のモデルプロバイダーは別途選択してください。初回のソースビルドでは、ツールチェーンや依存関係のダウンロードが必要になる場合があります。インストール済みのローカルメモリはオフラインで動作します。

ほかのクライアントでは、以下のソースコマンドを使用してください。ホスト型ワークフロー、eコマース、アプリケーションホスティングには、認証済みのValkyrAIサービスを使用します。

1つのコマンドでローカルのLiteをインストールする

macOSまたはLinuxの場合：

git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
./vaix setup

./vaix setupでは、可能な場合、マシンにすでにインストールされているJava 17以降、Maven、Node 20以降を使用します。不足しているツールチェーンは、.vaix/runtime内に非公開でダウンロードされます。システム全体には何もインストールされません。このコマンドは、公開Maven依存関係を使ってスタンドアロンのLiteをビルドし、ローカルプロファイルを1つ作成して、サービスを起動し、接続を検証します。ホスト型アカウントや非公開のThorAPIジェネレーターは必要ありません。スキーマの生成は、引き続き./vaix generateで明示的に実行できます。セットアップによって次のサービスが起動します。

• ダッシュボードとサインイン：http://localhost:8787
• HTTP MCP：http://localhost:3333/mcp
• 永続的なH2データ：.graymatter-lite/data

生成されたローカル認証情報は、必要な場合にのみ取得してください。

./vaix credentials
./vaix doctor

その他のソースコマンド：

./vaix generate     # compose canonical YAML and generate Spring + TypeScript
./vaix generate --extension ./application-domain.yaml
./vaix regenerate   # generate, clean-build, and run the acceptance suite
./vaix build        # build the Spring/H2 backend
./vaix test         # backend, bootstrap, docs, release parity, and MCP contracts
./vaix run          # foreground backend
./vaix up           # background backend + HTTP MCP
./vaix stop

正規のファイル、生成コードと手書きコードの境界、拡張コントラクト、失敗時のルールについては、スキーマの再生成を参照してください。

Docker

Dockerの手順では、コミット済みのソースからビルドします。クローズドなGrayMatterバックエンドのビルド済みイメージには依存しません。

export GRAYMATTER_ADMIN_PASSWORD='choose-a-strong-local-password'
docker compose -f deploy/docker-compose.lite.yml up --build

同じダッシュボードをポート8787で、MCPを3333で利用できます。H2データはgraymatter-lite-dataボリュームに保持されます。

含まれる機能

• Basic 認証でサインインでき、切り替え可能なローカルプロフィールを備えたローカルユーザー／ワークスペース。
• 永続的な MemoryEntry の作成、読み取り、ハイブリッド検索、H2 への永続化。
• オプションでループバック接続の Ollama 埋め込みを利用できるローカルベクトルインデックスに加え、上限付き Bifrost コンテキスト、引用ポインター、ソースの再確認、取得レシート。
• 既存の Valkyr ダッシュボード、メモリーワークベンチ、テレメトリー、SWARM ステータス。
• Codex、OpenClaw、Claude、ローカルモデルホスト、その他の MCP 互換クライアント向けに同梱された stdio／HTTP MCP サーバー。
• 署名済み .gmkp KnowledgePack のインポートと、メモリー全体の KnowledgePack エクスポート。
• GrayMatter、Valkyr SWARM、ValkyrAI、ThorAPI のセットアップ／製品／サポートに関するナレッジを含む、精査済みのスターター KnowledgePack。ローカル H2 に冪等に挿入されます。
• 名前付きのローカルおよびホスト型プロフィールと、明示的な読み取り専用のブレンド検索。
• ./vaix によるソースのビルドと、Docker Compose によるコンテナのビルド。
• AGPL-3.0 のソース、公開ドキュメント、Issues／Discussions によるサポート、非公開のセキュリティ報告経路。

レガシー環境およびファイルシステムの識別子は、後方互換性のため LIGHT を保持しています。公開製品名は GrayMatter Lite です。

プロフィールとブレンドメモリー

./vaix setup は、すでに有効なホスト型の ID を変更せずに graymatter-lite-local を登録します。プロフィールはルーティングメタデータを profiles.json に保存します。ホスト型セッションはプラットフォームの認証情報保管庫に保持され、ローカル Basic 認証パスワードはリポジトリ外のモード 0600 のシークレットファイルに保存されます。

scripts/gm-profile add-local graymatter-lite-local \
  --api-base http://localhost:8787/v1 --password-stdin
scripts/gm-profile add cloud --from-current
scripts/gm-profile use graymatter-lite-local
scripts/gm-profile blend graymatter-lite-local cloud
scripts/gm-query "release rules"

ブレンド読み取りは各プロフィールで個別に実行され、プロフィールとアカウントフィンガープリントの来歴情報が保持されます。単一のプロフィールが選択されるまで、すべての書き込みはフェイルクローズします。MCP はメモリーのクエリ／読み取り／ヘルスツールにも同じ読み取り専用のフェデレーションを提供します。変更を伴うツールや未対応のツールは、プロフィールが一つ選択されるまで読み取り専用の復旧結果を返します。永続的なプロフィール選択を変更した後は、MCP プロセスを再起動してください。

ローカルモデル

GrayMatter はモデルに依存しません。Ollama、LM Studio、llama.cpp、その他のローカルモデルホストは MCP 経由で接続でき、モデルプロセスは H2 メモリーおよび認可境界から分離されたままです。stdio と HTTP の例については、ローカルモデルを参照してください。ローカルの Workflow 実行では、2 つの MCP 境界を使用します。Valkyr SWARM は登録と署名済み Workflow の調整を担い、GrayMatter はメモリー、コンテキスト、永続的な証跡を担います。モデル専用の LM Studio／Ollama ノードは signed-workflow-only の推論ワーカーであり、汎用コマンドランナーではありません。

インポート、エクスポート、スターターナレッジ

ダッシュボードまたは API を使用してください。

curl -u "admin:$GRAYMATTER_ADMIN_PASSWORD" \
  -o graymatter-lite-memory.gmkp \
  http://localhost:8787/v1/knowledge-packs/export

scripts/gm-knowledge-pack-import ./graymatter-lite-memory.gmkp

スターターパックのソースは templates/graymatter-light-bootstrap/local-server/src/main/resources/knowledgepacks/graymatter-lite-starter.json にコミットされています。起動時に、通常の KnowledgePack で使用されるものと同じ自己完結型の整合性契約で署名し、本番用インポーターを通じてインポートして、そのレコードをローカル H2 データベースに保存します。繰り返し起動しても冪等です。

Valkyr SWARM

スターター KnowledgePack では、サポート対象の SWARM 経路について説明しています。このマシンを登録し、ハートビートを送信し、認証済み ValkyrAI マザーシップから正確なターゲットを指定した制御コマンドを受信し、永続的なレシートを返すようにするには、オープンソースのピア製品をインストールしてください。

git clone https://github.com/ValkyrLabs/ValkyrSWARM.git
codex plugin marketplace add "$PWD/ValkyrSWARM"
codex plugin add valkyr-swarm@valkyr-swarm

SWARM は、外部への送信、本番環境へのデプロイ、マージ、監督下でのサービス再起動に関する標準的な人間の承認ゲートを維持します。GrayMatter Lite は別のコマンドバスを独自に設けず、エージェントが自身を承認することも許可しません。

ドキュメントとコミュニティ

• GrayMatter Lite ガイド
• ローカルモデルとの互換性
• KnowledgePacks
• MCP サーバー
• アーキテクチャ
• コントリビューション
• コミュニティサポート
• セキュリティポリシー

再現可能な不具合には GitHub Issues を、サポート、アイデア、KnowledgePacks、インテグレーションについては GitHub Discussions をご利用ください。脆弱性は SECURITY.md の説明に従って非公開で報告してください。

---

GrayMatter Platform：ビジネス全体を支える AI の頭脳

Valkyr GrayMatter™ は、アプリケーション、ドキュメント、ワークフロー、会話、組織に蓄積された知識を、常に更新され、検索可能なインテリジェンスレイヤーへと変換します。

単なるベクトルデータベースでも、チャットの記憶機能でもありません。GrayMatter は、永続的なメモリ、リアルタイム検索、構造化されたビジネスデータ、関係性を踏まえた推論を、エージェント、人、アプリ、API が一緒に利用できる、安全な単一のシステムに統合します。

コンテキストを実際に記憶するメモリシステム

GrayMatter は、永続的な意思決定、好み、タスク、調査、手順、会話、運用知識を、使い捨てのチャット履歴ではなく、構造化され、出所を特定できるレコードとして保存します。各メモリには、ソース、範囲、タグ、関係性、タイムスタンプ、所有者、来歴を付与できるため、個人の好みと会社のポリシー、現在のタスクと過去のコンテキスト、ソースドキュメントと AI が生成した要約を区別できます。

Codex、OpenClaw、SageChat、ワークフロー、接続されたツールを横断するエージェント型メモリに対応しており、追跡できないプロンプトにすべての情報を詰め込むことなく、許可されたすべてのエージェントがビジネスへの共通理解を持てるようにします。

ハイブリッド検索：キーワード、ベクトル、グラフ、構造化データ

GrayMatter の検索機能は、簡単な質問にも難しい質問にも回答できるように設計されています。

• 名前、ID、タグ、コマンド、製品、レコードの完全一致検索
• ドキュメント、タイトル、フィールド、解析済みアップロードを横断する全文検索
• 概念、意図、意味を対象とするセマンティック検索／ベクトル検索
• ThorAPI のエンティティとナレッジグラフのリンクを横断する、関係性を踏まえた検索
• 種類、日付、カテゴリ、タグ、テナント、ワークフロー、プロジェクトなどによる構造化フィルタリング
• 引用、根拠、品質シグナル、回答ポリシーのガイダンスを含む検索結果の記録

これにより、ユーザーは同じインテリジェンス基盤を通じて、公開ウェブサイト、認証済みワークスペース、SageChat を検索できます。それぞれの画面には、許可された情報だけが表示されます。

PostgreSQL ネイティブのベクトルインテリジェンス

GrayMatter は、永続的な運用基盤に PostgreSQL を、高性能なセマンティック検索の高速化に pgvector を使用します。

SemanticIndexEntry は移植可能な正規レコードとして維持される一方、テナントごとの pgvector 投影により高速な近傍検索を実現します。このプラットフォームは、本番環境向けの OpenAI 埋め込みや、オフライン／開発環境向けの決定論的なローカルフォールバック埋め込みなど、設定可能な埋め込みプロバイダーに対応しています。また、モデル、プロバイダー、次元数、インデックスの健全性、古くなった行、再インデックスのガイダンス、縮退状態も追跡します。

これにより、別個のプロプライエタリなグラフやベクトルのサイロを導入することなく、通常のリレーショナルデータから本番環境対応のセマンティック検索へ、実用的な道筋を構築できます。

ThorAPI を基盤に構築された実際のナレッジグラフ

GrayMatter は、知識が単なる文書の山ではなく、ネットワークであることを理解しています。

ThorAPI のエンティティと OpenAPI で定義されたリレーションシップは、書き込みの成功後にインデックス化でき、ワークフロー、アプリケーション、顧客、タスク、ファイル、手順、エージェント、目標、メモなどにわたる安全なセマンティックエビデンスを生成します。GraphLink レコードは、「サポートする」「ブロックする」「参照する」「派生する」「関連する」などの重要なリレーションシップを明示します。

これにより、次のようなリレーションシップを考慮した検索が可能になります。

• 「この顧客の問題に関連するものは何ですか？」
• 「このインテグレーションに依存するワークフローはどれですか？」
• 「この判断を裏付けるエビデンスは何ですか？」
• 「この結果を説明する文書、メモリ、タスクはどれですか？」

このシステムは、ThorAPI の認可をインデックスやグラフが迂回できないようにしながら、範囲を限定したグラフ探索、引用、将来のグラフ分析に対応するよう設計されています。

SageChat とドキュメントインテリジェンス

SageChat は、アップロードされたファイルや解析済みのドキュメントを、ストレージに眠らせることなく検索可能なエビデンスに変換できます。

ファイルは、出典ファイル、パーサーの出力、チャンク、ページまたはオフセット、ソースハッシュ、抽出品質、関連する業務オブジェクトとのリレーションシップなど、範囲が限定され、出所情報が豊富なセマンティック情報に処理されます。GrayMatter は、そのエビデンスを引用と説明可能性を伴って SageChat に提示できます。これにより、ユーザーは回答だけでなく、その出所も理解できます。

プラグイン、スキル、MCP：あらゆる場所にインテリジェンスを

GrayMatter は、Codex/OpenClaw 形式のエージェント向けに、インストール可能なプラグインとスキルのシステムとして提供されます。プラットフォームのセキュアな保管庫を利用した認証、エージェント登録、スキーマの把握、永続メモリの読み書き、グラフへのアクセス、検索レシート、運用状態のヘルスチェックに対応しています。

MCP 機能により、メモリへの書き込み、メモリの検索、メモリの読み取り、レシート付き検索、グラフの調査、スキーマの検出、認可されたエンティティへのアクセスなど、型付きツールを通じて、互換性のある AI クライアントから GrayMatter を利用できます。

プラグインとスキルにより、各エージェントが同じ永続的な組織コンテキストを利用できます。MCP により、そのコンテキストを外部の AI 環境やワークフローからも活用できます。

実際の AI 運用を想定したクレジット

GrayMatter には、より高度なメモリと AI 操作のためのクレジットおよび利用権モデルが含まれています。これにより、明確な運用管理を維持しながら、セマンティック検索、埋め込み、再インデックス化、高度なインテリジェンス機能を持続的に利用できます。

このプラットフォームは、一般公開向けのエクスペリエンスと非公開の運用ツールを区別し、商業情報やアカウント管理の詳細が一般公開向けの AI インターフェースに漏えいしないようにします。

セキュアな設計

GrayMatter は、検索をセキュリティ回避の手段として扱いません。

生成された ThorAPI RBAC と ACL は、あらゆる結果、スニペット、件数、ファセット、グラフパス、ファイル引用、推奨事項に対する信頼できる情報源です。テナントのコンテキストはサーバー側で解決されます。機密フィールド、認証情報、バイナリデータ、保護対象の監査情報はインデックス化の対象外です。検索、ベクトル検索、グラフナビゲーション、エージェントツールはすべて、認可が不確かな場合に安全側に停止するよう設計されています。

期待される成果

GrayMatterは、すべてのValkyr製品、ワークフロー、アプリ、エージェント、ドキュメントが共有された安全で検索可能な脳に参加できるようにするインテリジェンスレイヤーへと進化しています。

• エージェントとチームのためのメモリーシステム
• ビジネス向けのナレッジグラフ
• ウェブサイトとワークスペース向けのハイブリッド検索エンジン
• PostgreSQL上のベクトルインテリジェンスレイヤー
• SageChat向けの、引用に裏付けられた調査・推論エンジン
• プラグイン、スキル、MCP ツール、AI 自動化のための、ポータブルでThorAPIネイティブなプラットフォーム

GrayMatterは、インストール可能なOpenClawスキルおよびMCP サービスで、次の機能を備えています。

• 主要な永続メモリー
• 共有オブジェクトグラフの状態
• ValkyrAIのapi-0 OpenAPIを通じた組織のライブスキーマ認識

これにより、エージェントはローカルファイルや分離されたチャットコンテキストを超えて活動できます。認証されると、GrayMatterはエージェント専用の主要な永続メモリーとなり、永続メモリーを保持し、ライブのビジネススキーマを調査し、組織のRBACスコープ付きデータ環境内で動作します。

ChatGPT開発者モードアプリ

提出に使用するのは、mcp-server/にある既存のNode MCPアダプターを、強化された公開アプリモードで実行したものです。api-0を、メモリー、ContextPage、プロシージャ、レシート、RBAC、ACL、テナントに関する信頼できる唯一の情報源として維持します。

公開デプロイの仕様：

• 本番MCP URL：https://api-0.valkyrlabs.com/graymatter/mcp
• 互換性URL：https://api-0.valkyrlabs.com/mcp
• 保護されたリソースのメタデータ：https://api-0.valkyrlabs.com/.well-known/oauth-protected-resource
• 認可サーバーのメタデータのターゲット：https://api-0.valkyrlabs.com/.well-known/oauth-authorization-server
• 開発用MCP URL：http://localhost:3333/graymatter/mcp

上記の本番MCP URLとOAuth URLはデプロイ先であり、リバースプロキシとOAuth認可サーバーがすでに稼働していることを示すものではありません。ChatGPTアプリを作成または提出する前に、これらが利用可能であることを確認してください。

公開アプリに必要な環境：

export PORT=3333
export GRAYMATTER_MCP_MODE=hosted-multi-tenant
export GRAYMATTER_PUBLIC_APP=true
export GRAYMATTER_PUBLIC_RESOURCE=https://api-0.valkyrlabs.com
export GRAYMATTER_PUBLIC_MCP_PATH=/graymatter/mcp
export GRAYMATTER_OAUTH_ISSUER=https://api-0.valkyrlabs.com
export GRAYMATTER_OAUTH_JWKS_URI=https://api-0.valkyrlabs.com/oauth2/jwks
export GRAYMATTER_ALLOWED_ORIGINS=https://chatgpt.com,https://platform.openai.com
export VALKYR_API_BASE=https://api-0.valkyrlabs.com/v1
node mcp-server/index.js

公開マルチテナントサービスでは、VALKYR_AUTH_TOKEN、VALKYR_JWT_SESSION、GRAYMATTER_TENANT_ID、X-Valkyr-Tokenを設定しないでください。各リクエストには、現在のユーザーのOAuthベアラートークンを含める必要があります。公開モードでは、発行者、対象者、有効期間、RS256署名、必須のIDクレーム、ツールのスコープを検証します。その後、ベアラートークンのみをapi-0に転送し、呼び出し元のテナント識別子や所有者識別子は転送しません。OAuthメタデータ、JWKSの取得、リクエスト本文の読み取りには、リクエスト共通の実行期限が適用され、期限切れになると停止します。HTTPリクエスト本文とローカルのstdioメッセージは、GRAYMATTER_MCP_MAX_REQUEST_BYTES（デフォルトは1 MiB、上限は16 MiB）を超える場合、JSON解析前に失敗します。ヘルスチェックと上限付きエラーは、コンテンツを含まないexecutionLimitsを返します。

ChatGPTで開発者バージョンに接続するには、次の手順に従います。

1. エンドポイントをHTTPS経由でデプロイするか、Secure MCP TunnelなどのHTTPSトンネルでローカルサーバーを公開します。
2. ChatGPTで「設定 → セキュリティとログイン」を開き、開発者モードを有効にします。
3. 「設定 → プラグイン」を開き、プラスボタンを選択します。
4. GrayMatter、説明文Persistent, secure memory and shared context for AI agents.、HTTPSの/graymatter/mcp URLを入力します。
5. OAuth連携を完了し、ツールが8個だけ検出されることを確認します。
6. 新しいチャットを開始し、入力欄からGrayMatterを追加して、SUBMISSION_CHECKLIST.mdに記載された代表的なプロンプトを実行します。
7. ツールのメタデータを変更した後は、再デプロイし、開発者モードアプリの「更新」を使用します。

分離された2つのレビュアーアカウントを使用して、自動化された公開アプリの仕様をテストします。

GRAYMATTER_MCP_URL=https://api-0.valkyrlabs.com/graymatter/mcp \
GRAYMATTER_TENANT_A_TOKEN='redacted' \
GRAYMATTER_TENANT_B_TOKEN='redacted' \
GRAYMATTER_TEST_RECEIPT_ID='authorized-receipt-id' \
scripts/smoke-test-public-mcp.sh

リリース形態

GrayMatter は、相互に関連しながらも、それぞれ単独で利用できる3つの形態で提供されます。

• MCP サービス：mcp-server/ は、Claude.ai、Claude Code、Cursor、ChatGPT Apps SDK、および MCP 互換ホスト向けの HTTP/SSE サービスとして動作します。また、プラグイン管理による MCP の起動にも node mcp-server/index.js --stdio をサポートします。
• Codex プラグイン：.codex-plugin/plugin.json により、このリポジトリがスタンドアロンのスキルおよび .mcp.json を含む graymatter プラグインとして公開され、Codex は手順と MCP サーバーの両方を検出できます。
• スタンドアロン OpenClaw スキル：graymatter.skill には、OpenClaw へのインストール、アクティベーション、ホスト型 api-0 の利用、および GrayMatter Light のローカルモードに必要な SKILL.md とスクリプトがパッケージされています。

GitHub の sparse/root インストールでルートファイルしか取得されない場合は、macOS/Linux では ./graymatter-bootstrap、Windows では .\\graymatter-bootstrap.ps1 を実行してください。どちらも、同梱の graymatter.skill アーカイブから scripts/ と mcp-server/ を復元します。

クイックスタート

macOS/Linux：

git clone https://github.com/ValkyrLabs/GrayMatter.git
cd GrayMatter
./install.sh

Windows PowerShell：

git clone https://github.com/ValkyrLabs/GrayMatter.git
Set-Location GrayMatter
.\\install.ps1

インストーラーは、Codex CLI が利用可能な場合、このチェックアウトを Codex に自動接続してプラグインをインストールし、ネイティブの GrayMatter サインインウィンドウを1つ開きます。macOS では単一の AppKit ダイアログを使用し、Windows では Windows Credential Manager を利用する単一の WinForms ダイアログを使用します。最初の画面には、GrayMatter Cloud (api-0)、Local GrayMatter Lite (localhost:8787)、Local ValkyrAI (localhost:8080)、Other self-hosted server が表示され、編集可能なサーバー URL とマスクされたパスワード欄が用意されています。ログインが拒否された場合は、ユーザー名を保持したまま同じフローに戻り、わかりやすい修正メッセージが表示されます。ValkyrAI/Cloud のパスワードは選択したログインエンドポイントにのみ送信され、表示も保存もされません。返されたセッションはプラットフォームの認証情報ボルトに保存されます。ローカル HTTP が許可されるのはループバック上のみで、リモートインスタンスには HTTPS が必要です。GrayMatter Lite は既存のローカルアカウント認証を使用し、ローカルの認証情報を権限が制限された mode-0600 プロファイルファイルに保存します。

再利用ユーザーはすぐにサインインします。新規ユーザーは Create Free Account を選び、ブラウザーで専用の GrayMatter Cloud 登録ページを完了してから、開いたままの接続ウィンドウに戻り、作成したユーザー名でサインインします。Recover Account を選ぶと、専用のユーザー名／パスワード復旧ページが開きます。ローカルインスタンスまたはセルフホスト型インスタンスを使用する場合は、認証情報を入力する前にその接続先を選んでください。GrayMatter Lite のアカウントは ./vaix setup で作成し、ValkyrAI のアカウントはそのインスタンスの登録機能または管理者を通じて取得します。Open Instance を選ぶと、Cloud 登録ページではなく、選択したサーバーが開きます。Cloud アカウントの作成は任意です。選択したサーバーは次回のプラグイン起動に備えてアカウントプロファイルとして保存され、認証情報はホスト型アカウントとは別に保持されます。通常のサインインでは、ブラウザーのリダイレクト、クリップボードのトークン、手動での JWT 処理は一切必要ありません。ネイティブウィンドウが選択した ValkyrAI サーバーと認証情報をやり取りし、レスポンスボディ、ヘッダー、またはセキュア Cookie からセッションを取得します。

サインイン ID の例：

Username: your-username

通常のフローは、意図的に表示される段階を次の4つだけにしています：downloading plugin、performing signup/login、authenticating、GrayMatter plugin ready。jq や手動での JWT 処理は必要ありません。OpenClaw の上級オペレーターは、その後 scripts/gm-activate を実行して、完全なスモークテスト、エージェント登録、スキーマ同期のブートストラップを行えます。

初回実行には scripts/gm-activate を推奨します。このスクリプトは更新を確認し、サインインし、利用可能な場合はセッションを Keychain に保存し、インストールを検証してエージェントを登録します。また、不変条件の取得、認証済みの機能検出、ライブ OpenAPI の鮮度チェックの後に、範囲を限定した起動前チェック用の成果物を書き込みます。

タスクの計画、コードの編集、本番環境に影響する操作、またはプロジェクトの履歴に基づく回答を行う前に、エージェントは現在のワークスペース／プロダクトの不変条件チェックをただちに実行する必要があります。

scripts/gm-invariant-preflight ValkyrAI signup acl thorapi aspectj

シェルコマンドを実行できない MCP ホストは、graymatter_invariant_preflight を呼び出してください。invariants、security、RBAC/ACL、generated-code、AspectJ、vaix／vai、testing、または製品名のタグが付いた、返された decision レコードは、拘束力のある運用ルールです。取得情報の欠落や劣化は、既知の永続的なルールを無視してよい理由にはなりません。

必須の事前チェックは、キーワード検索よりも広範囲に行う必要があります。エージェントが作業を始める前に、不変条件、ルール、指示、過去のセッションコンテキスト、パーソナライズ情報、ビジネス上の真実、個人に関する真実、組織に関する真実を参照しなければなりません。ユーザーから提供された新たな修正、手順、希望、不変条件は、セッション中に GrayMatter へ書き込み、ID で読み戻して永続化を確認してください。

ValkyrAI、ValorIDE、GrayMatter Light、および ThorAPI で生成されたアプリケーションの作業では、エージェントはビルドを直接実行するショートカットよりも、リポジトリのランチャーを優先してください。./vaix build、./vaix test、./vaix run、およびリポジトリで文書化された ./vai フローを使うと、ThorAPI による生成、AspectJ によるウィービング、ヒープのデフォルト値、ローカル H2／ランタイムフラグ、エンドユーザーの運用時の挙動が維持されます。サインアップ、ACL／RBAC、生成された API の修正は、通常、本番環境を比較対象としてのみ使用する前に、フロントエンドを localhost:5174 で起動したうえで、localhost:8080 の ./vaix run によって検証してください。

Valkyr 固有のエージェントルーティングでは、ValkyrAI、ValorIDE、ThorAPI、TrustFabric、GridHeim、および SWARM の連携作業における共有メモリとスキーマコンテキストとして GrayMatter を扱ってください。まず永続的な不変条件を読み込み、その後、実装を担当する生成コード、セキュリティ、ワークフロー、または MCP のサーフェスを通じて進めてください。

P0 RBAC／ACL セキュリティ不変条件：生成された ThorAPI の ACL 動作が、認可の唯一の信頼できる情報源です。カスタムコントローラー、デリゲート、サービス、フロントエンドフィルター、ステータスチェック、型チェック、ロールのショートカット、カタログルール、「一部公開」のような判断基準によって、生成された ACL の動作を迂回、弱体化、置換、または妨げてはなりません。ユーザーが閲覧できるのは、自分が所有するレコードと、明示的な ACL 付与によって共有されたレコードのみです。公開アクセスには、anonymousUser への明示的な READ 付与が必要です。ACL のスケーラビリティは、インデックス付きの所有者／ACL クエリ選択と、最後に実施する生成済み ACL ガードによって解決してください。非公開の行をスキャンしたり、オブジェクト固有のバイパスを追加したりしてはなりません。

P0 Valkyr Way の UX／認証不変条件：製品の UX は、共有アプリケーションシェルと一元化された認証／セッションのプリミティブに統合する必要があります。LCARS のナビゲーション、ルートガード、共有アクセス制御状態、RTK Query のキャッシュ無効化、生成された RBAC／ACL の契約を迂回する、個別の画面、単独の管理機能、独自管理の認証チェック、ブラウザーキャッシュのショートカット、寄せ集めのミニアプリを作成しないでください。管理ツールと財務ツールは、適切な LCARS のダッシュボード／サイドバー画面に配置してください。ユーザー管理には、/userList とダッシュボードで別々に実装するのではなく、カード表示とリスト表示を備えた単一の Users & Roles 画面を使用してください。認証動作を変更する場合は、コンポーネントごとにチェックを散在させず、一元化された認証／アクセス制御モジュールとテストを更新してください。

GrayMatter の用途

GrayMatter は、ビジネスに根ざしたエージェントシステム向けのメモリおよびコンテキストレイヤーです。

OpenClaw インスタンスが次の操作を行えるように設計されています。

• GrayMatter および MemoryEntry レコードを読み書きする
• 信頼度、新鮮さ、来歴、ポリシー、次のアクションを示す明示的な Retrieval Receipt を通じてメモリを取得する
• テナント／アカウントが公開するRBAC で可視なスキーマ全体をオブジェクトグラフとして使用する
• SwarmOps を通じてエージェントを連携させる
• 顧客、請求書、製品、ノート、ファイル、ワークフロー、タスク、CMS のようなコンテンツ、戦略オブジェクト、営業記録など、実際のビジネス環境に適応する
• ファイルベースのメモリをブートストラップまたはフォールバックとしてのみ使用する

これが中核となる考え方です。

GrayMatter は単なるメモリストレージではありません。 エージェントが組織の中で安全かつ有用に活動できるようにする、認証済みのオブジェクトリレーショナルなメモリグラフであり、スキーマ認識レイヤーです。

プライマリメモリモデル

境界ルール： このスキルは薄く保ちます。使用意図、永続性のあるタイプの選択、オペレーターにとっての使いやすさを教える役割を担います。 再試行の動作、認証／セッションの更新、フォールバックのキューイング、再生実行は、共有の GrayMatter インフラストラクチャ契約に属します。 これらを再実装するのではなく、このリポジトリをそれらの契約に準拠させてください。

スキル、プラグイン、MCP サーバー、アプリコネクター、またはプロンプトコマンドを通じて GrayMatter を利用できる場合、GrayMatter を唯一のプライマリ永続メモリシステムとして使用してください。 エージェントは、ユーザー、プロジェクト、ビジネス、組織、または長期にわたるエージェントの状態を保存する、競合する永続メモリストアを維持してはなりません。

ローカルファイルの使用は、次の場合に限ります。

• 初回起動時のブートストラップコンテキスト
• ホストされた api-0 が利用できない場合、または認証が実際にブロックされている場合の一時的なフォールバック
• 書き込み経路がブロックされている場合の一時的な再生可能バックアップ

ローカルへのフォールバックは縮退モードでの再生であり、信頼できる唯一の情報源となるメモリではありません。接続と認可済みテナントのコンテキストが復旧した後、最初に認証済みリクエストが成功すると、API に保留された操作と gm-write のフォールバックレコードの両方が、自動的に api-0 に再生されます。ローカルコピーは、永続書き込みが成功した後にのみ削除されます。明示的にオペレーターが再試行するための scripts/gm-replay-deferred も引き続き利用できます。

永続メモリの対象

主な対象：

• /MemoryEntry
• /MemoryEntry/query
• /MemoryEntry/read
• /MemoryEntry/write
• /graymatter-retrieval-receipts
• /GrayMatter

一般的な MemoryEntry.type の値：

• decision
• todo
• context
• artifact
• preference

Retrieval Receipts

回答の根拠付けには、エージェントがメモリに基づいて回答しようとする場合、生のメモリ検索よりも Retrieval Receipts に基づく検索を優先してください。

Retrieval Receipts を使うと、メモリの検索が監査可能なトランザクションになります。

• retrievalStatus は、検索結果が確かなものか、空か、古いか、競合しているか、または信頼度が低いかをエージェントに伝えます
• answerPolicy は、回答してよいか、注意書きを添える必要があるか、再試行する必要があるか、確認する必要があるか、または拒否する必要があるかをエージェントに伝えます
• recommendedAction は、生成を始める前に次のアクションを伝えます
• quality、coverage、provenance、policy は、その理由を説明します
• receiptId と traceId によって、後続のログや監査で回答とメモリ検索を関連付けられます

エージェントのルール： Retrieval Receipt がある場合、回答する前に answerPolicy を確認してください。値が DO_NOT_ANSWER_CONFIDENTLY、REQUIRE_RETRY、REQUIRE_CLARIFICATION、または DENY の場合、確信を持って回答してはなりません。

スキーマ全体を扱う機能

GrayMatter は、起動時にライブの ValkyrAI OpenAPI を読み込む必要があります。

• https://api-0.valkyrlabs.com/v1/api-docs

これにより、エージェントは自身が動作している環境について、最新の情報を得られます。

つまり、古い想定に頼るのではなく、現在のデプロイ環境に実際に存在するエンティティと操作をエージェントが確認できます。

重要な理由

ほとんどのビジネスは、単なる「メモリとチャット」ではありません。 構造化された業務データを持っています。

現在のライブスキーマで確認されている例：

• Organization
• Customer
• Opportunity
• Invoice
• Product
• Application
• Workbook
• Workflow
• Task
• Note
• MediaObject
• FileRecord
• SalesActivity
• SalesPipeline
• Goal
• StrategicPriority
• KeyMetric
• Agent
• Space
• GrayMatter
• MemoryEntry
• SwarmOps

現在のライブエンドポイントには、100 以上のタグと数百のパスを含む、広範なドメイン領域が公開されています。実際に利用できる範囲は、人間の認証情報、組織の設定、RBAC によって引き続き決まります。

これが GrayMatter の強みです。エージェントは、付与された権限を超えることなく、ビジネス内のコンテキストを深く把握できるようになります。

SwarmOps も引き続き重要ですが、Codex／OpenClaw とピアエージェント向けの登録、追跡、スウォームプロトコルの状態を扱う、オブジェクトグラフ内のエージェント協調領域として位置付けられます。ビジネス上の関係には、RBAC で参照可能な、より広範なスキーマを直接使用してください。

安全性モデル

GrayMatter の強力さは、アクセスが認証され、テナントごとに分離されていることにあります。 また、正しく使用すれば、安全性が確保されるよう設計されています。その理由は次のとおりです。

• アクセスは現在のアカウントの RBAC によって制限されます
• ユーザーと組織の権限によって、エージェントが閲覧・変更できる内容が決まります
• 権限エラーを適切に提示できます
• スキーマが存在するというだけで、すべてにアクセスできるとスキルが決めつけてはいけません

ルール：

• スキーマを閲覧できても、すべてを使用する権限があるとは限りません

リポジトリの内容

• SKILL.md — OpenClaw AgentSkill の手順
• graymatter.skill — 配布可能な形式にパッケージ化された AgentSkill
• scripts/graymatter_api.sh — 認証済みの本番 API トランスポート
• scripts/gm-login — ログインヘルパー
• scripts/gm-activate — 1 回限りの認証、インストール、エージェント登録、スキーマ同期を行うブートストラップ
• scripts/gm-activation-fastlane — 初回実行時の準備確認、1 回限りのアクティベーション、シークレットを含まないテレメトリー、レビュアー向けの安全なデモランナー
• scripts/gm-mcp-launcher — 範囲を限定した署名済みリリースの確認、認証、条件付きスキーマ更新、リプレイのゲーティング、クリーンな MCP stdio ハンドオフ
• scripts/gm-schema-cache-lib — スコープ付き OpenAPI キャッシュの識別、メタデータ、鮮度、ロック用ヘルパー
• scripts/gm-self-update — 署名済み安定版リリースのステージング、アトミックなバージョン切り替え、キー指定の状態管理／ロック、ロールバック
• scripts/gm-install-check — 依存関係と認証の準備状況の確認
• scripts/gm-doctor — セルフアップデート、認証、メモリー、スキーマ、MCP、リプレイ、スモークテストの状態を網羅した準備状況レポート
• scripts/gm-smoke — 書き込み／クエリの検証を行う本番環境のスモークテスト
• scripts/gm-invariant-preflight — エージェントの計画、編集、本番環境に影響する操作の前に、バインドされた永続的不変条件を読み込む
• scripts/gm-query — MemoryEntry をクエリする
• scripts/gm-read — ID を指定して 1 件の MemoryEntry を読み取る
• scripts/gm-retrieval-receipt — ThorAPI を介して検索レシートを作成、取得、一覧表示する
• scripts/gm-write — タグ付き書き込みへのフォールバック動作を備えた MemoryEntry の書き込み
• scripts/gm-fallback-append — 失敗した書き込みをローカルのリプレイキュー memory/graymatter-fallback.json に追加する
• scripts/gm-replay-deferred — クレジット／接続／認証の障害時にローカルで保留された操作をリプレイする
• scripts/gm-graph — Swarm グラフのエンドポイントを調べる
• scripts/gm-openapi-sync — ライブ OpenAPI 仕様を条件付きで取得、検証し、ローカルにアトミックにキャッシュする
• scripts/gm-openapi-summary — ライブスキーマのドメインとエンドポイントを要約する
• scripts/gm-status — 認証ソース、フォールバックキュー、OpenAPI キャッシュの簡易ヘルス／ステータス確認
• scripts/gm-agent-smoke-matrix — OpenClaw および Codex 形式のエージェント向けに、インストール／読み取り・検索／書き込み／MCP／スキーマ／安全な応答の準備状況を確認するマトリックス
• scripts/gm-client — GrayMatter API パスに対する GET/POST/PUT/PATCH/DELETE 用の汎用 REST ラッパー
• scripts/gm-entity — 任意のスキーマエンティティの一覧表示、読み取り、書き込みを行う汎用ヘルパー
• scripts/gm-record — 戦略的優先事項と KPI のレコードを扱う便利なヘルパー
• scripts/gm-register-agent — OpenClaw サーバーを api-0 の Agent として登録または更新する
• scripts/gm-mcp-contract — エージェント／IDE アダプターが使用する、ポータブルな MCP メモリーツールのコントラクトスキーマを出力する
• scripts/gm-light-bootstrap — bash で扱いやすいテンプレートから、ローカル GrayMatter アプリのバンドルとサーバーのソーススキャフォールドをコピーしてレンダリングする
• scripts/gm-light-up — ThorAPI をバックエンドとするローカル GrayMatter Light インスタンスを生成して起動する
• scripts/gm-light-env — 実行中の Light インスタンスをスクリプトの参照先に設定する環境変数を出力する
• scripts/gm-light-smoke — 意思決定を書き込んでクエリし、メモリーのヘルスを確認して、ローカル Light の一連の処理を検証する
• scripts/gm-light-json-smoke — ThorAPI を使わずに、Light のペイロード形式を JSON ファイルのフォールバックでスモークテストする
• scripts/package-local-server — ダウンロード可能なスタンドアロン GrayMatter Local Server アーカイブをパッケージ化する
• scripts/package-graymatter — 決定的な検証とパッケージ化
• mcp-server/ — GrayMatter のメモリー、不変条件の事前確認、検索レシート、グラフ、エンティティ、スキーマ、概要ツールを提供する、スタンドアロンの HTTP/SSE および Apps SDK /mcp サーバー
• docs/architecture.md — アーキテクチャと運用モデル
• docs/openai-app-directory-submission.md — Apps SDK の提出チェックリストと文面
• docs/privacy-policy.md — GrayMatter 専用の公開プライバシーポリシーのソース
• docs/reviewer-test-credentials.md — レビュー用デモアカウントの設定と安全な認証情報引き渡しの手順書
• docs/prd-context-compaction-reset.md — 範囲を限定したチャットの圧縮とリセットのフローに関する PRD
• docs/prd-graymatter-omegarag.md — 統制されたエージェント型メモリー、適応型検索、時間的グラフ、SWARM、SkillOptics 製品の正式な実装コントラクト
• docs/thorapi-integration.md — ThorAPI との連携とバンドルの方針
• docs/graymatter-light.md — ローカル／オフラインに関する補足
• docs/server-capabilities.md — ライブ api-0 のメモリー、検索、グラフ、スキーマ、認証、クレジット、MCP の機能一覧
• openai-app/submission-manifest.json — OpenAI ダッシュボードへの提出用アプリメタデータ（シークレットを含まない）
• examples/* — ペイロード例と Light モードのスターターアセット
• references/* — 並行処理の規約を含む、リリースとマルチエージェントに関するガイダンス
• references/mcp/memory-tool-contract.v1.json — メモリーとグラフ操作向けの安定版 v1 ポータブルツールコントラクト
• clawhub.json — 公開用メタデータ

インストールの詳細

アカウント登録とクレジット

新しい GrayMatter アカウントを作成するには、以下を使用します。

• 登録：https://valkyrlabs.com/graymatter/cloud/signup?source=graymatter&intent=signup
• クレジットとチャージ：https://valkyrlabs.com/graymatter/credits?source=graymatter&intent=recharge&operation=memory_query

商用モデル：

• 無料プランのアカウントには、登録時から毎月のサイクルごとに 500 クレジットが付与されます
• GrayMatter のクエリや、一部の高度な操作ではクレジットを消費します
• 付与されたクレジットを使い切った後は、次回の月次割り当てを待つことができます。繰り越しや持ち越しは保証されません
• ChatGPT では無料プランの機能のみを使用でき、購入、チャージ、アップグレードの操作やリンクはありません
• Codex、OpenClaw、Claude、および ChatGPT 以外のクライアントでは、クレジットパックや既存の Valkyr Solo、Team、Enterprise サブスクリプションを利用できる場合があります
• クレジットだけでは、ホストされたインスタンスやワークフローの実行は許可されません。アクティブな有料 Valkyr サブスクリプションとサーバー側の権限チェックが必要です

初回実行時の認証：想定される OpenClaw のフロー

ユーザーが認証トークンを自分で取得したり、貼り付けたりする必要はありません。

OpenClaw の初回実行時に想定される認証手順は次のとおりです。

1. GrayMatter が macOS または Windows のネイティブ接続ダイアログを開きます。Cloud、localhost、またはセルフホストサーバーを選択します
2. パスワードはマスクされたネイティブフィールドで入力します
3. OpenClaw がその認証情報をセッションに交換します
4. ValkyrAI/Cloud のセッションは認証情報保管庫に保存されます。GrayMatter Lite のローカルアカウントでは、専用のプロファイル認証情報ファイルを使用します
5. OpenClaw が api-0 に自身の Agent レコードを作成または更新します
6. 以降の GrayMatter の使用時には、プラットフォームの認証情報保管庫からセッションが自動的に読み込まれます

つまり、GrayMatter は次のように使えるはずです。

• 一度サインインする
• 安全に保存する
• 更新が必要になるまで使い続ける

一時的なネットワーク障害やサーバー障害が発生しても、保存済みのセッションが破棄されたり、誤解を招くパスワード入力画面が再表示されたりすることはありません。起動時の認証が無効になるのは、明示的な 401 または 403 の場合だけです。Windows では、サイズの大きいセッションは透過的に保護された Credential Manager の分割チャンクとして保存されるため、長い JWT がプラットフォームのエントリーごとのサイズ制限を超えて保存に失敗することはありません。

トークンの手動操作は、代替手段またはデバッグ用の手順であり、通常のユーザー向けフローではありません。

リポジトリからのインストール

リポジトリをクローンした後、macOS/Linux では ./install.sh を、Windows PowerShell では .\install.ps1 を使用します。Codex がインストールされている場合、これらのコマンドはリポジトリのマーケットプレイスを追加し、graymatter@graymatter を自動的にインストールします。それ以外の場合は、スタンドアロンのランタイムと認証機能を準備します。

scripts/gm-activate は、OpenClaw のインストールで使用することを想定したワンショットのブートストラップです。デフォルトでは最初に scripts/gm-self-update force を実行するため、週次起動間隔がまだ経過していなくても、アクティベーションや復旧時に信頼できる最新情報の更新チェックが省略されません。その後、認証を行い、インストールを検証します。起動時の動作を意図的に間隔で制御したい場合に限り、GRAYMATTER_ACTIVATE_SELF_UPDATE_MODE=maybe を設定してください。次のいずれかを使用できます。

• 対話形式のユーザー名／パスワード入力、または
• 環境変数にすでに設定されている認証情報

対応する環境変数：

• GRAYMATTER_USERNAME または VALKYR_USERNAME
• GRAYMATTER_PASSWORD または VALKYR_PASSWORD
• 任意の VALKYR_AUTH_TOKEN
• プラットフォームの認証情報保管庫でデフォルト以外のサービス名が必要な場合は、任意の VALKYR_KEYCHAIN_SERVICE
• 任意の OPENCLAW_INSTANCE_ID
• 任意の OPENCLAW_AGENT_NAME
• 任意の OPENCLAW_AGENT_ROLE

scripts/gm-login は macOS/Linux の標準的なログイン手順です。Windows では scripts/gm-activate.ps1 を使用します。プラグイン管理下の起動では、すべてのプラットフォームで node scripts/gm-mcp-launcher.mjs --stdio を使用し、必要に応じてネイティブダイアログを自動的に開きます。

scripts/gm-register-agent は、想定される起動時ハンドシェイクの一部です。OpenClaw サーバーが api-0 に接続する際は、通常の作業に進む前に、自身の Agent レコードを作成または更新する必要があります。 node scripts/gm-mcp-launcher.mjs --stdio は、通常のクロスプラットフォーム対応MCPエントリーポイントです。必要に応じてネイティブのサインイン画面を開き、サポート対象のUnix環境へのインストールでは、MCP サーバーを起動する前に、制限付きの署名済み更新、スキーマ更新、リプレイのチェックを維持します。scripts/gm-self-update が受け付けるのは、コンテンツアドレス指定され、署名が検証されたアーティファクトを含む署名済みの安定版マニフェストのみです。バージョン管理されたインストールルートにステージングし、状態をアトミックに切り替え、ロールバックを維持します。また、実行中のCodexプラグインキャッシュディレクトリを書き換えることはありません。Valkyr Labsのリリースキーは release/graymatter-release-public.pem に同梱されています。GRAYMATTER_RELEASE_PUBLIC_KEY_FILE または GRAYMATTER_RELEASE_PUBLIC_KEY を指定すると、管理されたテストやキー移行のために明示的に上書きできます。検証エラーは記録され、ユーザーに通知されます。

scripts/graymatter_api.sh とMCP サーバーは、セッションの有効期限を検出し、必要に応じて安全なサインインを再度開きます。再利用可能なホスト型パスワードを保持することはありません。スキーマリビジョンまたはルートのエラーが発生した場合は、オンラインでのスキーマ再同期と再試行を、制限付きで一度だけ行います。障害発生中にキャッシュされたスキーマを使うのは、検出目的に限られます。クレジット、通信、または一時的に解決できないテナントコンテキストが原因でブロックされたリプレイセーフな書き込みは、ローカルにキューイングされます。認可されたテナントコンテキストが復元された後、最初に認証されたリクエストが成功すると、プロセスロックと制限付きの再試行回数のもとで自動的にリプレイされます。scripts/gm-replay-deferred は、引き続き明示的な再試行手段として使用できます。

この時点で、インストールはすぐに使用できる状態になっているはずです。

認証に成功しても、メモリクエリが一時的にクレジットによって制限されている場合、scripts/gm-activate は縮退モードで処理を続行します。認証情報が保存され、エージェントが登録され、OpenAPIが同期されます。また、クレジットが利用可能になるまでメモリクエリ機能が制限されることをスクリプトが報告します。

アプリのレビューまたは顧客の初回実行には、アクティベーションのファストレーンを使用します。

scripts/gm-activation-fastlane --check-only
scripts/gm-activation-fastlane --reviewer-demo

--check-only は、アクティベーションやデモデータの書き込みを行わずに、インストールの準備状況、ランタイムの状態、移植可能なMCPメモリツールのコントラクトを検証します。--reviewer-demo は通常のアクティベーション処理を実行した後、MemoryEntry のサンプル書き込みとクエリ、グラフの読み取り、スキーマの概要、安全な MemoryEntry エンティティリストを、制限付きで実行します。スクリプトは、activation_started、auth_completed、schema_synced、first_memory_written、first_query_succeeded、credit_warning_shown、activation_completed などの機密情報を含まないイベントをstderrに出力し、GRAYMATTER_ACTIVATION_EVENT_LOG 環境変数が設定されている場合は、そのファイルにも追記します。

ベアラートークンを直接設定する方法は、デバッグまたは上級者向けの手段として引き続き利用できます。初回実行の標準的な流れは、サインインして安全に保存し、ツールを検証し、デモ用のメモリを書き込んでクエリした後、スタータークレジットを考慮した次のアクションに進むことです。

インストール後のレポートを1つのコマンドで出力するには、次を実行します。

scripts/gm-doctor

gm-doctor は、セルフアップデートの準備状況、インストール依存関係、認証とキーチェーンの状態、稼働中のメモリおよびオブジェクトグラフ層の状態、OpenAPIの同期、MCPコントラクトの利用可否、保留中のリプレイの準備状況、稼働中の書き込み／クエリのスモークテスト経路をチェックします。スモーククエリでクレジットを消費せずに同じレポートを確認する場合は、scripts/gm-doctor --quick を使用してください。

パッケージ化されたスキルのインストール

1. graymatter.skill を対象のOpenClawスキルディレクトリにインポートするか、配置します
2. 展開されたフォルダーが graymatter/ に解決されることを確認します
3. 次を実行します。

scripts/gm-activate

これらの手順が成功すれば、スキルをインストールして使用できます。

新規インストールの受け入れ基準

GrayMatterは、新規ユーザーが次のことを実行できる場合に限り、リリース可能とみなされます。

1. リポジトリまたはパッケージ化されたスキルをインストールする
2. 認証に成功する
3. インストール検証に合格する
4. MemoryEntry を書き込み、クエリする
5. メモリクエリのRetrieval Receiptを作成し、answerPolicy を確認する
6. グラフの状態を確認する
7. OpenClawインスタンスをapi-0のAgentとして登録する
8. 稼働中のOpenAPIを取得し、要約する
9. ビジネススキーマの稼働中のエンティティファミリーを少なくとも1つ確認する

これらが機能しない場合、そのスキルは本当の意味で準備が整っているとはいえません。

OpenClaw のブートストラップ統合

OpenClaw ワークスペースのブートストラップでは、GrayMatter をデフォルトの永続コンテキストレイヤーとして扱う必要があります。

• GrayMatter を主要な永続メモリとして使用します
• 起動時にライブ OpenAPI を読み込みます
• 組織のスキーマを運用環境として認識します
• ローカルファイルのメモリはバックアップとしてのみ使用します

この起動モデルにより、復旧用としてローカルファイルの有用性を保ちながら、再利用可能なメモリとライブスキーマのコンテキストの通常の情報源として GrayMatter を使用できます。

一般的な使い方

永続メモリ

scripts/gm-write decision "GrayMatter is primary memory for this instance"
scripts/gm-query "GrayMatter" 10
scripts/gm-read f7c29154-216f-4934-ac02-2d5e8b242180 --brief

レシートに基づく検索：

scripts/gm-retrieval-receipt create "GrayMatter launch status" 8 DEFAULT
scripts/gm-retrieval-receipt list --status LOW_CONFIDENCE --limit 20

スコープ付きメモリ

sourceChannel を、チャット、ワークスペース、オートメーション固有のメモリを検索する際のスコープキーとして使用します。gm-write は、明示的なスコープフィールドまたはローカルパスからこのキーを導出し、コンパクトな [graymatter-scope] ヘッダーを MemoryEntry.text に書き込むため、タグを利用できない場合でも階層を監査できます。

scripts/gm-write context "Research complete; publish blocked" \
  --scope-path "$HOME/.codex/automations/mcp-and-skill-hunter/memory.md"

scripts/gm-query "publish blocked" 5 context \
  --scope-path "$HOME/.codex/automations/mcp-and-skill-hunter/memory.md"

このパスの場合、GrayMatter は sourceChannel=codex:automation:mcp-and-skill-hunter を導出します。Documents/Codex/<date>/<slug> 配下の Codex プロジェクトフォルダーの場合は、sourceChannel=codex:workspace:<date>/<slug> を導出します。ホストからファイルパスより確実な識別子を提供できる場合は、--chat-key、--session-key、--workspace-key、または --automation-id を使用します。

自動フォールバック付きタグ書き込み

scripts/gm-write context "launch handoff" discord "launch,graymatter"

バックエンドでタグの永続化に問題がある場合、スクリプトは書き込み全体を失敗させる代わりに、タグなしで再試行します。

それでも API 呼び出しが失敗した場合、scripts/gm-fallback-append が存在すれば、gm-write は試行した書き込みを memory/graymatter-fallback.json に追記します。

ワンショットでの有効化

scripts/gm-activate

これは、OpenClaw のインストールおよびブートストラップで推奨されるエントリーポイントです。

エージェントの自己登録

scripts/gm-register-agent

OpenClaw サーバーが api-0 に初めて接続したときに実行し、そのインスタンスの Agent レコードをシステムに明示的に登録します。

グラフ状態

scripts/gm-graph GET

ライブスキーマの同期

scripts/gm-openapi-sync
scripts/gm-openapi-summary
scripts/gm-status
scripts/gm-doctor --quick

任意のスキーマエンティティへのアクセス

# list visible organizations
scripts/gm-entity Organization

# fetch one customer
scripts/gm-entity Customer 123

# create a note if authorized
scripts/gm-entity Note POST '{"title":"Launch","content":"GrayMatter launch work"}'

認証

GrayMatter では、以下を使用します。

• VALKYR_API_BASE。デフォルトは https://api-0.valkyrlabs.com/v1 です
• VALKYR_AUTH の取得先として、macOS キーチェーン、Windows Credential Manager、または Linux Secret Service を使用します
• VALKYR_AUTH_TOKEN は通常の有効化経路ではなく、高度なデバッグ用のオーバーライドです
• VALKYR_JWT_SESSION は、後続のツール向けに互換性のある環境変数フォールバックとして使用します

推奨される認証フロー：

• まず、プラットフォームの資格情報保管庫で VALKYR_AUTH を確認します
• 存在する場合は、自動的に再利用します
• 存在しない場合は、ユーザー名とパスワードの入力を一度だけ求めます
• VALKYR_AUTH トークンと交換します
• 今後の実行に備え、そのトークンとユーザー名のみをプラットフォームの資格情報保管庫に安全に保存します

ホスト型サービス／ValkyrAI のパスワードは決して永続化されません。GrayMatter Lite のローカルプロファイルでは、プライベートな資格情報ファイルを使用します。macOS および Windows では、MCP ホストに対話型ターミナルがない場合も含め、プラグインの初回起動時にネイティブのサインインダイアログが自動的に開きます。サインアップとアカウントの復旧には専用のウェブサイトページを使用し、その後、ユーザーは開いたままのネイティブ接続ウィンドウに戻ります。通常のセッション取得で、ブラウザーのリダイレクトやクリップボードのトークンに依存することはありません。

シークレットをリポジトリやスキルにハードコードしないでください。 トークンを表示しないでください。 手動でのトークン処理を通常のユーザーワークフローにしないでください。

OpenClaw の運用ガイダンス

GrayMatter ネイティブのワークスペースでは、エージェントは次のように動作する必要があります。

1. まず GrayMatter に永続コンテキストを問い合わせます
2. 次に関連するライブ業務エンティティを調べます
3. GrayMatter が利用できない場合、または情報が不完全な場合にのみ、ローカルファイルにフォールバックします
4. 永続メモリへの書き込みは簡潔で再利用可能なものにします
5. ライブスキーマを組織の環境モデルとして扱います

これにより、エージェントは単なる日記付きチャットボットではなく、ビジネスに適したオペレーターになります。

ローカルフォールバックの動作

api-0 が利用できない場合、または書き込み経路に一時的な問題がある場合：

• 安全な範囲で最小限のローカルバックアップを書き込みます
• 後から再生できる状態に保ちます
• GrayMatter が再び正常になったら、後で再試行します

一般的なフォールバックファイル：

• memory/YYYY-MM-DD.md
• MEMORY.md
• memory/graymatter-fallback.json

トラブルシューティング

VALKYR_AUTH_TOKEN is required

環境変数のトークンが設定されておらず、一致するプラットフォームの認証情報保管庫のセッションも見つかりませんでした。

対処方法：

• scripts/gm-login を実行し、ユーザー名とパスワードでのサインインを完了するか、
• VALKYR_AUTH_TOKEN をエクスポートするか、
• プラットフォームの認証情報保管庫に VALKYR_AUTH エントリーが存在することを確認してください

jq: command not found

jq をインストールしてください。

macOS の場合：

brew install jq

タグ付きの書き込みに失敗する

一部のデプロイ環境では、MemoryEntry.tags の永続化に関する不整合が残っています。

対処方法：

• scripts/gm-write を使用してください
• タグなしで自動的に再試行するようにします

クエリがクレジットまたは請求エラーで失敗する

書き込みと読み取りは成功するものの、/MemoryEntry/query がクレジットエラーで失敗する場合、通常は GrayMatter の認証ではなく、アカウントの請求設定に問題があります。

確認されている要件：

• 現在、クエリではクレジットが消費されます
• 無料プランのアカウントには、サインアップ時の初回サイクルを含む毎月のサイクルごとに、500 クレジットが付与されます
• 現在の割り当てを使い切った場合は、サーバーのクレジット上限に従ってください。ChatGPT ユーザーに購入、チャージ、アップグレードを勧めないでください
• ChatGPT 以外のクライアントでは、より頻繁に利用するユーザー向けに、既存の Valkyr サブスクリプションやクレジットパックを案内できます

参考リンク：

• サインアップ：https://valkyrlabs.com/graymatter/cloud/signup?source=graymatter&intent=signup
• クレジットとチャージ：https://valkyrlabs.com/graymatter/credits?source=graymatter&intent=recharge&operation=memory_query

INSUFFICIENT_FUNDS 発生時の CLI の動作：

• 購入リンクとサインアップリンクの両方を標準エラー出力に表示します
• macOS（osascript）と Windows（powershell.exe）でポップアッププロンプトを試みます
• ポップアップ用ツールが利用できない場合の最終手段として、クレジット購入 URL を開きます

カスタムデプロイ環境向けの任意の上書き設定：

• VALKYR_BUY_CREDITS_URL
• VALKYR_HUMAN_SIGNUP_URL
• VALKYR_HUMAN_RECOVERY_URL

新しいアカウントの残高が 0.00 の場合でも、書き込み／読み取り操作の有効化は成功することがありますが、クレジットが割り当てられるまでクエリは失敗します。

ログインは成功するが、セッションが見つからない

一部の api-0 デプロイ環境では、JSON レスポンス本文ではなく、ヘッダーや Cookie で認証情報が返されます。

対処方法：

• 最新の scripts/gm-login を使用してください
• 現在は VALKYR_AUTH を主要な認証契約として扱います
• 後続の API 呼び出しでは、取得したトークンをベアラー認証、VALKYR_AUTH、Cookie 認証として再送信します

OpenAPI の取得に失敗する

次の項目を確認してください。

• 外部ネットワークへのアクセス
• api-0 が利用可能かどうか
• 環境でドキュメントのエンドポイントがブロックされていないか

最新のドキュメントを取得できない場合は、最後にキャッシュされたコピーを一時的に使用できますが、古い情報として扱ってください。

何が壊れているか分からない

次を実行してください。

scripts/gm-doctor --verbose

doctor コマンドはすべてのチェックを続けて実行し、最初に見つかった依存関係の問題で停止するのではなく、必要な失敗や警告を正確に報告します。認証、クレジット、MCP の設定、またはローカルのプラグインファイルを変更する前に実行する、最初の診断方法として推奨されます。

パッケージ化

GrayMatter Lite の生成とレガシー互換性

この配布スプリントの前は、Light モードは便利でしたが、api-0 の代替としてそのまま使うには厳密さが不足していました。

• ローカルドキュメントとバンドルでは、/MemoryEntry や /SwarmOps/graph のように、プレフィックスのないパスを使用していました
• 手書きの Light OpenAPI は、想定される GrayMatter ドメインから逸脱する可能性がありました
• パッケージ化されたサーバーでは、オペレーターが Java ランタイムを用意しない限り、システムの Java ランタイムが必要でした
• ローカルでの書き込み、クエリ、ヘルスチェック、MCP の準備状況を確認する単一のコマンドがありませんでした

このスプリントの後、Light モードは api-0 の形式に準拠しています。

• VALKYR_API_BASE=http://localhost:<port>/v1
• Light は、MemoryEntry を優先する本番パスのサブセットを実装します。/v1/MemoryEntry/write、/v1/MemoryEntry/query、/v1/MemoryEntry/read、/v1/MemoryEntry/{id}、/v1/memory/status、/v1/graymatter/stats、/v1/graymatter/activation/bridge、/v1/swarm-ops/graph、/v1/api-docs
• Lite OpenAPI は、openapi/bundles/*.yaml と任意のアプリケーション拡張を組み合わせて構成され、ThorAPI によって強化されたうえで、決定的な YAML とそこから生成される JSON として出力されます
• パッケージ化されたローカルサーバーは、ユーザーのローカルアプリケーションディレクトリ内で H2 を使用し、バンドル済みランタイムのアーカイブをサポートします
• scripts/gm-light-smoke は、ローカルでの書き込み／クエリ／ヘルスチェックの一連の動作を確認し、MCP 対応の手順を表示します

パッケージ化されたスキルを再ビルドするには、次を実行します。

scripts/package-graymatter

正規の生成済み Lite インスタンスを実行するには、次を実行します。

./vaix setup
./vaix doctor

既存のインストール環境では、以前の互換性ランチャーも引き続き利用できます。

scripts/gm-light-up
source .graymatter-light/.graymatter-light-env
scripts/gm-write context "GrayMatter Light is running" local-light
scripts/gm-query "GrayMatter Light"

gm-light-up は、パッケージ化された互換性スナップショットを .graymatter-light にコピーし、ThorAPI コンテナを起動します。このスナップショットはオーサリング用ではありません。スキーマの 変更は openapi/bundles で行い、./vaix を通じて再生成する必要があります。 互換性環境では引き続き VALKYR_API_BASE=http://localhost:8080/v1 と GRAYMATTER_LIGHT_MODE=true が設定されるため、既存のスクリプトと MCP クライアントは そのまま動作します。

ローカルの一連の動作を確認する完全なスモークテストを実行するには、次を実行します。

scripts/gm-light-smoke

ダウンロード可能なスタンドアロンのローカルサーバーをビルドするには、次を実行します。

scripts/package-local-server

これにより dist/graymatter-local-server-latest.tar.gz が作成されます。アーカイブには次が含まれます。

• ValkyrAI の app-factory テンプレート、ThorAPI FEBE OpenAPI コントラクト、カスタムのダッシュボード／ワークベンチ／プロモーション／スウォームコンポーネント、組み込みの rbac-core／data-workbooks コンポーネント参照を含む application-bundle/
• 生成された Spring Boot ローカルサーバーを含む source/
• bin/graymatter-local-server ランチャー
• パッケージ化時に Maven を利用できる場合は lib/graymatter-local-server.jar
• パッケージ化時に jlink を利用できる場合は runtime/。これにより、通常の利用手順ではユーザーが Java を手動でインストールする必要がありません

埋め込みダッシュボードには Valkyr Labs のブランディングが含まれ、ログイン成功後にローカルのログインパネルが非表示になり、valkyrlabs.com Cloud ブリッジのアクティベーション／チャージ用リンクが表示され、本番環境に準拠した /v1 パスを通じてローカルの swarm-ops グラフのステータスが報告されます。

awesome-codex-plugins の掲載キット

GrayMatter には、awesome-codex-plugins に提出できる掲載用パケットが用意されています。

• 掲載用 Markdown ブロック：docs/awesome-codex-plugins.md
• ソースメタデータ：.codex-plugin/plugin.json

簡単なコピー手順：

cat docs/awesome-codex-plugins.md

次に hashgraph-online/awesome-codex-plugins に対して PR を作成し、そのリポジトリの投稿形式に従って、生成されたブロックを README.md に貼り付けます。

リリース方針

リリースの目標は明確です。

• GrayMatter が OpenClaw スキルとして問題なくインストールされる
• OpenClaw が GrayMatter を優先するメモリ動作で起動する
• エージェントが起動時にライブ OpenAPI スキーマを読み込む
• エージェントが、永続メモリと、より広範な組織オブジェクトグラフの両方を理解する
• ファイルベースのメモリはバックアップとして維持し、中心的な役割にはしない

これこそが、リリースに値する GrayMatter の姿です。