@letta-ai/letta-code 0.12.6 → 0.12.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.12.6",
+  "version": "0.12.8",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {

package/skills/defragmenting-memory/SKILL.md

@@ -0,0 +1,169 @@
+---
+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.
+---
+
+# 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
+3. Restoring the cleaned files back to memory
+
+## When to Use
+
+- Memory blocks have redundant information
+- Memory lacks structure (walls of text)
+- Memory contains contradictions
+- Memory has grown stale or outdated
+- After major project milestones
+- Every 50-100 conversation turns
+
+## Workflow
+
+### Step 1: Backup Memory to Files
+
+```bash
+npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working
+```
+
+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.
+
+### Step 2: Spawn Memory 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.
+
+Focus on:
+- Reorganize and consolidate redundant information
+- Add clear structure with markdown headers
+- Organize content with bullet points
+- Resolve contradictions
+- Improve scannability
+
+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.
+
+Files to edit: persona.md, human.md, project.md
+Do NOT edit: skills.md (auto-generated), loaded_skills.md (system-managed)
+
+After editing, provide a report with before/after character counts and list any deleted files.`
+})
+```
+
+The memory subagent will:
+- Read the files from `.letta/backups/working/`
+- Edit them to reorganize and consolidate redundancy
+- Merge related blocks together for better organization
+- 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
+
+```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
+
+## Example Complete Flow
+
+```typescript
+// Step 1: Backup memory to files
+Bash({
+  command: "npx tsx <SKILL_DIR>/scripts/backup-memory.ts $LETTA_AGENT_ID .letta/backups/working",
+  description: "Backup memory to files"
+})
+
+// Step 2: Clean up (subagent edits files and deletes merged ones)
+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."
+})
+
+// Step 3: Restore
+Bash({
+  command: "npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/working",
+  description: "Restore cleaned memory blocks"
+})
+```
+
+## Rollback
+
+If something goes wrong, restore from a previous backup:
+
+```bash
+# Find the backup directory
+ls -la .letta/backups/<agent-id>/
+
+# Restore from specific timestamp
+npx tsx <SKILL_DIR>/scripts/restore-memory.ts $LETTA_AGENT_ID .letta/backups/<agent-id>/<timestamp>
+```
+
+## Dry Run
+
+Preview changes without applying them:
+
+```bash
+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
+- 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.
+
+## Tips
+
+**What to clean up:**
+- Duplicate information (consolidate into one well-organized section)
+- Walls of text without structure (add headers and bullets)
+- Contradictions (resolve by clarifying or choosing the better guidance)
+- 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
+- Add clear headers and bullet points for scannability
+- Group similar information together logically
+- After merging blocks, DELETE the source files to avoid duplication
+
+**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
+
+**What to preserve:**
+- User preferences (sacred - never delete)
+- Project conventions discovered through experience
+- Important context for future sessions
+- Learnings from past mistakes
+- Any information that has unique value
+
+**Good memory structure:**
+- Use markdown headers (##, ###)
+- Organize with bullet points
+- Keep related information together
+- Make it scannable at a glance

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

@@ -0,0 +1,198 @@
+#!/usr/bin/env npx tsx
+/**
+ * Backup Memory Blocks to Local Files
+ *
+ * Exports all memory blocks from an agent to local files for checkpointing and editing.
+ * Creates a timestamped backup directory with:
+ * - Individual .md files for each memory block
+ * - manifest.json with metadata
+ *
+ * This script is standalone and can be run outside the CLI process.
+ * It reads auth from LETTA_API_KEY env var or ~/.letta/settings.json.
+ *
+ * Usage:
+ *   npx tsx backup-memory.ts <agent-id> [backup-dir]
+ *
+ * Example:
+ *   npx tsx backup-memory.ts agent-abc123
+ *   npx tsx backup-memory.ts $LETTA_AGENT_ID .letta/backups/working
+ */
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { 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)
+const require = createRequire(import.meta.url);
+const Letta = require("@letta-ai/letta-client")
+  .default as typeof import("@letta-ai/letta-client").default;
+type LettaClient = InstanceType<typeof Letta>;
+
+export interface BackupManifest {
+  agent_id: string;
+  timestamp: string;
+  backup_path: string;
+  blocks: Array<{
+    id: string;
+    label: string;
+    filename: string;
+    limit: number;
+    value_length: number;
+  }>;
+}
+
+/**
+ * Get API key from env var or settings file
+ */
+function getApiKey(): string {
+  if (process.env.LETTA_API_KEY) {
+    return process.env.LETTA_API_KEY;
+  }
+
+  const settingsPath = join(homedir(), ".letta", "settings.json");
+  try {
+    const settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+    if (settings.env?.LETTA_API_KEY) {
+      return settings.env.LETTA_API_KEY;
+    }
+  } catch {
+    // Settings file doesn't exist or is invalid
+  }
+
+  throw new Error(
+    "No LETTA_API_KEY found. Set the env var or run the Letta CLI to authenticate.",
+  );
+}
+
+/**
+ * Create a Letta client with auth from env/settings
+ */
+function createClient(): LettaClient {
+  return new Letta({ apiKey: getApiKey() });
+}
+
+/**
+ * Backup memory blocks to local files
+ */
+async function backupMemory(
+  agentId: string,
+  backupDir?: string,
+): Promise<string> {
+  const client = createClient();
+
+  // Create backup directory
+  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+  const defaultBackupDir = join(
+    process.cwd(),
+    ".letta",
+    "backups",
+    agentId,
+    timestamp,
+  );
+  const backupPath = backupDir || defaultBackupDir;
+
+  mkdirSync(backupPath, { recursive: true });
+
+  console.log(`Backing up memory blocks for agent ${agentId}...`);
+  console.log(`Backup location: ${backupPath}`);
+
+  // Get all memory blocks
+  const blocksResponse = await client.agents.blocks.list(agentId);
+  const blocks = Array.isArray(blocksResponse)
+    ? blocksResponse
+    : (blocksResponse as { items?: unknown[] }).items ||
+      (blocksResponse as { blocks?: unknown[] }).blocks ||
+      [];
+
+  console.log(`Found ${blocks.length} memory blocks`);
+
+  // Export each block to a file
+  const manifest: BackupManifest = {
+    agent_id: agentId,
+    timestamp: new Date().toISOString(),
+    backup_path: backupPath,
+    blocks: [],
+  };
+
+  for (const block of blocks as Array<{
+    id: string;
+    label?: string;
+    value?: string;
+    limit?: number;
+  }>) {
+    const label = block.label || `block-${block.id}`;
+    const filename = `${label}.md`;
+    const filepath = join(backupPath, filename);
+
+    // Write block content to file
+    const content = block.value || "";
+    writeFileSync(filepath, content, "utf-8");
+
+    console.log(`  ✓ ${label} -> ${filename} (${content.length} chars)`);
+
+    // Add to manifest
+    manifest.blocks.push({
+      id: block.id,
+      label,
+      filename,
+      limit: block.limit || 0,
+      value_length: content.length,
+    });
+  }
+
+  // Write manifest
+  const manifestPath = join(backupPath, "manifest.json");
+  writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), "utf-8");
+  console.log(`  ✓ manifest.json`);
+
+  console.log(`\n✅ Backup complete: ${backupPath}`);
+  return backupPath;
+}
+
+// CLI Entry Point - check if this file is being run directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+    console.log(`
+Usage: npx tsx backup-memory.ts <agent-id> [backup-dir]
+
+Arguments:
+  agent-id     Agent ID to backup (can use $LETTA_AGENT_ID)
+  backup-dir   Optional custom backup directory
+               Default: .letta/backups/<agent-id>/<timestamp>
+
+Examples:
+  npx tsx backup-memory.ts agent-abc123
+  npx tsx backup-memory.ts $LETTA_AGENT_ID
+  npx tsx backup-memory.ts agent-abc123 .letta/backups/working
+    `);
+    process.exit(0);
+  }
+
+  const agentId = args[0];
+  const backupDir = args[1];
+
+  if (!agentId) {
+    console.error("Error: agent-id is required");
+    process.exit(1);
+  }
+
+  backupMemory(agentId, backupDir)
+    .then((path) => {
+      // Output just the path for easy capture in scripts
+      console.log(path);
+    })
+    .catch((error) => {
+      console.error(
+        "Error backing up memory:",
+        error instanceof Error ? error.message : String(error),
+      );
+      process.exit(1);
+    });
+}
+
+export { backupMemory };