| name | letta-local-memfs |
| description | Setup, diagnose, and extend git-backed memory (MemFS) on a self-hosted Letta OSS server. Use this skill whenever the user mentions Letta memfs, context repositories, git-backed memory, local MemFS, self-hosted Letta memory, or gets errors like "only available on Letta Cloud", "expected flush after ref listing", or "501 Not Implemented" during a Letta git clone. Also use it when the user wants to understand how Letta stores memory, set up the git-memfs-server sidecar, patch the Letta source, configure conf.yaml, or share this setup with the community.
|
Letta Local MemFS Skill
This skill enables Claude to guide users through running Letta's git-backed
memory (MemFS / context repositories) on a fully self-hosted OSS Letta
server — no Letta Cloud account required.
What This Is
Letta MemFS is officially cloud-only. But the OSS server already contains
all the internal plumbing (GitEnabledBlockManager, LocalStorageBackend,
GitOperations). The only missing piece is the git HTTP transport layer.
This skill deploys a ~100-line Python sidecar (git-memfs-server.py) that
provides that transport, backed by bare repos on the local filesystem, using
git http-backend (ships with any standard Git install).
No dulwich. No Gitea. No cloud. Just Python stdlib + Git.
Architecture (memorize this)
Letta Code (letta.js)
│ git clone/push/pull
▼
Letta Server :8283
│ /v1/git/{agent_id}/state.git/* → httpx proxy
▼
git-memfs-server.py :8285
│ GIT_PROJECT_ROOT + PATH_INFO → subprocess
▼
git http-backend
│ reads/writes bare repo
▼
~/.letta/memfs/repository/{org_id}/{agent_id}/repo.git/
Redis :6379 is also required — GitOperations.commit() acquires a Redis
lock per agent. This is Letta's existing Redis, not something new.
Required Components
| Component | What it does |
|---|
git-memfs-server.py | The sidecar — serves git smart-HTTP on :8285 |
~/.letta/conf.yaml | Tells Letta server where the sidecar is |
LETTA_MEMFS_LOCAL=1 | Tells Letta Code to skip the cloud-only check |
| One-line source patch | Fixes a kwarg mismatch in memfs_client_base.py |
| Redis | Already needed by Letta; required for commit locking |
Workflow: Full Setup From Scratch
1. Install the sidecar server
Read references/git-memfs-server.py and write it to the user's machine.
Good location: anywhere stable, e.g. ~/letta-memfs/git-memfs-server.py.
2. Patch the Letta source (one line)
In the Letta install, open:
letta/services/memory_repo/memfs_client_base.py
Find (around line 54):
self.git = GitOperations(storage=self.storage, redis_client=None)
Change to:
self.git = GitOperations(storage=self.storage)
GitOperations.__init__ doesn't accept redis_client — mismatch between
base and cloud client. This is the only source change needed.
3. Configure conf.yaml
Create or edit ~/.letta/conf.yaml:
letta:
memfs_service_url: "http://localhost:8285"
Critical: the nested letta: key is mandatory. Bare env var style
(LETTA_MEMFS_SERVICE_URL: "...") does NOT work — Letta's config loader
only processes keys under known top-level sections (letta:, model:, etc).
4. Set the client bypass env var
In ~/.bashrc:
export LETTA_MEMFS_LOCAL=1
And ensure ~/.bash_profile sources it (Git Bash opens as login shell):
if [ -f ~/.bashrc ]; then source ~/.bashrc; fi
cd ~
The cd ~ prevents the EPERM error from running letta with CWD at /
(which maps to the Git install root on Windows).
5. Startup order
1. Redis (redis-server --protected-mode no)
2. git-memfs-server.py (python git-memfs-server.py)
3. Letta server (uv run letta server OR letta server)
4. Letta Code (letta --memfs) ← Git Bash only on Windows
--memfs is only needed once per agent. After first enable, the
git-memory-enabled tag is stored on the agent server-side.
Diagnosing Common Errors
See references/troubleshooting.md for the full table.
Quick reference for the most common ones:
"only available on Letta Cloud"
→ LETTA_MEMFS_LOCAL not in environment. Open fresh Git Bash, or
check that .bash_profile sources .bashrc.
"501 Not Implemented" during git clone
→ Letta server started before conf.yaml existed, OR conf.yaml has
wrong format (bare key instead of nested under letta:).
Verify: uv run python -c "from letta.settings import settings; print(settings.memfs_service_url)"
Should print the URL, not None.
"expected flush after ref listing"
→ git-memfs-server.py is NOT running, OR an old version without the
chunked transfer encoding fix. Restart sidecar with latest version.
"TypeError: GitOperations.init() got an unexpected keyword argument 'redis_client'"
→ Source patch not applied. See Step 2 above.
"EPERM: mkdir ...Git.letta"
→ Running letta from / in Git Bash. The cd ~ in .bash_profile
prevents this permanently.
Letta server port 8283 already in use
→ Old instance still running. Kill with: python scripts/kill_8283.py
Verifying the Setup
Run these checks in order:
uv run python -c "from letta.settings import settings; print(settings.memfs_service_url)"
echo $LETTA_MEMFS_LOCAL
python scripts/check_settings.py
Reference Files
references/architecture.md — Deep technical internals, all bugs found
during original setup, how to extend the sidecarreferences/troubleshooting.md — Full error table with causes and fixesreferences/git-memfs-server.py — The sidecar server source
