letta-code: Curing the Coding Agent's Goldfish Memory

The 50 First Dates Problem

The standard interaction model for AI coding tools is fundamentally flawed. Every time you open a new terminal session with Claude Code or Codex, you are meeting a stranger. The agent has no memory of the architectural decisions you made yesterday. It does not know your preferred linting rules. It suffers from a permanent case of goldfish memory.

Developers spend the first ten minutes of every session re-pasting context, explaining the directory structure, and begging the model not to use deprecated APIs. Letta Code views this as a systemic failure. Instead of building a better prompt wrapper, the Letta team built an OS-level abstraction for AI memory.

A Filesystem for the Artificial Mind

The core of Letta's architecture is MemFS. Rather than stuffing a monolithic text file into the LLM context window, Letta provisions a virtual directory structure for every agent. This filesystem lives in `.letta/agents/{id}/memory` and mimics a real hard drive.

The agent interacts with this memory through `.mdx` files equipped with frontmatter. Files like `persona.mdx` and `human.mdx` define the agent's core identity and its understanding of the user. Because this memory is structured as an actual filesystem, the agent can use internal commands to read, write, and organize its own knowledge base over time. If a developer corrects a stylistic error, the agent writes that correction to disk. The next session boots with that knowledge already loaded.

Rendering React to the Terminal

Building a rich user interface in a raw shell environment is notoriously difficult. To solve this, Letta Code leans on Ink. Ink is a React renderer that targets the terminal instead of the DOM. This allows the engineering team to construct complex visual components using familiar React hooks.

Components like `AdvancedDiffRenderer` and `ApprovalDialogRich` are written in TypeScript and JSX. They are then translated into standard ANSI escape codes. This bridges the gap between a modern GUI and the speed of a CLI tool.

import { Text, Box } from 'ink';
import React from 'react';

export const AgentStatus = ({ memorySize, activeSkills }) => (
  <Box borderStyle="round" borderColor="green" padding={1}>
    <Box flexDirection="column">
      <Text bold>Letta Agent Active</Text>
      <Text color="gray">MemFS Blocks: {memorySize}</Text>
      <Text color="cyan">Loaded Skills: {activeSkills.join(', ')}</Text>
    </Box>
  </Box>
);

Hierarchical Intelligence

An agent needs tools to be useful. Letta handles this through a hierarchical `.skills/` directory system. The capabilities of the agent change dynamically based entirely on which folder the developer is currently working in.

When Letta Code boots, it performs a resolution cascade. It first checks the current working directory for a `.skills/` folder. It then checks for agent-specific skills, followed by global user skills, and finally bundled defaults. This means a developer can commit a `.skills/` directory to a specific Git repository. Anyone who clones that repo and runs Letta will automatically equip their agent with the exact test scripts and deployment tools required for that specific project.

The Contractor vs. The Coworker

The current generation of AI tools operates like a series of day laborers. You hire them, explain the job from scratch, they do the work, and they leave. Letta Code introduces the paradigm of the coworker. The coworker retains context, learns preferences, and builds a persistent model of the codebase.

Because the memory state is decoupled from the LLM provider, developers are not locked into a specific ecosystem. You can swap Anthropic's Claude for Google's Gemini without losing the persona or the project context the agent has accumulated.