Memory

With Letta Code, you can 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 own memory as it works.

Letta Code agents are intended to become more sophisticated over time. It is generally good practice to work with a single agent per git repository, for example — this will help develop an agent highly specialized to specific projects or tasks. You can further specialize your agents by working with agents that focus on specific aspects of your project, such as design, backend, security, database, etc.

Refer to the main guide for more general information about Letta’s memory system.

Starting a session

When you run letta in a project directory, Letta Code automatically resumes your last used agent:

Start Letta Code

letta

● Resumed last used agent in ~/my-project
  → Agent: my-agent
  → https://app.letta.com/agents/agent-xxx
  → Use /pinned or /resume to switch agents

• Existing project → resumes the last used agent automatically
• New project → creates a new agent automatically

You can close your terminal, come back days later, and pick up right where you left off.

Agent options

Force create a new agent

letta --new

Connect to a specific agent by ID

letta --agent <agent-id>

Pinned agents

Pin agents to quickly access them across projects.

Pinning agents

Pin current agent globally (available everywhere)

> /pin

Pin current agent locally (this project only)

> /pin -l

Unpin globally

> /unpin

Unpin locally

> /unpin -l

You can also rename the agent while pinning:

Rename and pin

> /pin MyAgent

Managing pinned agents

Open the pinned agents selector

> /pinned

Browse all agents

> /resume

Use the selector to:

• Enter - Switch to an agent
• P - Pin/unpin the selected agent locally
• D - Unpin from all locations

Initializing memory

When starting with a new project, run /init to help your agent understand the codebase:

> /init

What /init does

The internal prompts used by /init, /remember, and other commands are available in the Letta Code repository. These define exactly what instructions the agent receives when you run each command.

The agent will first ask you questions to understand your needs:

• Research depth: Standard (quick, ~5-20 tool calls) or deep (comprehensive, ~100+ tool calls)
• Your identity: Which git contributor are you? This helps correlate git history to your coding style
• Related repositories: Are there other repos (backend, shared libs) you work with?
• Workflow preferences: How proactive should the agent be? Auto-commit or ask first?
• Communication style: Terse or detailed responses?

Then the agent will research your project:

Standard initialization focuses on essentials:

• Reads README, package.json, configuration files
• Reviews git status and recent commits (provided automatically)
• Explores key directories
• Creates/updates memory blocks with project commands, architecture, and your preferences

Deep research initialization is comprehensive:

• Everything in standard, plus:
• Analyzes git history for commit patterns and conventions
• Identifies main contributors and team dynamics
• Explores architecture deeply across multiple directories
• Identifies pain points (frequently buggy areas) and code evolution
• Creates specialized memory blocks for conventions, gotchas, and architecture

Memory blocks created

/init typically creates or updates these blocks:

• human: Your identity, workflow preferences, and communication style
• persona: Behavioral rules you want the agent to follow
• project: Often split into multiple focused blocks:
  • project-commands: Build, test, lint commands
  • project-architecture: Directory structure and key modules
  • project-conventions: Commit style, PR process, code patterns
  • project-gotchas: Footguns and things to watch out for

The agent updates memory incrementally as it researches, ensuring nothing is lost even in long research sessions.

Run /init again whenever you want the agent to re-analyze the project, such as after major changes or adding documentation that you want the agent to ingest.

Updating memory

Automatic updates

As the agent works, it may update its memory with important information. For example, after discovering your project uses pnpm instead of npm, it may decide to remember that for future sessions.

Manual updates

Agents can sometimes fail to store information on their own, or they may not notice that a particular piece of information is useful for the future.

You can use /remember to explicitly tell the agent to remember something:

Remember something specific

> /remember Always use pnpm instead of npm in this project

Without arguments, the agent reflects on recent interactions and updates memory as appropriate:

Suggest a memory update without specifics

> /remember

The prompt used when invoking /remember is available here.

If your agent is not consistently remembering important information, as the agent to update its policies to be more dilligent in the future, and communicate what information you expect it to store. For example, “Actively store information about my preferences, decisions, and anything I explicitly ask you to remember.”

Sleeptime memory

Agents remember information using tools, such as memory. Agents must actively choose to remember information, unless the agent has a sleeptime agent attached. When a sleeptime agent is attached to your coding agent, memory operations are offloaded to an asynchronous agent designed to passively update memories while the primary agent works. To enable sleeptime agents when creating a new agent:

Create agent with sleeptime

letta --new --sleeptime

Or set it as the default in ~/.letta/settings.json:

~/.letta/settings.json

{
  "enableSleeptime": true
}

See sleeptime agents documentation for more details on how sleeptime works.

Sleeptime may improve the memory quality of your primary coding agent, but it can also result in additional cost.

Viewing memory blocks

Use the /memory command to view all memory blocks attached to your agent:

> /memory

The memory viewer shows:

• List view: All blocks with label, character count, description preview, and content preview (3 lines)
• Detail view: Press Enter on a block to see its full content with scrolling

Navigation:

• j/k or arrow keys to navigate between blocks
• Enter to view full block content
• ESC to go back or close

You can also click the “View/edit in the ADE” link to open the block in the Letta ADE for direct editing.

How memory works

Memory is stored as blocks on the Letta server. Each block has a label, description, content, and size limit. Agents can read and write to their own blocks. To learn more about memory blocks, check the main documentation page.

Configuration files

Local files track pinned agents and settings:

File	Purpose	Git
~/.letta/settings.json	Globally pinned agents, API keys	N/A
.letta/settings.local.json	Last used agent, locally pinned agents	Ignored
.letta/settings.json	Shared project settings	Commit

Best practices

1. Run /init on new projects - Helps the agent understand your codebase
2. Use /remember for important context - Explicitly save information you want persisted
3. Commit .letta/settings.json - Share project context with your team
4. Keep .letta/settings.local.json gitignored - Personal settings stay personal