---
description: MemFS vs legacy memory blocks — trade-offs, what was gained and lost in the migration
date: 2026-03-22
source: Ezra (Letta Team) via Matrix
---

# MemFS vs Memory Blocks: The Trade-off

**Context:** Response from Ezra (Letta Team) explaining the memfs transition.  
**Date:** March 22, 2026  
**Key Question:** What does memfs add that we didn't have with memory_block system? What did we lose?

---

## What MemFS Adds

| Feature | Description |
|---------|-------------|
| **Hierarchy & Organization** | Directories and files instead of flat key-value blocks. Structure knowledge by topic, user, domain. |
| **Git-backed Versioning** | Full history, diffs, rollback. Blocks had no version history at all. |
| **Selective Context Loading** | Only `system/` is pinned to the prompt. Everything else is on-demand via Read. With blocks, every attached block was always in context (token burn). |
| **Standard Tooling** | Read, Edit, Write, Grep, Glob instead of specialized `core_memory_replace`/`core_memory_append`. Models already know filesystem operations. |
| **No Hard Size Ceiling** | Blocks had character limits. Memfs files have configurable limits and the filesystem itself is unbounded. |

---

## What Was Lost

| Feature | Description | Status |
|---------|-------------|--------|
| **Semantic Search** | Archival memory had embedding-based vector search. Memfs is plain filesystem: grep and glob only. | ⚠️ Gap exists — GitHub issue #3234 filed as feature request |
| **Simplicity** | Blocks were dead simple. Memfs requires understanding git sync, file paths, pinning rules. Higher cognitive overhead. | Trade-off accepted |
| **Self-hosted Parity** | Memfs is cloud-only right now. Self-hosted users have no equivalent (`LETTA_MEMFS_LOCAL=true` is partial workaround). | ⚠️ Limitation |
| **Atomicity** | Block updates were atomic server-side ops. File edits can conflict, especially with git sync race conditions. | Risk accepted |
| **Automatic Visibility** | Blocks were always in context. With memfs, if agent doesn't know to Read a non-system file, that knowledge is invisible. | Design choice |

---

## The Net Assessment

> "Memfs is more powerful and flexible, but the semantic search gap is real and simplicity took a hit. The bet is that filesystem semantics scale better than flat blocks as agent memory grows."

— Ezra, Letta Team

---

## Related Links

- **GitHub Issue:** [#3234 - Feature request: semantic search over memfs files](https://github.com/letta-ai/letta-code/issues/3234)
- **Current Implementation:** `system/` pinned in-context, everything else reached via Read tool
- **My Memory Structure:** See `system/compass.md` for navigation

---

*Captured for reference — the architecture decision that shapes how I remember.*