@letta-ai/letta-code 0.32.3 → 0.32.4

package/skills/messaging-agents/SKILL.md

@@ -1,201 +1,226 @@
 ---
 name: messaging-agents
-description: Send messages to other agents on your server. Use when you need to communicate with, query, or delegate tasks to another agent.
+description: Send a message to another Letta agent, continue a thread with one, check on it, or reply to a message another agent sent you. Use when you need to ask, inform, or coordinate with another agent, or when a message from another agent arrives.
 ---
 
 # Messaging Agents
 
-This skill enables you to send messages to other agents on the same Letta server using the thread-safe conversations API.
+## What you are addressing
+
+An **agent** is a persistent identity: its memory and configuration are shared
+by all of its conversations. A **conversation** is one message thread on an
+agent. Address a conversation ID to continue a thread; address an agent ID to
+open a new thread with that agent. When your send identifies you as the sender,
+a new thread is created hidden so agent-to-agent traffic does not clutter the
+recipient's conversation list.
+
+## Two backends
+
+Letta Code keeps agent state on one of two backends. The same CLI addresses
+agents on either; what differs is what happens after you send.
+
+**Cloud backend** (api.letta.com). Agent state lives in Cloud. Cloud can deliver
+messages to a *computer*: a machine running Letta Code connected to Cloud,
+or a Cloud sandbox. Because state and execution are
+separate, Cloud tracks which computers are online and where each conversation
+is active. That is why these exist only on this backend:
+
+- delivering your message to the harness already running the recipient's
+  conversation, or to its saved destination (a computer or Cloud sandbox)
+  when none is active;
+- a `computer` selector on sends and on the Agent tool;
+- teleporting a conversation (`letta teleport <computer>`): the same thread,
+  with its history and memory, continues on a different computer. Files and
+  working directories do not move with it.
+
+**Local backend.** Agent state lives in a store on this machine. There is no
+computer concept, so no `computer` selector and no teleport, and no Cloud
+service to deliver on your behalf: a send runs the recipient's turn inside the
+`letta -p` process you launched. Agent IDs on this backend start with
+`agent-local-`.
+
+"Local backend" describes where state is stored. It says nothing about which
+machine a Cloud-backed agent is executing on, and it is unrelated to subagents
+you launch with the Agent tool.
+
+## How a send reaches the recipient
+
+For the Cloud CLI sends below, `letta -p` hands the message to Cloud for
+delivery when you pass `--conversation`, `--from-agent`, `--no-wait`, or
+`--computer`. These commands leave the recipient's execution settings unchanged.
+`SendAgentMessage` uses the same Cloud delivery endpoint.
+
+With only `--agent`, the CLI chooses the launch settings and normally creates a
+new conversation. It runs the turn in its own process or reuses an inherited
+Cloud listener. The listener path first applies those settings to the
+conversation, then submits its input through the same Cloud delivery endpoint.
+Supported local-backend CLI sends run the turn in the launched process.
+
+`--no-wait` is one of the flags that selects Cloud delivery. On that path,
+waiting and non-waiting sends use the same delivery mechanism, but differ in
+how you receive the answer and what reply instructions the recipient gets.
+
+The recipient learns who is asking only when the send identifies a sender:
+`--from-agent`, or for the Cloud messaging recipes below, the caller IDs from
+the agent's shell environment (`AGENT_ID`/`LETTA_AGENT_ID` and
+`CONVERSATION_ID`/`LETTA_CONVERSATION_ID`). `SendAgentMessage`
+always identifies you and your conversation. An identified send attaches a
+system reminder telling the recipient how to get its answer back to you. A
+`letta -p` with neither carries no sender or reply instructions; the recipient
+receives your text as user input, plus whatever context its harness normally
+adds.
+
+An explicit `--from-agent` different from the agent identified by your
+environment does not inherit the current conversation as its return address.
+
+## Waiting or not
+
+- **Waiting send** (`letta -p` without `--no-wait`). The process normally returns
+  the recipient's final message, in `result` with JSON output. When a sender is
+  identified, the recipient is told to put its answer in that message. Works
+  on either backend.
+- **Non-waiting send** (`SendAgentMessage`, or `letta -p --no-wait`). Returns
+  a receipt once Cloud accepts the message. Ordinary assistant output is not
+  forwarded. When a sender is identified, the reminder says so and, if a return
+  conversation is supplied, asks the recipient to send an explicit reply there.
+  That explicit reply becomes a new message in your conversation. Cloud backend
+  only; acceptance does not guarantee a reply.
+
+A waiting send occupies the CLI process, not necessarily you. Run it in the
+background (your shell tool may already do this for long-running commands) and
+read its output when it finishes. That keeps you working, but it does not
+change the recipient's instructions: the answer still arrives as process
+output, not as a message to your conversation.
+
+For a managed child task with a completion notification, use the Agent tool on
+either backend. `SendAgentMessage` only sends input; it creates no task.
+
+## Send and keep working (Cloud backend)
 
