@letta-ai/letta-code 0.11.0 → 0.11.2-next.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);
+    }
+  })();
+}

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,223 @@
+#!/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 { homedir } from "node:os";
+import { join } from "node:path";
+import Letta from "@letta-ai/letta-client";
+
+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(): Letta {
+  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: Letta,
+  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);
+    }
+  })();
+}

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

@@ -0,0 +1,193 @@
+#!/usr/bin/env npx tsx
+
+/**
+ * Search Messages - Search past conversations with vector/FTS search
+ *
+ * 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 search-messages.ts --query <text> [options]
+ *
+ * Options:
+ *   --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 (overrides LETTA_AGENT_ID env var)
+ *
+ * Output:
+ *   Raw API response with search results
+ */
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import Letta from "@letta-ai/letta-client";
+
+interface SearchMessagesOptions {
+  query: string;
+  mode?: "vector" | "fts" | "hybrid";
+  startDate?: string;
+  endDate?: string;
+  limit?: number;
+  allAgents?: boolean;
+  agentId?: string;
+}
+
+/**
+ * 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(): Letta {
+  return new Letta({ apiKey: getApiKey() });
+}
+
+/**
+ * Search messages in past conversations
+ * @param client - Letta client instance
+ * @param options - Search options
+ * @returns Array of search results with scores
+ */
+export async function searchMessages(
+  client: Letta,
+  options: SearchMessagesOptions,
+): Promise<Awaited<ReturnType<typeof client.messages.search>>> {
+  // Default to current agent unless --all-agents is specified
+  let agentId: string | undefined;
+  if (!options.allAgents) {
+    agentId = getAgentId(options.agentId);
+  }
+
+  return await client.messages.search({
+    query: options.query,
+    agent_id: agentId,
+    search_mode: options.mode ?? "hybrid",
+    start_date: options.startDate,
+    end_date: options.endDate,
+    limit: options.limit ?? 10,
+  });
+}
+
+function parseArgs(args: string[]): SearchMessagesOptions {
+  const queryIndex = args.indexOf("--query");
+  if (queryIndex === -1 || queryIndex + 1 >= args.length) {
+    throw new Error("Missing required argument: --query <text>");
+  }
+
+  const options: SearchMessagesOptions = {
+    query: args[queryIndex + 1] as string,
+  };
+
+  const modeIndex = args.indexOf("--mode");
+  if (modeIndex !== -1 && modeIndex + 1 < args.length) {
+    const mode = args[modeIndex + 1] as string;
+    if (mode === "vector" || mode === "fts" || mode === "hybrid") {
+      options.mode = mode;
+    }
+  }
+
+  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;
+    }
+  }
+
+  if (args.includes("--all-agents")) {
+    options.allAgents = true;
+  }
+
+  const agentIdIndex = args.indexOf("--agent-id");
+  if (agentIdIndex !== -1 && agentIdIndex + 1 < args.length) {
+    options.agentId = args[agentIdIndex + 1];
+  }
+
+  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 searchMessages(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 search-messages.ts --query <text> [options]
+
+Options:
+  --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 (overrides LETTA_AGENT_ID env var)
+`);
+      process.exit(1);
+    }
+  })();
+}