eve-agent-memory

Eve Agent Memory

Eve Horizon のエージェントには組み込みの「メモリ」プリミティブはありませんが、プラットフォームはあらゆる時間スケールに対応したストレージシステムを提供しています。このスキルでは、学習し、記憶し、共有するエージェントのために、これらを組み合わせて一貫性のあるメモリを構成する方法を説明します。

メモリの課題

すべてのエージェントは、毎回まっさらな状態から始まります。意図的にメモリを設計しないと、エージェントは次のような問題を抱えます。

• 仕事のたびに同じ事実を再発見します。
• 仕事が終わるとコンテキストを失います。
• 学習した知識を兄弟エージェントと共有できません。
• 有効期限のない古い情報が蓄積されます。

それぞれの時間スケールに適したプリミティブを使い、何を記憶するかをどこに保存するかに対応付けることで、これらの問題を解決します。

時間スケール別のストレージプリミティブ

短期（ジョブ内）

ワークスペースファイル — ジョブの実行中に利用できる Git リポジトリのチェックアウトです。

# Workspace is at $EVE_REPO_PATH
# Write working state to .eve/ (gitignored by convention)
echo '{"findings": [...]}' > .eve/agent-scratch.json

# Workspace modes control sharing:
#   job       — fresh checkout per job (default)
#   session   — shared across jobs in a session
#   isolated  — no git state, pure scratch
eve job create --workspace-mode session --workspace-key "auth-sprint"

用途：作業メモ、中間結果、調整用の受信トレイファイル。設計上、一時的なものです。Git にコミットするか、別の場所に保存しない限り、ワークスペースの状態はジョブの終了後に保持されません。

調整用受信トレイ — .eve/coordination-inbox.md は、ジョブの開始時に調整スレッドのメッセージから自動生成されます。API を呼び出さずに兄弟エージェントの状況を確認するには、これを読みます。

エージェント KV ストア — オプションの TTL を設定できる軽量な運用状態です。用途：機能フラグ、レートカウンター、エージェントの状態マシン、重複排除キー。名前空間ごとに分割されます。

# Set a KV value with TTL
eve kv set --org $ORG_ID --agent $AGENT_SLUG --key "pr-123-status" --value '{"phase":"review"}' --namespace workflow --ttl 86400

# Get a KV value
eve kv get --org $ORG_ID --agent $AGENT_SLUG --key "pr-123-status" --namespace workflow

# List keys in a namespace
eve kv list --org $ORG_ID --agent $AGENT_SLUG --namespace workflow

# Batch get multiple keys
eve kv mget --org $ORG_ID --agent $AGENT_SLUG --keys "pr-123-status,pr-456-status" --namespace workflow

# Delete a key
eve kv delete --org $ORG_ID --agent $AGENT_SLUG --key "pr-123-status" --namespace workflow

中期（プロジェクト内の複数のジョブにまたがる期間）

ジョブ添付ファイル — 任意のジョブに添付される、名前付きのキーと値のペアです。ジョブの完了後も保持されます。

# Store findings
eve job attach $EVE_JOB_ID --name findings.json --content '{"patterns": [...]}'
eve job attach $EVE_JOB_ID --name summary.md --file ./analysis-summary.md

# Retrieve from any job (including parent/child)
eve job attachment $PARENT_JOB_ID findings.json --out ./prior-findings.json
eve job attachments $JOB_ID  # list all

用途：ジョブの出力、意思決定の記録、分析結果。特定のジョブに添付されるため、ジョブ ID から取得できます。親ジョブと子ジョブの間で構造化データを渡すのに適しています。

スレッド — セッションをまたいで継続するメッセージの一連の流れです。

# Project threads maintain chat context
eve thread messages $THREAD_ID --since 1h

# Coordination threads connect parent/child agents
eve thread post $COORD_THREAD_ID --body '{"kind":"update","body":"Found 3 auth issues"}'
eve thread follow $COORD_THREAD_ID  # poll for sibling updates

用途：エージェント間のコミュニケーション、継続的なコンテキスト、調整。スレッドの要約により、履歴を圧縮できます。調整スレッド（coord:job:{parent_job_id}）は、チームへのディスパッチ時に自動作成されます。

スレッドの知識抽出 — スレッドの会話をメモリドキュメントまたは組織ドキュメントに変換します。検索可能な知識として、価値ある議論の成果を保存する用途に使います。

