How to Use Letta: A Beginner's Guide to Agent Memory

CodexFuse Team · 2026-11-01T16:49:40.000Z · 16 min read

Learning how to use Letta takes one focused session, and by the end your agent will remember things across conversations the way a good assistant remembers your preferences — because it writes what it learns into its own memory. This letta tutorial is the missing beginner arc: the mental-model lesson, installing the current Agent SDK, creating your first stateful agent, the memory commands that teach it, the dreaming lesson that consolidates what it learned, and the skills habit that extends it. One naming note first: the Letta MemGPT rename landed on September 23, 2024 — old MemGPT tutorials target a retired API, so this guide uses only the current SDK everywhere. And one trap to dodge before you type anything: pip install letta no longer installs the memory platform at all; today it installs Letta Code, a terminal coding agent. The Agent SDK you actually want is a TypeScript package. If you build agents with a general-purpose framework first, start with our Agno beginner guide — Agno is the framework that runs agents; Letta is the memory OS those agents run on. Different layers, and this guide keeps that line sharp.

What Is Letta, Exactly?

The Letta AI platform builds stateful AI agents — agents with persistent memory that survives across conversations, models, and machines. The agent's memory is its own: it lives in a git-backed memory filesystem called MemFS that the agent can inspect and edit as it learns, rather than a context window that gets wiped every session. A small slice of memory (the system/ files, like persona and human) stays in the agent's context on every turn; everything else stays out of context, and the agent sees a file tree and reads only what it needs. Letta offers a managed cloud, a local mode, and a self-hosted server, with a free tier that includes three stateful agents and 5 MiB of storage per memory repository.

How Does Letta's Memory Actually Work?

Think of Letta agent memory as an operating system for what the agent knows: the agent owns a git repository, edits it like files, and commits become memories. When you create an agent, each memory entry you pass — a label and a value — becomes a Markdown file in that repository, named from its label, and creation-time memory lands under system/. Files under system/ are injected into the system prompt on every turn, so keep them small: who the agent is (persona) and who the human is (human). Everything else the agent learns lands elsewhere in the repository, and because the agent sees the whole file tree, it can pull any file into context on demand instead of carrying everything around. Edits only become memory once they are committed and pushed — which is why /remember feels instant but is really a git commit under the hood.

This is the single idea that separates Letta from a plain chatbot with a long context window. A long context window is a bigger whiteboard; MemFS is a filing cabinet the agent organizes itself, with version history. The persona and human shorthands are just conveniences: persona sets who the agent is, human sets what it knows about you, and both are memory blocks like any other. Shared memory repositories let several agents read the same files — but note that Letta-hosted shared repositories are a cloud feature; self-hosted deployments share memory by pointing agents at their own git remote.

What Do You Need Before You Start?

You need Node.js, a Letta account, and an API key — nothing else. Create the key at platform.letta.com/api-keys and export it as LETTA_API_KEY in your shell; the SDK reads that variable by default, so you never paste the key into code. The free tier gives you three stateful agents and 5 MiB of storage per memory repository, which is plenty for learning — the Pro plan at $20 per month raises that to 20 agents and 50 MiB per repository. You do not need to understand git deeply, but knowing that the agent's memory is a git repo will make every command below feel obvious.

If you plan to self-host the Letta server later instead of using the cloud, you will also want a machine that stays on — our VPS hosting guide explains what that means and how to pick one.

How Do You Install the Letta Agent SDK?

Install the current TypeScript SDK with one command: npm install @letta-ai/letta-agent-sdk tsx. The client class is LettaAgentClient, imported from @letta-ai/letta-agent-sdk — if a tutorial shows you letta_client from Python, it is describing the retired V1 API and will not work against the current platform. The SDK supports three backends: cloud (the managed platform), local (the SDK starts its own App Server subprocess on your machine), and remote (you point it at a server you run yourself). Beginners should start with cloud — it removes every infrastructure question from the first session.

Do not confuse the SDK with Letta Code: npm install -g @letta-ai/letta-code installs the terminal coding agent (it needs Node.js 22.19 or newer), and pip install letta installs that same coding agent via Python packaging. Both are useful tools, but neither is the Agent SDK this guide teaches.

How Do You Create Your First Letta Agent?

You create an agent in five steps: initialize the client, call createAgent with a persona and human block, open a session, send a message, and stream the reply. Here is the complete arc.

1. Initialize the client. The SDK reads LETTA_API_KEY from the environment, so client setup is two lines.
2. Create the agent with starting memory. Pass persona and human strings — each becomes a Markdown file under system/ in the agent's memory repository. The call returns the agent's ID as a string, like agent-3f97f111-....
3. Open a session. An agent is the persistent entity; a conversation is a thread on it; a session is the live connection you talk through. createSession(agentId) starts a new conversation.
4. Send and stream. Send a message with session.send(...) and read the reply with for await (const message of session.stream()).
5. Come back later. The agent and its memory persist. resumeSession() accepts either an agent-xxx or a conv-xxx ID, so yesterday's agent is today's agent.

