/syncing-memory-filesystem

name: syncing-memory-filesystem
description: Manage git-backed memory repos. Load this skill when working with git-backed agent memory, setting up remote memory repos, resolving sync conflicts, or managing memory via git workflows.

Git-Backed Memory Repos

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

What the CLI Harness Does Automatically

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. Installs a **post-commit hook** that pushes commits to an optional additional remote (see "Additional memory-repository remote" below) 6. Sets canonical local git identity (`letta.agentId`, `user.name`, `user.email`) so direct `git commit` from the agent's shell attributes correctly to the agent — not the operator's global git identity 7. On subsequent startups: pulls latest changes, reconfigures credentials, hooks, and identity (self-healing) 8. 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.

Authentication (Preferred: Repo-Local)

The harness configures a **per-repo** credential helper during clone and refreshes it on pull/startup. This local setup is the default and recommended approach.

Why this matters: host-level **global** credential helpers (e.g. installed by other tooling) can conflict with memfs auth and cause confusing failures.

**Important:** Always use **single-line** format for credential helpers. Multi-line helpers can break tools that parse `git config --list` line-by-line.

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'

If you suspect global helper conflicts, inspect and clear host-specific global entries:

# 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

For cloning a *different* agent's repo, prefer a one-off auth header over global credential changes:

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 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)
• `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:**

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

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.

Additional Memory-Repository Remote

In addition to pushing to the Letta server, you can push every commit to a second git remote — e.g. a private GitHub repo — so you have a backup or a copy you can browse with regular tools.

**Via the slash command (recommended):**

/memory-repository set git@github.com: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

**How it works:**

• `/memory-repository set <url>` writes the URL to `letta.memoryRepository.url` in the memfs repo's local `.git/config` and installs a `post-commit` hook.
• After every commit, the hook reads `letta.memoryRepository.url` and asynchronously pushes to it in the background. Commits are never blocked by push failures.
• Push output and exit codes are appended to `.git/memory-repository-push.log` — visible via `/memory-repository status`.
• The setting is **per-repo**, so each agent on a machine has its own independent configuration.

**Auth:** uses your existing git credentials — SSH keys, credential helpers, or tokens in the URL. Letta does not store tokens for this feature. If you're pushing to GitHub, SSH is easiest.

**Manual equivalent (without the slash command):**

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

Clone Agent Memory

# 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

Enabling Git Memory (Manual)

If the harness `/memfs enable` failed, you can replicate it: