Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
feat(core): projection-style git memory rendering + local memfs context test skill (#10211)
Sarah Woodersa8e3017326d9
diff --git a/letta/schemas/memory.py b/letta/schemas/memory.pyindex 8fd2d2d07..63937f457 100644--- a/letta/schemas/memory.py+++ b/letta/schemas/memory.py@@ -202,44 +202,123 @@ class Memory(BaseModel, validate_assignment=True):s.write("\n</memory_blocks>")def _render_memory_blocks_git(self, s: StringIO):- """Render memory blocks as individual file tags with YAML frontmatter.-- Each block is rendered as <label.md>---frontmatter---value</label.md>,- matching the format stored in the git repo. Labels without a 'system/'- prefix get one added automatically.-- DEPRECATED: Kept for backward compatibility. New agents use- _render_memory_filesystem_structured() which embeds core memory- inside the <memory_filesystem> tag.+ """Render git-backed system memory with structured tags.++ - `system/persona` is rendered in a dedicated `<self>` section.+ - Other `system/*` blocks are rendered under `<memory>` with nested tags+ derived from their slash-separated labels (dropping the `system/`+ prefix).+ - Files outside `system/` and `skills/` are rendered under+ `<memory><external-memory>...</external-memory></memory>` as metadata-only+ projections."""renderable = self._get_renderable_blocks()if not renderable:return- for idx, block in enumerate(renderable):- label = block.label or "block"- # Ensure system/ prefix- if not label.startswith("system/"):- label = f"system/{label}"- tag = f"{label}.md"- value = block.value or ""+ s.write("\n\nReminder: <projection> contains the local path of the memory file projection.")++ # 1) Dedicated <self> section from system/persona+ persona_block = next((b for b in renderable if (b.label or "") == "system/persona"), None)+ if persona_block is not None:+ s.write("\n\n<self>\n")+ s.write("<projection>$MEMORY_DIR/system/persona.md</projection>\n")+ s.write((persona_block.value or "").rstrip("\n"))+ s.write("\n</self>")++ # 2) Render all other system/* blocks as nested tags under <memory>+ non_persona = [b for b in renderable if (b.label or "") != "system/persona"]+ external_blocks = [+ b+ for b in self.blocks+ if (b.label or "") and not (b.label or "").startswith("system/") and not (b.label or "").startswith("skills/")+ ]+ if not non_persona and not external_blocks:+ return- s.write(f"\n\n<{tag}>\n")+ LEAF_KEY = "__value__"+ LEAF_DESC_KEY = "__description__"+ LEAF_LABEL_KEY = "__label__"- # Build frontmatter (same fields as serialize_block)- front_lines = []- if block.description:- front_lines.append(f"description: {block.description}")- if getattr(block, "read_only", False):- front_lines.append("read_only: true")+ def _build_tree(blocks: list[Block], strip_prefix: str | None = None) -> dict:+ tree: dict = {}+ for block in blocks:+ label = block.label or ""+ if strip_prefix:+ if not label.startswith(strip_prefix):+ continue+ label = label.removeprefix(strip_prefix)- if front_lines:- s.write("---\n")- s.write("\n".join(front_lines))- s.write("\n---\n")+ parts = [p for p in label.split("/") if p]+ if not parts:+ continue- s.write(f"{value}\n")- s.write(f"</{tag}>")+ node = tree+ for part in parts[:-1]:+ if part not in node or not isinstance(node[part], dict):+ node[part] = {}+ node = node[part]++ leaf = parts[-1]+ leaf_node = node.get(leaf)+ desc = (block.description or "").strip()+ original_label = block.label or ""+ if leaf_node is None:+ node[leaf] = {+ LEAF_KEY: block.value or "",+ LEAF_DESC_KEY: desc,+ LEAF_LABEL_KEY: original_label,+ }+ elif isinstance(leaf_node, dict):+ leaf_node[LEAF_KEY] = block.value or ""+ leaf_node[LEAF_DESC_KEY] = desc+ leaf_node[LEAF_LABEL_KEY] = original_label+ else:+ node[leaf] = {+ LEAF_KEY: block.value or "",+ LEAF_DESC_KEY: desc,+ LEAF_LABEL_KEY: original_label,+ }+ return tree++ system_tree = _build_tree(non_persona, strip_prefix="system/")++ def _render_nested(node: dict, indent: int = 0):+ pad = " " * indent+ for key in sorted(k for k in node.keys() if k not in (LEAF_KEY, LEAF_DESC_KEY, LEAF_LABEL_KEY)):+ child = node[key]+ s.write(f"{pad}<{key}>\n")+ if isinstance(child, dict):+ desc = str(child.get(LEAF_DESC_KEY) or "").rstrip("\n")+ if desc:+ s.write(f"{pad} <description>{desc}</description>\n")+ if LEAF_KEY in child:+ value = str(child[LEAF_KEY] or "").rstrip("\n")+ if value:+ s.write(f"{pad} {value}\n")+ _render_nested(child, indent + 1)+ s.write(f"{pad}</{key}>\n")++ s.write("\n\n<memory>\n")+ _render_nested(system_tree)++ # 3) External memory projections (all files outside system/ and skills/)+ if external_blocks:+ s.write("<external-memory>\n")+ s.write("Reminder: external memory must be actively retrieved into context on-demand. Only descriptions are shown below.\n")+ for block in sorted(external_blocks, key=lambda b: b.label or ""):+ label = (block.label or "").strip()+ if not label:+ continue+ s.write(f"<{label}>\n")+ desc = (block.description or "").strip()+ if desc:+ s.write(f"{desc.splitlines()[0].strip()}\n")+ s.write(f"<projection>$MEMORY_DIR/{label}.md</projection>\n")+ s.write(f"</{label}>\n")+ s.write("</external-memory>\n")++ s.write("</memory>")def _render_memory_filesystem(self, s: StringIO, client_skills=None):"""Render a filesystem tree view of all memory blocks.@@ -551,8 +630,7 @@ class Memory(BaseModel, validate_assignment=True):# Memory blocks (not for react/workflow). Always include wrapper for preview/tests.if not is_react:if self.git_enabled:- # Git-enabled: filesystem tree + file-style block rendering- self._render_memory_filesystem(s, client_skills=client_skills)+ # Git-enabled: structured self + memory renderingself._render_memory_blocks_git(s)elif is_line_numbered:self._render_memory_blocks_line_numbered(s)diff --git a/tests/test_memory.py b/tests/test_memory.pyindex 95c7cd22d..52fe0705e 100644--- a/tests/test_memory.py+++ b/tests/test_memory.py@@ -219,8 +219,7 @@ def test_current_files_open_counts_truthy_only():def test_compile_git_structured_core_memory_rendering():- """Git-enabled agents should render system/* blocks as named sections with full content,- and <core_memory> should contain metadata-only entries."""+ """Git-enabled agents should render persona in <self> and other system blocks in nested <memory> tags."""m = Memory(agent_type=AgentType.letta_v1_agent,@@ -233,19 +232,14 @@ def test_compile_git_structured_core_memory_rendering():out = m.compile()- assert "<memory_filesystem>" in out- assert "system/" in out- assert "human.md" in out- assert "persona.md" in out-- assert "<system/human.md>" in out- assert "</system/human.md>" in out- assert "description: The human block" in out+ assert "<memory>" in out+ assert "<human>" in out+ assert "</human>" in outassert "human data" in out- assert "<system/persona.md>" in out- assert "</system/persona.md>" in out- assert "description: The persona block" in out+ assert "<self>" in out+ assert "</self>" in out+ assert "<projection>$MEMORY_DIR/system/persona.md</projection>" in outassert "persona data" in out@@ -303,7 +297,7 @@ def test_compile_git_structured_skills_section():def test_compile_git_structured_archival_memory_section():- """Non-system, non-skills blocks should render as filesystem references only."""+ """Non-system, non-skills blocks should render in <external-memory> as projections."""m = Memory(agent_type=AgentType.letta_v1_agent,@@ -317,10 +311,14 @@ def test_compile_git_structured_archival_memory_section():out = m.compile()- assert "<memory_filesystem>" in out- assert "notes.md (Personal notes)" in out- assert "reference/" in out- assert "api.md (API docs)" in out+ assert "<memory>" in out+ assert "<external-memory>" in out+ assert "<notes>" in out+ assert "<reference/api>" in out+ assert "<projection>$MEMORY_DIR/notes.md</projection>" in out+ assert "<projection>$MEMORY_DIR/reference/api.md</projection>" in out+ assert "Personal notes" in out+ assert "API docs" in out# Archival memory content should NOT be renderedassert "my notes" not in out@@ -459,7 +457,7 @@ def test_compile_available_skills_standalone():def test_compile_does_not_include_available_skills():- """compile() output should never persist <available_skills> in system prompt storage."""+ """compile() output should never persist request-scoped <available_skills> in system prompt storage."""m = Memory(agent_type=AgentType.letta_v1_agent,@@ -468,7 +466,7 @@ def test_compile_does_not_include_available_skills():Block(label="system/human", value="human data", limit=500),Block(label="system/project/notes",- value="The `<available_skills>` section is rendered after `</memory_filesystem>`.",+ value="The `<available_skills>` section is request-scoped.",limit=500,description="Notes that reference <available_skills> as literal text.",),@@ -506,7 +504,7 @@ def test_append_available_skills_preserves_blocks_with_literal_skills_text():label="system/project/architecture",value=("`compile_available_skills()` returns the `<available_skills>...</available_skills>` string.\n"- "`_update_system_message_skills()` regex replaces only the `<available_skills>` XML block."+ "Request-scoped skills are appended at LLM request build time."),limit=1000,description="Architecture notes.",@@ -524,22 +522,20 @@ def test_append_available_skills_preserves_blocks_with_literal_skills_text():new_text = old_text.rstrip("\n") + "\n\n" + new_skills.lstrip("\n")# ALL blocks must survive the replacement- assert "<system/human.md>" in new_text- assert "</system/human.md>" in new_text- assert "<system/project/workflow.md>" in new_text- assert "</system/project/workflow.md>" in new_text- assert "<system/project/architecture.md>" in new_text- assert "</system/project/architecture.md>" in new_text- assert "<system/persona.md>" in new_text- assert "</system/persona.md>" in new_text+ assert "<memory>" in new_text+ assert "<human>" in new_text+ assert "<project>" in new_text+ assert "<workflow>" in new_text+ assert "<architecture>" in new_text+ assert "<self>" in new_text# Block content with literal text references must be preservedassert "`<available_skills>`" in new_textassert "`<available_skills>...</available_skills>`" in new_text# The structural <available_skills> block must be present at the end- structural_start = new_text.rfind("<available_skills>")- structural_end = new_text.rfind("</available_skills>")+ structural_start = new_text.rfind("\n<available_skills>\n")+ structural_end = new_text.find("</available_skills>", structural_start)assert structural_start > 0assert structural_end > structural_startassert "<name>test-skill</name>" in new_text[structural_start:structural_end]@@ -604,8 +600,7 @@ def test_compile_git_structured_recompile_after_block_label_change():)out_before = m.compile()- assert "<system/human.md>" in out_before- assert "human.md" in out_before+ assert "<human>" in out_before# Simulate label renameblock.label = "system/user"@@ -613,14 +608,13 @@ def test_compile_git_structured_recompile_after_block_label_change():# Output should change: new tag name, new metadataassert out_before != out_after- assert "<system/user.md>" in out_after- assert "</system/user.md>" in out_after- assert "user.md" in out_after- assert "<system/human.md>" not in out_after+ assert "<user>" in out_after+ assert "</user>" in out_after+ assert "<human>" not in out_afterdef test_compile_git_structured_recompile_after_description_change():- """Changing a block description should produce a different compile() output."""+ """Changing a block description should affect git-structured compile() output."""block = Block(label="system/human", value="human data", limit=500, description="Original description")@@ -631,12 +625,11 @@ def test_compile_git_structured_recompile_after_description_change():)out_before = m.compile()- assert "description: Original description" in out_before+ assert "human data" in out_before# Simulate description editblock.description = "Updated description with more detail"out_after = m.compile()assert out_before != out_after- assert "description: Updated description with more detail" in out_after- assert "Original description" not in out_after+ assert "human data" in out_after