Letta Code SDK

The SDK interface to Letta Code. Build agents with persistent memory that learn over time.

import { prompt } from '@letta-ai/letta-code-sdk';

const result = await prompt('Find and fix the bug in auth.py', {
  allowedTools: ['Read', 'Edit', 'Bash'],
  permissionMode: 'bypassPermissions'
});
console.log(result.result);

Installation

npm install @letta-ai/letta-code-sdk

Quick Start

One-shot prompt

import { prompt } from '@letta-ai/letta-code-sdk';

const result = await prompt('Run: echo hello', {
  allowedTools: ['Bash'],
  permissionMode: 'bypassPermissions'
});
console.log(result.result); // "hello"

Multi-turn session

import { createSession } from '@letta-ai/letta-code-sdk';

await using session = createSession();

await session.send('What is 5 + 3?');
for await (const msg of session.stream()) {
  if (msg.type === 'assistant') console.log(msg.content);
}

await session.send('Multiply that by 2');
for await (const msg of session.stream()) {
  if (msg.type === 'assistant') console.log(msg.content);
}

Persistent memory

Agents persist across sessions and remember context:

import { createSession, resumeSession } from '@letta-ai/letta-code-sdk';

// First session
const session1 = createSession();
await session1.send('Remember: the secret word is "banana"');
for await (const msg of session1.stream()) { /* ... */ }
const agentId = session1.agentId;
session1.close();

// Later...
await using session2 = resumeSession(agentId);
await session2.send('What is the secret word?');
for await (const msg of session2.stream()) {
  if (msg.type === 'assistant') console.log(msg.content); // "banana"
}

Multi-threaded Conversations

Run multiple concurrent conversations with the same agent. Each conversation has its own message history while sharing the agent's persistent memory.

import { createSession, resumeSession, resumeConversation } from '@letta-ai/letta-code-sdk';

// Create an agent
const session = createSession();
await session.send('Hello!');
for await (const msg of session.stream()) { /* ... */ }
const agentId = session.agentId;
const conversationId = session.conversationId; // Save this!
session.close();

// Resume a specific conversation
await using session2 = resumeConversation(conversationId);
await session2.send('Continue our discussion...');
for await (const msg of session2.stream()) { /* ... */ }

// Create a NEW conversation on the same agent
await using session3 = resumeSession(agentId, { newConversation: true });
await session3.send('Start a fresh thread...');
// session3.conversationId is different from conversationId

// Resume with agent's default conversation
await using session4 = resumeSession(agentId, { defaultConversation: true });

// Resume last used session (agent + conversation)
await using session5 = createSession({ continue: true });

// Create new agent with a new (non-default) conversation
await using session6 = createSession({ newConversation: true });

Key concepts:

• Agent (agentId): Persistent entity with memory that survives across sessions
• Conversation (conversationId): A message thread within an agent
• Session (sessionId): A single execution/connection

Agents remember across conversations (via memory blocks), but each conversation has its own message history.

Agent Configuration

System Prompt

Choose from built-in presets or provide a custom prompt:

// Use a preset
createSession({
  systemPrompt: { type: 'preset', preset: 'letta-claude' }
});

// Use a preset with additional instructions
createSession({
  systemPrompt: { 
    type: 'preset', 
    preset: 'letta-claude',
    append: 'Always respond in Spanish.'
  }
});

// Use a completely custom prompt
createSession({
  systemPrompt: 'You are a helpful Python expert.'
});

Available presets:

• default / letta-claude - Full Letta Code prompt (Claude-optimized)
• letta-codex - Full Letta Code prompt (Codex-optimized)
• letta-gemini - Full Letta Code prompt (Gemini-optimized)
• claude - Basic Claude (no skills/memory instructions)
• codex - Basic Codex
• gemini - Basic Gemini

Memory Blocks

Configure which memory blocks the agent uses:

// Use default blocks (persona, human, project)
createSession({});

// Use specific preset blocks
createSession({
  memory: ['project', 'persona']  // Only these blocks
});

// Use custom blocks
createSession({
  memory: [
    { label: 'context', value: 'API documentation for Acme Corp...' },
    { label: 'rules', value: 'Always use TypeScript. Prefer functional patterns.' }
  ]
});

// Mix presets and custom blocks
createSession({
  memory: [
    'project',  // Use default project block
    { label: 'custom', value: 'Additional context...' }
  ]
});

// No optional blocks (only core skills blocks)
createSession({
  memory: []
});

Convenience Props

Quickly customize common memory blocks:

createSession({
  persona: 'You are a senior Python developer who writes clean, tested code.',
  human: 'Name: Alice. Prefers concise responses.',
  project: 'FastAPI backend for a todo app using PostgreSQL.'
});

// Combine with memory config
createSession({
  memory: ['persona', 'project'],  // Only include these blocks
  persona: 'You are a Go expert.',
  project: 'CLI tool for managing Docker containers.'
});

Tool Execution

Execute tools with automatic permission handling:

import { prompt } from '@letta-ai/letta-code-sdk';

// Run shell commands
const result = await prompt('List all TypeScript files', {
  allowedTools: ['Glob', 'Bash'],
  permissionMode: 'bypassPermissions',
  cwd: '/path/to/project'
});

// Read and analyze code
const analysis = await prompt('Explain what auth.ts does', {
  allowedTools: ['Read', 'Grep'],
  permissionMode: 'bypassPermissions'
});

API Reference

Functions

| Function | Description | |----------|-------------| | prompt(message, options?) | One-shot query, returns result directly | | createSession(options?) | Create new agent session | | resumeSession(agentId, options?) | Resume existing agent by ID | | resumeConversation(conversationId, options?) | Resume specific conversation (derives agent automatically) |

Session

| Property/Method | Description | |-----------------|-------------| | send(message) | Send user message | | stream() | AsyncGenerator yielding messages | | close() | Close the session | | agentId | Agent ID (for resuming later) | | sessionId | Current session ID | | conversationId | Conversation ID (for resuming specific thread) |

Options

interface SessionOptions {
  // Model selection
  model?: string;

  // Conversation options
  conversationId?: string;      // Resume specific conversation
  newConversation?: boolean;    // Create new conversation on agent
  continue?: boolean;           // Resume last session (agent + conversation)
  defaultConversation?: boolean; // Use agent's default conversation

  // System prompt: string or preset config
  systemPrompt?: string | {
    type: 'preset';
    preset: 'default' | 'letta-claude' | 'letta-codex' | 'letta-gemini' | 'claude' | 'codex' | 'gemini';
    append?: string;
  };

  // Memory blocks: preset names, custom blocks, or mixed
  memory?: Array<string | CreateBlock | { blockId: string }>;

  // Convenience: set block values directly
  persona?: string;
  human?: string;
  project?: string;

  // Tool configuration
  allowedTools?: string[];
  permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions';

  // Working directory
  cwd?: string;
}

Message Types

// Streamed during receive()
interface SDKAssistantMessage {
  type: 'assistant';
  content: string;
  uuid: string;
}

// Final message
interface SDKResultMessage {
  type: 'result';
  success: boolean;
  result?: string;
  error?: string;
  durationMs: number;
  conversationId: string;
}

Examples

See examples/ for comprehensive examples including:

• Basic session usage
• Multi-turn conversations
• Session resume with persistent memory
• Multi-threaded conversations (resumeConversation, newConversation)
• System prompt configuration
• Memory block customization
• Tool execution (Bash, Glob, Read, etc.)

Run examples:

bun examples/v2-examples.ts all

# Run just conversation tests
bun examples/v2-examples.ts conversations

License

Apache-2.0