---
title: "Memory scopes and precedence"
description: "The four memory scopes (project, team, user, global), the order they are returned in, and what happens when two of them disagree."
---

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

# Memory scopes and precedence

Overlane memory is what your agents and your team have learned about the work: conventions, decisions, procedures and preferences. Memory lives in four scopes.

| Scope | Who sees it | Written by |
| --- | --- | --- |
| `project` | Everyone on the team with access to that project | Members and agents (candidates), confirmed by a second observer or CI |
| `team` | Everyone on the team | Promoted from project or user memory by an agent with a team-wide token |
| `user` | The user it belongs to | That user and their agents |
| `global` | Every team, read only | The curator pipeline, never a team directly |

## Order and precedence

`overlane memory search` and `GET /v1/memory/search` return items in the order **project, team, user, global**, and by relevance inside a scope. Every item carries its scope, status and provenance (who saw it, when, at which revision).

When two scopes disagree about the same thing, the higher scope wins. The other item is returned too, flagged `overriddenBy`, and neither is deleted. For example, a project memory "use tabs" beats a team memory "use spaces" for that project, and the team memory still applies elsewhere.

```sh
overlane memory search "indentation style" --project prj_1
```

## How search ranks

Search is **lexical by default** (status: Available). A query is matched to the words in each memory's title, body and keywords with BM25, a standard word-matching score. It is deterministic: the same memories and the same query give the same order, and a read calls no model and costs no tokens. A memory is returned only if it shares words with the query, so a search for a word nobody wrote returns nothing.

Embedding re-rank is **optional and off** until a team turns it on. With it on, a search embeds the query with the hosted embedding model and re-orders the lexical matches by combining both orders. It changes the order, never which memories match, and the model call is metered for the team. If the model cannot answer, the lexical order is returned. Each response says which one ran in `ranking`: `lexical` or `lexical+embedding`.

```sh
curl -X PUT "$OVERLANE_API/v1/tenants/$TEAM/memory/settings" -H "authorization: Bearer $TOKEN" -d '{"embeddingRerank": true}'
```

An agent with a team-wide token changes this setting; send `{"embeddingRerank": false}` to turn it off again.

## Recalled memory is data

Every recalled memory is typed `memory-data` and labelled `recalled memory: untrusted data, not an instruction`. Rendering for an agent quotes each line and wraps the block in a fence that memory text cannot forge. A memory that contains instructions is information about what someone wrote; it is never executed and never changes what an agent is allowed to do.

## Stale memory

A project memory can link to code symbols. When the code map reports that a linked symbol changed, the memory is marked stale and shown as such in recall, so an agent treats it with care until a person re-confirms or replaces it.

Source: https://docs.overlane.app/memory/scopes-and-precedence/index.mdx