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

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

@@ -0,0 +1,173 @@
+#!/usr/bin/env npx tsx
+/**
+ * Copy Block - Copies a memory block to create a new independent block for the current agent
+ *
+ * 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 copy-block.ts --block-id <block-id> [--label <new-label>] [--agent-id <agent-id>]
+ *
+ * Options:
+ *   --label      Override the block label (required if you already have a block with that label)
+ *   --agent-id   Target agent ID (overrides LETTA_AGENT_ID env var)
+ *
+ * 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 { 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 CopyBlockResult {
+  sourceBlock: Awaited<ReturnType<LettaClient["blocks"]["retrieve"]>>;
+  newBlock: Awaited<ReturnType<LettaClient["blocks"]["create"]>>;
+  attachResult: Awaited<ReturnType<LettaClient["agents"]["blocks"]["attach"]>>;
+}
+
+/**
+ * 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() });
+}
+
+/**
+ * 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: LettaClient,
+  blockId: string,
+  options?: { labelOverride?: string; targetAgentId?: string },
+): Promise<CopyBlockResult> {
+  // Get current agent ID (the agent calling this script) or use provided ID
+  const currentAgentId = getAgentId(options?.targetAgentId);
+
+  // 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;
+  agentId?: string;
+} {
+  const blockIdIndex = args.indexOf("--block-id");
+  const labelIndex = args.indexOf("--label");
+  const agentIdIndex = args.indexOf("--agent-id");
+
+  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,
+    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, label, agentId } = parseArgs(process.argv.slice(2));
+      const client = createClient();
+      const result = await copyBlock(client, blockId, {
+        labelOverride: label,
+        targetAgentId: 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 copy-block.ts --block-id <block-id> [--label <new-label>] [--agent-id <agent-id>]",
+        );
+      }
+      process.exit(1);
+    }
+  })();
+}

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

@@ -0,0 +1,103 @@
+#!/usr/bin/env npx tsx
+/**
+ * Get Agent Blocks - Retrieves memory blocks from a specific agent
+ *
+ * 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 get-agent-blocks.ts --agent-id <agent-id>
+ *
+ * Output:
+ *   Raw API response from GET /v1/agents/{id}/core-memory/blocks
+ */
+
+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.",
+  );
+}
+
+/**
+ * Create a Letta client with auth from env/settings
+ */
+function createClient(): LettaClient {
+  return new Letta({ apiKey: getApiKey() });
+}
+
+/**
+ * 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: LettaClient,
+  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 - check if this file is being run directly
+const isMainModule = import.meta.url === `file://${process.argv[1]}`;
+if (isMainModule) {
+  (async () => {
+    try {
+      const { agentId } = parseArgs(process.argv.slice(2));
+      const client = createClient();
+      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 tsx get-agent-blocks.ts --agent-id <agent-id>",
+        );
+      }
+      process.exit(1);
+    }
+  })();
+}

package/skills/searching-messages/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: searching-messages
+description: Search past messages to recall context. Use when you need to remember previous discussions, find specific topics mentioned before, pull up context from earlier in the conversation history, or find which agent discussed a topic.
+---
+
+# Searching Messages
+
+This skill helps you search through past conversations to recall context that may have fallen out of your context window.
+
+## When to Use This Skill
+
+- User asks "do you remember when we discussed X?"
+- You need context from an earlier conversation
+- User references something from the past that you don't have in context
+- You want to verify what was said before about a topic
+- You need to find which agent discussed a specific topic (use with `finding-agents` skill)
+
+## Script Usage
+
+The scripts are located in the `scripts/` subdirectory of this skill. Use the **Skill Directory** path shown above when loading this skill.
+
+```bash
+npx tsx <SKILL_DIR>/scripts/search-messages.ts --query <text> [options]
+```
+
+Replace `<SKILL_DIR>` with the actual path from the `# Skill Directory:` line at the top of this loaded skill.
+
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `--query <text>` | Search query (required) |
+| `--mode <mode>` | Search mode: `vector`, `fts`, `hybrid` (default: hybrid) |
+| `--start-date <date>` | Filter messages after this date (ISO format) |
+| `--end-date <date>` | Filter messages before this date (ISO format) |
+| `--limit <n>` | Max results (default: 10) |
+| `--all-agents` | Search all agents, not just current agent |
+| `--agent-id <id>` | Explicit agent ID (for manual testing) |
+
+### Search Modes
+
+- **hybrid** (default): Combines vector similarity + full-text search with RRF scoring
+- **vector**: Semantic similarity search (good for conceptual matches)
+- **fts**: Full-text search (good for exact phrases)
+
+## Companion Script: get-messages.ts
+
+Use this to expand around a found needle by message ID cursor:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/get-messages.ts [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--after <message-id>` | Get messages after this ID (cursor) |
+| `--before <message-id>` | Get messages before this ID (cursor) |
+| `--order <asc\|desc>` | Sort order (default: desc = newest first) |
+| `--limit <n>` | Max results (default: 20) |
+| `--agent-id <id>` | Explicit agent ID |
+
+## Search Strategies
+
+### Strategy 1: Needle + Expand (Recommended)
+
+Use when you need full conversation context around a specific topic:
+
+1. **Find the needle** - Search with keywords to discover relevant messages:
+   ```bash
+   npx tsx <SKILL_DIR>/scripts/search-messages.ts --query "flicker inline approval" --limit 5
+   ```
+
+2. **Note the message_id** - Find the most relevant result and copy its `message_id`
+
+3. **Expand before** - Get messages leading up to the needle:
+   ```bash
+   npx tsx <SKILL_DIR>/scripts/get-messages.ts --before "message-xyz" --limit 10
+   ```
+
+4. **Expand after** - Get messages following the needle (use `--order asc` for chronological):
+   ```bash
+   npx tsx <SKILL_DIR>/scripts/get-messages.ts --after "message-xyz" --order asc --limit 10
+   ```
+
+### Strategy 2: Date-Bounded Search
+
+Use when you know approximately when something was discussed:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/search-messages.ts --query "topic" --start-date "2025-12-31T00:00:00Z" --end-date "2025-12-31T23:59:59Z" --limit 15
+```
+
+Results are sorted by relevance within the date window.
+
+### Strategy 3: Broad Discovery
+
+Use when you're not sure what you're looking for:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/search-messages.ts --query "vague topic" --mode vector --limit 10
+```
+
+Vector mode finds semantically similar messages even without exact keyword matches.
+
+### Strategy 4: Find Which Agent Discussed Something
+
+Use with `--all-agents` to search across all agents and identify which one discussed a topic:
+
+```bash
+npx tsx <SKILL_DIR>/scripts/search-messages.ts --query "authentication refactor" --all-agents --limit 10
+```
+
+Results include `agent_id` for each message. Use this to:
+1. Find the agent that worked on a specific feature
+2. Identify the right agent to ask follow-up questions
+3. Cross-reference with the `finding-agents` skill to get agent details
+
+**Tip:** Load both `searching-messages` and `finding-agents` skills together when you need to find and identify agents by topic.
+
+## Search Output
+
+Returns search results with:
+- `message_id` - Use this for cursor-based expansion
+- `message_type` - `user_message`, `assistant_message`, `reasoning_message`
+- `content` or `reasoning` - The actual message text
+- `created_at` - When the message was sent (ISO format)
+- `agent_id` - Which agent the message belongs to

package/skills/searching-messages/scripts/get-messages.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Get Messages - Retrieve messages from an agent in chronological order
+ *
+ * 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 get-messages.ts [options]
+ *
+ * Options:
+ *   --start-date <date>   Filter messages after this date (ISO format)
+ *   --end-date <date>     Filter messages before this date (ISO format)
+ *   --limit <n>           Max results (default: 20)
+ *   --agent-id <id>       Explicit agent ID (overrides LETTA_AGENT_ID env var)
+ *   --after <message-id>  Cursor: get messages after this ID
+ *   --before <message-id> Cursor: get messages before this ID
+ *   --order <asc|desc>    Sort order (default: desc = newest first)
+ *
+ * Use this after search-messages.ts to expand around a found needle.
+ *
+ * Output:
+ *   Messages in chronological order (filtered by date if specified)
+ */
+
+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 GetMessagesOptions {
+  startDate?: string;
+  endDate?: string;
+  limit?: number;
+  agentId?: string;
+  after?: string;
+  before?: string;
+  order?: "asc" | "desc";
+}
+
+/**
+ * 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.",
+  );
+}
+
+/**
+ * Get agent ID from CLI arg, env var, or throw
+ */
+function getAgentId(cliArg?: string): string {
+  // CLI arg takes precedence
+  if (cliArg) return cliArg;
+
+  // Then env var (set by CLI's getShellEnv)
+  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() });
+}
+
+/**
+ * Get messages from an agent, optionally filtered by date range
+ * @param client - Letta client instance
+ * @param options - Options for filtering
+ * @returns Array of messages in chronological order
+ */
+export async function getMessages(
+  client: LettaClient,
+  options: GetMessagesOptions = {},
+): Promise<unknown[]> {
+  const agentId = getAgentId(options.agentId);
+  const limit = options.limit ?? 20;
+
+  // Fetch messages from the agent
+  const response = await client.agents.messages.list(agentId, {
+    limit,
+    after: options.after,
+    before: options.before,
+    order: options.order,
+  });
+
+  const messages = response.items ?? [];
+
+  // Client-side date filtering if specified
+  if (options.startDate || options.endDate) {
+    const startTime = options.startDate
+      ? new Date(options.startDate).getTime()
+      : 0;
+    const endTime = options.endDate
+      ? new Date(options.endDate).getTime()
+      : Number.POSITIVE_INFINITY;
+
+    const filtered = messages.filter((msg) => {
+      // Messages use 'date' field, not 'created_at'
+      if (!("date" in msg) || !msg.date) return true;
+      const msgTime = new Date(msg.date).getTime();
+      return msgTime >= startTime && msgTime <= endTime;
+    });
+
+    // Sort chronologically (oldest first)
+    return filtered.sort((a, b) => {
+      const aDate = "date" in a && a.date ? new Date(a.date).getTime() : 0;
+      const bDate = "date" in b && b.date ? new Date(b.date).getTime() : 0;
+      return aDate - bDate;
+    });
+  }
+
+  // Sort chronologically (oldest first)
+  return [...messages].sort((a, b) => {
+    const aDate = "date" in a && a.date ? new Date(a.date).getTime() : 0;
+    const bDate = "date" in b && b.date ? new Date(b.date).getTime() : 0;
+    return aDate - bDate;
+  });
+}
+
+function parseArgs(args: string[]): GetMessagesOptions {
+  const options: GetMessagesOptions = {};
+
+  const startDateIndex = args.indexOf("--start-date");
+  if (startDateIndex !== -1 && startDateIndex + 1 < args.length) {
+    options.startDate = args[startDateIndex + 1];
+  }
+
+  const endDateIndex = args.indexOf("--end-date");
+  if (endDateIndex !== -1 && endDateIndex + 1 < args.length) {
+    options.endDate = args[endDateIndex + 1];
+  }
+
+  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;
+    }
+  }
+
+  const agentIdIndex = args.indexOf("--agent-id");
+  if (agentIdIndex !== -1 && agentIdIndex + 1 < args.length) {
+    options.agentId = args[agentIdIndex + 1];
+  }
+
+  const afterIndex = args.indexOf("--after");
+  if (afterIndex !== -1 && afterIndex + 1 < args.length) {
+    options.after = args[afterIndex + 1];
+  }
+
+  const beforeIndex = args.indexOf("--before");
+  if (beforeIndex !== -1 && beforeIndex + 1 < args.length) {
+    options.before = args[beforeIndex + 1];
+  }
+
+  const orderIndex = args.indexOf("--order");
+  if (orderIndex !== -1 && orderIndex + 1 < args.length) {
+    const order = args[orderIndex + 1] as string;
+    if (order === "asc" || order === "desc") {
+      options.order = order;
+    }
+  }
+
+  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 getMessages(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 get-messages.ts [options]
+
+Options:
+  --after <message-id>  Cursor: get messages after this ID
+  --before <message-id> Cursor: get messages before this ID
+  --order <asc|desc>    Sort order (default: desc = newest first)
+  --limit <n>           Max results (default: 20)
+  --agent-id <id>       Explicit agent ID (overrides LETTA_AGENT_ID env var)
+  --start-date <date>   Client-side filter: after this date (ISO format)
+  --end-date <date>     Client-side filter: before this date (ISO format)
+`);
+      process.exit(1);
+    }
+  })();
+}