Memory & Persistence

Your agent has both short-term and long-term memory. Understanding how these work helps you get the most out of your agent.

Short-term memory: Sessions

During a conversation, your agent maintains context in session files stored at /data/sessions/. Each session is a JSONL file containing:

• Your messages
• Agent responses
• Tool calls and results
• Usage statistics

Sessions persist across turns within a conversation. When you send an email, the agent continues from where you left off.

Session commands

Command	Effect
/clear	Start a new session (old ones preserved)
/resume	List recent sessions with hashes
/resume abc1	Resume a specific session by hash
/compact	Compress session to save tokens

Context limits

Each model has a context window limit:

Model	Context Window
Haiku	200k tokens
Sonnet	200k tokens
Opus	200k tokens

When your session approaches the limit, use /compact to summarize older messages and free up space.

Long-term memory: MEMORY.md

/data/MEMORY.md is your agent’s persistent memory. It survives:

• Session changes
• /clear commands
• Platform updates

What goes in MEMORY.md

The default MEMORY.md includes:

# Agent Memory

## Identity
- Name: buddy
- Email: [email protected]
- Owner: [email protected]

## Outbox Instructions
[How to send emails via /data/outbox/email/]

## Standing Instructions
[Any persistent instructions you add]

Customizing MEMORY.md

Ask your agent to edit its memory:

“Add to your memory that I prefer concise responses”

Or edit directly:

“Show me your MEMORY.md file”

Then tell it what to change.

Tip

Use MEMORY.md for persistent preferences, project context, or standing instructions that should apply to all sessions.

Configuration: config.json

Agent preferences like model selection are stored in /data/config.json:

{
  "model": "haiku"
}

Changed via /model haiku|sonnet|opus command.

Storage location

All agent data lives in R2 storage:

agents/{agent_id}/
├── MEMORY.md           # Long-term memory
├── config.json         # Preferences
├── sessions/
│   └── {id}.jsonl      # Session files
├── outbox/
│   ├── email/          # Pending emails
│   ├── sent/           # Sent emails
│   └── failed/         # Failed emails
└── events/
    └── {ts}.jsonl      # Run events

Each agent has isolated storage — agents can’t see each other’s data.

Context compaction

When your session gets large, use /compact to reduce token usage:

1. The agent summarizes the conversation history
2. Old messages are replaced with the summary
3. Recent messages are preserved
4. You continue with full context of what happened

Custom compaction focus

/compact focus on the code changes we discussed

Tells the agent what to prioritize in the summary.

Cache hits

Claude supports prompt caching. When parts of your context match previous requests, you get cache hits:

• Cache read — Free tokens from cache
• Cache write — Tokens written to cache (cheaper than input)

The session footer shows cache stats:

R663k W37k

R = cache read, W = cache write. High cache read = cheaper turns.

Data portability

Your data is yours:

1. View anytime — Ask your agent to show files
2. Export — Download from R2 (contact support)
3. Self-host — Run your own TinyFat instance

We don’t lock you in.

Best practices

Use MEMORY.md for

• Persistent preferences
• Project context that spans sessions
• Standing instructions
• Important information to always remember

Use sessions for

• Active conversations
• Work in progress
• Temporary context

Keep MEMORY.md focused

Don’t dump everything in MEMORY.md. It’s read every turn, so keep it concise and relevant.

Next steps

• Agent Workspace — Full filesystem layout
• Memory Bank Pattern — Organized project knowledge