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

# Memory System

> How Bothive agents remember what matters — across sessions, users, and time.

<div className="hero-container">
  <h1 className="hero-title">
    Memory System
  </h1>

  <p className="hero-subtitle">
    Memory is what makes an agent feel intelligent over time instead of starting from zero every turn.
  </p>
</div>

## The four memory types

<CardGroup cols={2}>
  <Card title="Conversation Memory" icon="comments" className="glass-effect">
    Stores the current conversation history. Automatically included in every turn. Has a configurable TTL and message window size.

    **Best for:** Support bots, assistants, any interactive chat
  </Card>

  <Card title="Persistent Memory" icon="database" className="glass-effect">
    Long-term storage that survives across sessions. Explicitly written and read. Think: user preferences, company name, recurring context.

    **Best for:** Personal assistants, CRM agents, user profiling
  </Card>

  <Card title="Ephemeral Memory" icon="clock" className="glass-effect">
    Single-session only. Gone when the conversation ends. Ideal for sensitive temporary state.

    **Best for:** Checkout flows, one-time auth challenges, wizard-style UX
  </Card>

  <Card title="Summarized Memory" icon="compress" className="glass-effect">
    Long conversations get auto-compressed into a summary. The agent sees the summary instead of the full history, keeping context window costs low.

    **Best for:** Long-running assistants, research agents, complex projects
  </Card>
</CardGroup>

## When to use each type

| Scenario                        | Memory Type                   | Reason                                     |
| ------------------------------- | ----------------------------- | ------------------------------------------ |
| Chat support bot                | `conversation`                | Natural back-and-forth, short session      |
| Personal executive assistant    | `persistent`                  | Needs to remember preferences across weeks |
| Checkout / payment flow         | `ephemeral`                   | Sensitive, no need to persist              |
| Research assistant (long tasks) | `summarized`                  | Prevents context overflow                  |
| SaaS product copilot            | `persistent` + `conversation` | Remembers user + handles current task      |
| One-off scheduled bot           | `ephemeral`                   | No session continuity needed               |

## HiveLang v5 memory configuration

```hivelang theme={null}
bot PersonalAssistant {
  description: "Executive assistant with long-term memory"

  capabilities {
    google_calendar.createEvent
    gmail.sendEmail
    gmail.readEmail
    notion.createPage
  }

  instructions {
    You are a personal executive assistant.
    Remember user preferences, recurring meetings, and project context.
    Always confirm before creating calendar events or sending emails.
  }
}
```

For persistent memory — write and read explicitly in your bot's on-event handlers:

```hivelang theme={null}
bot CRMAssistant {
  description: "Remembers customer context across sessions"

  on input {
    company = remember "customer_company"
    if company == null {
      say "What company are you from? I'll remember for next time."
    } else {
      say "Welcome back from {company}! How can I help?"
    }
  }

  on "my company is *" {
    remember "customer_company": $match[0]
    say "Got it — I'll remember you're from {$match[0]}."
  }
}
```

## Memory in Swarms

In a multi-agent swarm, memory is namespaced at the swarm level:

```hivelang theme={null}
swarm ResearchTeam {
  description: "Multi-agent research system"

  agent Scout {
    role: "Find initial sources"
    capabilities { web.search }
  }

  agent Analyst {
    role: "Synthesize findings"
    capabilities { ai.generate }
  }

  on input {
    sources = delegate to Scout with { topic: input }
    remember "last_sources": sources
    analysis = delegate to Analyst with { data: sources }
    remember "last_analysis": analysis
    say analysis
  }
}
```

Both `Scout` and `Analyst` can access swarm-level memory. Individual agent memory is private to that agent's execution.

## Memory best practices

<AccordionGroup>
  <Accordion title="Store context, not raw messages">
    Don't remember entire message transcripts. Extract and store structured facts: customer name, issue type, preferred language, plan tier. This keeps memory compact and useful.
  </Accordion>

  <Accordion title="Never store sensitive data in persistent memory">
    Payment card numbers, passwords, access tokens — these should never go into persistent memory. Use your integration's secure credential store instead.
  </Accordion>

  <Accordion title="Set appropriate TTLs">
    Conversation memory with no TTL will keep growing. Set a TTL that matches your use case: 24h for support bots, 7d for assistants, 90d for long-term CRM agents.
  </Accordion>

  <Accordion title="Use summarized memory for long contexts">
    If your agent handles 50+ message conversations, switch to `summarized` memory. It auto-compresses older messages and keeps the token cost flat.
  </Accordion>

  <Accordion title="Scope memory correctly in SaaS">
    Always scope memory to `(bot_id, user_id)`. Never store cross-user state in a single key — every user should see only their own memory.
  </Accordion>
</AccordionGroup>

## Memory and observability

Every memory read and write is visible in the run trace. Under **Runs → Trace**, you'll see:

* `memory.read` — what keys were fetched and their values
* `memory.write` — what was stored and when
* `memory.miss` — keys that were queried but had no value

This makes it easy to debug memory-related issues without guesswork.

## Next reads

<CardGroup cols={3}>
  <Card title="Architecture" icon="layer-group" href="./architecture" className="glass-effect" />

  <Card title="Observability" icon="chart-line" href="./observability" className="glass-effect" />

  <Card title="Build Your First Agent" icon="hammer" href="../guides/build-your-first-agent" className="glass-effect" />
</CardGroup>