Skip to main content
Memory Stores

Memory Store データ構造

Forward Memory Store API で共通するデータ構造、制約、マウント規則です。

Forward Memory Store API では 3 つの共通オブジェクトを使用します。階層は Memory Store → Memory → Memory Version です。
階層ID プレフィックス説明
Memory Storememstore_Memory のコンテナ。内容を直接保存せず、(identity, template) にマウントできます。
Memorymem_Store 内の Memory。相対 path で識別され、実際の content を保持します。
Memory Versionmemver_Memory の作成、更新、削除時に自動生成される変更不可のスナップショット。

Memory Store オブジェクト

{
  "id": "memstore_00mc7mukn7lkxr454tjd",
  "type": "memory_store",
  "name": "project-alpha-memory",
  "description": "Agent knowledge base for project Alpha",
  "status": "active",
  "entry_count": 12,
  "total_size": 4096,
  "metadata": {
    "team": "backend",
    "created_by": "forward"
  },
  "system_managed": false,
  "identity_id": null,
  "created_at": "2026-08-14T10:00:00Z",
  "updated_at": "2026-08-14T10:00:00Z",
  "archived_at": null,
  "binding_info": {
    "identity_template_count": 1
  }
}
フィールド型説明
idstringmemstore_ プレフィックスの Memory Store ID。
typestring常に memory_store。
namestringStore の表示名。
descriptionstringStore の説明。
statusstringactive または archived。
entry_countintegerStore 内の Memory エントリ数。
total_sizeintegerすべての Memory 内容の合計バイト数。
metadataobjectメタデータ。サーバーが挿入する created_by=forward を常に含みます。
system_managedbooleanSession 作成時に (identity, template) 用に自動作成されたデフォルト Store は true、ユーザーが明示的に作成した Store は false。
identity_idstring/nullシステム管理のデフォルト Store を所有する Identity。ユーザー作成の Store は null。
created_atstringRFC 3339 形式の作成時刻。
updated_atstringRFC 3339 形式の最終更新時刻。
archived_atstring/nullアーカイブ時刻。active の場合は null。
binding_info.identity_template_countinteger現在 Store をマウントしている (identity, template) の数。アーカイブと削除時に確認されます。

Store メタデータの制約

制約値
最大キー数15
キー長1–64 characters
値の型文字列である必要があります
値の長さ512 文字以下
予約キーcreated_by is injected by the server as "forward"; supplying it returns 400
上流の上限は 16 キーです。Forward が created_by を挿入して 1 枠を使用するため、呼び出し元が指定できるのは 15 キーです。

Memory オブジェクト

{
  "id": "mem_00mc7mvag5u68kkfvxhy",
  "type": "memory",
  "memory_store_id": "memstore_00mc7mukn7lkxr454tjd",
  "path": "decisions/arch-choice.md",
  "content": "# Architecture decision\n\nUse a microservices architecture.",
  "content_size_bytes": 99,
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "metadata": {
    "owner": "backend-team"
  },
  "created_at": "2026-08-14T10:00:00Z",
  "updated_at": "2026-08-14T10:00:00Z"
}
フィールド型説明
idstringmem_ プレフィックスの Memory ID。
typestring常に memory。
memory_store_idstring親 Memory Store の ID。
pathstringStore 内の大文字と小文字を区別する相対パス。
contentstring/nullUTF-8 プレーンテキスト。作成、更新、単一取得 API でのみ返され、一覧レスポンスでは省略されます。
content_size_bytesinteger内容のバイト数。
content_sha256string内容の SHA-256。楽観的同時実行制御に使用できます。
metadataobjectメタデータ。
created_atstringRFC 3339 形式の作成時刻。
updated_atstringRFC 3339 形式の最終更新時刻。

path の制約

制約値
相対パスであること/ で開始できません
最大長1,024 bytes
最大セグメント数58
セグメント長Up to 255 bytes
禁止セグメント空セグメント、.、..、または先頭か末尾に空白があるセグメント
禁止文字\ and NUL
大文字と小文字区別します
有効な例： notes/meeting-2026-08-14.md, config.yaml 無効な例： /notes/meeting.md, a/../b, notes//x.md

content の制約

制約値
Encodingbase64 ではない UTF-8 プレーンテキスト
最大サイズ元のリクエストバイトで 100 KiB
制御文字改行 \n、復帰 \r、タブ \t を除く非表示制御文字（U+0000～U+001F、U+007F）は使用できません

Memory メタデータの制約

制約値
最大キー数16
キー長1–64 characters
値の型文字列である必要があります
値の長さ512 文字以下
予約キーなし。Forward はエントリに created_by を挿入しません。呼び出し元がこのキーを使用でき、値はそのまま保存されて返されます。
Agent が Memory を書き込むと、エントリのメタデータ全体が {"source":"agent"} に置き換えられます。そのため、この API で設定したメタデータが通常の Agent 動作によって消去される場合があります。

