@letta-ai/letta-code 0.13.7 → 0.13.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.13.7",
+  "version": "0.13.9",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {
@@ -30,7 +30,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@letta-ai/letta-client": "^1.7.2",
+    "@letta-ai/letta-client": "^1.7.6",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",
     "open": "^10.2.0",

package/skills/defragmenting-memory/SKILL.md

@@ -1,15 +1,17 @@
 ---
 name: defragmenting-memory
-description: Defragments and cleans up agent memory blocks. Use when memory becomes messy, redundant, or poorly organized. Backs up memory, uses a subagent to clean it up, then restores the cleaned 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. Backs up memory, uses a subagent to decompose and clean it up, then restores the improved version.
 ---
 
 # Memory Defragmentation Skill
 
 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 the memory subagent to clean up the files
+2. Using a subagent to decompose and reorganize the files
 3. Restoring the cleaned files back to memory
 
+The focus is on **decomposition**—splitting large, multi-purpose blocks into focused, single-purpose components—rather than consolidation.
+
 ## When to Use
 
 - Memory blocks have redundant information
@@ -21,6 +23,8 @@ This skill helps you maintain clean, well-organized memory blocks by:
 
 ## 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: Backup Memory to Files
 
 ```bash
@@ -32,31 +36,88 @@ This creates:
 - `.letta/backups/working/` - Working directory with editable files
 - Each memory block as a `.md` file: `persona.md`, `human.md`, `project.md`, etc.
 
-### Step 2: Spawn Memory Subagent to Clean Files
+### Step 2: Spawn Subagent to Clean Files
 
 ```typescript
 Task({
   subagent_type: "memory",
-  description: "Clean up memory files",
-  prompt: `Edit the memory block files in .letta/backups/working/ to clean them up.
+  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.
+
+## 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)
 
-Focus on:
-- Reorganize and consolidate redundant information
-- Add clear structure with markdown headers
-- Organize content with bullet points
-- Resolve contradictions
-- Improve scannability
+2. **STRUCTURE** - Organize content with clear markdown formatting
+   - Use headers (##, ###) for subsections
+   - Use bullet points for lists
+   - Make content scannable at a glance
 
-IMPORTANT: When merging blocks, DELETE the redundant source files after consolidating their content (use Bash rm command). You have full bash access in the .letta/backups/working directory. Only delete files when: (1) you've merged their content into another block, or (2) the file contains only irrelevant/junk data with no project value.
+3. **CONCISENESS** - Remove redundancy and unnecessary detail
+   - Eliminate duplicate information across blocks
+   - Remove speculation ("probably", "maybe", "I think")
+   - Keep only what adds unique value
 
-Files to edit: persona.md, human.md, project.md
-Do NOT edit: skills.md (auto-generated), loaded_skills.md (system-managed)
+4. **CLARITY** - Resolve contradictions and improve readability
+   - If blocks contradict, clarify or choose the better guidance
+   - Use plain language, avoid jargon
+   - Ensure each statement is concrete and actionable
 
-After editing, provide a report with before/after character counts and list any deleted files.`
+5. **ORGANIZATION** - Group related information logically
+   - Within each block, organize content from general to specific
+   - Order sections by importance
+
+## Workflow
+
+1. **Analyze** - Read each file and identify its purpose(s)
+   - If a block serves 2+ distinct purposes, it needs decomposition
+   - 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")
+   - Ensure each new block has ONE primary purpose
+
+3. **Clean Up** - For remaining blocks (or new focused blocks):
+   - Add markdown structure with headers and bullets
+   - Remove redundancy
+   - Resolve contradictions
+   - Improve clarity
+
+4. **Delete** - Remove files only when appropriate
+   - After consolidating into other blocks (rare - most blocks should stay focused)
+   - 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
+- Content within each block is focused and relevant to its title
+- Well-organized with markdown structure
+- Clear reduction in confusion/overlap across blocks
+
+Provide a detailed report including:
+- Files created (new decomposed blocks)
+- Files modified (what changed)
+- Files deleted (if any, explain why)
+- Before/after character counts
+- Rationale for how decomposition improves the memory structure`
 })
 ```
 
-The memory subagent will:
+The subagent will:
 - Read the files from `.letta/backups/working/`
 - Edit them to reorganize and consolidate redundancy
 - Merge related blocks together for better organization
@@ -79,20 +140,23 @@ This will:
 ## Example Complete Flow
 
 ```typescript
-// Step 1: Backup memory to files
+// ⚠️ STEP 1 IS MANDATORY: Backup memory to files
+// This MUST complete successfully before proceeding to Step 2
 Bash({
   command: "npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working",
-  description: "Backup memory to files"
+  description: "Backup memory to files (MANDATORY prerequisite)"
 })
 
-// Step 2: Clean up (subagent edits files and deletes merged ones)
+// ⚠️ STEP 2 CAN ONLY BEGIN AFTER STEP 1 SUCCEEDS
+// The subagent works on the backed-up files, with the original memory safe
 Task({
   subagent_type: "memory",
-  description: "Clean up memory files",
-  prompt: "Edit memory files in .letta/backups/working/ to reorganize and consolidate redundancy. Focus on persona.md, human.md, and project.md. Merge related blocks together and DELETE the source files after merging (use Bash rm command - you have full bash access). Add clear structure. Report what was merged and where, and which files were deleted."
+  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."
 })
 
-// Step 3: Restore
+// 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"
@@ -119,19 +183,23 @@ Preview changes without applying them:
 npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working --dry-run
 ```
 
-## What the Memory Subagent Does
-
-The memory subagent focuses on cleaning up files. It:
-- Reads files from `.letta/backups/working/`
-- Edits files to improve structure and consolidate redundancy
-- Merges related blocks together to reduce fragmentation
-- Reorganizes information for better clarity and scannability
-- Deletes source files after merging their content (using Bash `rm` command)
-- Provides detailed before/after reports including merge operations
+## 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)
+- Reads and examines each file's content
+- Identifies multi-purpose blocks that serve 2+ distinct purposes
+- Splits large blocks into focused, single-purpose components
+- 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)
 
-The memory subagent runs with `bypassPermissions` mode, giving it full Bash access to delete files after merging them. The focus is on consolidation and reorganization.
+The focus is on decomposition—breaking apart large monolithic blocks into focused, specialized components rather than consolidating them together.
 
 ## Tips
 
@@ -142,18 +210,19 @@ The memory subagent runs with `bypassPermissions` mode, giving it full Bash acce
 - Speculation ("probably", "maybe" - make it concrete or remove)
 - Transient details that won't matter in a week
 
-**Reorganization Strategy:**
-- Consolidate duplicate information into a single, well-structured section
-- Merge related content that's scattered across multiple blocks
+**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"
 - Add clear headers and bullet points for scannability
-- Group similar information together logically
-- After merging blocks, DELETE the source files to avoid duplication
+- Group similar information together within focused blocks
 
 **When to DELETE a file:**
-- After merging - You've consolidated its content into another block (common and encouraged)
-- Junk data - File contains only irrelevant test/junk data with no project connection
-- Empty/deprecated - File is just a notice with no unique information
-- Don't delete - If file has unique information that hasn't been merged elsewhere
+- Only delete if file contains junk/irrelevant data with no project value
+- Don't delete after decomposing - Each new focused block is valuable
+- 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)

package/skills/defragmenting-memory/scripts/backup-memory.ts

@@ -21,7 +21,7 @@
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 // Use createRequire for @letta-ai/letta-client so NODE_PATH is respected
 // (ES module imports don't respect NODE_PATH, but require does)
@@ -70,7 +70,8 @@ function getApiKey(): string {
  * Create a Letta client with auth from env/settings
  */
 function createClient(): LettaClient {
-  return new Letta({ apiKey: getApiKey() });
+  const baseUrl = process.env.LETTA_BASE_URL || "https://api.letta.com";
+  return new Letta({ apiKey: getApiKey(), baseUrl });
 }
 
 /**
@@ -123,9 +124,16 @@ async function backupMemory(
     limit?: number;
   }>) {
     const label = block.label || `block-${block.id}`;
+    // For hierarchical labels like "A/B", create directory A/ with file B.md
     const filename = `${label}.md`;
     const filepath = join(backupPath, filename);
 
+    // Create parent directories if label contains slashes
+    const parentDir = dirname(filepath);
+    if (parentDir !== backupPath) {
+      mkdirSync(parentDir, { recursive: true });
+    }
+
     // Write block content to file
     const content = block.value || "";
     writeFileSync(filepath, content, "utf-8");

package/skills/defragmenting-memory/scripts/restore-memory.ts

@@ -16,10 +16,10 @@
  *   npx tsx restore-memory.ts $LETTA_AGENT_ID .letta/backups/working --dry-run
  */
 
-import { readdirSync, readFileSync } from "node:fs";
+import { readdirSync, readFileSync, statSync } from "node:fs";
 import { createRequire } from "node:module";
 import { homedir } from "node:os";
-import { extname, join } from "node:path";
+import { extname, join, relative } from "node:path";
 
 import type { BackupManifest } from "./backup-memory";
 
@@ -57,7 +57,33 @@ function getApiKey(): string {
  * Create a Letta client with auth from env/settings
  */
 function createClient(): LettaClient {
-  return new Letta({ apiKey: getApiKey() });
+  const baseUrl = process.env.LETTA_BASE_URL || "https://api.letta.com";
+  return new Letta({ apiKey: getApiKey(), baseUrl });
+}
+
+/**
+ * Recursively scan directory for .md files
+ * Returns array of relative file paths from baseDir
+ */
+function scanMdFiles(dir: string, baseDir: string = dir): string[] {
+  const results: string[] = [];
+  const entries = readdirSync(dir);
+
+  for (const entry of entries) {
+    const fullPath = join(dir, entry);
+    const stat = statSync(fullPath);
+
+    if (stat.isDirectory()) {
+      // Recursively scan subdirectory
+      results.push(...scanMdFiles(fullPath, baseDir));
+    } else if (stat.isFile() && extname(entry) === ".md") {
+      // Convert to relative path from baseDir
+      const relativePath = relative(baseDir, fullPath);
+      results.push(relativePath);
+    }
+  }
+
+  return results;
 }
 
 /**
@@ -77,22 +103,30 @@ async function restoreMemory(
     console.log("⚠️  DRY RUN MODE - No changes will be made\n");
   }
 
-  // Read manifest
+  // Read manifest for metadata only (block IDs)
   const manifestPath = join(backupDir, "manifest.json");
   let manifest: BackupManifest | null = null;
 
   try {
     const manifestContent = readFileSync(manifestPath, "utf-8");
     manifest = JSON.parse(manifestContent);
-    console.log(`Loaded manifest (${manifest?.blocks.length} blocks)\n`);
   } catch {
-    console.warn(
-      "Warning: No manifest.json found, will scan directory for .md files",
-    );
+    // Manifest is optional
   }
 
-  // Get current agent blocks
-  const blocksResponse = await client.agents.blocks.list(agentId);
+  // Get current agent blocks using direct fetch (SDK may hit wrong server)
+  const baseUrl = process.env.LETTA_BASE_URL || "https://api.letta.com";
+  const blocksResp = await fetch(
+    `${baseUrl}/v1/agents/${agentId}/core-memory`,
+    {
+      headers: { Authorization: `Bearer ${getApiKey()}` },
+    },
+  );
+  if (!blocksResp.ok) {
+    throw new Error(`Failed to list blocks: ${blocksResp.status}`);
+  }
+  const blocksJson = (await blocksResp.json()) as { blocks: unknown[] };
+  const blocksResponse = blocksJson.blocks;
   const currentBlocks = Array.isArray(blocksResponse)
     ? blocksResponse
     : (blocksResponse as { items?: unknown[] }).items ||
@@ -104,32 +138,22 @@ async function restoreMemory(
     ),
   );
 
-  // Determine which files to restore
-  let filesToRestore: Array<{
-    label: string;
-    filename: string;
-    blockId?: string;
-  }> = [];
-
-  if (manifest) {
-    // Use manifest
-    filesToRestore = manifest.blocks.map((b) => ({
-      label: b.label,
-      filename: b.filename,
-      blockId: b.id,
-    }));
-  } else {
-    // Scan directory for .md files
-    const files = readdirSync(backupDir);
-    filesToRestore = files
-      .filter((f) => extname(f) === ".md")
-      .map((f) => ({
-        label: f.replace(/\.md$/, ""),
-        filename: f,
-      }));
-  }
-
-  console.log(`Found ${filesToRestore.length} files to restore\n`);
+  // Always scan directory for .md files (manifest is only used for block IDs)
+  const files = scanMdFiles(backupDir);
+  console.log(`Scanned ${files.length} .md files\n`);
+  const filesToRestore = files.map((relativePath) => {
+    // Convert path like "A/B.md" to label "A/B"
+    // Replace backslashes with forward slashes (Windows compatibility)
+    const normalizedPath = relativePath.replace(/\\/g, "/");
+    const label = normalizedPath.replace(/\.md$/, "");
+    // Look up block ID from manifest if available
+    const manifestBlock = manifest?.blocks.find((b) => b.label === label);
+    return {
+      label,
+      filename: relativePath,
+      blockId: manifestBlock?.id,
+    };
+  });
 
   // Detect blocks to delete (exist on agent but not in backup)
   const backupLabels = new Set(filesToRestore.map((f) => f.label));
@@ -140,16 +164,8 @@ async function restoreMemory(
   // Restore each block
   let updated = 0;
   let created = 0;
-  let skipped = 0;
   let deleted = 0;
 
-  // Track new blocks for later confirmation
-  const blocksToCreate: Array<{
-    label: string;
-    value: string;
-    description: string;
-  }> = [];
-
   for (const { label, filename } of filesToRestore) {
     const filepath = join(backupDir, filename);
 
@@ -158,95 +174,62 @@ async function restoreMemory(
       const existingBlock = blocksByLabel.get(label);
 
       if (existingBlock) {
-        // Update existing block
-        const unchanged = existingBlock.value === newValue;
-
-        if (unchanged) {
-          console.log(`  ⏭️  ${label} - unchanged, skipping`);
-          skipped++;
-          continue;
-        }
-
+        // Update existing block using block ID (not label, which may contain /)
         if (!options.dryRun) {
-          await client.agents.blocks.update(label, {
-            agent_id: agentId,
-            value: newValue,
+          const baseUrl = process.env.LETTA_BASE_URL || "https://api.letta.com";
+          const url = `${baseUrl}/v1/blocks/${existingBlock.id}`;
+          const resp = await fetch(url, {
+            method: "PATCH",
+            headers: {
+              "Content-Type": "application/json",
+              Authorization: `Bearer ${getApiKey()}`,
+            },
+            body: JSON.stringify({ value: newValue }),
           });
+          if (!resp.ok) {
+            throw new Error(`${resp.status} ${await resp.text()}`);
+          }
         }
 
         const oldLen = existingBlock.value?.length || 0;
         const newLen = newValue.length;
-        const diff = newLen - oldLen;
-        const diffStr = diff > 0 ? `+${diff}` : `${diff}`;
+        const unchanged = existingBlock.value === newValue;
 
-        console.log(
-          `  ✓ ${label} - updated (${oldLen} -> ${newLen} chars, ${diffStr})`,
-        );
+        if (unchanged) {
+          console.log(`  ✓ ${label} - restored (${newLen} chars, unchanged)`);
+        } else {
+          const diff = newLen - oldLen;
+          const diffStr = diff > 0 ? `+${diff}` : `${diff}`;
+          console.log(
+            `  ✓ ${label} - restored (${oldLen} -> ${newLen} chars, ${diffStr})`,
+          );
+        }
         updated++;
       } else {
-        // New block - collect for later confirmation
-        console.log(`  ➕ ${label} - new block (${newValue.length} chars)`);
-        blocksToCreate.push({
-          label,
-          value: newValue,
-          description: `Memory block: ${label}`,
-        });
-      }
-    } catch (error) {
-      console.error(
-        `  ❌ ${label} - error: ${error instanceof Error ? error.message : String(error)}`,
-      );
-    }
-  }
-
-  // Handle new blocks (exist in backup but not on agent)
-  if (blocksToCreate.length > 0) {
-    console.log(`\n➕ Found ${blocksToCreate.length} new block(s) to create:`);
-    for (const block of blocksToCreate) {
-      console.log(`    - ${block.label} (${block.value.length} chars)`);
-    }
-
-    if (!options.dryRun) {
-      console.log(`\nThese blocks will be CREATED on the agent.`);
-      console.log(
-        `Press Ctrl+C to cancel, or press Enter to confirm creation...`,
-      );
-
-      // Wait for user confirmation
-      await new Promise<void>((resolve) => {
-        process.stdin.once("data", () => resolve());
-      });
-
-      console.log();
-      for (const block of blocksToCreate) {
-        try {
-          // Create the block
+        // New block - create immediately
+        if (!options.dryRun) {
           const createdBlock = await client.blocks.create({
-            label: block.label,
-            value: block.value,
-            description: block.description,
+            label,
+            value: newValue,
+            description: `Memory block: ${label}`,
             limit: 20000,
           });
 
           if (!createdBlock.id) {
-            throw new Error(`Created block ${block.label} has no ID`);
+            throw new Error(`Created block ${label} has no ID`);
           }
 
-          // Attach the newly created block to the agent
           await client.agents.blocks.attach(createdBlock.id, {
             agent_id: agentId,
           });
-
-          console.log(`  ✅ ${block.label} - created and attached`);
-          created++;
-        } catch (error) {
-          console.error(
-            `  ❌ ${block.label} - error creating: ${error instanceof Error ? error.message : String(error)}`,
-          );
         }
+        console.log(`  ✓ ${label} - created (${newValue.length} chars)`);
+        created++;
       }
-    } else {
-      console.log(`\n(Would create these blocks if not in dry-run mode)`);
+    } catch (error) {
+      console.error(
+        `  ❌ ${label} - error: ${error instanceof Error ? error.message : String(error)}`,
+      );
     }
   }
 
@@ -290,8 +273,7 @@ async function restoreMemory(
   }
 
   console.log(`\n📊 Summary:`);
-  console.log(`   Updated: ${updated}`);
-  console.log(`   Skipped: ${skipped}`);
+  console.log(`   Restored: ${updated}`);
   console.log(`   Created: ${created}`);
   console.log(`   Deleted: ${deleted}`);