import { LettaAgentClient } from "@letta-ai/letta-agent-sdk";

const client = new LettaAgentClient({ backend: "cloud" });

const agentId = await client.createAgent({
  name: "project-assistant",
  persona: "You are a senior software engineer who keeps a living memory of the project.",
  human: "The user prefers concise answers with code first, explanation after.",
});

const session = await client.createSession(agentId);
await session.send("We use pnpm in this repo, never npm.");
for await (const message of session.stream()) {
  console.log(message);
}

Two creation-time details matter later. First, systemPrompt and disallowedTools can only be set at agent creation — passing them to createSession() or resumeSession() throws, so decide them up front. Second, createAgent() accepts custom system-prompt strings, not preset names; if you want full control over starting memory beyond persona and human, pass explicit memory entries as { label, value } objects.

How Do You Teach Your Agent with Memory Commands?

You teach the agent with four CLI commands, and the habit is: notice a durable fact, say it once, let the agent file it. /init bootstraps or refreshes memory for the current project — the agent inspects the repository, asks about your working style when needed, and can review prior coding sessions with subagents. /remember <lesson> teaches explicitly: the agent decides where the lesson belongs in its memory hierarchy and commits the update to MemFS. /memory shows you what it saved, and you can also inspect $MEMORY_DIR directly since it is just files. /doctor audits the whole setup — memory placement, duplication, and how much of the system prompt your memory blocks consume.

Try it in one loop: send the agent a fact ("we use pnpm in this repo"), run /remember always use pnpm in this repo, then run /memory and watch the lesson appear as a committed file. The agent also updates memory on its own whenever it learns something durable — your explicit /remember is the override, not the only path. When memory grows messy over weeks, ask the agent to reorganize it: the memory workflow backs up the repository first, then splits large files, merges duplicates, and restructures the hierarchy. Since everything is git, nothing the agent "forgets" is ever truly gone — it is in the history. That git-backed property is also why version-controlling your own projects matters; our GitHub beginner guide covers the workflow the agent is quietly imitating.

What Is Dreaming in Letta?

Letta dreaming is the platform's background consolidation: while you work, background subagents review recent conversations, extract the durable lessons, and update memory without interrupting your active session. You configure it with three settings. trigger decides when dreaming runs: off, step-count, or compaction-event (when the context window gets compacted). behavior decides what happens at the trigger: reminder nudges the agent to update memory itself, while auto-launch spawns the background dreaming subagent automatically. stepCount sets the interval, for example 25 steps.

The gotcha that bites everyone once: behavior can only be set at agent creation. Sessions can override trigger and stepCount through the session's dreaming option, but never behavior — so if you want automatic dreaming, set it in createAgent, not later. In the CLI you configure dreaming with /sleeptime; in the app it lives under Dream settings, where you can also require the agent to review proposed memory updates in a second background conversation before they are applied. That review step is worth turning on while you are learning what the agent chooses to remember.

const agentId = await client.createAgent({
  name: "project-assistant",
  persona: "You are a senior software engineer who keeps a living memory of the project.",
  human: "The user prefers concise answers with code first, explanation after.",
  dreaming: { trigger: "step-count", behavior: "auto-launch", stepCount: 25 },
});

How Do Skills Work in Letta?

Skills are packaged instructions the agent loads for particular kinds of tasks, and the habit to build is: when the agent keeps doing a task the same way, turn the pattern into a skill. A skill is a directory containing a SKILL.md file with frontmatter (name and description), optionally alongside scripts/, references/, and templates/. Letta implements the open Agent Skills standard, so skills are portable concepts, not a proprietary format. Install one from GitHub, a registry, or a URL with the Letta CLI:

letta skills install anthropics/skills/pdf --agent agent-abc123

The install is committed to the agent's MemFS git repository under skills/<name>/SKILL.md — which means agent-owned skills travel with the agent, are versioned with its memory, and sync across machines for cloud agents. New skills are discovered on the agent's next message. Skills can come from four sources, and precedence is fixed: project (<cwd>/.agents/skills/) beats agent (the MemFS copy), which beats global (~/.letta/skills/), which beats bundled (harness-shipped). You control which sources a session exposes with skillSources, at creation or per session. Two practical notes: the agent can install skills for itself (a bundled acquiring-skills skill teaches it how), or simply write skills/<name>/SKILL.md into its memory directly. And if you already keep project skills in a .agents/skills/ directory — for example via Vercel's npx skills add — that is exactly what Letta's project source reads, so your existing skills work unchanged. If you live in the terminal, our OpenCode beginner guide covers the terminal-agent side of this world — OpenCode is the agent you drive by hand; a Letta skill is a habit you give an agent that drives itself.

Can You Self-Host Letta?