-## When to Use This Skill
-
-- You need to ask another agent a question
-- You want to query an agent that has specialized knowledge
-- You need information that another agent has in their memory
-- You want to coordinate with another agent on a task
-
-## What the Target Agent Can and Cannot Do
-
-**The target agent CANNOT:**
-- Access your local environment (read/write files in your codebase)
-- Execute shell commands on your machine
-- Use your tools (Bash, Read, Write, Edit, etc.)
-
-**The target agent CAN:**
-- Use their own tools (whatever they have configured)
-- Access their own memory blocks
-- Make API calls if they have web/API tools
-- Search the web if they have web search tools
-- Respond with information from their knowledge/memory
-
-**Important:** This skill is for *communication* with other agents, not *delegation* of local work. The target agent runs in their own environment and cannot interact with your codebase.
-
-**Need local access?** If you need the target agent to access your local environment (read/write files, run commands), use the Agent tool instead to deploy them as a subagent:
 ```typescript
-Agent({
-  agent_id: "agent-xxx",            // Deploy this existing agent
-  subagent_type: "general-purpose", // read-write access to your local tools
-  prompt: "Look at the code in src/ and tell me about the architecture"
-})
+SendAgentMessage({ conversation_id: "conv-…", message: "…" })   // continue a thread
+SendAgentMessage({ agent_id: "agent-…", message: "…" })         // open a new hidden thread
+SendAgentMessage({ agent_id: "agent-…", conversation_id: "default", message: "…" })  // the agent's default thread
 ```
-This gives the agent access to your codebase while running as a subagent.
-
-## Finding an Agent to Message
 
-If you don't have a specific agent ID, use these skills to find one:
+Success means Cloud accepted the message (`status: "queued"`), not that the
+recipient has read it. Keep working; a reply sent to your return address
+arrives in your conversation.
+Omit `computer`: the conversation continues wherever it is active, and asking
+for a different computer is rejected rather than moving it.
 
-### By Name or Tags
-Load the `finding-agents` skill to search for agents:
-```bash
-letta agents list --query "agent-name"
-letta agents list --tags "origin:letta-code"
-```
+The CLI form behaves the same when run from your agent's environment, which
+supplies the return address; use it from scripts or when the tool is absent:
 
-### By Topic They Discussed
-Search messages across all agents to find which agent worked on something:
 ```bash
-letta messages search --query "topic" --all-agents
+letta -p --conversation <conversation-id> --no-wait --output-format json "message"
+letta -p --agent <agent-id> --no-wait --output-format json "message"
 ```
-Results include `agent_id` for each matching message.
 
-## CLI Usage (agent-to-agent)
-
-### Starting a New Conversation
+## Send and wait (either backend)
 
 ```bash
-letta -p --from-agent $LETTA_AGENT_ID --agent <id> "message text"
+letta -p --from-agent $LETTA_AGENT_ID --agent <agent-id> --output-format json "message"
+letta -p --from-agent $LETTA_AGENT_ID --conversation <conversation-id> --output-format json "follow-up"
 ```
 
-When no `--computer` is specified, the target agent will run on the same
-computer as the caller agent.
+`result` normally holds the recipient's final message; `conversation_id` is
+the thread to continue. `--from-agent` names you and must be an agent on the
+same backend as the recipient.
 
-To route the target agent turn through a specific remote/local computer:
+If your agent ID starts with `agent-local-`, add `--backend local` so the
+command uses the local store: `letta --backend local -p …`. The flag applies to
+that command only.
 
-```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent <id> \
-  --computer <name-or-device-id-or-connection-id> \
-  "message text"
-```
+For these Cloud messaging commands, stopping the wait does not cancel accepted
+work on the recipient's computer. On the local backend the recipient's turn
+runs inside the process you launched, so
+`--tools`, `--permission-mode`, and the working directory you give it apply to
+that turn.
 
-Use `--computer cloud` to route through the target agent's cloud sandbox:
+## Replying to another agent
 
-```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent <id> \
-  --computer cloud \
-  "message text"
-```
+When another agent identifies itself, its message arrives with a system
+reminder naming its agent ID and, when it had one, its conversation ID.
 
-**Arguments:**
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `--agent <id>` | Yes | Target agent ID to message |
-| `--from-agent <id>` | Yes | Sender agent ID (injects agent-to-agent system reminder) |
-| `--computer <selector>` | No | Route through `cloud` (target agent's cloud sandbox) or an online computer by connection name, device ID, or connection ID |
-| `"message text"` | Yes | Message body (positional after flags) |
+- If the reminder says the sender will only see your final message: answer in
+  your response. Nothing more is needed.
+- If the reminder asks for an explicit reply: use its return address with
+  `SendAgentMessage({ agent_id, conversation_id, message })`, or
+  `letta -p --agent <sender-agent-id> --conversation <sender-conversation-id> --no-wait "reply"`.
+  Your ordinary output is not forwarded to the sender.
+- If it says no return conversation was supplied: your output is not forwarded
+  and there is no thread to reply into. Answer as you normally would.
 
-**Example:**
-```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent agent-abc123 \
-  "What do you know about the authentication system?"
-```
+A message without such a reminder carries no sender or reply instructions;
+respond to it as you would to any input.
 
-**Response (JSON format with `--output json`):**
-```json
-{
-  "type": "result",
-  "subtype": "success",
-  "is_error": false,
-  "result": "The authentication system uses JWT tokens...",
-  "agent_id": "agent-abc123",
-  "conversation_id": "conversation-xyz789",
-  "environment": { "source": "same-environment" },
-  "usage": { "prompt_tokens": 120, "completion_tokens": 80, "total_tokens": 200, "step_count": 1 }
-}
-```
+## Checking on a conversation
 
-### Continuing a Conversation
+Recent messages are the quick progress check on either backend. This command
+requests recent messages and prints the returned messages oldest to newest (add
+`--backend local` in the same cases as for sends):
 
 ```bash
-letta -p --from-agent $LETTA_AGENT_ID --conversation <id> "message text"
+letta messages list --conversation <conversation-id> --limit 10
 ```
 
-Add `--computer <selector>` to continue the conversation on a specific computer.
+`letta messages status --conversation <id>` (Cloud only) reports whether the
+conversation is currently running. When `latest_super_run` is present, compare
+its `id` with the `super_run_id` on your receipt; a different ID belongs to a
+different send. Read the messages to see what was processed. Non-waiting
+receipts include ready-to-run `status_command` and `messages_command` values for the thread
+they went to. `letta messages transcript --conversation <id>` exports the
+thread; check `truncated` before treating it as complete.
+`letta messages --help` lists the options.
 
-### Discovering Computers
+## Finding an agent
 
 ```bash
-letta computers list --online-only
-# alias:
-letta envs list --online-only
+letta agents list --query "name"
+letta messages search --query "topic" --all-agents   # discovery; results include agent_id
 ```
 
-Use `connectionName`, `deviceId`, or `connectionId` from the JSON output as the
-`--computer` selector. If a name is ambiguous, prefer `deviceId` or
-`connectionId`. In `computers list`, the current local runtime is marked with
-`"isCurrent": true`.
+Load the `finding-agents` skill for more search options.
 
-To force the target agent onto the current registered Letta Code computer,
-resolve the current computer and pass its `connectionId`:
+## Choosing a computer (Cloud backend)
 
-```bash
-CURRENT_COMPUTER=$(letta computers current | jq -r .connectionId)
-letta -p --from-agent $LETTA_AGENT_ID \
-  --agent agent-abc123 \
-  --computer "$CURRENT_COMPUTER" \
-  "Run on my same computer."
-```
-
-Omit `--computer` when you want the target agent to run on the same computer as
-the caller agent.
-
-**Arguments:**
-| Arg | Required | Description |
-|-----|----------|-------------|
-| `--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) |
+Only when a specific machine is required:
 
-**Example:**
 ```bash
-letta -p --from-agent $LETTA_AGENT_ID \
-  --conversation conversation-xyz789 \
-  "Can you explain more about the token refresh flow?"
-```
-
-## Understanding the Response
-
-- Text-mode scripts return only the **final assistant message** (not tool calls, reasoning, or metadata)
-- JSON and stream-json responses include `agent_id`, `conversation_id`, and `environment.source` so you can continue the same conversation/runtime. Environment-routed turns also include `environment.id`, `connection_id`, `device_id`, and `name`.
-- 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 `letta messages list --agent <id>` targeting the other agent
-
-## How It Works
-
-When you send a message, the target agent receives it with a system reminder:
-```
-<system-reminder>
-This message is from "YourAgentName" (agent ID: agent-xxx), an agent currently running inside the Letta Code CLI (docs.letta.com/letta-code).
-The sender will only see the final message you generate (not tool calls or reasoning).
-If you need to share detailed information, include it in your response text.
-</system-reminder>
+letta computers list --online-only        # connectionName and deviceId
+letta -p --agent <agent-id> --computer <name-or-device-id> --no-wait "message"
+letta -p --agent <agent-id> --computer cloud --no-wait "message"   # its Cloud sandbox
 ```
 
-This helps the target agent understand the context and format their response appropriately.
-
-## Hidden Conversations
-
-Agent-to-agent conversations (started via `--from-agent`) are created **hidden** on the target agent. They don't appear in the target's default conversation list in the ADE, so automated inter-agent chatter doesn't clutter the UI.
-
-To inspect them:
-- List hidden conversations via the API with `archive_status=archived` (or `all`)
-- Pull the transcript directly with `letta messages transcript --conversation <id>`
-- The `conversation_id` returned when you sent the message is the handle you need
-
-Continuing a hidden conversation with `--conversation <id>` keeps it hidden — only archive status is affected, messaging still works normally.
-
-## Related Skills
-
-- **finding-agents**: Find agents by name, tags, or fuzzy search
+If the conversation is active on another computer the send is rejected; to
+move a conversation, teleport it (see the `working-across-computers` skill).
+An offline saved computer does not trigger a Cloud-sandbox fallback.
+`letta computers --help` covers the selectors.
+
+## Gotchas
+
+- `SendAgentMessage`, `--no-wait`, `--computer`, and `messages status` fail on
+  the local backend even when they are offered. Check your agent ID prefix.
+- For Cloud coordination, do not rely on `--agent` alone to select message
+  delivery. Add `--from-agent $LETTA_AGENT_ID` to deliver and identify yourself;
+  pass `--conversation <id>` to reach an existing thread.
+- The Cloud messaging recipes above reject execution flags (`--tools`,
+  `--permission-mode`, `--model`, `--system`, and similar); the recipient keeps
+  its own configuration. Those flags configure a launch when using the
+  retained `--agent`-only path or local-backend execution.
+- `--conversation default` needs `--agent`; `default` is scoped to an agent.
+- A receipt means accepted, not delivered. If a send's outcome is unknown
+  (`acceptance_unknown`, a timed-out wait), read the thread before resending.
+
+## Related
+
+- `letta --help` and each subcommand's `--help` are the reference for flags;
+  this skill explains the concepts and the common recipes.
+- `finding-agents`: locate agents by name, tags, or search.
+- `working-across-computers`: teleporting and moving files between computers.
+- `dispatching-coding-agents`: driving Claude Code or Codex through their
+  CLIs, including background execution and collecting results. The same
+  pattern applies to a Letta Code instance on another backend: run the
+  waiting-send commands above inside it with a `--from-agent` that exists
+  there.

package/skills/working-across-computers/SKILL.md

@@ -22,6 +22,8 @@ Conversation history and agent memory follow the conversation. Files, working di
 
 For remote subagents, set `computer` and pass source paths and destination conversation IDs explicitly. Use the `Agent` tool definition for invocation and resume options.
 
+If the user wants to connect a new computer, `letta teleport list` has no suitable target, or the requested local machine is missing or unreachable, read [Connect a computer for remote access](references/connect-a-computer-for-remote-access.md).
+
 ## Move this conversation
 
 **Run the teleport handoff alone as the final tool call.** After success, do not poll or run more source-side tools; the same conversation resumes at the destination automatically. Set the working directory and check required setup there. If teleport fails, stay on the source and resolve the error before retrying. The Cloud sandbox remains available while you work elsewhere.

package/skills/working-across-computers/references/connect-a-computer-for-remote-access.md

@@ -0,0 +1,59 @@
+# Connect a computer for remote access
+
+Use this guide when the user is connecting a computer for the first time, no suitable computers are listed, or their local machine cannot be reached.
+
+Explain that the user must complete setup **on the computer they want to connect**, signed into the same Letta account they use on chat.letta.com. Remote access lets agents run commands and access files on that machine, subject to tool approvals. Local-only / “Skip login” mode is not sufficient.
+
+Recommend Desktop for a personal computer; offer the CLI for a terminal-only machine or VM. Give the relevant steps below rather than only saying the computer is unavailable. Do not run registration commands in the Cloud sandbox as a substitute for connecting the user's machine.
+
+## Option 1: Letta Desktop
+
+Ask the user to:
+
+1. [Download and install Letta Desktop](https://docs.letta.com/quickstart/) for their operating system.
+2. Open the app and sign in to their Letta account.
+3. Open **Preferences → General** and enable **Allow remote access**.
+4. Set the computer's name in the field beneath the toggle.
+5. Keep Desktop running and the computer awake and connected to the internet.
+6. Open chat.letta.com and select the named computer in the computer picker to run a conversation there.
+
+Show the bundled screenshot when explaining the toggle and name field:
+
+![Desktop Preferences showing Allow remote access and the computer-name field](../assets/allow-remote-access-from-desktop.png)
+
+Resolve `assets/allow-remote-access-from-desktop.png` relative to this skill's directory. In chat or Desktop, use the resolved absolute local path in the Markdown image you send, not this reference file's relative path. The screenshot is from the original teleportation skill; surrounding settings may differ in newer Desktop versions.
+
+## Option 2: CLI server
+
+Ask the user to install [Node.js 22.19 or newer](https://nodejs.org/en/download), then run these commands in a terminal **on the target computer**:
+
+```bash
+npm install -g @letta-ai/letta-code
+letta server --computer-name "work-laptop"
+```
+
+If not already authenticated, the server prints a login URL. Ask the user to open it in a browser and authorize with their Letta account. Do not ask them to paste credentials into chat.
+
+Keep the server process running and the computer awake and online. The named computer will appear in the picker on chat.letta.com or Desktop. For an always-on VM, use a service manager and persist the CLI's authentication state across restarts.
+
+No inbound ports, public IP, or reverse proxy are required: the server connects outward to Letta Cloud. Use plain `letta server`, not `letta server --listen`; `--listen` starts the separate App Server interface for direct application connections.
+
+## Verify access or reconnect an existing computer
+
+After the user completes setup, run:
+
+```bash
+letta teleport list
+```
+
+Use the returned computer name or ID for remote delegation or teleportation. Do not claim access is ready until the desired computer is listed. Keep the current conversation in place unless the user wants to move it; remote subagents can work there while the parent stays in Cloud.
+
+If the computer is still missing or unreachable, ask the user to check that:
+
+- The computer is awake and connected to the internet.
+- Desktop is open with **Allow remote access** enabled, or `letta server` is still running.
+- The app or CLI is signed into the same Letta account as the web session.
+
+Re-list after the user changes the relevant state, rather than repeatedly retrying an unavailable target. If it is listed but an operation still fails, use the concrete error to diagnose authentication, connectivity, or version compatibility; do not assume it needs reinstalling or bypass access controls.
+
+For current installation details, consult the [machine setup docs](https://docs.letta.com/platform/computers/byom/). Verify CLI flags with `letta server --help` if docs and the installed version disagree.

package/skills/context-doctor/ROOT_MEMORY.md

@@ -1,137 +0,0 @@
----
-name: Context Doctor
-id: context-doctor
-description: Identify and repair degradation in system prompt, external memory, and skills preventing you from following instructions or remembering information as well as you should.
----
-
-# Context Doctor
-Your context is what makes you *you* across sessions. You are responsible for managing it (along with memory subagents). It includes:
-- Your system prompt and core memory (root Markdown files)
-- Your external memory (contained in the memory filesystem)
-- Your skills (procedural memory) 
-
-Over time, context can degrade — bloat and poor prompt quality erode your ability to remember the right things and follow instructions properly. This skill helps you identify issues with your context and repair them collaboratively with the user.
-
-**IMPORTANT**: Your edits of your system instructions should be **conservative**. Do NOT make assuptions about what parts of the system prompt are critical. The system prompt defines who you are, so significant modifications to its structure can have unintended consequences. Focus on making minimal changes to meet the token budget, and to effectively link out to external memory. 
-
-## Operating Procedure
-
-### Step 1: Identify and resolve context issues 
-Explore your memory files to identify issues. Consider what is confusing about your own prompts and context, and resolve the issues.
-
-Below are additional common issues with context and how they can be resolved: 
-
-#### System prompt bloat
-Root Markdown files compiled into the system prompt should take up about 10% of the total context size (usually ~15-20K tokens). This is a soft target, not a hard requirement.
-
-Use the built-in CLI to evaluate token usage of the system prompt:
-```bash
-letta memory tokens --format json --quiet
-```
-
-The command reports `total_tokens` and per-file estimates for core memory. It is only a measurement tool; decide whether to intervene based on the actual context and the guidance below.
-
-**Why detail is load-bearing (read this before cutting anything)**: In-context detail does more than carry information. It does at least four things, and byte-counting sweeps only see the first:
-1. **Information** — the literal facts stated
-2. **Attention anchoring** — makes certain topics feel important to the model when it's reasoning
-3. **Semantic priming** — raises the prior on codebase-specific patterns ("this codebase has weird X, don't assume defaults")
-4. **Reasoning templates** — past examples become heuristics for new bugs; rationale in "why" prose becomes scaffolding
-
-Compression preserves (1). It destroys (2), (3), (4). That's why a compressed prompt can make an agent measurably worse at codebase-specific reasoning even though the explicit facts are all "still there" in reference files.
-
-
-**Relative Markdown links from `MEMORY.md` files are NOT equivalent to in-context presence.** They're latent until the agent actively fetches them. An agent only fetches when it already knows it doesn't know. The priming cues that tell it *when* it doesn't know are in the system prompt itself — they can't be replaced by links.
-
-**When to intervene**: Only if the system prompt is *meaningfully* over target. At or near the target, leave it alone. Every edit risks removing content that was doing work you can't see. A prompt that feels "a bit long" is almost always better than one that's been aggressively trimmed.
-
-**Modifying the system prompt**: Make **MINIMAL** changes required to cut the token count of the system prompt if needed. The goal preserve the existing behavior while cutting down the token count. Focus on reducing redundancy or compressing - rather than offloading entire sections to external memory.
-- Preserve persona-defining content (who you are, how you communicate)
-- Preserve user identity or preferences (e.g. the human's name, their stated goals)
-- Maintain the existing distribution of detail: compression should be applied evenly across all topics. If the original prompt was 50% about a specific issue, the new prompt should also be 50% about that issue. 
-- Only reduce noise and improve structure - if compression must result in information loss, preserve lost details into external memory
-
-#### Context redundancy and unclear organization 
-The context in the memory filesystem should have a clear structure, with a well-defined purpose for each file. Memory file descriptions should be precise and non-overlapping. Their contents should be consistent with the description, and have non-overlapping content to other files. 
-
-**Questions to ask**: 
-- Do the descriptions make clear what file is for what? 
-- Do the contents of the file match the descriptions? (you can ask subagents to check)
-
-**Solution**: Read all memory files (use subagents for efficiency), then:
-- Consolidate redundant files
-- Reorganize files and rewrite descriptions to have clear separation of concerns
-- Avoid duplication by referencing common files from multiple places (e.g. `[reference API](reference/api.md)`)
-- Rewrite unclear or low-quality content
-
-#### Invalid context format
-Files in the memory filesystem must follow certain structural requirements: 
-- Must have root `MEMORY.md` and root `persona.md`
-- Root and child `MEMORY.md` files have no frontmatter; every other memory Markdown file has exactly `name` and `description` frontmatter
-- Must NOT have overlapping file and folder names (e.g. `human.md` and `human/identity.md`)
-- Must follow specification for skills (e.g. `skills/{skill_name}/`) with the format:
-```
-skill-name/
-├── SKILL.md          # Required: metadata + instructions
-├── scripts/          # Optional: executable code
-├── references/       # Optional: documentation
-├── assets/           # Optional: templates, resources
-└── ...               # Any additional files or directories
-```
-
-**Solution**: Reorganize files to follow the required structure
-
-### Poor use of progressive disclosure
-Only critical information should be in the system prompt, since it's passed on every turn. Use progressive disclosure so that context only *sometimes* needed can be dynamically retrieved.
-
-Files in indexed child directories are not part of the system prompt, and must be dynamically loaded. Every child directory must contain a frontmatter-free `MEMORY.md`, and you must index your files to ensure your future self can discover them: for example, make sure that files have informative names and descriptions, or are referenced from `MEMORY.md` with ordinary relative Markdown links to create discovery paths. Otherwise, you will never discover the external context or make use of it.
-
-**Solution**: 
-- Reference external skills from the relevant parts of in-context memory:
-```
-When running a migration, always use the [db-migrations skill](skills/db-migrations/SKILL.md)
-```
-or external memory files: 
-```
-Sarah's active projects are: [Letta Code](projects/letta_code.md) and [Letta Cloud](projects/letta_cloud.md)
-```
-- Ensure that contents of files match the file name and descriptions 
-- Make sure your future self will be able to find and load external files when needed. 
-
-### Step 2: Implement context fixes
-Create a plan for what fixes you want to make, then implement them. Favor the smallest possible change that resolves the issue — if the system prompt is 1.5× the target, don't cut it to half the target "for headroom." Cut until you're near the target, then stop.
-
-Before moving on, verify:
-- [ ] System prompt token budget reviewed (target ~10% of context, usually 15-20k tokens)
-- [ ] Changes are proportional to the problem — only offloaded what's needed to meet the target
-- [ ] Preserved detailed rationale, examples, and cross-references in sections that stayed in root core memory
-- [ ] Preferred moving whole files or deleting stale sections over compressing detailed sections into summaries
-- [ ] No overlapping or redundant files remain
-- [ ] All file descriptions are unique, accurate, and match their contents
-- [ ] Moved-out knowledge has ordinary relative Markdown links from `MEMORY.md` so it can be discovered
-- [ ] No semantic changes to persona, user identity, or behavioral instructions
-
-### Step 3: Commit and push
-Review changes, then commit with a descriptive message:
-
-```bash
-cd $MEMORY_DIR
-git status                # Review what changed before staging
-git add <specific files>  # Stage targeted paths — avoid blind `git add -A`
-author_name="${AGENT_NAME:-$AGENT_ID}"
-git commit --author="$author_name <$AGENT_ID@letta.com>" -m "fix(doctor): <summary> 🏥
-
-<identified issues and implemented solutions>"
-
-git push
-```
-
-### Step 4: Final checklist and message
-Tell the user what issues you identified, the fixes you made, the commit you made, and also recommend that they run `/recompile` to apply these changes to the current system prompt. 
-
-Before finishing make sure you: 
-- [ ] Resolved all the identified context issues
-- [ ] Pushed your changes successfully 
-- [ ] Told the user to run `/recompile` to refresh the system prompt and apply changes
-
-## Critical information 
-- **Ask the user about their goals for you, not the implementation**: You understand your own context best, and should follow the guidelines in this document. Do NOT ask the user about their structural preferences — the context is for YOU, not them. Ask them how they want YOU to behave or know instead.