Skip to content

armgit / letta

Public Imported from GitHub
0

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.py
index 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 rendering
self._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.py
index 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 out
assert "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 out
assert "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 rendered
assert "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 preserved
assert "`<available_skills>`" in new_text
assert "`<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 > 0
assert structural_end > structural_start
assert "<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 rename
block.label = "system/user"
@@ -613,14 +608,13 @@ def test_compile_git_structured_recompile_after_block_label_change():
# Output should change: new tag name, new metadata
assert 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_after
def 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 edit
block.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