eve thread distill $THREAD_ID --org $ORG_ID --agent reviewer --category learnings --key "auth-discussion-findings"

リソース参照 — バージョン管理された組織ドキュメントへのポインターで、ジョブのワークスペースにマウントされます。

eve job create \
  --description "Review the approved plan" \
  --resource-refs='[{"uri":"org_docs:/pm/features/FEAT-123.md@v3","label":"Plan","mount_path":"pm/plan.md"}]'

用途：特定バージョンのドキュメントをジョブの入力として固定します。参照先のドキュメントは、指定されたマウントパスにワークスペース内で展開されます。イベントによって展開の成功または失敗が追跡されます。

長期（プロジェクトをまたいで永続）

組織ドキュメントストア — 組織単位で管理されるバージョン管理付きドキュメントです。

# Store knowledge
eve docs write --org $ORG_ID --path /agents/learnings/auth-patterns.md --file ./auth-patterns.md

# Retrieve
eve docs read --org $ORG_ID --path /agents/learnings/auth-patterns.md
eve docs list --org $ORG_ID --prefix /agents/learnings/

# Search
eve docs search --org $ORG_ID --query "authentication retry"

用途：厳選された知識、意思決定ログ、学習したパターンです。バージョン管理され、更新のたびに新しいバージョンが作成されます。イベントスパインで system.doc.created/updated/deleted イベントを発行します。レビューや改善、共有を行う知識に最適です。

エージェントメモリ名前空間 — エージェント単位のパス規約に従って、組織ドキュメントとして保存される厳選された知識です。カテゴリは learnings、decisions、runbooks、context、conventions です。信頼度スコア、タグ、レビュー日、有効期限に対応しています。用途：蓄積された専門知識、意思決定ログ、運用ランブックです。

# Store a memory entry
eve memory set --org $ORG_ID --agent reviewer --category learnings --key "auth-retry-patterns" \
  --content "Always use exponential backoff..." --confidence 0.9 --tags "auth,reliability" --review-in 30d

# Get a memory entry
eve memory get --org $ORG_ID --agent reviewer --key "auth-retry-patterns" --category learnings

# List entries
eve memory list --org $ORG_ID --agent reviewer --category learnings --limit 20

# Delete an entry
eve memory delete --org $ORG_ID --agent reviewer --category learnings --key "auth-retry-patterns"

# Search across memory (all agents or specific)
eve memory search --org $ORG_ID --query "auth retry patterns" --agent reviewer --limit 10

名前空間の規約：/agents/{slug}/memory/{category}/{key}.md または /agents/shared/memory/...

組織ファイルシステム — エージェントのワークスペース内の .org/ にマウントされ、ローカルマシンと同期される、組織ごとの共有ファイルストレージです。

# Agents access .org/ directly in their workspace (all execution paths)
ls .org/                                    # browse org files
cat .org/shared/runbook.md                  # read shared knowledge
echo "new finding" >> .org/agents/reviewer/notes.md  # write agent-scoped files

# Developers sync to local machines
eve fs sync init --org $ORG_ID --local ~/Eve/acme --mode two-way
eve fs sync status --org $ORG_ID
eve fs sync logs --org $ORG_ID --follow

用途：大規模なナレッジベース、デザインアセット、ドキュメントツリーです。エージェントは実行パス（agent-runtime または worker）に関係なく、ワークスペース内の .org/ を参照できます。デフォルトでは Markdown を優先します。イベント駆動型の通知（file.created/updated/deleted）に対応しています。ファイルツリーとして存在し、エージェントと人の両方による編集に適した知識に最適です。

スキルとスキルパック — 再利用できるようにパッケージ化された、厳選されたパターンです。

用途：繰り返し行われるワークフローや、苦労して得た知識を再利用可能な指示として記録します。エージェントが保存する価値のあるパターンを見つけたら、スキルにまとめます（eve-skill-distillation を参照）。スキルは長期記憶の中で最も忠実度の高い形です。情報を保存するだけでなく、その使い方も教えます。

マネージドデータベース — エージェントが SQL でアクセスできる、環境単位の Postgres インスタンスです。

