syncing-memory-filesystem

基于 Git 的记忆仓库

带有 git-memory-enabled 标签的 Agent 会将其记忆块存储在可通过 Letta API 访问的 Git 仓库中。这样可以对 Agent 记忆进行版本控制、协作和外部编辑。

功能：

• 存储在云端（GCS）
• 可通过 $LETTA_BASE_URL/v1/git/<agent-id>/state.git 访问
• 双向同步：API <-> Git（由 webhook 触发，延迟约为 2-3s）
• 结构：系统块位于 memory/system/*.md

CLI Harness 会自动执行的操作

启用 memfs 后，Letta Code CLI 会自动：

1. 为 Agent 添加 git-memory-enabled 标签（触发后端创建 Git 仓库）
2. 将仓库克隆到 ~/.letta/agents/<agent-id>/memory/（Git 根目录即为 memory 目录）
3. 在 memory/.git/config 中配置本地凭据助手（使 git push/git pull 无需繁琐的认证操作即可正常工作）
4. 安装一个提交前钩子，在每次提交前验证 frontmatter（见下文）
5. 安装一个提交后钩子，将提交推送到可选的附加远程端（见下文“附加记忆仓库远程端”）
6. 设置规范的本地 Git 身份（letta.agentId、user.name、user.email），以便 Agent 的 shell 直接执行 git commit 时，提交者正确归属 Agent，而非操作员的全局 Git 身份
7. 后续启动时：拉取最新更改，重新配置凭据、钩子和身份（自动修复）
8. 会话期间：定期检查 git status，并提醒你（Agent）在有未提交更改时提交/推送

如果上述任一步骤失败，你可以按照以下章节手动执行。

身份验证（首选：仓库本地配置）

Harness 会在克隆期间配置每个仓库单独的凭据助手，并在拉取/启动时刷新该配置。 这种本地配置是默认且推荐的方式。

原因：主机级别的全局凭据助手（例如由其他工具安装的凭据助手）可能会与 memfs 身份验证冲突，导致难以理解的故障。

重要提示：凭据助手必须始终使用单行格式。多行助手可能导致逐行解析 git config --list 的工具出错。

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

要克隆其他 Agent 的仓库，建议使用一次性身份验证标头，而不是更改全局凭据：

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

提交前钩子（Frontmatter 验证）

Harness 会安装一个 Git 提交前钩子，在每次提交前验证 memory/ 下的 .md 文件。这可以避免推送服务器会拒绝的内容。

规则：

• 每个 .md 文件都必须包含 YAML frontmatter（以 --- 开始和结束）
• 必需字段：description（非空字符串）
• read_only 是受保护字段：你（Agent）不能添加、删除或更改该字段。read_only: true 的文件完全不能修改。此字段只能由服务器/用户设置。
• 不接受未知的 frontmatter 键

有效文件格式：

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

Block content goes here.

如果钩子拒绝提交，请阅读错误消息——其中会准确指出违反规则的文件及规则。修复文件后重试。

额外的记忆仓库远程端

除了推送到 Letta 服务之外，你还可以将每次提交推送到第二个 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 查看。
• 此设置按仓库独立配置，因此同一台机器上的每个 Agent 都有各自独立的配置。

**身份验证：**使用你现有的 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.

克隆 Agent 记忆

# 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 记忆（手动操作）

如果 harness 的 /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/）会关联到 Agent，并显示在 Agent 的系统提示词中。

要求

• Agent 必须带有 git-memory-enabled 标签
• 有效且可访问 Agent 的 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：

• 等待 2-3 秒，让 webhook 完成处理
• 确认 Agent 带有 git-memory-enabled 标签
• 检查你是否有权写入该 Agent

Harness 设置失败（运行 /memfs enable 后没有 .git/）：

• 检查调试日志（LETTA_DEBUG=1）
• 按照上文“启用 Git 记忆（手动操作）”中的步骤操作

无法立即看到更改：

• 双向同步需要 2-3 秒处理 webhook
• 使用 git pull 获取最新的 API 更改
• 使用 git fetch 检查远程端，而不进行合并