> 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/scope-routing.md).

# Scope Routing

When evo distills memories and skills from conversations, it must decide where to store them. The scope routing system ensures content lands at the appropriate level: project-specific or global.

## Default Routing

**When unsure, evo defaults to project scope** (the current working directory). This prevents project-specific facts from polluting the global namespace.

Only truly universal facts that apply across ALL projects should be stored at global scope.

## Deduplication Across Scopes

Before creating a project-scoped memory or skill, evo checks if the same title/name already exists at global scope:

* If a **global memory** with the same title exists → skip creating the project duplicate
* If a **global skill** with the same name exists → skip creating the project duplicate

This prevents redundant storage and ensures the global version takes precedence.

## How It Works

During `reflectBatch`:

1. evo queries both the current scope AND global scope for existing memories/skills
2. The reflection prompt is augmented with:
   * Titles already stored in the current scope
   * Titles already stored at global scope (with instructions not to duplicate)
3. The model is guided to prefer project scope unless the fact is clearly universal
4. Post-reflection, any candidates matching global titles are filtered out

## Prompt Guidance

The reflector receives explicit instructions:

> When unsure about scope, default to project scope (the current working directory). Only use global scope for truly universal facts that apply across ALL projects. Skip creating a project-scoped memory if the same title already exists at global scope — the global one takes precedence.

## Example Behavior

| Scenario                                                      | Outcome                                  |
| ------------------------------------------------------------- | ---------------------------------------- |
| User sets language preference at global scope                 | Global memory "Language" created         |
| User sets language preference at project scope, global exists | Project memory skipped                   |
| User learns a project-specific workflow                       | Project skill created                    |
| User learns a universal command pattern                       | Global skill (if explicit), else project |

## Best Practices

1. **Be explicit** when storing global facts — mark them as universal
2. **Let project scope be the default** for most knowledge
3. Global memories should be rare and truly universal
4. Review the scope tree (`GET /evo/scopes`) to audit distribution


---

# 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/scope-routing.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.