@letta-ai/letta-code 0.11.1 → 0.11.2-next.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.11.1",
+  "version": "0.11.2-next.1",
   "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.6.1",
+    "@letta-ai/letta-client": "1.6.4",
     "glob": "^13.0.0",
     "ink-link": "^5.0.0",
     "open": "^10.2.0"

package/skills/finding-agents/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: finding-agents
+description: Find other agents on the same server. Use when the user asks about other agents, wants to migrate memory from another agent, or needs to find an agent by name or tags.
+---
+
+# Finding Agents
+
+This skill helps you find other agents on the same Letta server.
+
+## When to Use This Skill
+
+- User asks about other agents they have
+- User wants to find a specific agent by name
+- User wants to list agents with certain tags
+- You need to find an agent ID for memory migration
+- You found an agent_id via message search and need details about that agent
+
+## Script Usage
+
+```bash
+npx ts-node scripts/find-agents.ts [options]
+```
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--name <name>` | Exact name match |
+| `--query <text>` | Fuzzy search by name |
+| `--tags <tag1,tag2>` | Filter by tags (comma-separated) |
+| `--match-all-tags` | Require ALL tags (default: ANY) |
+| `--include-blocks` | Include agent.blocks in response |
+| `--limit <n>` | Max results (default: 20) |
+
+## Common Patterns
+
+### Finding Letta Code Agents
+
+Agents created by Letta Code are tagged with `origin:letta-code`. To find only Letta Code agents:
+
+```bash
+npx ts-node scripts/find-agents.ts --tags "origin:letta-code"
+```
+
+This is useful when the user is looking for agents they've worked with in Letta Code CLI sessions.
+
+### Finding All Agents
+
+If the user has agents created outside Letta Code (via ADE, SDK, etc.), search without the tag filter:
+
+```bash
+npx ts-node scripts/find-agents.ts
+```
+
+## Examples
+
+**List all agents (up to 20):**
+```bash
+npx ts-node scripts/find-agents.ts
+```
+
+**Find agent by exact name:**
+```bash
+npx ts-node scripts/find-agents.ts --name "ProjectX-v1"
+```
+
+**Search agents by name (fuzzy):**
+```bash
+npx ts-node scripts/find-agents.ts --query "project"
+```
+
+**Find only Letta Code agents:**
+```bash
+npx ts-node scripts/find-agents.ts --tags "origin:letta-code"
+```
+
+**Find agents with multiple tags:**
+```bash
+npx ts-node scripts/find-agents.ts --tags "frontend,production" --match-all-tags
+```
+
+**Include memory blocks in results:**
+```bash
+npx ts-node scripts/find-agents.ts --query "project" --include-blocks
+```
+
+## Output
+
+Returns the raw API response with full agent details. Key fields:
+- `id` - Agent ID (e.g., `agent-abc123`)
+- `name` - Agent name
+- `description` - Agent description
+- `tags` - Agent tags
+- `blocks` - Memory blocks (if `--include-blocks` used)
+
+## Related Skills
+
+- **migrating-memory** - Once you find an agent, use this skill to copy/share memory blocks
+- **searching-messages** - Search messages across all agents to find which agent discussed a topic. Use `--all-agents` to get `agent_id` values, then use this skill to get full agent details.
+
+### Finding Agents by Topic
+
+If you need to find which agent worked on a specific topic:
+
+1. Load both skills: `searching-messages` and `finding-agents`
+2. Search messages across all agents:
+   ```bash
+   search-messages.ts --query "topic" --all-agents --limit 10
+   ```
+3. Note the `agent_id` values from matching messages
+4. Get agent details:
+   ```bash
+   find-agents.ts --query "partial-name"
+   ```
+   Or use the agent_id directly in the Letta API

package/skills/finding-agents/scripts/find-agents.ts

@@ -0,0 +1,134 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Find Agents - Search for agents with various filters
+ *
+ * Usage:
+ *   npx ts-node find-agents.ts [options]
+ *
+ * Options:
+ *   --name <name>         Exact name match
+ *   --query <text>        Fuzzy search by name
+ *   --tags <tag1,tag2>    Filter by tags (comma-separated)
+ *   --match-all-tags      Require ALL tags (default: ANY)
+ *   --include-blocks      Include agent.blocks in response
+ *   --limit <n>           Max results (default: 20)
+ *
+ * Output:
+ *   Raw API response from GET /v1/agents
+ */
+
+import type Letta from "@letta-ai/letta-client";
+import { getClient } from "../../../../agent/client";
+import { settingsManager } from "../../../../settings-manager";
+
+interface FindAgentsOptions {
+  name?: string;
+  query?: string;
+  tags?: string[];
+  matchAllTags?: boolean;
+  includeBlocks?: boolean;
+  limit?: number;
+}
+
+/**
+ * Find agents matching the given criteria
+ * @param client - Letta client instance
+ * @param options - Search options
+ * @returns Array of agent objects from the API
+ */
+export async function findAgents(
+  client: Letta,
+  options: FindAgentsOptions = {},
+): Promise<Awaited<ReturnType<typeof client.agents.list>>> {
+  const params: Parameters<typeof client.agents.list>[0] = {
+    limit: options.limit ?? 20,
+  };
+
+  if (options.name) {
+    params.name = options.name;
+  }
+
+  if (options.query) {
+    params.query_text = options.query;
+  }
+
+  if (options.tags && options.tags.length > 0) {
+    params.tags = options.tags;
+    if (options.matchAllTags) {
+      params.match_all_tags = true;
+    }
+  }
+
+  if (options.includeBlocks) {
+    params.include = ["agent.blocks"];
+  }
+
+  return await client.agents.list(params);
+}
+
+function parseArgs(args: string[]): FindAgentsOptions {
+  const options: FindAgentsOptions = {};
+
+  const nameIndex = args.indexOf("--name");
+  if (nameIndex !== -1 && nameIndex + 1 < args.length) {
+    options.name = args[nameIndex + 1];
+  }
+
+  const queryIndex = args.indexOf("--query");
+  if (queryIndex !== -1 && queryIndex + 1 < args.length) {
+    options.query = args[queryIndex + 1];
+  }
+
+  const tagsIndex = args.indexOf("--tags");
+  if (tagsIndex !== -1 && tagsIndex + 1 < args.length) {
+    options.tags = args[tagsIndex + 1]?.split(",").map((t) => t.trim());
+  }
+
+  if (args.includes("--match-all-tags")) {
+    options.matchAllTags = true;
+  }
+
+  if (args.includes("--include-blocks")) {
+    options.includeBlocks = true;
+  }
+
+  const limitIndex = args.indexOf("--limit");
+  if (limitIndex !== -1 && limitIndex + 1 < args.length) {
+    const limit = Number.parseInt(args[limitIndex + 1] as string, 10);
+    if (!Number.isNaN(limit)) {
+      options.limit = limit;
+    }
+  }
+
+  return options;
+}
+
+// CLI entry point
+if (require.main === module) {
+  (async () => {
+    try {
+      const options = parseArgs(process.argv.slice(2));
+      await settingsManager.initialize();
+      const client = await getClient();
+      const result = await findAgents(client, options);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(
+        "Error:",
+        error instanceof Error ? error.message : String(error),
+      );
+      console.error(`
+Usage: npx ts-node find-agents.ts [options]
+
+Options:
+  --name <name>         Exact name match
+  --query <text>        Fuzzy search by name
+  --tags <tag1,tag2>    Filter by tags (comma-separated)
+  --match-all-tags      Require ALL tags (default: ANY)
+  --include-blocks      Include agent.blocks in response
+  --limit <n>           Max results (default: 20)
+`);
+      process.exit(1);
+    }
+  })();
+}

package/skills/initializing-memory/SKILL.md

@@ -18,6 +18,18 @@ This command may be run in different scenarios:
 
 Before making changes, use the `memory` tool to inspect your current memory blocks and understand what already exists.
 
+## Memory Migration Option
+
+If you're setting up a new agent that should inherit memory from an existing agent, consider using the `migrating-memory` skill:
+
+1. Load the skill: `Skill({ command: "load", skills: ["migrating-memory"] })`
+2. Follow its workflow to copy or share blocks from another agent
+
+**When to suggest migration**:
+- User mentions they have an existing agent with useful memory
+- User is replacing an old agent with a new one
+- User wants to share memory blocks across multiple agents
+
 ## What Coding Agents Should Remember
 
 ### 1. Procedures (Rules & Workflows)

package/skills/migrating-memory/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: migrating-memory
+description: Migrate memory blocks from an existing agent to the current agent. Use when the user wants to copy or share memory from another agent, or during /init when setting up a new agent that should inherit memory from an existing one.
+---
+
+# Migrating Memory
+
+This skill helps migrate memory blocks from an existing agent to a new agent, similar to macOS Migration Assistant for AI agents.
+
+## When to Use This Skill
+
+- User is setting up a new agent that should inherit memory from an existing one
+- User wants to share memory blocks across multiple agents
+- User is replacing an old agent with a new one
+- User mentions they have an existing agent with useful memory
+
+## Migration Methods
+
+### 1. Manual Copy (Recommended for partial content)
+
+If you only need **part** of a source block, or the source is messy and needs cleanup:
+1. Use `get-agent-blocks.ts` to view the source block's content
+2. Use the `memory` tool to create a new block with just the content you want
+3. No scripts needed - you have full control over what gets copied
+
+Best for: Extracting sections, cleaning up messy content, selective migration.
+
+### 2. Script Copy (Full block duplication)
+
+Creates new blocks with the same content using `copy-block.ts`. After copying:
+- You own the copy - changes don't sync
+- Use `--label` flag if you already have a block with that label
+- Best for: One-time migration, forking an agent
+
+### 3. Share (Linked Blocks)
+
+Attaches the same block to multiple agents using `attach-block.ts`. After sharing:
+- All agents see the same block content
+- Changes by any agent are visible to all others
+- Can be read-only (target can read but not modify)
+- Best for: Shared knowledge bases, synchronized state
+
+**Note:** You cannot have two blocks with the same label. When copying, use `--label` to rename if needed.
+
+## Workflow
+
+### Step 1: Identify Source Agent
+
+Ask the user for the source agent's ID (e.g., `agent-abc123`).
+
+If they don't know the ID, load the **finding-agents** skill to search:
+```
+Skill({ command: "load", skills: ["finding-agents"] })
+```
+
+Example: "What's the ID of the agent you want to migrate memory from?"
+
+### Step 2: View Source Agent's Blocks
+
+Inspect what memory blocks the source agent has:
+
+```bash
+npx ts-node scripts/get-agent-blocks.ts --agent-id <source-agent-id>
+```
+
+This shows each block's ID, label, description, and value.
+
+### Step 3: Migrate Blocks
+
+For each block you want to migrate, choose copy or share:
+
+**To Copy (create independent block):**
+```bash
+npx ts-node scripts/copy-block.ts --block-id <block-id> [--label <new-label>]
+```
+
+Use `--label` if you already have a block with that label (e.g., `--label project-imported`).
+
+**To Share (attach existing block):**
+```bash
+npx ts-node scripts/attach-block.ts --block-id <block-id>
+```
+
+Add `--read-only` flag to share to make this agent unable to modify the block.
+
+Note: These scripts automatically target the current agent (you) for safety.
+
+## Script Reference
+
+All scripts are located in the `scripts/` directory and output raw API responses (JSON).
+
+| Script | Purpose | Args |
+|--------|---------|------|
+| `get-agent-blocks.ts` | Get blocks from an agent | `--agent-id` |
+| `copy-block.ts` | Copy block to current agent | `--block-id`, optional `--label` |
+| `attach-block.ts` | Attach existing block to current agent | `--block-id`, optional `--read-only` |
+
+## Authentication
+
+The bundled scripts automatically use the same authentication as Letta Code:
+- Keychain/secrets storage
+- `~/.config/letta/settings.json` fallback
+- `LETTA_API_KEY` environment variable
+
+You can also make direct API calls using the Letta SDK if you have the API key available.
+
+## Example: Migrating Project Memory
+
+Scenario: You're a new agent and want to inherit memory from an existing agent "ProjectX-v1".
+
+1. **Get source agent ID from user:**
+   User provides: `agent-abc123`
+
+2. **List its blocks:**
+   ```bash
+   npx ts-node scripts/get-agent-blocks.ts --agent-id agent-abc123
+   # Shows: project (block-def456), human (block-ghi789), persona (block-jkl012)
+   ```
+
+3. **Copy project knowledge to yourself:**
+   ```bash
+   # If you don't have a 'project' block yet:
+   npx ts-node scripts/copy-block.ts --block-id block-def456
+   
+   # If you already have 'project', use --label to rename:
+   npx ts-node scripts/copy-block.ts --block-id block-def456 --label project-v1
+   ```
+
+4. **Optionally share human preferences (read-only):**
+   ```bash
+   npx ts-node scripts/attach-block.ts --block-id block-ghi789 --read-only
+   ```

package/skills/migrating-memory/scripts/attach-block.ts

@@ -0,0 +1,100 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Attach Block - Attaches an existing memory block to an agent (sharing)
+ *
+ * Usage:
+ *   npx ts-node attach-block.ts --block-id <block-id> --target-agent-id <agent-id> [--read-only]
+ *
+ * This attaches an existing block to another agent, making it shared.
+ * Changes to the block will be visible to all agents that have it attached.
+ *
+ * Options:
+ *   --read-only    Target agent can read but not modify the block
+ *
+ * Output:
+ *   Raw API response from the attach operation
+ */
+
+import type Letta from "@letta-ai/letta-client";
+import { getClient } from "../../../../agent/client";
+import { getCurrentAgentId } from "../../../../agent/context";
+import { settingsManager } from "../../../../settings-manager";
+
+/**
+ * Attach an existing block to the current agent (sharing it)
+ * @param client - Letta client instance
+ * @param blockId - The block ID to attach
+ * @param readOnly - Whether this agent should have read-only access
+ * @param targetAgentId - Optional target agent ID (defaults to current agent)
+ * @returns API response from the attach operation
+ */
+export async function attachBlock(
+  client: Letta,
+  blockId: string,
+  readOnly = false,
+  targetAgentId?: string,
+): Promise<Awaited<ReturnType<typeof client.agents.blocks.attach>>> {
+  // Get current agent ID (the agent calling this script) or use provided ID
+  const currentAgentId = targetAgentId ?? getCurrentAgentId();
+
+  const result = await client.agents.blocks.attach(blockId, {
+    agent_id: currentAgentId,
+  });
+
+  // If read-only is requested, update the block's read_only flag for this agent
+  // Note: This may require a separate API call depending on how read_only works
+  if (readOnly) {
+    // The read_only flag is per-block, not per-agent attachment
+    // For now, we'll note this in the output
+    console.warn(
+      "Note: read_only flag is set on the block itself, not per-agent. " +
+        "Use the block update API to set read_only if needed.",
+    );
+  }
+
+  return result;
+}
+
+function parseArgs(args: string[]): {
+  blockId: string;
+  readOnly: boolean;
+} {
+  const blockIdIndex = args.indexOf("--block-id");
+  const readOnly = args.includes("--read-only");
+
+  if (blockIdIndex === -1 || blockIdIndex + 1 >= args.length) {
+    throw new Error("Missing required argument: --block-id <block-id>");
+  }
+
+  return {
+    blockId: args[blockIdIndex + 1] as string,
+    readOnly,
+  };
+}
+
+// CLI entry point
+if (require.main === module) {
+  (async () => {
+    try {
+      const { blockId, readOnly } = parseArgs(process.argv.slice(2));
+      await settingsManager.initialize();
+      const client = await getClient();
+      const result = await attachBlock(client, blockId, readOnly);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(
+        "Error:",
+        error instanceof Error ? error.message : String(error),
+      );
+      if (
+        error instanceof Error &&
+        error.message.includes("Missing required argument")
+      ) {
+        console.error(
+          "\nUsage: npx ts-node attach-block.ts --block-id <block-id> [--read-only]",
+        );
+      }
+      process.exit(1);
+    }
+  })();
+}

package/skills/migrating-memory/scripts/copy-block.ts

@@ -0,0 +1,108 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Copy Block - Copies a memory block to create a new independent block for the current agent
+ *
+ * Usage:
+ *   npx ts-node copy-block.ts --block-id <block-id> [--label <new-label>]
+ *
+ * Options:
+ *   --label    Override the block label (required if you already have a block with that label)
+ *
+ * This creates a new block with the same content as the source block,
+ * then attaches it to the current agent. Changes to the new block
+ * won't affect the original.
+ *
+ * Output:
+ *   Raw API response from each step (retrieve, create, attach)
+ */
+
+import type Letta from "@letta-ai/letta-client";
+import { getClient } from "../../../../agent/client";
+import { getCurrentAgentId } from "../../../../agent/context";
+import { settingsManager } from "../../../../settings-manager";
+
+interface CopyBlockResult {
+  sourceBlock: Awaited<ReturnType<typeof Letta.prototype.blocks.retrieve>>;
+  newBlock: Awaited<ReturnType<typeof Letta.prototype.blocks.create>>;
+  attachResult: Awaited<
+    ReturnType<typeof Letta.prototype.agents.blocks.attach>
+  >;
+}
+
+/**
+ * Copy a block's content to a new block and attach to the current agent
+ * @param client - Letta client instance
+ * @param blockId - The source block ID to copy from
+ * @param options - Optional settings: labelOverride, targetAgentId
+ * @returns Object containing source block, new block, and attach result
+ */
+export async function copyBlock(
+  client: Letta,
+  blockId: string,
+  options?: { labelOverride?: string; targetAgentId?: string },
+): Promise<CopyBlockResult> {
+  // Get current agent ID (the agent calling this script) or use provided ID
+  const currentAgentId = options?.targetAgentId ?? getCurrentAgentId();
+
+  // 1. Get source block details
+  const sourceBlock = await client.blocks.retrieve(blockId);
+
+  // 2. Create new block with same content (optionally override label)
+  const newBlock = await client.blocks.create({
+    label: options?.labelOverride || sourceBlock.label || "migrated-block",
+    value: sourceBlock.value,
+    description: sourceBlock.description || undefined,
+    limit: sourceBlock.limit,
+  });
+
+  // 3. Attach new block to current agent
+  const attachResult = await client.agents.blocks.attach(newBlock.id, {
+    agent_id: currentAgentId,
+  });
+
+  return { sourceBlock, newBlock, attachResult };
+}
+
+function parseArgs(args: string[]): { blockId: string; label?: string } {
+  const blockIdIndex = args.indexOf("--block-id");
+  const labelIndex = args.indexOf("--label");
+
+  if (blockIdIndex === -1 || blockIdIndex + 1 >= args.length) {
+    throw new Error("Missing required argument: --block-id <block-id>");
+  }
+
+  return {
+    blockId: args[blockIdIndex + 1] as string,
+    label:
+      labelIndex !== -1 && labelIndex + 1 < args.length
+        ? (args[labelIndex + 1] as string)
+        : undefined,
+  };
+}
+
+// CLI entry point
+if (require.main === module) {
+  (async () => {
+    try {
+      const { blockId, label } = parseArgs(process.argv.slice(2));
+      await settingsManager.initialize();
+      const client = await getClient();
+      const result = await copyBlock(client, blockId, { labelOverride: label });
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(
+        "Error:",
+        error instanceof Error ? error.message : String(error),
+      );
+      if (
+        error instanceof Error &&
+        error.message.includes("Missing required argument")
+      ) {
+        console.error(
+          "\nUsage: npx ts-node copy-block.ts --block-id <block-id> [--label <new-label>]",
+        );
+      }
+      process.exit(1);
+    }
+  })();
+}

package/skills/migrating-memory/scripts/get-agent-blocks.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env npx ts-node
+/**
+ * Get Agent Blocks - Retrieves memory blocks from a specific agent
+ *
+ * Usage:
+ *   npx ts-node get-agent-blocks.ts --agent-id <agent-id>
+ *
+ * Output:
+ *   Raw API response from GET /v1/agents/{id}/core-memory/blocks
+ */
+
+import type Letta from "@letta-ai/letta-client";
+import { getClient } from "../../../../agent/client";
+import { settingsManager } from "../../../../settings-manager";
+
+/**
+ * Get memory blocks for a specific agent
+ * @param client - Letta client instance
+ * @param agentId - The agent ID to get blocks from
+ * @returns Array of block objects from the API
+ */
+export async function getAgentBlocks(
+  client: Letta,
+  agentId: string,
+): Promise<Awaited<ReturnType<typeof client.agents.blocks.list>>> {
+  return await client.agents.blocks.list(agentId);
+}
+
+function parseArgs(args: string[]): { agentId: string } {
+  const agentIdIndex = args.indexOf("--agent-id");
+  if (agentIdIndex === -1 || agentIdIndex + 1 >= args.length) {
+    throw new Error("Missing required argument: --agent-id <agent-id>");
+  }
+  return { agentId: args[agentIdIndex + 1] as string };
+}
+
+// CLI entry point
+if (require.main === module) {
+  (async () => {
+    try {
+      const { agentId } = parseArgs(process.argv.slice(2));
+      await settingsManager.initialize();
+      const client = await getClient();
+      const result = await getAgentBlocks(client, agentId);
+      console.log(JSON.stringify(result, null, 2));
+    } catch (error) {
+      console.error(
+        "Error:",
+        error instanceof Error ? error.message : String(error),
+      );
+      if (
+        error instanceof Error &&
+        error.message.includes("Missing required argument")
+      ) {
+        console.error(
+          "\nUsage: npx ts-node get-agent-blocks.ts --agent-id <agent-id>",
+        );
+      }
+      process.exit(1);
+    }
+  })();
+}