Back to Details

syncing-memory-filesystem

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Git-Backed Memory Repos

基于Git的内存仓库

Agents with the 
git-memory-enabled
tag have their memory blocks stored in git repositories accessible via the Letta API. This enables version control, collaboration, and external editing of agent memory.
Features:
  • Stored in cloud (GCS)
  • Accessible via 
    $LETTA_BASE_URL/v1/git/<agent-id>/state.git
  • Bidirectional sync: API <-> Git (webhook-triggered, ~2-3s delay)
  • Structure: 
    memory/system/*.md
    for system blocks
带有
git-memory-enabled
标签的Agent，其内存块会存储在可通过Letta API访问的Git仓库中。这实现了Agent内存的版本控制、协作和外部编辑功能。
功能特性：
  • 存储在云端（GCS）
  • 可通过
    $LETTA_BASE_URL/v1/git/<agent-id>/state.git
    访问
  • 双向同步：API <-> Git（由Webhook触发，延迟约2-3秒）
  • 结构：
    memory/system/*.md
    用于存储系统块

What the CLI Harness Does Automatically

CLI工具自动完成的操作

When memfs is enabled, the Letta Code CLI automatically:
  1. Adds the 
    git-memory-enabled
    tag to the agent (triggers backend to create the git repo)
  2. Clones the repo into 
    ~/.letta/agents/<agent-id>/memory/
    (git root is the memory directory)
  3. Configures a local credential helper in 
    memory/.git/config
    (so 
    git push
    /
    git pull
    work without auth ceremony)
  4. Installs a pre-commit hook that validates frontmatter before each commit (see below)
  5. On subsequent startups: pulls latest changes, reconfigures credentials and hook (self-healing)
  6. During sessions: periodically checks 
    git status
    and reminds you (the agent) to commit/push if dirty
If any of these steps fail, you can replicate them manually using the sections below.
当启用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. 安装提交前钩子，在每次提交前验证前置元数据（详见下文）
  5. 后续启动时：拉取最新变更，重新配置凭证和钩子（自修复）
  6. 会话期间：定期检查
    git status
    ，若存在未提交变更则提醒你（Agent）进行提交/推送
如果上述任何步骤失败，你可以使用下文的步骤手动完成。

Authentication

认证

The harness configures a per-repo credential helper during clone. To verify or reconfigure:
bash
cd ~/.letta/agents/<agent-id>/memory
工具会在克隆期间为每个仓库配置凭证助手。如需验证或重新配置：
bash
cd ~/.letta/agents/<agent-id>/memory

Check if configured

检查是否已配置

git config --get credential.$LETTA_BASE_URL.helper
git config --get credential.$LETTA_BASE_URL.helper

Reconfigure (e.g. after API key rotation)

重新配置（例如API密钥轮换后）

git config credential.$LETTA_BASE_URL.helper
'!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'

For cloning a *different* agent's repo (e.g. during memory migration), set up a global helper:

```bash
git config --global credential.$LETTA_BASE_URL.helper \
  '!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'
git config credential.$LETTA_BASE_URL.helper
'!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'

若要克隆其他Agent的仓库（例如内存迁移时），请设置全局助手：

```bash
git config --global credential.$LETTA_BASE_URL.helper \
  '!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'

Pre-Commit Hook (Frontmatter Validation)

提交前钩子（前置元数据验证）

The harness installs a git pre-commit hook that validates 
.md
files under 
memory/
before each commit. This prevents pushes that the server would reject.
Rules:
  • Every 
    .md
    file must have YAML frontmatter (
    ---
    header and closing 
    ---
    )
  • Required fields: 
    description
    (non-empty string), 
    limit
    (positive integer)
  • read_only
    is a protected field: you (the agent) cannot add, remove, or change it. Files with 
    read_only: true
    cannot be modified at all. Only the server/user sets this field.
  • Unknown frontmatter keys are rejected
Valid file format:
markdown
---
description: What this block contains
limit: 20000
---

Block content goes here.
If the hook rejects a commit, read the error message — it tells you exactly which file and which rule was violated. Fix the file and retry.
工具会安装一个Git提交前钩子，在每次提交前验证
memory/
下的
.md
文件。这可以避免服务器拒绝的推送操作。
规则：
  • 每个
    .md
    文件必须包含YAML前置元数据（以
    ---
    开头和结尾）
  • 必填字段：
    description
    （非空字符串）、
    limit
    （正整数）
  • read_only
    是受保护字段：你（Agent）无法添加、删除或修改它。带有
    read_only: true
    的文件完全不可修改，仅服务器/用户可设置此字段。
  • 未知的前置元数据键会被拒绝
有效文件格式：
markdown
---
description: 此块包含的内容
limit: 20000
---

块内容写在这里。
如果钩子拒绝了提交，请阅读错误信息——它会明确告诉你哪个文件违反了哪条规则。修复文件后重试即可。

Clone Agent Memory

克隆Agent内存

bash
undefined
bash
undefined

Clone agent's memory repo

克隆Agent的内存仓库

git clone "$LETTA_BASE_URL/v1/git/<agent-id>/state.git" ~/my-agent-memory
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
undefined
ls ~/my-agent-memory/memory/system/ cat ~/my-agent-memory/memory/system/human.md
undefined

Enabling Git Memory (Manual)

手动启用Git内存

If the harness 
/memfs enable
failed, you can replicate it:
bash
AGENT_ID="<your-agent-id>"
AGENT_DIR=~/.letta/agents/$AGENT_ID
MEMORY_REPO_DIR="$AGENT_DIR/memory"
如果工具的
/memfs enable
命令失败，你可以手动完成以下步骤：
bash
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!)

1. 添加git-memory-enabled标签（重要：保留现有标签！）

First GET the agent to read current tags, then PATCH with the new tag appended.

先GET Agent信息读取当前标签，再PATCH追加新标签。

The harness code does: tags = [...existingTags, "git-memory-enabled"]

工具代码执行逻辑：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"]}'
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/

2. 将仓库克隆到memory/目录

mkdir -p "$MEMORY_REPO_DIR" git clone "$LETTA_BASE_URL/v1/git/$AGENT_ID/state.git" "$MEMORY_REPO_DIR"
mkdir -p "$MEMORY_REPO_DIR" git clone "$LETTA_BASE_URL/v1/git/$AGENT_ID/state.git" "$MEMORY_REPO_DIR"

3. Configure local credential helper

3. 配置本地凭证助手

cd "$MEMORY_REPO_DIR" git config credential.$LETTA_BASE_URL.helper
'!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'
undefined
cd "$MEMORY_REPO_DIR" git config credential.$LETTA_BASE_URL.helper
'!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f'
undefined

Bidirectional Sync

双向同步

API Edit -> Git Pull

API编辑 -> Git拉取

bash
undefined
bash
undefined

1. Edit block via API (or use memory tools)

1. 通过API编辑块（或使用内存工具）

2. Pull to get changes (webhook creates commit automatically)

2. 拉取变更（Webhook会自动创建提交）

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

Changes made via the API are automatically committed to git within 2-3 seconds.
cd ~/.letta/agents/<agent-id>/memory git pull

通过API做出的变更会在2-3秒内自动提交到Git。

Git Push -> API Update

Git推送 -> API更新

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

1. Edit files locally

1. 本地编辑文件

echo "Updated info" > system/human.md
echo "更新后的信息" > system/human.md

2. Commit and push

2. 提交并推送

git add system/human.md git commit -m "fix: update human block" git 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)

3. API会自动同步变更（Webhook触发，延迟约2-3秒）

undefined
undefined

Conflict Resolution

冲突解决

When both API and git have diverged:
bash
cd ~/.letta/agents/<agent-id>/memory
当API和Git内容出现分歧时：
bash
cd ~/.letta/agents/<agent-id>/memory

1. Try to push (will be rejected)

1. 尝试推送（会被拒绝）

git push # -> "fetch first"
git push # -> "fetch first"

2. Pull to create merge conflict

2. 拉取变更以创建合并冲突

git pull --no-rebase
git pull --no-rebase

-> CONFLICT in system/human.md

-> CONFLICT in system/human.md

3. View conflict markers

3. 查看冲突标记

cat system/human.md
cat system/human.md

<<<<<<< HEAD

<<<<<<< HEAD

your local changes

你的本地变更

=======

=======

server changes

服务器变更

>>>>>>> <commit>

>>>>>>> <commit>

4. Resolve

4. 解决冲突

echo "final resolved content" > system/human.md git add system/human.md git commit -m "fix: resolved conflict in human block"
echo "最终的已解决内容" > system/human.md git add system/human.md git commit -m "fix: resolved conflict in human block"

5. Push resolution

5. 推送解决后的内容

git push
git push

-> API automatically updates with resolved content

-> API会自动更新为已解决的内容

undefined
undefined

Block Management

块管理

Create New Block

创建新块

bash
undefined
bash
undefined

Create file in system/ directory (automatically attached to agent)

在system/目录下创建文件（会自动关联到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
echo "我的新块内容" > 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

-> 块会自动创建并关联到Agent

undefined
undefined

Delete/Detach Block

删除/分离块

bash
undefined
bash
undefined

Remove file from system/ directory

从system/目录中移除文件

git rm system/persona.md git commit -m "chore: remove persona block" git push
git rm system/persona.md git commit -m "chore: remove persona block" git push

-> Block automatically detached from agent

-> 块会自动从Agent中分离

undefined
undefined

Directory Structure

目录结构

~/.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
System blocks (
memory/system/
) are attached to the agent and appear in the agent's system prompt.
~/.letta/agents/<agent-id>/
├── .letta/
│   └── config.json              # Agent元数据
└── memory/                      # Git仓库根目录
    ├── .git/                    # Git仓库数据
    └── system/                  # 系统块（关联到Agent）
        ├── human.md
        └── persona.md
系统块（
memory/system/
）会关联到Agent，并出现在Agent的系统提示词中。

Requirements

要求

  • Agent must have 
    git-memory-enabled
    tag
  • Valid API key with agent access
  • Git installed locally
  • Agent必须带有
    git-memory-enabled
    标签
  • 拥有可访问Agent的有效API密钥
  • 本地已安装Git

Troubleshooting

故障排除

Clone fails with "Authentication failed":
  • Check credential helper: 
    git config --get credential.$LETTA_BASE_URL.helper
  • Reconfigure: see Authentication section above
  • Verify the endpoint is reachable: 
    curl -u letta:$LETTA_API_KEY $LETTA_BASE_URL/v1/git/<agent-id>/state.git/info/refs?service=git-upload-pack
Push/pull doesn't update API:
  • Wait 2-3 seconds for webhook processing
  • Verify agent has 
    git-memory-enabled
    tag
  • Check if you have write access to the agent
Harness setup failed (no .git/ after /memfs enable):
  • Check debug logs (
    LETTA_DEBUG=1
    )
  • Follow "Enabling Git Memory (Manual)" steps above
Can't see changes immediately:
  • Bidirectional sync has a 2-3 second delay for webhook processing
  • Use 
    git pull
    to get latest API changes
  • Use 
    git fetch
    to check remote without merging
克隆失败，提示“Authentication failed”：
  • 检查凭证助手：
    git config --get credential.$LETTA_BASE_URL.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的写入权限
工具设置失败（执行/memfs enable后无.git/目录）：
  • 查看调试日志（
    LETTA_DEBUG=1
    ）
  • 按照上文“手动启用Git内存”的步骤操作
无法立即看到变更：
  • 双向同步因Webhook处理存在2-3秒延迟
  • 使用
    git pull
    获取API的最新变更
  • 使用
    git fetch
    检查远程变更，无需合并