データとストレージ

データの保存場所、誰が何を読めるか、そして顧客向けページが誤って内部データを見ることがないようにエージェントが従うルールについて説明します。

物が存在する3つの場所

1. ワークスペース（`~/workspace/`）

エージェントが実行されるファイルシステムです。Markdown の下書き、生成されたアセット、カスタムスキル、ジョブ、スクラッチスペース、およびこれらのドキュメントはすべてここに保存されます。

所有者：agent Linux ユーザー（エージェント自身）。
チャットから到達可能です。コンソールプロセスまたは公開サイトプロセスからは到達できません。
2つの慣例的なパス：
~/workspace/uploads/：チャットに貼り付けたファイルはここに配置されます。
~/workspace/downloads/：エージェントがワークスペース UI 経由でダウンロード用に登録したファイル。ゲート付き URL で nginx によって提供されます。

2. PostgreSQL（3つのデータベース）

構造化されたデータの永続的な状態管理には、アプリケーションの状態として SQLite や JSON ファイルを使用しないでください。

データベース	所有者	Agent	Console	Public site
`console_db`	console	R/W	R/W	(blocked)
`site_db`	site	R/W	R/W	R/W
`console_site_db`	shared	R/W	R/W	R/W

どこに何を配置するか:

console_db: 内部専用の状態。顧客リスト、取引ステージ、内部スコアリングテーブル、監査ログ。公開サイトはアクセスできません。REVOKE はデータベースロール層で行われ、単なる慣例ではありません。
site_db: 公開サイトがレンダリングするコンテンツ。事前計算されたレポート、ドキュメントページ、ページレンダリング時に安価に読み取れるべきもの。Console が書き込み、サイトが読み取ります。
console_site_db: 明示的なクロスサーフェスチャネル。Console がモデレーションキューに書き込み、サイトが承認されたエントリをレンダリングし、サイトがインタラクションシグナルを書き戻し、Console がそれらを読み取ります。

3. メモリと進捗状況

ワークスペース内の 2 つの特別なファイル:

~/workspace/.memory.md: 各チャットの開始時に読み込まれ、「remember this: X」で追記するファイル
~/workspace/progress.md: 変更ログ。エージェントが重要な変更後に追記し、何が起こったかを再構築するために読むことができるファイル

これらは意図的にマークダウン形式になっています。grep で検索したり、バージョン管理したり、手動で編集したり、再度 grep で検索したりできます。

1つではなく3つのデータベースを使う理由

2つの理由があります。

サーフェスの分離。 公開サイトの訪問者は、原理的には、サイトが認証に使用するデータベースロールをクエリする方法を見つけることができます。そのロールが site_db へのアクセスのみを持つ場合、漏洩の影響範囲は、すでに公開すると決定したデータに限定されます。
意図の明確化。 Agent が Console アプリを書く場合、console_db を使用することがわかります。サイトページを書く場合は site_db を使用します。サーフェス間のワークフローを構築する場合は console_site_db を使用します。「このテーブルは公開すべきか?」という偶発的な疑問は生じません。

エージェントはこれらのルールを曲げようとはしません。「この Console ページを公開してください」と依頼すると、サイトから console_db に直接アクセスするのではなく、console_site_db を経由してデータを移動し、サイト上で読み取りパスを再構築する必要があると説明します。

データベースの操作

パターンは、毎回同じです：

SQLAlchemy セッションは src/db.py（アプリ間で共有されるモジュール）からインポートします。
Pydantic モデルは、すべての入力とすべての API 境界を保護します。
SQLAlchemy がオーバーキルな場合（読み取り専用のトークンゲート付きルックアップ、シンプルなスクリプト）のみ、生の psycopg2 を使用します。

新しいアプリの上部には CREATE TABLE IF NOT EXISTS ステートメントが表示されます。エージェントはスキーマをコードとして扱います。各アプリは独自のテーブルを宣言します。プラットフォームのマイグレーションシステムはありません。新しいカラムは ALTER TABLE で追加され、エージェントは変更をログに記録します。

ClickHouse はどうですか

ClickHouse は、PostgreSQL では遅くなるような分析ワークロードに対してローカルで利用できます。数百万行にわたる時系列のロールアップや列指向の集計などです。エージェントは ClickHouse を使用する前にスキルを読み取り、意図的に選択し、その理由を説明します。デフォルトは PostgreSQL のままです。

存在しない場所

プラットフォーム管理のオブジェクトストレージはありません。 50 MB の PDF や動画を保存したい場合は、~/workspace/downloads/（nginx でゲート）にファイルとして保存するか、Postgres の BYTEA カラム（小さなアーティファクトには問題ありません）として保存してください。
シークレット用の環境変数はありません。 認証情報は、サーフェスとコネクタにスコープされた型付きシークレットストアに保存されます。エージェントがそれらをファイルやデータベースカラムにコピーすることはありません。
ワークスペース UI が公開する以外の「プラットフォーム設定」ページはありません。 スケジュール、モード、承認はすべて明示的なトグルです。

データのライフサイクル

作成したファイルは、削除するまで残ります。エージェントはワークスペースをガベージコレクションしません。
データベースの行は、ユーザー（または明示的なクリーンアップジョブ）が削除するまで残ります。エージェントは、「90日より古い vsg_runs の行を毎週日曜日に削除する」といった指示を受けると、クリーンアップジョブを作成します。
メモリと進捗ファイルは時間とともに増加します。エージェントは、メモリが煩雑になると、時折プルーニングを提案します。
コネクタの監査ログはプラットフォームによって保持されます。閲覧は可能ですが、削除はできません。

内部の仕組み。 各 Postgres ロールは Unix ソケットのピア認証（OS ユーザーがロール名と一致）を介して認証されます。漏洩するパスワードも、設定ミスを起こす接続文字列もありません。GRANT と REVOKE は明示的で可視化されています。system_db データベースはプラットフォーム内部（api-proxy、connectors サービス、bridge）のために存在しており、どのサーフェスもそこに接続することはありません。