> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ultraclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# How Memory Works

> Your UltraClaw AI agent remembers your conversations and preferences. Learn how the layered memory system works.

# How Memory Works

Your UltraClaw agent doesn't forget. Every conversation is stored, indexed, and recalled when relevant — giving your agent persistent context that grows more useful over time.

<Info>
  Your memory is stored on your **own private virtual server** — completely isolated from other users. Your conversation logs, MEMORY.md, and all stored context belong only to you.
</Info>

## The Layered Memory System

Your agent's memory has three layers that work together to give it both **immediate recall** and **long-term knowledge**.

<CardGroup cols={3}>
  <Card title="Daily Logs" icon="calendar-day">
    Every conversation is saved as a daily log, organized by date. Your agent loads **today's and yesterday's logs** automatically at the start of each session.
  </Card>

  <Card title="Long-Term Memory" icon="book">
    Important facts, preferences, and context are stored in a curated **MEMORY.md** file that loads with every session — giving your agent instant access to what matters most.
  </Card>

  <Card title="Vector Search" icon="magnifying-glass">
    When your agent needs to recall something from weeks or months ago, it searches across all past conversations using semantic similarity — finding relevant context even if you don't remember the exact words.
  </Card>
</CardGroup>

## What Loads Automatically

At the start of each session, your agent loads:

1. **MEMORY.md** — your curated long-term facts
2. **Today's conversation log** — everything discussed so far today
3. **Yesterday's conversation log** — recent context from the day before

This means your agent always knows who you are, what you've been working on recently, and what you've told it to remember.

## Saving to Long-Term Memory

Want your agent to remember something important? Just say it naturally:

* *"Remember that my QuickBooks company ID is 12345"*
* *"Save to memory: I prefer morning briefings at 7am Pacific"*
* *"Add to memory that Sarah's birthday is March 15th"*

Your agent writes these facts to **MEMORY.md**, where they persist across every future conversation.

<Tip>
  Keep MEMORY.md focused on **curated facts** — not full transcripts. Think contact details, preferences, account numbers, and key decisions. A lean memory file means faster, more efficient sessions.
</Tip>

## Compaction

As conversations grow, the context window fills up. **Compaction** summarizes older parts of the conversation to free up space while retaining the key information.

<Tabs>
  <Tab title="Automatic">
    Your agent automatically compacts the conversation when the context reaches approximately **40,000 tokens**. This happens seamlessly — you won't notice any interruption.
  </Tab>

  <Tab title="Manual">
    Run `/compact` at any time to force a compaction. This is useful when you're switching topics and want to free up context for something new.
  </Tab>
</Tabs>

During compaction, your agent:

1. Summarizes the conversation so far
2. Preserves key facts, decisions, and action items
3. Frees up the context window for new messages

<Info>
  Compaction doesn't delete anything. Your full conversation logs are always stored in daily logs and remain searchable via vector search.
</Info>

## Best Practices

<Steps>
  <Step title="Curate Your MEMORY.md">
    Periodically review what's in your agent's long-term memory. Remove outdated facts and keep it focused. Ask your agent: *"Show me what's in MEMORY.md"*
  </Step>

  <Step title="Use 'Save to Memory' Deliberately">
    Don't save everything — save the things that matter across conversations. Preferences, important dates, account details, recurring instructions.
  </Step>

  <Step title="Compact Before Switching Topics">
    If you've had a long conversation about one topic and want to pivot, run `/compact` first. Your agent will carry forward what matters and free up space.
  </Step>

  <Step title="Trust Vector Search for Old Conversations">
    You don't need to memorize everything. If your agent needs context from a conversation three weeks ago, it can search for it automatically.
  </Step>
</Steps>

## Checking Your Context

Use the `/context` slash command to see how much of the context window is currently being used. This helps you understand when a compaction might be beneficial.