---
title: Memory | Letta Docs
description: Understand Letta Agent's self-improving memory system
---

With Letta Agent, you use the same agent indefinitely — across sessions, days, or months — and have it get better over time. Your agent remembers past interactions, learns your preferences, and self-edits its memory as it works.

Letta Agent also lets you customize your agent’s personality. With Claude Code or Codex, every user gets the same agent that acts identically. With Letta Agent, you can deeply personalize your agents to be unique to *you*.

## Agents and conversations

In Letta Agent, there are two important session concepts: **agents** and **conversations**.

- An **agent** has a name, memory, model configuration, and collective message history.
- A **conversation** is a single message thread, or “session”, with an agent. One agent can have many parallel conversations.

When you run the `letta` CLI without any arguments, it resumes the default conversation with your last-used agent. To run multiple CLI sessions with one agent in parallel, use `letta --new` to start a new conversation, or `/new` while inside the CLI.

Letta Agent includes a default agent and a few example presets. To switch agents in the CLI, use `/agents`. You can favorite an agent with `/pin`, or by clicking the favorite button in the desktop app.

## Initializing memory

Run `/init` to bootstrap or refresh your agent’s memory. Letta Agent inspects the current project, asks about your working style when needed, and can review prior Claude Code and OpenAI Codex sessions using [subagents](/letta-agent/subagents/index.md).

If your memory structure has drifted or become messy, run `/doctor` to audit memory placement and token usage.

## Teaching your agent

Your agent can update memory on its own when it learns something durable. You can also direct it explicitly with `/remember`:

Terminal window

```
> /remember always use pnpm in this repo
```

## Dreaming (sleep-time compute)

Letta Agent can launch sleep-time or “dream” subagents that review recent conversations and write useful lessons into memory.

Use `/sleeptime` in the CLI to configure reflection, or click the sleeping alien icon in the app.

The trigger settings determine when the background dream runs:

- `Off`: disable dream subagents
- `Step count`: trigger a dream every N user messages
- `Compaction event`: trigger a dream when the context window is compacted

For larger cleanups, ask your agent to reorganize memory. The memory defragmentation flow backs up current memory, then launches a subagent to split large files, merge duplicates, and restructure the hierarchy.

## How memory is stored

Letta Agent stores agent memory in **MemFS**: a git-backed memory filesystem, also called a [context repository](https://www.letta.com/blog/context-repositories). MemFS projects the agent’s memory blocks into markdown files on the local machine with version history, conflict resolution, and direct inspection/editing when needed.

If your agent is running on [Constellation](/letta-agent/constellation/index.md), its memory is managed in Letta’s cloud service, and cloned locally in `$MEMORY_DIR` for your agent to edit.

If your agent is running on the local backend, its memory is stored in local git repos on your own machine - so make sure to back up your local agent’s state to prevent data loss.

## Memory structure

Each projected memory file is markdown with YAML frontmatter:

```
---
description: "Who I am, what I value, and how I approach working with people."
---


My name is Letta Agent. I'm a stateful coding assistant — I remember, I learn, and I grow.
```

## The `system/` directory

Files in `system/` are always loaded into the agent’s system prompt. This is where the agent keeps information it needs on every turn: persona, important user preferences, durable project facts, and critical workflow rules.

Files outside `system/` are visible through the memory tree, including their paths and descriptions, but their full contents are loaded only when relevant. This keeps the context window lean while preserving deeper reference material.

Your agent manages this hierarchy over time: creating files, reorganizing folders, and moving content in or out of `system/` as it learns what should stay in context.

## Skills in memory

Your agent can store skills inside its memory, allowing skills to travel with the agent, rather than remain stuck on a device. These skills live under `$MEMORY_DIR/skills`:

```
$MEMORY_DIR/skills/
└── my-skill/
    └── SKILL.md
```

Skills in this directory are owned by that agent and versioned with the rest of its memory repository. See the full [skills](/letta-agent/skills/index.md) docs for all skill sources and precedence rules.

## Git synchronization

When your agent edits memory, the changes are committed to the memory repository. Constellation agents push commits to sync back to the cloud; local-only agents commit to the local git repository.

Memory subagents, such as dream and doctor subagents, use git worktrees so they can write memory concurrently without blocking the main agent.