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 a message, 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 (currently 200k tokens for all Claude models). 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
• Channel switches

What goes in MEMORY.md

The default MEMORY.md includes:

# agentname — Agent Memory

## Identity
- Email: agentname@tinyfat.com
- Owner: you@example.com

## Email Response Pattern
[How to send emails via /data/outbox/email/]

## Rules
[Default behavior rules]

Customizing MEMORY.md

Ask your agent to edit its memory:

“Add to your memory that I prefer concise responses”

Or:

“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 on all channels.

Configuration: config.json

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

{
  "model": "sonnet"
}

The default model is claude-sonnet-4-6. Change it with /model haiku or /model sonnet, or just ask your agent to switch.

Cross-channel memory

All channels (Email, Telegram, Slack) share the same:

• MEMORY.md — Persistent memory
• Sessions — Conversation history
• Storage — /data directory

Start a conversation on email, continue on Telegram. Your agent remembers everything.

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/
    └── {name}/         # Scheduled 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.

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 instance with troublemaker

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