@letta-ai/letta-code 0.14.4 → 0.14.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letta-ai/letta-code",
-  "version": "0.14.4",
+  "version": "0.14.6",
   "description": "Letta Code is a CLI tool for interacting with stateful Letta agents from the terminal.",
   "type": "module",
   "bin": {

package/skills/acquiring-skills/SKILL.md

@@ -64,10 +64,11 @@ Browse these repositories to discover available skills. Check the README for ski
 
 | Location | Path | When to Use |
 |----------|------|-------------|
+| **Agent-scoped** | `~/.letta/agents/<agent-id>/skills/<skill>/` | Skills for a single agent (default for agent-specific capabilities) |
 | **Global** | `~/.letta/skills/<skill>/` | General-purpose skills useful across projects |
 | **Project** | `.skills/<skill>/` | Project-specific skills |
 
-**Rule**: If useful across multiple projects, install globally. If project-specific, install in `.skills/`.
+**Rule**: Default to **agent-scoped** for changes that should apply only to the current agent. Use **project** for repo-specific skills. Use **global** only if all agents should inherit the skill.
 
 ## How to Download Skills
 
@@ -80,10 +81,12 @@ Skills are directories containing SKILL.md and optionally scripts/, references/,
 git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
 
 # 2. Copy the skill to your skills directory
+# For agent-scoped (recommended default):
+cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/skills/
 # For global:
-cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
+# cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
 # For project:
-cp -r /tmp/skills-temp/skills/webapp-testing .skills/
+# cp -r /tmp/skills-temp/skills/webapp-testing .skills/
 
 # 3. Cleanup
 rm -rf /tmp/skills-temp
@@ -93,7 +96,7 @@ rm -rf /tmp/skills-temp
 
 ```bash
 git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-rsync -av /tmp/skills-temp/skills/webapp-testing/ ~/.letta/skills/webapp-testing/
+rsync -av /tmp/skills-temp/skills/webapp-testing/ ~/.letta/agents/<agent-id>/skills/webapp-testing/
 rm -rf /tmp/skills-temp
 ```
 
@@ -106,6 +109,7 @@ Skill(command: "refresh")
 ```
 
 This scans `~/.letta/skills/` and `.skills/` and updates your `skills` memory block.
+Agent-scoped skills under `~/.letta/agents/<agent-id>/skills/` are included in the scan as well.
 
 ## Complete Example
 
@@ -117,7 +121,7 @@ User asks: "Can you help me test my React app's UI?"
 4. **Download** (trusted source):
    ```bash
    git clone --depth 1 https://github.com/anthropics/skills /tmp/skills-temp
-   cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/skills/
+   cp -r /tmp/skills-temp/skills/webapp-testing ~/.letta/agents/<agent-id>/skills/
    rm -rf /tmp/skills-temp
    ```
 5. **Refresh**: `Skill(command: "refresh")`

package/skills/defragmenting-memory/SKILL.md

@@ -37,7 +37,7 @@ Memory files live at `~/.letta/agents/$LETTA_AGENT_ID/memory/` and are synced to
 Before the subagent edits files, create a timestamped backup of the memfs directory:
 
 ```bash
-cp -r ~/.letta/agents/$LETTA_AGENT_ID/memory/ ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-$(date +%Y%m%d-%H%M%S)/
+letta memfs backup --agent $LETTA_AGENT_ID
 ```
 
 ⚠️ **CRITICAL**: You MUST complete the backup before proceeding to Step 2. The backup is your safety net.
@@ -160,7 +160,7 @@ After the subagent finishes, **memfs sync will automatically propagate changes**
 ```typescript
 // Step 1: Safety backup (MANDATORY)
 Bash({
-  command: "cp -r ~/.letta/agents/$LETTA_AGENT_ID/memory/ ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-$(date +%Y%m%d-%H%M%S)/",
+  command: "letta memfs backup --agent $LETTA_AGENT_ID",
   description: "Backup memfs directory before defrag"
 })
 
@@ -180,11 +180,10 @@ If something goes wrong, restore from the safety backup:
 
 ```bash
 # Find backups
-ls -la ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-*/
+letta memfs backups --agent $LETTA_AGENT_ID
 
 # Restore from a specific backup (replace the current memory dir)
-rm -rf ~/.letta/agents/$LETTA_AGENT_ID/memory/
-cp -r ~/.letta/agents/$LETTA_AGENT_ID/memory-backup-<TIMESTAMP>/ ~/.letta/agents/$LETTA_AGENT_ID/memory/
+letta memfs restore --agent $LETTA_AGENT_ID --from memory-backup-<TIMESTAMP> --force
 ```
 
 On next CLI startup, memfs sync will detect the changes and update API blocks accordingly.

package/skills/finding-agents/SKILL.md

@@ -15,10 +15,10 @@ This skill helps you find other agents on the same Letta server.
 - 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
+## CLI Usage
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts [options]
+letta agents list [options]
 ```
 
 ### Options
@@ -39,7 +39,7 @@ npx tsx <SKILL_DIR>/scripts/find-agents.ts [options]
 Agents created by Letta Code are tagged with `origin:letta-code`. To find only Letta Code agents:
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts --tags "origin:letta-code"
+letta agents list --tags "origin:letta-code"
 ```
 
 This is useful when the user is looking for agents they've worked with in Letta Code CLI sessions.
@@ -49,39 +49,39 @@ This is useful when the user is looking for agents they've worked with in Letta
 If the user has agents created outside Letta Code (via ADE, SDK, etc.), search without the tag filter:
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts
+letta agents list
 ```
 
 ## Examples
 
 **List all agents (up to 20):**
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts
+letta agents list
 ```
 
 **Find agent by exact name:**
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts --name "ProjectX-v1"
+letta agents list --name "ProjectX-v1"
 ```
 
 **Search agents by name (fuzzy):**
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts --query "project"
+letta agents list --query "project"
 ```
 
 **Find only Letta Code agents:**
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts --tags "origin:letta-code"
+letta agents list --tags "origin:letta-code"
 ```
 
 **Find agents with multiple tags:**
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts --tags "frontend,production" --match-all-tags
+letta agents list --tags "frontend,production" --match-all-tags
 ```
 
 **Include memory blocks in results:**
 ```bash
-npx tsx <SKILL_DIR>/scripts/find-agents.ts --query "project" --include-blocks
+letta agents list --query "project" --include-blocks
 ```
 
 ## Output
@@ -105,11 +105,11 @@ 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
+   letta messages search --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"
+   letta agents list --query "partial-name"
    ```
    Or use the agent_id directly in the Letta API

package/skills/messaging-agents/SKILL.md

@@ -47,37 +47,37 @@ If you don't have a specific agent ID, use these skills to find one:
 ### By Name or Tags
 Load the `finding-agents` skill to search for agents:
 ```bash
-npx tsx <FINDING_AGENTS_SKILL_DIR>/scripts/find-agents.ts --query "agent-name"
-npx tsx <FINDING_AGENTS_SKILL_DIR>/scripts/find-agents.ts --tags "origin:letta-code"
+letta agents list --query "agent-name"
+letta agents list --tags "origin:letta-code"
 ```
 
 ### By Topic They Discussed
 Load the `searching-messages` skill to find which agent worked on something:
 ```bash
-npx tsx <SEARCHING_MESSAGES_SKILL_DIR>/scripts/search-messages.ts --query "topic" --all-agents
+letta messages search --query "topic" --all-agents
 ```
 Results include `agent_id` for each matching message.
 
-## Script Usage
+## CLI Usage (agent-to-agent)
 
 ### Starting a New Conversation
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/start-conversation.ts --agent-id <id> --message "<text>"
+letta -p --from-agent $LETTA_AGENT_ID --agent <id> "message text"
 ```
 
 **Arguments:**
 | Arg | Required | Description |
 |-----|----------|-------------|
-| `--agent-id <id>` | Yes | Target agent ID to message |
-| `--message <text>` | Yes | Message to send |
-| `--timeout <ms>` | No | Max wait time in ms (default: 120000) |
+| `--agent <id>` | Yes | Target agent ID to message |
+| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
+| `"message text"` | Yes | Message body (positional after flags) |
 
 **Example:**
 ```bash
-npx tsx <SKILL_DIR>/scripts/start-conversation.ts \
-  --agent-id agent-abc123 \
-  --message "What do you know about the authentication system?"
+letta -p --from-agent $LETTA_AGENT_ID \
+  --agent agent-abc123 \
+  "What do you know about the authentication system?"
 ```
 
 **Response:**
@@ -93,28 +93,28 @@ npx tsx <SKILL_DIR>/scripts/start-conversation.ts \
 ### Continuing a Conversation
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/continue-conversation.ts --conversation-id <id> --message "<text>"
+letta -p --from-agent $LETTA_AGENT_ID --conversation <id> "message text"
 ```
 
 **Arguments:**
 | Arg | Required | Description |
 |-----|----------|-------------|
-| `--conversation-id <id>` | Yes | Existing conversation ID |
-| `--message <text>` | Yes | Follow-up message to send |
-| `--timeout <ms>` | No | Max wait time in ms (default: 120000) |
+| `--conversation <id>` | Yes | Existing conversation ID |
+| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
+| `"message text"` | Yes | Follow-up message (positional after flags) |
 
 **Example:**
 ```bash
-npx tsx <SKILL_DIR>/scripts/continue-conversation.ts \
-  --conversation-id conversation-xyz789 \
-  --message "Can you explain more about the token refresh flow?"
+letta -p --from-agent $LETTA_AGENT_ID \
+  --conversation conversation-xyz789 \
+  "Can you explain more about the token refresh flow?"
 ```
 
 ## Understanding the Response
 
 - Scripts return only the **final assistant message** (not tool calls or reasoning)
 - The target agent may use tools, think, and reason - but you only see their final response
-- To see the full conversation transcript (including tool calls), use the `searching-messages` skill with `--agent-id` targeting the other agent
+- To see the full conversation transcript (including tool calls), use the `searching-messages` skill with `letta messages list --agent <id>` targeting the other agent
 
 ## How It Works
 

package/skills/migrating-memory/SKILL.md

@@ -7,6 +7,14 @@ description: Migrate memory blocks from an existing agent to the current agent.
 
 This skill helps migrate memory blocks from an existing agent to a new agent, similar to macOS Migration Assistant for AI agents.
 
+> **Requires Memory Filesystem (memfs)**
+>
+> This workflow is memfs-first. If memfs is enabled, do **not** use the legacy block commands — they can conflict with file-based edits.
+>
+> **To check:** Look for a `memory_filesystem` block in your system prompt. If it shows a tree structure starting with `/memory/` including a `system/` directory, memfs is enabled.
+>
+> **To enable:** Ask the user to run `/memfs enable`, then reload the CLI.
+
 ## When to Use This Skill
 
 - User is setting up a new agent that should inherit memory from an existing one
@@ -14,30 +22,42 @@ This skill helps migrate memory blocks from an existing agent to a new agent, si
 - User is replacing an old agent with a new one
 - User mentions they have an existing agent with useful memory
 
-## Migration Methods
+## Migration Method (memfs-first)
+
+### Export → Copy → Sync
 
-### 1. Manual Copy (Recommended for partial content)
+This is the recommended flow:
 
-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
+1. **Export the source agent's memfs to a temp directory**
+   ```bash
+   letta memfs export --agent <source-agent-id> --out /tmp/letta-memfs-<source-agent-id>
+   ```
 
-Best for: Extracting sections, cleaning up messy content, selective migration.
+2. **Copy the files you want into your own memfs**
+   - `system/` = attached blocks (always loaded)
+   - root = detached blocks
 
-### 2. Script Copy (Full block duplication)
+   Example:
+   ```bash
+   cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
+   cp /tmp/letta-memfs-agent-abc123/notes.md ~/.letta/agents/$LETTA_AGENT_ID/memory/
+   ```
 
-Creates new blocks with the same content using `copy-block.ts`. After copying:
-- You own the copy - changes don't sync
-- Best for: One-time migration, forking an agent
+3. **Sync to API**
+   ```bash
+   letta memfs sync --agent $LETTA_AGENT_ID
+   ```
 
-### 3. Share (Linked Blocks)
+This gives you full control over what you bring across and keeps everything consistent with memfs.
 
-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
+## Legacy Fallback (only if memfs is disabled)
+
+If memfs is **not enabled**, you can use block-level commands:
+- `letta blocks list`
+- `letta blocks copy`
+- `letta blocks attach`
+
+⚠️ **Do not use these if memfs is enabled** — they can diverge from file-based edits.
 
 ## Handling Duplicate Label Errors
 
@@ -47,13 +67,13 @@ Attaches the same block to multiple agents using `attach-block.ts`. After sharin
 
 1. **Use `--label` (copy only):** Rename the block when copying:
    ```bash
-   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id <id> --label project-imported
+   letta blocks copy --block-id <id> --label project-imported
    ```
 
 2. **Use `--override` (copy or attach):** Automatically detach your existing block first:
    ```bash
-   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id <id> --override
-   npx tsx <SKILL_DIR>/scripts/attach-block.ts --block-id <id> --override
+   letta blocks copy --block-id <id> --override
+   letta blocks attach --block-id <id> --override
    ```
    If the operation fails, the original block is automatically reattached.
 
@@ -63,7 +83,7 @@ Attaches the same block to multiple agents using `attach-block.ts`. After sharin
    ```
    Then run the copy/attach script.
 
-**Note:** `attach-block.ts` does NOT support `--label` because attached blocks keep their original label (they're shared, not copied).
+**Note:** `letta blocks attach` does NOT support `--label` because attached blocks keep their original label (they're shared, not copied).
 
 ## Workflow
 
@@ -78,55 +98,6 @@ 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 tsx <SKILL_DIR>/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 tsx <SKILL_DIR>/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 tsx <SKILL_DIR>/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`, `--override` |
-| `attach-block.ts` | Attach existing block to current agent | `--block-id`, optional `--read-only`, `--override` |
-
-## 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".
@@ -134,22 +105,17 @@ Scenario: You're a new agent and want to inherit memory from an existing agent "
 1. **Get source agent ID from user:**
    User provides: `agent-abc123`
 
-2. **List its blocks:**
+2. **Export their memfs:**
    ```bash
-   npx tsx <SKILL_DIR>/scripts/get-agent-blocks.ts --agent-id agent-abc123
-   # Shows: project (block-def456), human (block-ghi789), persona (block-jkl012)
+   letta memfs export --agent agent-abc123 --out /tmp/letta-memfs-agent-abc123
    ```
 
-3. **Copy project knowledge to yourself:**
+3. **Copy the relevant files into your memfs:**
    ```bash
-   # If you don't have a 'project' block yet:
-   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id block-def456
-   
-   # If you already have 'project', use --label to rename:
-   npx tsx <SKILL_DIR>/scripts/copy-block.ts --block-id block-def456 --label project-v1
+   cp -r /tmp/letta-memfs-agent-abc123/system/project ~/.letta/agents/$LETTA_AGENT_ID/memory/system/
    ```
 
-4. **Optionally share human preferences (read-only):**
+4. **Sync:**
    ```bash
-   npx tsx <SKILL_DIR>/scripts/attach-block.ts --block-id block-ghi789 --read-only
+   letta memfs sync --agent $LETTA_AGENT_ID
    ```

package/skills/searching-messages/SKILL.md

@@ -15,16 +15,12 @@ This skill helps you search through past conversations to recall context that ma
 - 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.
+## CLI Usage
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/search-messages.ts --query <text> [options]
+letta messages search --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 |
@@ -35,7 +31,8 @@ Replace `<SKILL_DIR>` with the actual path from the `# Skill Directory:` line at
 | `--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) |
+| `--agent <id>` | Explicit agent ID (overrides LETTA_AGENT_ID) |
+| `--agent-id <id>` | Alias for `--agent` |
 
 ### Search Modes
 
@@ -43,12 +40,12 @@ Replace `<SKILL_DIR>` with the actual path from the `# Skill Directory:` line at
 - **vector**: Semantic similarity search (good for conceptual matches)
 - **fts**: Full-text search (good for exact phrases)
 
-## Companion Script: get-messages.ts
+## Companion Command: messages list
 
 Use this to expand around a found needle by message ID cursor:
 
 ```bash
-npx tsx <SKILL_DIR>/scripts/get-messages.ts [options]
+letta messages list [options]
 ```
 
 | Option | Description |
@@ -57,7 +54,8 @@ npx tsx <SKILL_DIR>/scripts/get-messages.ts [options]
 | `--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 |
+| `--agent <id>` | Explicit agent ID (overrides LETTA_AGENT_ID) |
+| `--agent-id <id>` | Alias for `--agent` |
 
 ## Search Strategies
 
@@ -67,19 +65,19 @@ 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
+   letta messages search --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
+   letta messages list --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
+   letta messages list --after "message-xyz" --order asc --limit 10
    ```
 
 ### Strategy 2: Date-Bounded Search
@@ -87,7 +85,7 @@ Use when you need full conversation context around a specific topic:
 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
+letta messages search --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.
@@ -97,7 +95,7 @@ Results are sorted by relevance within the date window.
 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
+letta messages search --query "vague topic" --mode vector --limit 10
 ```
 
 Vector mode finds semantically similar messages even without exact keyword matches.
@@ -107,7 +105,7 @@ Vector mode finds semantically similar messages even without exact keyword match
 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
+letta messages search --query "authentication refactor" --all-agents --limit 10
 ```
 
 Results include `agent_id` for each message. Use this to: