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

# How Vibey remembers

> How Vibey keeps the goal, your own words, and the next step through long work, each time earlier conversation has to be condensed.

Every model has a context window. Long work outgrows it: a day of reviews, a queue of tasks, a migration that takes hundreds of steps. To keep going, an agent has to condense the earlier conversation, again and again. This page explains how [Vibey](https://docs.avibe.bot/agents/vibey.md) does it, and why it is built this way. To see how well it holds up, read the [memory benchmark](https://docs.avibe.bot/agents/vibey-memory-benchmark.md).

## The problem

The usual approach asks the model to write a fresh summary of everything so far, every time. Each rewrite loses a little, and over many rewrites the losses add up:

* **The long-term goal fades.** Each rewrite decides again what still matters. A goal set at the start and not discussed lately gets shorter, then drops out.
* **A subtask becomes "the goal".** A summary captures what happened most recently. When the current subtask is done, the summary says the work is done, even though the larger job still has items left.
* **Your words drift.** A constraint you stated is paraphrased, then the paraphrase is paraphrased. Limits soften, permissions widen or vanish, and a background message that says "the user asked…" can be taken for something you said.

A typical case: you ask the agent to work through a queue of pull requests, oldest first, and to interrupt you only when one needs your decision. Several condensations later, a rewritten summary remembers the pull request under review right now, but not the queue, how far it got, or when you wanted to be interrupted.

## Mind, memo, and now

Vibey's condensation is called a checkpoint. It is consolidation, not bookkeeping: like a mind sorting through the day's experience during sleep, Vibey looks back over the work, revises its understanding layer by layer, and lets go of details. The original conversation stays stored, so a detail it let go can be looked up again.

A checkpoint has three parts, and each changes in its own way:

| Part | What it holds | How it changes |
| - | - | - |
| **Mind** | Vibey's understanding of the work: for whom and why, the goals, key decisions, lessons | Revised edit by edit. What did not change stays word for word. Mission entries cannot be deleted. |
| **Memo** | Your own words: the messages you typed that still guide the work | Vibey only ticks which messages to keep. Avibe copies their original text from the record. |
| **Now** | The current step, progress, what it is waiting on, next steps | Rewritten every time. |

### The mind

The mind has four sections, from the most stable to the most changeable:

1. **Where I stand:** for whom and why the work is done, what Vibey owns and where that ends, and its agreements with you: how to report, when to ask, what it may decide, and what it is authorized to do.
2. **Goals:** the **Mission**, the ultimate purpose of the conversation in Vibey's own words, and the **Workstreams** that serve it, each with its status and, where it has a queue, how far it got and what is next.
3. **Key decisions,** each with its reason.
4. **Lessons,** written as principles that also apply later.

At each checkpoint, Vibey looks back over what happened since the previous one and revises the mind with edits. It changes only what changed and leaves the rest as it was; the file can be edited, never overwritten. Memory keeps condensing: a finished workstream folds into one line, recurring lessons merge into a principle, and an overturned decision folds into the one that replaced it. When Vibey's understanding changes at its root, for example when it realizes you want something other than what it thought, it rewrites that section.

The mission is the anchor. A Mission entry is never deleted: when it is done, withdrawn by you, or replaced, its status is marked on the entry itself. Avibe enforces this: a mind with fewer Mission entries than before is rejected. The mission changes only when you change it. When the current step is done, the next step returns to its workstream; when the workstream is done, it returns to the mission or asks you.

Each section has a length limit: Where I stand 1,000 tokens, Goals 2,000, Key decisions 1,500, and Lessons 1,500. These hold on models with a context window of 192,000 tokens or more, and shrink in proportion on smaller ones.

### The memo

Each message you typed that a checkpoint moves out of the context becomes a candidate. Vibey sees them as a checklist: one line per message, with a checkbox, its number, and a short preview. Its only job is to tick:

* **Keep** a message that sets or changes the direction, states a constraint or a prohibition, expresses a preference, or grants a permission.
* **Release** a kept message once it is withdrawn, superseded, or done, or once the mind holds its meaning completely.
* **Skip** instructions that only move the work along, such as "continue", and short replies that make no sense on their own.

Avibe accepts a change to the checkboxes and nothing else. It then copies each ticked message's original text from the record into the checkpoint. The model never retypes your words, so they cannot drift. Each message keeps up to 300 tokens; a longer one is cut short and says which message number holds all of it. Together, the kept messages take at most 3,000 tokens, shrinking in proportion on models with a window under 192,000 tokens.

A message that was not ticked is not offered again, but it stays in the record under its number.

### The now

The now is the working state, written fresh at each checkpoint:

* the current step, and the workstream it belongs to
* progress: done, in progress, and blocked or open
* what Vibey is waiting on: background commands, Watches, Tasks, delegated runs, and questions to you, with their ids
* the next steps, tied to your latest explicit request and quoting your words
* pitfalls: mistakes, false assumptions, and dead ends, with the exact error text
* exact references: the paths, ids, commands, links, and values needed to continue

## How a checkpoint runs

```mermaid theme={null}
flowchart TD
    A["The context nears the model's limit"] --> B["Checkpoint turn, same model:<br/>edit the mind, tick the memo,<br/>write the now"]
    B --> C{"Avibe checks<br/>all three"}
    C -- "a problem" --> D["One repair request,<br/>then the fallbacks"]
    D --> E
    C -- "valid" --> E["Avibe assembles the checkpoint:<br/>mind, your words from the record,<br/>now, files, skills"]
    E --> F["It replaces the earlier conversation,<br/>and Vibey continues the same task"]
```

A checkpoint starts when the next request would pass about 90% of the model's context window. It starts earlier when the room kept for the reply and a safety margin need more space, or when the model's price per token rises above a context size.

First, Avibe writes two files into the session's scratch folder: the previous mind (an empty template the first time) and the memo checklist. The checkpoint turn then pauses the work and runs on the same model, with the conversation as it stands. Vibey can read files, but it can change only those two files, and it has at most five rounds of tool calls. The request tells Vibey that it comes from Avibe, not from you, and that it must not be recorded as something you said.

After a checkpoint, each request carries:

1. the system prompt, rebuilt for every turn: Vibey's identity, rules, Skills catalog, and your `AGENTS.md` files. A checkpoint never condenses it.
2. the checkpoint, framed as Vibey's own recollection rather than new instructions. Your words and your agreements in it still apply.
3. the most recent messages, word for word, up to 20,000 tokens. On a small model, the limit is a quarter of the checkpoint threshold.

When a checkpoint falls inside the turn in progress, the messages you sent in that turn stay as you wrote them. The checkpoint states that they are the current request, and that where the two disagree, your messages win.

## Who said what

Not every input comes from you. Watches, Tasks, callbacks, and other Agent sessions also send messages into a session. Each input no person typed begins with a source line, such as:

```text theme={null}
[Harness: Watch <watch-id> "<watch name>"]
[Harness: Task <task-id> "<task name>"]
[Harness: agent run <run-id> from #<session-id>]
[Harness: callback of run <run-id> from #<session-id>]
```

Avibe writes this line from how the input was dispatched, never from its text, so a background message that says "the user asked…" still reads as background. If a message you type starts with `[Harness:`, Avibe puts your name before it, so the label cannot be forged. The source line applies to every Agent backend, not only Vibey.

The checkpoint relies on it twice. The instruction tells Vibey that only messages you typed are your words. The memo goes further: its candidates come from the record's own type, so a Watch's, a Task's, a callback's, or another session's message can never enter it, whatever its text says.

## What else a checkpoint carries

* **Skills, by recency.** Skills whose loaded text would leave the context come back as they read now. The most recently loaded come first, each up to 5,000 tokens. Together they take at most 25,000 tokens or a tenth of the model's window, whichever is smaller, with at most 20 skills. A carried skill does not count as a new load, so one that is not loaded again eventually drops out. A cut skill says how to load all of it with `vibe skill load`.
* **A short file list.** Paths only: the 10 files most recently modified and the 5 most recently read, with a note when earlier ones were pushed out. Files that matter go into the now's exact references.
* **Where the full record is.** Earlier messages, the inputs and Vibey's replies, stay in Avibe's database. The checkpoint tells Vibey where they are and how to read your own messages in order. A memo entry's number points to its message. Tool outputs are not kept there; Vibey runs the tool again when it needs the output.

You can read the same record yourself:

```bash theme={null}
vibe data query --sql "SELECT context_seq, substr(content_text,1,300) FROM messages WHERE session_id='<session-id>' AND type='user' ORDER BY context_seq LIMIT 50" --format text
```

## Checks and fallbacks

Avibe checks every checkpoint before it is used:

* **Now:** exactly one checkpoint block, with a minimum length.
* **Mind:** every heading intact and in order, no fewer Mission entries than before, and each section within its limit.
* **Memo:** nothing changed except checkboxes, and the kept messages within their budget.

Avibe sends one repair request that names every problem it found. If something is still wrong after that, it falls back, keeping more rather than less:

| Still wrong after the repair | What Avibe does |
| - | - |
| No usable now | This checkpoint fails, and the context stays as it was. |
| The mind lost its structure, or grew past twice its limits | The previous mind is kept. |
| A mind section is over its limit | The whole mind is kept in the record. The checkpoint shows that section cut short and points to a read-only copy of the whole mind under `~/.avibe`. |
| The memo was changed beyond its checkboxes, or left as written because the turn ran out of tool rounds | Every candidate message is kept: more of your words, never fewer. |
| The kept messages are over budget | They are shortened evenly, and each says where its full text is. If even that is not enough, the first message and the newest ones are kept, and the others stay in the record under their numbers. |

A failed checkpoint changes nothing: a request that still fits is sent as it is, and a later request tries again. When the conversation is too large for a checkpoint turn, Vibey takes the checkpoint over its earlier part, up to about half, trying at most twice. When the request no longer fits and no checkpoint can be taken, Vibey moves about the earliest half out without calling the model. When it fits, that move keeps the previous checkpoint: its mind, now, and skills, and a memo with every message you typed that moves out. After two checkpoints in one run fail or make too little room, Vibey takes no more checkpoints in that run, and only that move makes room. If the newest tool output alone cannot fit, it is cut to fit and says so.

## What you see

Nothing interrupts you. There is no notice and no `/compact`: Vibey takes a checkpoint in the middle of a turn and carries on with the same task. That turn takes a little longer, because the checkpoint is extra requests to the same model, which use tokens like any other request. A failed checkpoint is silent as well; Avibe's log records why.

You hear about context only when nothing more can move out. Then Vibey stops and says what is too large, for example: **This conversation has grown too long to continue reliably. Start a new session with /new.**

## Limits

* **Condensed is not complete.** What is not in the mind, the memo, the now, or the recent messages is gone from the context. Vibey has to look it up in the record, and it re-runs a tool to see that tool's output again.
* **The model writes the mind and the now.** A checkpoint is only as good as the model that writes it, and results differ by model; see the [benchmark](https://docs.avibe.bot/agents/vibey-memory-benchmark.md).
* **Bounded budgets.** Very long messages are cut in the memo and referenced by number. On models with a window under 192,000 tokens, the mind and memo budgets shrink in proportion.
* **One session.** A checkpoint is the memory of its own session.
* **Vibey only.** Claude Code, Codex, and OpenCode run unchanged in Avibe and condense their context in their own way. The source line on background inputs applies to them too.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.