Memory Version オブジェクト

{
  "id": "memver_00mc7mw0t337kbcx5q52",
  "type": "memory_version",
  "memory_store_id": "memstore_00mc7mukn7lkxr454tjd",
  "memory_id": "mem_00mc7mvag5u68kkfvxhy",
  "path": "decisions/arch-choice.md",
  "content": "# Architecture decision\n\nUse a microservices architecture.",
  "content_size_bytes": 99,
  "content_sha256": "1712de0d497a5aeef2beeccf4fbb7d5a16944975438d0c25447b9c1fba13099a",
  "operation": "updated",
  "redacted": false,
  "redacted_at": null,
  "created_at": "2026-08-14T10:00:00Z"
}
フィールド型説明
idstringmemver_ プレフィックスの Memory Version ID。
typestring常に memory_version。
memory_store_idstring親 Memory Store の ID。
memory_idstring親 Memory の ID。
pathstringこのバージョンに記録された Memory の path。
contentstring/nullバージョン内容。単一取得 API でのみ返され、一覧レスポンスでは省略されます。墨消し済みの場合は null。
content_size_bytesintegerバージョン内容のバイト数。
content_sha256stringバージョン内容の SHA-256。
operationstringバージョンを生成した操作：created、updated、deleted。
redactedbooleanバージョンが墨消しされているかどうか。
redacted_atstring/null墨消し時刻。未実施の場合は null。
created_atstringRFC 3339 形式のバージョン作成時刻。

Memory Store マウントオブジェクト

(identity, template) 上のマウントレコードです。 
{
  "memory_store_id": "memstore_00mc7mukn7lkxr454tjd",
  "identity_id": "idn_63ee28747a35cff93771c491",
  "template_id": "tmpl_eb3377fb74ad413e17b3d755",
  "access": "read_only",
  "system_managed": false,
  "name": "team-a",
  "status": "active",
  "entry_count": 12,
  "created_at": "2026-08-14T10:00:00Z"
}
フィールド型説明
memory_store_idstringマウントされた Memory Store の ID。
identity_idstringマウントを所有する Identity。
template_idstringマウントを所有する Template。
accessstringread_write または read_only。以下のアクセス規則を参照してください。
system_managedbooleanシステムが自動作成したデフォルト Store 枠は true。
namestringマウントした Store の表示名。Store エンティティから取得します。ベストエフォート方式で、Store を読み取れない場合は空文字列です。
statusstringマウントした Store の状態（active / archived）。Store エンティティから取得します。ベストエフォート方式で、Store を読み取れない場合は空文字列です。
entry_countintegerマウントした Store の Memory エントリ数。Store エンティティから取得します。ベストエフォート方式で、Store を読み取れない場合は 0 です。
created_atstringRFC 3339 形式のマウント作成時刻。

アクセス規則とマウント上限

ルール説明
唯一の書き込み可能 Storeシステム管理のデフォルト Store（system_managed=true）だけが read_write で Session に挿入されます。
明示的マウントのアクセスユーザーがマウントした Store は常に read_only です。Agent は読み取れますが書き込めません。
マウント上限1 つの (identity, template) には、デフォルト枠を除いて最大 10 個を明示的にマウントできます。
一覧の順序デフォルト Store が先頭で、明示的なマウントは作成時刻の昇順で続きます。
書き込み可能な Store が複数あると上流の書き込み先選択に決定的な順序がないため、Forward は書き込み可能な Store を必ず 1 つに制限します。

Session 内での見え方

Session 作成時、Forward はその (identity, template) のすべての active なマウントを Session リソースに挿入します。すべての Store の Memory は path によって sandbox 内のフラットな名前空間に統合されます。 
/data/.qoder/awareness/<memory.path>
sandbox には memory_store や mem_ の階層は表示されず、Agent は path で直接ファイルを読み取ります。複数の Store に同じ path があると互いに隠れる可能性があります。優先順はマウント作成時刻に基づいて一定ですが直感的ではないため、Store ごとに異なる path プレフィックスを使用してください。
セルフホスト Environment では読み込まれません：Session がセルフホスト Environment（config.type=self_hosted）で実行される場合、Forward は Memory Store を Session に挿入しません。マウント関係には影響しません。マウント API は通常どおりレスポンスを返し、Store とエントリも Memory Store API から引き続き読み書きできます。ただし、Agent の sandbox からこれらの Memory は見えません。Agent に Memory を使用させるには、マネージド（cloud）Environment で Session を実行してください。
はじめに
Agent の定義
Agent 環境の設定
Agent にタスクを委任する
Agent 連携
Agent コンテキストの管理
アカウント
ベストプラクティス
お知らせ
API リファレンス