Redflag/reference/PR-memfs-selfhosted.md

PR: Fix MemFS for Self-Hosted and Configurable Backends

Problem

Subagents fail to spawn on self-hosted Letta servers because applyMemfsFlags tries to git clone from http://localhost:8283/v1/git/{agent_id}/state.git, which returns HTTP 501 (Not Implemented) on self-hosted.

Error:

fatal: unable to access 'http://10.10.20.19:8283/v1/git/.../state.git/': 
The requested URL returned error: 501

Root Cause

The current code only checks isLettaCloud() but doesn't handle:

1. Self-hosted servers without git endpoint
2. Future Gitea/Codeberg backends
3. Graceful fallback when remote is unavailable

Solution

E: Local-First Initialization

• Always initialize local git repo first
• Try to pull/clone remote only if available
• Gracefully continue with local state if remote fails

F: Configurable Backend

• Add LETTABOT_MEMFS_BACKEND environment variable:
  • "cloud" - Force Letta Cloud mode
  • "local" - Force local-only (for Gitea/Codeberg)
  • "auto" - Auto-detect (default)
  • "none" - Disable remote sync

Changes

1. src/agent/memoryGit.ts

• Add initLocalMemoryRepo(agentId) function
• Initializes local git repo with proper config
• Creates initial directory structure
• Installs pre-commit hooks

2. src/agent/memoryFilesystem.ts

• Modify applyMemfsFlags to use local-first approach
• Check LETTABOT_MEMFS_BACKEND env var
• Handle 501/404 errors gracefully
• Continue with local state if remote unavailable

Usage

For Self-Hosted (current fix):

# No changes needed - auto-detects and uses local mode
export LETTABOT_MEMFS=true
lettabot start

For Gitea Backend (future):

export LETTABOT_MEMFS=true
export LETTABOT_MEMFS_BACKEND=local
export LETTABOT_MEMFS_REMOTE=https://gitea.example.com/ani/memory.git
lettabot start

For Letta Cloud (unchanged):

export LETTABOT_MEMFS=true
# Works as before with cloud git endpoint

Testing

1. Self-hosted: Subagents now spawn successfully
2. Local repo created: ~/.letta/agents/{id}/memory/.git/
3. Graceful degradation: Works without remote sync

Backwards Compatibility

• Letta Cloud users: No change
• Self-hosted users: Now works (was broken)
• Future Gitea/Codeberg: Supported via LETTABOT_MEMFS_BACKEND

Related

Fixes subagent spawn failures on self-hosted servers. Enables future Gitea/Codeberg integration.