> For the complete documentation index, see [llms.txt](https://evo-5.gitbook.io/evo/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://evo-5.gitbook.io/evo/concepts/how-it-works.md).

# How It Works

evo maintains a **recall + reflect loop** that runs automatically during your agent sessions.

## The Loop

```
┌─────────────────────────────────────────────────────────┐
│                                                         │
│   ┌─────────┐    ┌─────────┐    ┌─────────┐           │
│   │ RECALL  │───▶│  TURN   │───▶│ REFLECT │───┐       │
│   └─────────┘    └─────────┘    └─────────┘   │       │
│        ▲                                       │       │
│        │                                       │       │
│        │         ┌─────────────┐               │       │
│        └─────────│   MEMORY    │◀──────────────┘       │
│                  │    STORE    │                       │
│                  └─────────────┘                       │
│                                                         │
└─────────────────────────────────────────────────────────┘
```

### 1. Recall

Before each prompt, evo queries the memory store for relevant items:

* **Global memories** — facts and constraints that apply everywhere
* **Project memories** — knowledge specific to the current working directory
* **Session memories** — context from the current conversation

These memories are assembled into the system prompt or injected as context, depending on the host.

### 2. Turn

The agent processes your prompt with the recalled context available. evo observes but doesn't interfere.

### 3. Reflect

After a successful turn completes, evo distills the conversation into structured memory items:

* What facts were established?
* What constraints were confirmed?
* What procedures were followed?
* What skills were demonstrated?

Failed, aborted, or interrupted turns are never reflected — only successful completions produce memories.

## Structured Memory

Every memory item has:

| Field     | Description                                      |
| --------- | ------------------------------------------------ |
| `scope`   | Where it applies: global, project, session, etc. |
| `kind`    | What type: fact, constraint, procedure, skill    |
| `title`   | Short identifier                                 |
| `content` | The actual knowledge                             |
| `tags`    | Categorization and search terms                  |
| `source`  | Which session and turn it came from              |

This structure enables precise recall and prevents the memory store from becoming a disorganized scratchpad.

## Batch Distillation

Reflection doesn't happen after every single turn. Instead, turns are queued and distilled in batches. This approach:

* **Improves quality**: Patterns only become visible across multiple turns
* **Reduces costs**: Fewer model calls for reflection
* **Catches relationships**: The pitfall stepped into three times, the convention confirmed repeatedly

See [Batch Distillation](/evo/concepts/batch-distillation.md) for details on thresholds and configuration.

## What Gets Remembered

The reflection prompt explicitly instructs the model to capture:

* **Facts**: Established truths about the project or domain
* **Constraints**: Rules, requirements, red lines
* **Procedures**: How to do something, step by step
* **Skills**: Reusable capabilities with clear triggers

And to reject:

* Secrets, credentials, API keys
* Raw logs or temporary data
* Guesses or uncertain claims
* Transient task state

## What Gets Forgotten

evo includes automatic eviction:

* **Semantic eviction**: When new information contradicts old, the old is removed
* **Capacity limits**: Each scope has a maximum item count (default 40)
* **Staleness**: Oldest, least-used items are candidates for removal

The latest information always wins — this is a core design principle.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://evo-5.gitbook.io/evo/concepts/how-it-works.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.