@letta-ai/letta-code 0.13.11 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.13.11",
+  "version": "0.14.0",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {
@@ -40,7 +40,7 @@
     "@vscode/ripgrep": "^1.17.0"
   },
   "devDependencies": {
-    "@types/bun": "latest",
+    "@types/bun": "^1.3.7",
     "@types/diff": "^8.0.0",
     "@types/picomatch": "^4.0.2",
     "@types/react": "^19.2.9",

package/skills/defragmenting-memory/SKILL.md

@@ -1,17 +1,26 @@
 ---
 name: defragmenting-memory
-description: Decomposes and reorganizes agent memory blocks into focused, single-purpose components. Use when memory has large multi-topic blocks, redundancy, or poor organization. Backs up memory, uses a subagent to decompose and clean it up, then restores the improved version.
+description: Decomposes and reorganizes agent memory blocks into focused, single-purpose components. Use when memory has large multi-topic blocks, redundancy, or poor organization.
 ---
 
 # Memory Defragmentation Skill
 
+> **Requires Memory Filesystem (memfs)**
+>
+> This skill works by directly editing memory files on disk. It requires the memory filesystem feature to be enabled.
+>
+> **To check:** Look for a `memory_filesystem` block in your system prompt. If it shows a tree structure starting with `/memory/` including a `system/` directory, memfs is enabled.
+>
+> **To enable:** Ask the user to run `/memfs enable`, then reload the CLI.
+
 This skill helps you maintain clean, well-organized memory blocks by:
-1. Dumping current memory to local files and backing up the agent file
-2. Using a subagent to decompose and reorganize the files
-3. Restoring the cleaned files back to memory
+1. Creating a safety backup of the memfs directory
+2. Using a subagent to decompose and reorganize the memory files in-place
 
 The focus is on **decomposition**—splitting large, multi-purpose blocks into focused, single-purpose components—rather than consolidation.
 
+Memory files live at `~/.letta/agents/$LETTA_AGENT_ID/memory/` and are synced to API blocks automatically by **memfs sync** on CLI startup. There is no separate backup/restore step needed.
+
 ## When to Use
 
 - Memory blocks have redundant information
@@ -23,36 +32,62 @@ The focus is on **decomposition**—splitting large, multi-purpose blocks into f
 
 ## Workflow
 
-⚠️ **CRITICAL SAFETY REQUIREMENT**: You MUST complete Step 1 (backup) before proceeding to Step 2. The backup is your safety net. Do not spawn the subagent until the backup is guaranteed to have succeeded.
+### Step 1: Safety Backup
 
-### Step 1: Backup Memory to Files
+Before the subagent edits files, create a timestamped backup of the memfs directory:
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working
+cp -r ~/.letta/agents/$LETTA_AGENT_ID/memory/ ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-$(date +%Y%m%d-%H%M%S)/
 ```
 
-This creates:
-- `.letta/backups/<agent-id>/<timestamp>/` - Timestamped memory blocks backup
-- `.letta/backups/working/` - Working directory with editable files
-- Each memory block as a `.md` file: `persona.md`, `human.md`, `project.md`, etc.
+⚠️ **CRITICAL**: You MUST complete the backup before proceeding to Step 2. The backup is your safety net.
 
-### Step 2: Spawn Subagent to Clean Files
+### Step 2: Spawn Subagent to Edit Memory Files
+
+The memory subagent works directly on the memfs `system/` directory. After it finishes, memfs sync will propagate changes to the API on next CLI startup.
 
 ```typescript
 Task({
   subagent_type: "memory",
-  description: "Clean up and decompose memory files",
-  prompt: `⚠️ CRITICAL PREREQUISITE: The agent memory blocks MUST be backed up to .letta/backups/working/ BEFORE you begin this task. The main agent must have run backup-memory.ts first. You are ONLY responsible for editing the files in that working directory—the backup is your safety net.
-
-You are decomposing and reorganizing memory block files in .letta/backups/working/ to improve clarity and focus. "Decompose" means take large memory blocks with multiple sections and split them into smaller memory blocks, each with fewer sections and a single focused purpose.
+  description: "Decompose and reorganize memory files",
+  prompt: `You are decomposing and reorganizing memory files in ~/.letta/agents/${LETTA_AGENT_ID}/memory/system/ to improve clarity and focus.
+
+These files ARE the agent's memory — they sync directly to API memory blocks via memfs. Changes you make here will be picked up automatically.
+
+## Directory Structure
+
+~/.letta/agents/<agent-id>/memory/
+├── system/       ← Attached blocks (always loaded in system prompt) — EDIT THESE
+├── notes.md      ← Detached blocks at root level (on-demand) — can create here
+├── archive/      ← Detached blocks can be nested too
+└── .sync-state.json  ← DO NOT EDIT (internal sync tracking)
+
+## Files to Skip (DO NOT edit)
+- memory_filesystem.md (auto-generated tree view)
+- skills.md (auto-generated)
+- loaded_skills.md (system-managed)
+- .sync-state.json (internal)
+
+## What to Edit
+- persona.md → Consider splitting into: persona/identity.md, persona/values.md, persona/approach.md
+- project.md → Consider splitting into: project/overview.md, project/architecture.md, project/conventions.md, etc.
+- human.md → Consider splitting into: human/identity.md, human/preferences.md, etc.
+- Any other non-system blocks present
+
+## How Memfs File ↔ Block Mapping Works
+- File path relative to memory root becomes the block label (system/ prefix for attached, root level for detached)
+- Example: system/project/tooling/bun.md → block label "project/tooling/bun"
+- New files you create will become new memory blocks on next sync
+- Files you delete will cause the corresponding blocks to be deleted on next sync
+- YAML frontmatter is supported for metadata (label, description, limit, read_only)
 
 ## Evaluation Criteria
 
 1. **DECOMPOSITION** - Split large, multi-purpose blocks into focused, single-purpose components
-   - Example: A "persona" block mixing Git operations, communication style, AND behavioral preferences should become separate blocks like "communication-style.md", "behavioral-preferences.md", "version-control-practices.md"
-   - Example: A "project" block with structure, patterns, rendering, error handling, and architecture should split into specialized blocks like "architecture.md", "patterns.md", "rendering-approach.md", "error-handling.md"
-   - Goal: Each block should have ONE clear purpose that can be described in a short title
-   - Create new files when splitting (e.g., communication-style.md, behavioral-preferences.md)
+   - Example: A "persona" block mixing identity, values, AND approach should become persona/identity.md, persona/values.md, persona/approach.md
+   - Example: A "project" block with overview, architecture, conventions, and gotchas should split into project/overview.md, project/architecture.md, project/conventions.md, project/gotchas.md
+   - Goal: Each block should have ONE clear purpose described by its filename
+   - Use hierarchical / naming (e.g., project/tooling/bun.md, not project-tooling-bun.md)
 
 2. **STRUCTURE** - Organize content with clear markdown formatting
    - Use headers (##, ###) for subsections
@@ -80,8 +115,7 @@ You are decomposing and reorganizing memory block files in .letta/backups/workin
    - Flag blocks where subtopics could be their own focused blocks
 
 2. **Decompose** - Split multi-purpose blocks into specialized files
-   - Create new .md files for each focused purpose
-   - Use clear, descriptive filenames (e.g., "keyboard-protocols.md", "error-handling-patterns.md")
+   - Create new files using hierarchical paths (e.g., project/tooling/bun.md)
    - Ensure each new block has ONE primary purpose
 
 3. **Clean Up** - For remaining blocks (or new focused blocks):
@@ -91,16 +125,10 @@ You are decomposing and reorganizing memory block files in .letta/backups/workin
    - Improve clarity
 
 4. **Delete** - Remove files only when appropriate
-   - After consolidating into other blocks (rare - most blocks should stay focused)
+   - After moving all content to new decomposed files
    - Never delete a focused, single-purpose block
    - Only delete if a block contains junk/irrelevant data with no value
 
-## Files to Edit
-- persona.md → Consider splitting into: communication-style.md, behavioral-preferences.md, technical-practices.md
-- project.md → Consider splitting into: architecture.md, patterns.md, rendering.md, error-handling.md, etc.
-- human.md → OK to keep as-is if focused on understanding the user
-- DO NOT edit: skills.md (auto-generated), loaded_skills.md (system-managed)
-
 ## Success Indicators
 - No block tries to cover 2+ distinct topics
 - Each block title clearly describes its single purpose
@@ -118,86 +146,63 @@ Provide a detailed report including:
 ```
 
 The subagent will:
-- Read the files from `.letta/backups/working/`
-- Edit them to reorganize and consolidate redundancy
-- Merge related blocks together for better organization
+- Read files from `~/.letta/agents/<agent-id>/memory/system/` (and root level for detached)
+- Edit them to reorganize and decompose large blocks
+- Create new hierarchically-named files (e.g., `project/overview.md`)
 - Add clear structure with markdown formatting
-- Delete source files after merging their content into other blocks
-- Provide a detailed report of changes (including what was merged where)
-
-### Step 3: Restore Cleaned Files to Memory
+- Delete source files after decomposing their content into focused children
+- Provide a detailed report of changes
 
-```bash
-npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working
-```
-
-This will:
-- Compare each file to current memory blocks
-- Update only the blocks that changed
-- Show before/after character counts
-- Skip unchanged blocks
+After the subagent finishes, **memfs sync will automatically propagate changes** to API blocks on the next CLI startup. No manual restore step is needed.
 
 ## Example Complete Flow
 
 ```typescript
-// ⚠️ STEP 1 IS MANDATORY: Backup memory to files
-// This MUST complete successfully before proceeding to Step 2
+// Step 1: Safety backup (MANDATORY)
 Bash({
-  command: "npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working",
-  description: "Backup memory to files (MANDATORY prerequisite)"
+  command: "cp -r ~/.letta/agents/$LETTA_AGENT_ID/memory/ ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-$(date +%Y%m%d-%H%M%S)/",
+  description: "Backup memfs directory before defrag"
 })
 
-// ⚠️ STEP 2 CAN ONLY BEGIN AFTER STEP 1 SUCCEEDS
-// The subagent works on the backed-up files, with the original memory safe
+// Step 2: Spawn subagent to decompose and reorganize
 Task({
   subagent_type: "memory",
-  description: "Clean up and decompose memory files",
-  prompt: "Decompose and reorganize memory block files in .letta/backups/working/. Be aggressive about splitting large multi-section blocks into many smaller, single-purpose blocks with fewer sections. Prefer creating new focused files over keeping large blocks. Structure with markdown headers and bullets. Remove redundancy and speculation. Resolve contradictions. Organize logically. Each block should have ONE clear purpose. Create new files for decomposed blocks rather than consolidating. Report files created, modified, deleted, before/after character counts, and rationale for changes."
+  description: "Decompose and reorganize memory files",
+  prompt: "Decompose and reorganize memory files in ~/.letta/agents/$LETTA_AGENT_ID/memory/system/. These files sync directly to API blocks via memfs. Be aggressive about splitting large multi-section blocks into many smaller, single-purpose blocks using hierarchical / naming. Skip memory_filesystem.md, skills.md, loaded_skills.md, and .sync-state.json. Structure with markdown headers and bullets. Remove redundancy and speculation. Resolve contradictions. Organize logically. Each block should have ONE clear purpose. Report files created, modified, deleted, before/after character counts, and rationale for changes."
 })
 
-// Step 3: Restore (only after cleanup is approved)
-// Review the subagent's report before running this
-Bash({
-  command: "npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working",
-  description: "Restore cleaned memory blocks"
-})
+// No Step 3 needed — memfs sync handles propagation to API blocks
 ```
 
 ## Rollback
 
-If something goes wrong, restore from a previous backup:
+If something goes wrong, restore from the safety backup:
 
 ```bash
-# Find the backup directory
-ls -la .letta/backups/<agent-id>/
+# Find backups
+ls -la ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-*/
 
-# Restore from specific timestamp
-npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/<agent-id>/<timestamp>
+# Restore from a specific backup (replace the current memory dir)
+rm -rf ~/.letta/agents/$LETTA_AGENT_ID/memory/
+cp -r ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-<TIMESTAMP>/ ~/.letta/agents/$LETTA_AGENT_ID/memory/
 ```
 
-## Dry Run
-
-Preview changes without applying them:
-
-```bash
-npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working --dry-run
-```
+On next CLI startup, memfs sync will detect the changes and update API blocks accordingly.
 
 ## What the Subagent Does
 
 The subagent focuses on decomposing and cleaning up files. It has full tool access (including Bash) and:
-- Discovers `.md` files in `.letta/backups/working/` (via Glob or Bash)
+- Discovers `.md` files in `~/.letta/agents/<agent-id>/memory/system/` (via Glob or Bash)
 - Reads and examines each file's content
 - Identifies multi-purpose blocks that serve 2+ distinct purposes
-- Splits large blocks into focused, single-purpose components
+- Splits large blocks into focused, single-purpose components with hierarchical naming
 - Modifies/creates .md files for decomposed blocks
 - Improves structure with headers and bullet points
 - Removes redundancy and speculation across blocks
 - Resolves contradictions with clear, concrete guidance
 - Organizes content logically (general to specific, by importance)
 - Provides detailed before/after reports including decomposition rationale
-- Does NOT run backup scripts (main agent does this)
-- Does NOT run restore scripts (main agent does this)
+- Does NOT run any backup or restore scripts
 
 The focus is on decomposition—breaking apart large monolithic blocks into focused, specialized components rather than consolidating them together.
 
@@ -212,17 +217,17 @@ The focus is on decomposition—breaking apart large monolithic blocks into focu
 
 **Decomposition Strategy:**
 - Split blocks that serve 2+ distinct purposes into focused components
-- Create new specialized blocks with clear, single-purpose titles
-- Example: A "persona" mixing communication style + Git practices → split into "communication-style.md" and "version-control-practices.md"
-- Example: A "project" with structure + patterns + rendering → split into "architecture.md", "patterns.md", "rendering.md"
+- Use hierarchical `/` naming: `project/tooling/bun.md`, not `project-bun.md`
+- Create parent index files that reference children
+- Example: A "persona" mixing identity + values + approach → split into `persona/identity.md`, `persona/values.md`, `persona/approach.md`
+- Example: A "project" with overview + architecture + conventions → split into `project/overview.md`, `project/architecture.md`, `project/conventions.md`
 - Add clear headers and bullet points for scannability
 - Group similar information together within focused blocks
 
 **When to DELETE a file:**
 - Only delete if file contains junk/irrelevant data with no project value
-- Don't delete after decomposing - Each new focused block is valuable
+- Delete source files after fully decomposing content into child files
 - Don't delete unique information just to reduce file count
-- Exception: Delete source files only if consolidating multiple blocks into one (rare)
 
 **What to preserve:**
 - User preferences (sacred - never delete)
@@ -236,3 +241,4 @@ The focus is on decomposition—breaking apart large monolithic blocks into focu
 - Organize with bullet points
 - Keep related information together
 - Make it scannable at a glance
+- Use `/` hierarchy for discoverability