syncing-memory-filesystem

Git 連携メモリリポジトリ

git-memory-enabled タグを持つエージェントは、Letta API 経由でアクセスできる git リポジトリにメモリブロックが保存されます。これにより、エージェントのメモリをバージョン管理、共同編集、および外部から編集できるようになります。

機能：

• クラウド（GCS）に保存
• $LETTA_BASE_URL/v1/git/<agent-id>/state.git からアクセス可能
• 双方向同期：API <-> Git（webhook によるトリガー、約2～3秒の遅延）
• 構造：システムブロックは memory/system/*.md

CLI ハーネスが自動的に行うこと

memfs が有効な場合、Letta Code CLI は自動的に次の処理を行います。

1. エージェントに git-memory-enabled タグを追加します（バックエンドで git リポジトリが作成されます）
2. リポジトリを ~/.letta/agents/<agent-id>/memory/ にクローンします（git のルートは memory ディレクトリです）
3. memory/.git/config にローカルの認証情報ヘルパーを設定します（認証の手間なく git push／git pull を実行できます）
4. 各コミット前にフロントマターを検証するpre-commit フックをインストールします（下記を参照）
5. 任意の追加リモートにコミットをプッシュするpost-commit フックをインストールします（下記の「追加のメモリリポジトリリモート」を参照）
6. 正規のローカル git ID（letta.agentId、user.name、user.email）を設定します。これにより、エージェントのシェルから直接 git commit しても、オペレーターのグローバル git ID ではなく、エージェントに正しく関連付けられます
7. 以降の起動時に、最新の変更をプルし、認証情報、フック、ID を再設定します（自己修復）
8. セッション中、定期的に git status を確認し、変更がある場合はコミット／プッシュするようあなた（エージェント）に促します

これらの手順で問題が発生した場合は、以下のセクションを使って手動で同じ設定を行えます。

認証（推奨：リポジトリローカル）

ハーネスはクローン時にリポジトリごとの認証情報ヘルパーを設定し、プル／起動時に更新します。 このローカル設定がデフォルトであり、推奨される方法です。

重要な理由：ホストレベルのグローバル認証情報ヘルパー（他のツールによってインストールされたものなど）が memfs 認証と競合し、原因の分かりにくいエラーを引き起こすことがあります。

重要： 認証情報ヘルパーは必ず1行形式で使用してください。複数行のヘルパーは、git config --list を1行ずつ解析するツールで問題を起こすことがあります。

cd ~/.letta/agents/<agent-id>/memory

# Check local helper(s)
git config --local --get-regexp '^credential\..*\.helper$'

# Reconfigure local helper (e.g. after API key rotation) - SINGLE LINE
git config --local credential.$LETTA_BASE_URL.helper '!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'

グローバルヘルパーの競合が疑われる場合は、ホスト固有のグローバル設定を確認して削除してください。

# Inspect Letta-related global helpers
git config --global --get-regexp '^credential\..*letta\.com.*\.helper$'

# Example: clear a conflicting host-specific helper
git config --global --unset-all credential.https://api.letta.com.helper

別のエージェントのリポジトリをクローンする場合は、グローバルな認証設定を変更するのではなく、一時的な認証ヘッダーを使うことをおすすめします。

AUTH_HEADER="Authorization: Basic $(printf 'letta:%s' "$LETTA_API_KEY" | base64 | tr -d '\n')"
git -c "http.extraHeader=$AUTH_HEADER" clone "$LETTA_BASE_URL/v1/git/<agent-id>/state.git" ~/my-agent-memory

Pre-Commit フック（フロントマターの検証）

ハーネスは、各コミット前に memory/ 以下の .md ファイルを検証する git pre-commit フックをインストールします。これにより、サーバーに拒否されるプッシュを防ぎます。

ルール：

• すべての .md ファイルに YAML フロントマター（--- で始まり、--- で閉じるヘッダー）が必要です
• 必須フィールド：description（空でない文字列）
• read_only は保護されたフィールドです。あなた（エージェント）は追加、削除、変更できません。read_only: true のファイルは一切変更できません。このフィールドを設定できるのはサーバー／ユーザーのみです
• 不明なフロントマターのキーは拒否されます

有効なファイル形式：

---
description: What this block contains
---

Block content goes here.

フックによってコミットが拒否された場合は、エラーメッセージを確認してください。違反したファイルとルールが正確に示されます。ファイルを修正して再試行してください。

追加のメモリーリポジトリーリモート

Letta サーバーへのプッシュに加えて、すべてのコミットを 2 つ目の Git リモート（たとえば、プライベートな GitHub リポジトリー）にもプッシュできます。これにより、バックアップを作成したり、通常のツールで閲覧できるコピーを用意したりできます。

スラッシュコマンドを使用する場合（推奨）：

/memory-repository set [email protected]:you/my-memory.git
/memory-repository status
/memory-repository push        # force a push now, e.g. after a network failure
/memory-repository unset       # stop pushing

仕組み：

• /memory-repository set <url> は、URL を memfs リポジトリーのローカルな .git/config の letta.memoryRepository.url に書き込み、post-commit フックをインストールします。
• コミットのたびに、フックが letta.memoryRepository.url を読み取り、バックグラウンドで非同期にプッシュします。プッシュに失敗しても、コミットがブロックされることはありません。
• プッシュの出力と終了コードは .git/memory-repository-push.log に追記されます。/memory-repository status で確認できます。
• 設定はリポジトリーごとに適用されるため、マシン上の各エージェントがそれぞれ独立した設定を持ちます。

認証： 既存の Git 認証情報（SSH キー、認証情報ヘルパー、または URL 内のトークン）を使用します。この機能のために Letta がトークンを保存することはありません。GitHub にプッシュする場合は、SSH が最も簡単です。

手動での同等の設定（スラッシュコマンドを使用しない場合）：

cd ~/.letta/agents/<agent-id>/memory
git config --local letta.memoryRepository.url [email protected]:you/my-memory.git
# Hook is installed automatically by the CLI on startup; no manual install needed.

エージェントメモリーをクローンする

# Clone agent's memory repo
git clone "$LETTA_BASE_URL/v1/git/<agent-id>/state.git" ~/my-agent-memory

# View memory blocks
ls ~/my-agent-memory/memory/system/
cat ~/my-agent-memory/memory/system/human.md

Git メモリーを有効にする（手動）

ハーネスでの /memfs enable に失敗した場合は、次の手順で同じ設定を行えます。

AGENT_ID="<your-agent-id>"
AGENT_DIR=~/.letta/agents/$AGENT_ID
MEMORY_REPO_DIR="$AGENT_DIR/memory"

# 1. Add git-memory-enabled tag (IMPORTANT: preserve existing tags!)
# First GET the agent to read current tags, then PATCH with the new tag appended.
# The harness code does: tags = [...existingTags, "git-memory-enabled"]
curl -X PATCH "$LETTA_BASE_URL/v1/agents/$AGENT_ID" \
  -H "Authorization: Bearer $LETTA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tags": ["origin:letta-code", "git-memory-enabled"]}'

# 2. Clone the repo into memory/
mkdir -p "$MEMORY_REPO_DIR"
git clone "$LETTA_BASE_URL/v1/git/$AGENT_ID/state.git" "$MEMORY_REPO_DIR"

# 3. Configure local credential helper (single-line format required)
cd "$MEMORY_REPO_DIR"
git config --local credential.$LETTA_BASE_URL.helper '!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'

双方向同期

API の編集 → Git のプル

# 1. Edit block via API (or use memory tools)
# 2. Pull to get changes (webhook creates commit automatically)
cd ~/.letta/agents/<agent-id>/memory
git pull

API 経由で行った変更は、2～3 秒以内に Git に自動でコミットされます。

Git のプッシュ → API の更新

cd ~/.letta/agents/<agent-id>/memory

# 1. Edit files locally
echo "Updated info" > system/human.md

# 2. Commit and push
git add system/human.md
git commit -m "fix: update human block"
git push

# 3. API automatically reflects changes (webhook-triggered, ~2-3s delay)

競合の解決

API と Git の両方で変更が加えられた場合：

cd ~/.letta/agents/<agent-id>/memory

# 1. Try to push (will be rejected)
git push  # -> "fetch first"

# 2. Pull to create merge conflict
git pull --no-rebase
# -> CONFLICT in system/human.md

# 3. View conflict markers
cat system/human.md
# <<<<<<< HEAD
# your local changes
# =======
# server changes
# >>>>>>> <commit>

# 4. Resolve
echo "final resolved content" > system/human.md
git add system/human.md
git commit -m "fix: resolved conflict in human block"

# 5. Push resolution
git push
# -> API automatically updates with resolved content

ブロックの管理

新しいブロックを作成する

# Create file in system/ directory (automatically attached to agent)
echo "My new block content" > system/new-block.md
git add system/new-block.md
git commit -m "feat: add new block"
git push
# -> Block automatically created and attached to agent

ブロックを削除／切り離す

# Remove file from system/ directory
git rm system/persona.md
git commit -m "chore: remove persona block"
git push
# -> Block automatically detached from agent

ディレクトリー構造

~/.letta/agents/<agent-id>/
├── .letta/
│   └── config.json              # Agent metadata
└── memory/                      # Git repo root
    ├── .git/                    # Git repo data
    └── system/                  # System blocks (attached to agent)
        ├── human.md
        └── persona.md

システムブロック（memory/system/）はエージェントにアタッチされ、エージェントのシステムプロンプトに表示されます。

要件

• エージェントに git-memory-enabled タグが付いていること
• エージェントへのアクセス権がある有効な API キー
• ローカルに Git がインストールされていること

トラブルシューティング

「Authentication failed」と表示され、クローンに失敗する場合：

• ローカルのヘルパーを確認します：git -C ~/.letta/agents/<agent-id>/memory config --local --get-regexp '^credential\..*\.helper$'
• 競合するグローバルヘルパーがないか確認します：git config --global --get-regexp '^credential\..*letta\.com.*\.helper$'
• ローカルのヘルパーを再設定します。上記の「認証」セクションを参照してください
• エンドポイントにアクセスできることを確認します：curl -u letta:$LETTA_API_KEY $LETTA_BASE_URL/v1/git/<agent-id>/state.git/info/refs?service=git-upload-pack

プッシュ／プルしても API が更新されない場合：

• Webhook の処理に 2～3 秒かかるため、しばらく待ちます
• エージェントに git-memory-enabled タグが付いていることを確認します
• エージェントへの書き込み権限があることを確認します

ハーネスのセットアップに失敗し、/memfs enable の後に .git/ がない場合：

• デバッグログを確認します（LETTA_DEBUG=1）
• 上記の「Git メモリーを有効にする（手動）」の手順に従います

変更がすぐに表示されない場合：

• Webhook の処理により、双方向同期には 2～3 秒の遅延があります
• git pull を使って最新の API の変更を取得します
• git fetch を使って、マージせずにリモートを確認します