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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.11.1",
+  "version": "0.11.2-next.2",
   "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,177 @@
+#!/usr/bin/env npx tsx
+/**
+ * Find Agents - Search for agents with various filters
+ *
+ * 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 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 { readFileSync } 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>;
+
+interface FindAgentsOptions {
+  name?: string;
+  query?: string;
+  tags?: string[];
+  matchAllTags?: boolean;
+  includeBlocks?: boolean;
+  limit?: number;
+}
+
+/**
+ * Get API key from env var or settings file
+ */
+function getApiKey(): string {
+  // First check env var (set by CLI's getShellEnv)
+  if (process.env.LETTA_API_KEY) {
+    return process.env.LETTA_API_KEY;
+  }
+
+  // Fall back to settings file
+  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() });
+}
+
+/**
+ * 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: LettaClient,
+  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 - check if this file is being run directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  (async () => {
+    try {
+      const options = parseArgs(process.argv.slice(2));
+      const client = createClient();
+      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 tsx 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,161 @@
+#!/usr/bin/env npx tsx
+/**
+ * Attach Block - Attaches an existing memory block to an agent (sharing)
+ *
+ * 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.
+ * It reads agent ID from LETTA_AGENT_ID env var or --agent-id arg.
+ *
+ * Usage:
+ *   npx tsx attach-block.ts --block-id <block-id> [--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:
+ *   --agent-id   Target agent ID (overrides LETTA_AGENT_ID env var)
+ *   --read-only  Target agent can read but not modify the block
+ *
+ * Output:
+ *   Raw API response from the attach operation
+ */
+
+import { readFileSync } 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>;
+
+/**
+ * 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.",
+  );
+}
+
+/**
+ * Get agent ID from CLI arg, env var, or throw
+ */
+function getAgentId(cliArg?: string): string {
+  if (cliArg) return cliArg;
+  if (process.env.LETTA_AGENT_ID) {
+    return process.env.LETTA_AGENT_ID;
+  }
+  throw new Error(
+    "No agent ID provided. Use --agent-id or ensure LETTA_AGENT_ID env var is set.",
+  );
+}
+
+/**
+ * Create a Letta client with auth from env/settings
+ */
+function createClient(): LettaClient {
+  return new Letta({ apiKey: getApiKey() });
+}
+
+/**
+ * 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: LettaClient,
+  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 = getAgentId(targetAgentId);
+
+  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;
+  agentId?: string;
+} {
+  const blockIdIndex = args.indexOf("--block-id");
+  const agentIdIndex = args.indexOf("--agent-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,
+    agentId:
+      agentIdIndex !== -1 && agentIdIndex + 1 < args.length
+        ? (args[agentIdIndex + 1] as string)
+        : undefined,
+  };
+}
+
+// CLI entry point - check if this file is being run directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  (async () => {
+    try {
+      const { blockId, readOnly, agentId } = parseArgs(process.argv.slice(2));
+      const client = createClient();
+      const result = await attachBlock(client, blockId, readOnly, 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 tsx attach-block.ts --block-id <block-id> [--agent-id <agent-id>] [--read-only]",
+        );
+      }
+      process.exit(1);
+    }
+  })();
+}