3d54b46572
- Created reference/memfs_vs_blocks.md with Ezra's explanation of what was gained/lost - Updated compass.md to reference the new file in both reference section and Recently Added - Documents the semantic search gap (#3234) and other trade-offs
56 lines
2.7 KiB
Markdown
56 lines
2.7 KiB
Markdown
---
|
|
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.*
|