Yes — a Letta self hosted deployment comes in three shapes to choose from. backend: "cloud" is the managed platform with a managed sandbox or bring-your-own-computer option. backend: "local" makes the SDK start its own App Server as a subprocess on your machine — the fastest way to run everything locally with no account questions. backend: "remote" connects the SDK to an App Server you run yourself, for example letta server --backend local --listen ws://127.0.0.1:4500, and container deployment is documented for that shape. One boundary to respect: shared, Letta-hosted memory repositories are a cloud feature, so a self-hosted deployment shares memory by pointing agents at its own git remote instead.

For a first project, stay on the cloud backend until the agent's behavior — not the infrastructure — is what you are debugging. When you do move to self-hosting, our Docker beginner guide covers the container skills the documented deployment path assumes.

Letta vs Mem0: Which Memory Approach Fits You?

The honest answer depends on whether you want a memory layer or a memory platform. Mem0 is a drop-in memory layer: you bolt passive fact extraction onto whatever agent stack you already run, and it remembers facts across sessions. Letta is a full agent platform built around agent-curated memory tiers: the memory architecture is deeply integrated with the agent framework, which means your agents have to be Letta agents — it is not a drop-in layer for arbitrary agent implementations. A third bet exists too: Zep builds a temporal knowledge graph over the conversation history. An independent comparison frames it cleanly: passive fact extraction (Mem0), agent-curated tiers (Letta), temporal knowledge graph (Zep).

Say the difference once and it sticks: Mem0 remembers for your agents; Letta gives your agents a memory they manage themselves.

How Is Letta Different from Agno and OpenCode?

These three live in different lanes, and the queue of confused beginners is long enough that the lines are worth drawing once. Agno is the agent framework: it runs agents, tools, and teams — the engine room. Letta is the memory OS: it is the layer a stateful agent runs on so it remembers across sessions. OpenCode is the terminal agent: the hands-on coding agent you drive interactively in your shell. You could, in principle, combine the ideas — but never compare them as rivals, because they answer different questions: Agno answers "how do I run agents," Letta answers "how do my agents remember," and OpenCode answers "how do I get coding done in my terminal right now." Our Agno beginner guide and OpenCode beginner guide cover those lanes; this guide owns the memory lane.

What Are the 7 Mistakes Every Letta Beginner Makes?

Every one of these comes from a real beginner trap documented above — read the table, then never pay the tuition.

Sources

Every fact in this guide was verified against live documentation on November 1, 2026: the Letta Agent SDK quickstart and API reference (install command, LettaAgentClient, createAgent shape, sessions), the Letta memory and dreaming documentation (MemFS model, /init, /remember, /memory, /doctor, /sleeptime, dreaming trigger and behavior), the skills documentation (Agent Skills standard, skill sources and precedence, letta skills install), the deployment documentation (cloud, local, and remote backends, self-hosted App Server), the Letta CLI documentation (Letta Code install paths), the official pricing page (free tier: 3 stateful agents and 5 MiB per memory repository; Pro: $20 per month, up to 20 agents and 50 MiB per repository), the Letta Code PyPI page (version 0.34.x; V1 server retired at 0.16.8), the MemGPT-to-Letta rename announcement of September 23, 2024, and two independent memory-architecture comparisons covering the Letta versus Mem0 versus Zep landscape.

Frequently Asked Questions

Is Letta the same as MemGPT?

Letta is the renamed MemGPT — the project came out of stealth under the Letta name on September 23, 2024, and the old letta_client Python API targeted a V1 server that has since been retired. Treat any MemGPT-era tutorial as historical: the current product is the TypeScript Agent SDK built around LettaAgentClient.

Does pip install letta install the Letta platform?

No — and this is the most common beginner trap. The letta PyPI package now installs Letta Code, a stateful terminal coding agent, not the agent-memory platform. To build memory-enabled agents with the SDK, install @letta-ai/letta-agent-sdk from npm instead.

How much does Letta cost?

The free tier costs $0 and includes three stateful agents with 5 MiB of storage per memory repository — enough to learn the full arc in this guide. The Pro plan is $20 per month for up to 20 agents and 50 MiB per memory repository, and usage-based Developer plans cover heavier workloads.

Can Letta work with my existing agents built on another framework?

Not as a drop-in. Letta's memory architecture is deeply integrated with its agent framework, so agents have to be Letta agents to use MemFS, dreaming, and agent-owned skills. If your agents already exist on another stack and you only need them to remember facts, a memory layer like Mem0 is the honest fit.

Where does a Letta agent's memory actually live?

In a git repository owned by the agent, projected onto the machine by MemFS. Memory you set at creation becomes Markdown files under system/ and stays in context every turn; everything else is a file tree the agent reads on demand. Edits become memory when committed and pushed, shared repositories are a cloud feature, and self-hosted deployments point agents at their own git remote.

Letta rewards one habit above all: teach the durable thing once, in the open, with /remember, and let dreaming do the filing while you sleep. Build that habit and your agents stop starting over every morning.