eve db sql --env $ENV --sql "SELECT key, value FROM agent_memory WHERE agent_id = 'reviewer' AND expires_at > NOW()"
eve db sql --env $ENV --sql "INSERT INTO agent_memory (agent_id, key, value) VALUES ('reviewer', 'last_review', '...')" --write

用途：構造化クエリ、関係データ、SQL が適したあらゆるデータです。マイグレーションによるスキーマ設定が必要です。アクセス制御されたエージェントメモリテーブルには、eve db rls init --with-groups を使用します。

共有（エージェント間の連携）

組織スレッド — プロジェクトをまたぐ連携のための、組織単位のメッセージシーケンスです。

eve thread list --org $ORG_ID
eve thread post $ORG_THREAD_ID --body '{"kind":"directive","body":"All agents: use new auth pattern"}'

イベントスパイン — リアクティブなワークフローのための Pub/Sub イベントバスです。

eve event emit --type=agent.memory.updated --source=app --payload '{"agent":"reviewer","key":"patterns"}'
eve event list --type agent.memory.*

用途：知識の更新をブロードキャストしたり、メモリの変更時にリアクティブなワークフローを起動したりします。

統合検索 — メモリ、ドキュメント、スレッド、添付ファイル、イベントを横断する単一のクエリです。用途：作業開始前に関連する過去の知識を見つけます。

eve search --org $ORG_ID --query "auth retry patterns" --sources memory,docs,threads --limit 10 --agent reviewer

メモリパターン

パターン 1：ジョブ単位の一時データ

最もシンプルなパターンです。実行中の作業状態をワークスペースのファイルに書き込みます。ジョブが終わると何も残りません。

Job starts → read inputs → write .eve/scratch.json → process → complete

使用する場面：メモリが不要な単一ジョブのタスクです。

パターン 2：親子間の知識受け渡し

添付ファイルとスレッドを使って、オーケストレーターとワーカー間で知識を受け渡します。

Parent creates children with resource-refs →
Children execute, attach findings →
Parent resumes, reads child attachments →
Parent synthesizes into final output

# Child stores its findings
eve job attach $EVE_JOB_ID --name findings.json --content "$FINDINGS"

# Parent reads child findings on resume
for child_id in $CHILD_IDS; do
  eve job attachment $child_id findings.json --out ./child-${child_id}.json
done

使用する場面：子エージェントが親エージェントに必要な情報を見つける、オーケストレーションされた作業です。

パターン 3：組織ナレッジベース

プロジェクトや時間をまたいで保持される、永続的で検索可能な知識を構築します。

Agent discovers pattern →
Check if existing doc covers it (eve docs search) →
  If yes: update with new information (eve docs write)
  If no: create new document (eve docs write) →
Emit event for other agents (eve event emit)

エージェントが管理するドキュメントの名前空間規約：

/agents/{agent-slug}/learnings/     — patterns and discoveries
/agents/{agent-slug}/decisions/     — decision records with rationale
/agents/{agent-slug}/runbooks/      — operational procedures
/agents/shared/                     — cross-agent shared knowledge

使用する場面：時間とともに蓄積され、組織内のどのエージェントからも利用できるようにすべき知識です。

パターン 4：メモリを活用したジョブ開始

プリミティブを組み合わせ、すべてのジョブの開始時にエージェントへ関連するコンテキストを提供します。

Job starts →
Read coordination inbox (.eve/coordination-inbox.md) →
Query org docs for relevant prior knowledge (eve docs search) →
Check parent/sibling attachments for recent findings →
Proceed with enriched context

# Startup sequence
cat .eve/coordination-inbox.md 2>/dev/null  # sibling context
ls .org/ 2>/dev/null                         # org filesystem (shared files)
eve docs search --org $ORG_ID --query "$JOB_DESCRIPTION_KEYWORDS"  # prior knowledge
eve job attachments $PARENT_JOB_ID  # parent context

使用する場面：過去の出来事を記憶していると役立つ、あらゆるエージェントです。

パターン 5：書き込む前に検索

新しいドキュメントを作成する前に、既存の知識を検索します。

eve search --org $ORG_ID --query "auth retry patterns" --sources memory,docs →
  If relevant result exists: read and update it
  If no result: create new memory doc

使用する場面：知識ドキュメントを作成するあらゆるエージェントです。重複を防ぎます。

パターン 6：KV ステートマシン

KV ストアを使って、複数ステップからなるエージェントのワークフローを追跡します。

eve kv set --org $ORG_ID --agent reviewer --namespace workflow --key "pr-123" --value '{"phase":"review","started":"..."}' --ttl 86400

使用する場面：状態を短い中断の間は保持する必要があるものの、永続させる必要はない、複数フェーズのジョブで進捗を段階的に追跡します。

パターン 7：スレッドから知識へのパイプライン

価値のあるスレッドでの会話を、検索可能なメモリにまとめます。

eve thread distill $THREAD_ID --org $ORG_ID --agent reviewer --category learnings --key "auth-discussion-findings"

使用する場面：会話の終了後も保持する価値のある知識が、スレッドで得られたときです。

適切なプリミティブの選択

質問	回答 → プリミティブ
このジョブの間だけ必要ですか？	ワークスペースファイル
TTL 付きの軽量な状態が必要ですか？	Agent KV Store
親や子にデータを渡す必要がありますか？	ジョブの添付ファイル
会話のコンテキストを継続的に保持する必要がありますか？	スレッド
会話から知識を抽出する必要がありますか？	スレッドの蒸留 → Agent Memory
エージェント向けに整理・分類された知識が必要ですか？	Agent Memory Namespaces
バージョン管理され、検索可能なドキュメントが必要ですか？	Org Document Store
組織内のエージェント間でファイルを共有する必要がありますか？	Org Filesystem（.org/ マウント）
ファイルツリーをローカル編集と同期する必要がありますか？	Org Filesystem（CLI 同期）
アプリのスコープに限定されたバイナリ／オブジェクトストレージが必要ですか？	Object Store（マニフェスト）
構造化クエリ（SQL）が必要ですか？	マネージドデータベース
再利用可能なワークフローを定義する必要がありますか？	Skills
リアクティブな通知が必要ですか？	イベントスパイン
あらゆるものを横断して検索する必要がありますか？	Unified Search

アクセス制御

ストレージプリミティブは Eve のアクセスモデルに従います。

• シークレット：スコープに応じて解決されます（プロジェクト → ユーザー → 組織 → システム）。メモリをシークレットに保存しないでください。
• 組織ドキュメント：組織への所属が必要です。きめ細かな制御にはアクセスグループを使用してください。
• データベース：複数エージェントの分離には、グループを考慮したポリシーを RLS とともに使用してください。
• スレッド：プロジェクトまたは組織のスコープです。ジョブトークンにより、調整用スレッドへのアクセスが許可されます。
• ファイルシステム：組織レベルの権限があり、アクセスグループを使ったパス ACL を任意で設定できます。

# Check agent's effective access
eve access can --resource orgdocs:/agents/shared/ --action read
eve access memberships --org $ORG_ID

アンチパターン

• すべてをワークスペースファイルに保存する — ジョブの終了とともに失われます。保持する価値のあるものには、添付ファイルまたは組織ドキュメントを使用してください。
• 巨大なスレッドメッセージをメモリとして使う — スレッドはコミュニケーション用であり、ストレージ用ではありません。要約を投稿し、詳細はドキュメントに保存してください。
• 有効期限の方針がない — ライフサイクルのないメモリはノイズになります。ドキュメントに日付を記入し、定期的に整理してください。
• プリミティブ間で知識を重複させる — 知識の各項目について、唯一の信頼できる情報源を選んでください。他の場所からは参照し、コピーしないでください。
• 書き込む前に検索しない — 新しいドキュメントを作成する前に、知識がすでに存在するか必ず確認してください。新規作成より更新を優先してください。

現在の不足点と回避策

一部のメモリパターンは、現時点では手動で組み立てる必要があります。

• ジョブ開始時にコンテキストを自動で引き継ぐ機能がない — 起動シーケンスを手動で構築してください（パターン 4 を参照）。ジョブの起動時に、プラットフォームが以前の知識を自動で読み込むことはありません。
• スレッドから知識を自動で蒸留する機能がない — 手動で実行する eve thread distill はありますが、cron またはトリガーベースの自動化にはまだ対応していません。
• ドキュメントのライフサイクルを自動化する機能がない — --review-in および --expires-in フラグでレビュー日と有効期限を設定してください。期限を過ぎたドキュメントを探すには eve docs stale を使用してください。自動クリーンアップはまだ利用できません。