From a1db9acbebd8834eb949eecdb9b6e5a46d65cf8e Mon Sep 17 00:00:00 2001 From: Sarah Wooders Date: Thu, 19 Feb 2026 20:52:12 -0800 Subject: [PATCH] docs(skills): prefer repo-local memfs auth and warn on global helper conflicts (#1054) --- .../builtin/initializing-memory/SKILL.md | 2 +- .../syncing-memory-filesystem/SKILL.md | 38 +++++++++++++------ 2 files changed, 27 insertions(+), 13 deletions(-) diff --git a/src/skills/builtin/initializing-memory/SKILL.md b/src/skills/builtin/initializing-memory/SKILL.md index 19de22c..432e77f 100644 --- a/src/skills/builtin/initializing-memory/SKILL.md +++ b/src/skills/builtin/initializing-memory/SKILL.md @@ -717,4 +717,4 @@ git push | Subagent exits with code `null`, 0 tool uses | `letta.js` not built | Run `bun run build` | | Subagent hangs on "Tool requires approval" | Wrong subagent type | Use `subagent_type: "history-analyzer"` (workers) or `"memory"` (synthesis) | | Merge conflict during synthesis | Workers touched overlapping files | Resolve by checking `git log` for context | -| Auth fails on push ("repository not found") | Credential helper broken | Use `http.extraHeader` (see syncing-memory-filesystem skill) | +| Auth fails on push ("repository not found") | Credential helper broken or global helper conflict | Reconfigure **repo-local** helper and check/clear conflicting global `credential..helper` entries (see syncing-memory-filesystem skill) | diff --git a/src/skills/builtin/syncing-memory-filesystem/SKILL.md b/src/skills/builtin/syncing-memory-filesystem/SKILL.md index 0ef70a0..c5d66d2 100644 --- a/src/skills/builtin/syncing-memory-filesystem/SKILL.md +++ b/src/skills/builtin/syncing-memory-filesystem/SKILL.md @@ -26,26 +26,39 @@ When memfs is enabled, the Letta Code CLI automatically: If any of these steps fail, you can replicate them manually using the sections below. -## Authentication +## Authentication (Preferred: Repo-Local) -The harness configures a per-repo credential helper during clone. To verify or reconfigure: +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. ```bash cd ~/.letta/agents//memory -# Check if configured -git config --get credential.$LETTA_BASE_URL.helper +# Check local helper(s) +git config --local --get-regexp '^credential\..*\.helper$' -# Reconfigure (e.g. after API key rotation) -git config credential.$LETTA_BASE_URL.helper \ +# Reconfigure local helper (e.g. after API key rotation) +git config --local 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: +If you suspect global helper conflicts, inspect and clear host-specific global entries: ```bash -git config --global 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 +``` + +For cloning a *different* agent's repo, prefer a one-off auth header over global credential changes: + +```bash +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//state.git" ~/my-agent-memory ``` ## Pre-Commit Hook (Frontmatter Validation) @@ -104,7 +117,7 @@ git clone "$LETTA_BASE_URL/v1/git/$AGENT_ID/state.git" "$MEMORY_REPO_DIR" # 3. Configure local credential helper cd "$MEMORY_REPO_DIR" -git config credential.$LETTA_BASE_URL.helper \ +git config --local credential.$LETTA_BASE_URL.helper \ '!f() { echo "username=letta"; echo "password=$LETTA_API_KEY"; }; f' ``` @@ -216,8 +229,9 @@ git push ## Troubleshooting **Clone fails with "Authentication failed":** -- Check credential helper: `git config --get credential.$LETTA_BASE_URL.helper` -- Reconfigure: see Authentication section above +- Check local helper(s): `git -C ~/.letta/agents//memory config --local --get-regexp '^credential\..*\.helper$'` +- Check for conflicting global helper(s): `git config --global --get-regexp '^credential\..*letta\.com.*\.helper$'` +- Reconfigure local helper: see Authentication section above - Verify the endpoint is reachable: `curl -u letta:$LETTA_API_KEY $LETTA_BASE_URL/v1/git//state.git/info/refs?service=git-upload-pack` **Push/pull doesn't update API:**