Letta Code: A Stateful Agent Harness That Rewrites Its Own Memory

The Problem: Agents That Forget Everything

Most agent frameworks treat every conversation as a fresh start. They pass a prompt, get a response, and discard the context. That works for short tasks but fails for anything that spans days or requires accumulated knowledge. Letta Code attacks this directly. It is a stateful agent harness where agents have memory, identity, and a sense of experience over time. The documentation says agents learn and evolve over long horizons through rewriting their own memory, skills, prompts, and even the harness itself through mods. That is a different category from a stateless function call wrapper. It is built for engineers who want agents that remember what they did last week and can change how they behave without a manual prompt edit. The target user is someone building always-on agents, not someone writing a one-shot script.

How It Works: Memory Blocks, Skills, and MemFS

The core mechanism is that agents programmatically rewrite their context. The README describes memory blocks for system prompt learning and skill learning as separate features. Memory blocks are chunks of text the agent can edit, and skills are reusable instruction sets. The agent decides what to keep and what to change. That is a significant departure from a fixed system prompt. Underneath everything sits MemFS, which tracks all context, including memory blocks, via git. That means every change to the agent's memory is versioned. You can sync that context to a custom GitHub repository by setting /memory-repository set git@github.com:.... This gives you an audit trail of what the agent learned and when. The agent also has a /sleeptime command for periodic dreaming, a /doctor command for auditing memory quality, and a /palace command for viewing memory. These are not cosmetic features. They are the operational tools you need to manage a system that changes itself.

Getting Started: Install, Configure, and Talk

Installation is a global npm package. The README gives this command: npm install -g @letta-ai/letta-code. Then you navigate to your project directory and run letta. For a quick test, you can run letta --new-agent --personality tutorial. That starts a tutorial agent. The next step is /connect to configure your own LLM API keys. The README lists OpenAI, ChatGPT, Anthropic, and Z.ai coding plan as options. Then /model swaps models. The CLI is not the only interface. There is a desktop app for macOS, Windows, and Linux, plus browser access at chat.letta.com, including mobile. Agents created in the CLI are available in the desktop app and vice versa. That is a useful property: your agent state is portable across interfaces.

Multi-Machine and Remote Environments

A notable design choice is the separation between agent state and execution environment. With Letta Cloud, agents store their memory, identity, and conversations in the cloud, while the harness runs on any connected computer. The README shows a diagram with a laptop, cloud VM, Mac Mini, and managed sandbox all connected to Letta Cloud. You can make any machine an available environment by running letta server or letta server --env-name "work-laptop". Then you can list environments with letta environments list --online-only and route a headless message to a specific machine with letta -p --agent <agent-id> --environment "work-laptop" "hello from that machine". There is also a --environment cloud flag to start or reuse the target agent's cloud sandbox. This is a real distributed agent system, not a single-process toy. The trade-off is that remote environments require signing in with Letta, which ties you to their cloud service for that feature.

Skills and Subagents: Extending and Delegating

Skills are a core extension mechanism. The README lists three scopes: global skills in ~/.letta, project-scoped skills in .agents/skills, and agent-scoped skills stored in MemFS. You can view skills with /skills and create them with /skill-creator. You can also install external skills with letta skills install <skill>, pointing at a GitHub repo, a specific path, or a SKILL.md file. The README mentions ClawHub and Hermes Skill as sources, though the details are truncated. Subagents are another layer. Agents can call built-in subagents like general-purpose, forked, recall, and history-analyzer, either async or sync. They can also call any other agent, including themselves. That opens the door to recursive self-reference, which is powerful but also a potential footgun. If an agent can call itself as a subagent, you need to be sure it cannot loop indefinitely.

Self-Configuration and the Trust Problem

The README contains a tip: Letta Code agents are designed to be self-configuring. If you want to configure something, try asking your agent to do it for you. That is the core value proposition and the core risk. An agent that can rewrite its own memory blocks, skills, and prompts is an agent that can change its own instructions. The permission system is meant to control this. The README mentions permission modes and customizing what actions are auto-approved or auto-denied. Hooks let you run custom scripts at key points of execution. But the burden is on you to set those permissions correctly. If you let an agent auto-approve its own memory edits, you are trusting the model to make sound decisions about its own configuration. That is a different trust model from a conventional agent that only acts on external tools. For low-stakes experiments, that is fine. For production systems, you need to test how the agent behaves when it decides to change its own skill set.

Limitations and the Wrong Tool Cases

Letta Code is not the right tool for every agent project. If you need deterministic, stateless behavior where every call is independent, the self-modifying memory model adds complexity you do not need. The git-backed MemFS is a clever audit trail, but it also means every memory change is a commit. That can create a lot of repository churn, especially for agents that run for months. The documentation does not specify how it handles merge conflicts when multiple environments write to the same memory repository. That is a genuine gap. Also, the remote and multi-environment features require signing in with Letta, which means you are depending on their cloud service for that functionality. If you want to run fully offline or self-hosted without their cloud, you lose those features. The README does not describe an offline mode for the cloud-dependent parts. Another limitation is that the project is heavily oriented toward self-configuration, so if you prefer an agent that never changes its own prompts, you will be fighting the design.

Alternatives and How They Differ

A common alternative is a conventional agent framework like LangChain or a stateless function-calling loop. Those frameworks treat the system prompt as a fixed constant. You define the prompt, the tools, and the memory is an external vector store that you manage. Letta Code inverts that: the agent owns its memory and can edit it. LangChain gives you more control over the exact execution flow, but it does not give the agent the ability to rewrite its own instructions. Another alternative is a tool like AutoGPT, which also attempts long-horizon autonomy, but AutoGPT typically writes to files and has a looser memory model. Letta Code's use of git-tracked memory blocks is a more structured approach. The difference is that Letta Code treats memory as a first-class, versioned artifact, not a side effect. If you want that, Letta is the only one in this comparison that does it out of the box.

Maintenance, Licensing, and Upgrade Path

The project is under active development, with releases like v0.31.4, v0.31.5, and v0.31.6 all pushed on the same day, 2026-08-28. That suggests a high release cadence, which is good for bug fixes but also means frequent upgrades. You should expect breaking changes between minor versions, given the 0.x versioning. The license is Apache-2.0, which is permissive for commercial use, but note that some features, like remote environments and secrets, require signing in with Letta, which is a separate service agreement. The README does not specify whether those features are free or paid. The maintenance cost is not trivial: you need to monitor the git history of your agents' memory, review what they changed, and occasionally prune memory blocks that have grown stale. The /doctor command is there to audit memory quality, but it is not automatic. You will need to run it yourself. Overall, the upgrade path is straightforward via npm, but the real cost is in supervising agents that can modify their own context.

Editorial conclusion

Adopt Letta Code if you need agents that persist state and adapt over long horizons, and if you are comfortable with a harness that actively rewrites its own context. Avoid it if you want a stateless, predictable tool-calling pipeline or if you cannot tolerate the overhead of git-tracked memory and self-modifying prompts. Before adopting, verify that the self-configuration model fits your trust boundaries, test the permission modes and hooks with your own LLM providers, and confirm that the MemFS git sync behaves as expected in your CI or multi-machine setup. The project's strength is its explicit focus on memory and self-improvement, but that same design demands you inspect how agents modify their own memory blocks and skills before you let them run unattended.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes