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
2.7 KiB
2.7 KiB
description, date, source
| description | date | source |
|---|---|---|
| MemFS vs legacy memory blocks — trade-offs, what was gained and lost in the migration | 2026-03-22 | 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
- Current Implementation:
system/pinned in-context, everything else reached via Read tool - My Memory Structure: See
system/compass.mdfor navigation
Captured for reference — the architecture decision that shapes how I remember.