# What a memory is

A memory is a short piece of text stating something about your product's world, stored together with everything Brain needs to rank it, show it, and decide what it supersedes. Brain keeps one memory pool per product: everything written into it — by your agents, by the people on your team, or by the sources you connect — lands in that single pool and is searched together, and two products never see each other's memories.

This page explains the model. The tasks it supports — adding, searching, correcting, deleting — are on [add, search and correct memories](/brain/memories), and the mechanics of calling Brain from your own agents are published by the platform: [look up a Brain tool](/reference/mcp-tools).

## What a memory carries

- **The content.** Plain text. This is what search matches against and what a person reads.
- **When it was recorded.** Every memory carries its creation time, and may also carry the time the statement is *about*, when that is known.
- **Its kind.** A label Brain derives itself: `Fact`, `Summary`, `Identity`, `Basic`, `Knowledge`, `Raw`, `Schema` or `Intention`. A writer never sets it.
- **Its source authority.** How much weight the statement carries against a competing one. See [source authority](#source-authority) below.
- **Its scope.** Whether the memory belongs to the whole product or only to the agent that wrote it. See [shared and private](#shared-and-private) below.
- **Tags and metadata.** A writer may attach structured metadata to what it stores; Brain keeps it verbatim and shows it on the memory.
- **Its status and history.** Whether the memory is the current version of what it states, and which memories it replaced.

Only the content is edited afterwards. Everything else is fixed when the memory is written, and the system never silently rewrites a memory in place: a statement that stops being true is replaced by a newer memory, and the older one stops being the current version.

## One write, several memories

Storing something is not a straight copy. Brain keeps the text exactly as it was submitted, then reads it for the individual statements it contains and stores each of those as its own memory. A paragraph describing a release decision therefore produces the verbatim text plus several separate facts, each searchable on its own.

Two consequences are worth knowing:

- The number of memories in your product grows faster than the number of writes.
- Text that contains no extractable statement — an empty document, a binary blob that came through as text — produces only the verbatim record. That is normal, not an error.

> When a newly derived fact contradicts one already stored, Brain does not keep both as equals. It supersedes the old one, subject to the authority rule below. Listing and searching show only the current version.

## Where memories come from

- **Your agents.** An agent working inside your product stores what it learns. This is the main writer in a live product, and the only writer that can choose a private scope.
- **People.** People do not type memories in themselves. What they contribute is written through the agents they work with, or through the documents they put in a connected source.
- **Connected sources.** A daemon pulls from GitHub, Google Drive or ClickUp on a schedule and writes what it finds into the shared pool. See [ingest a source on a schedule](/brain/daemons).
- **Brain itself.** During cognition Brain writes memories nobody submitted: recurring patterns it induced across what it already holds, and standing intentions it derived from them — the `Schema` and `Intention` kinds. See [how memory maintains itself](/brain/cognition).

## Shared and private

Every memory has one of two scopes.

| Scope | Who reads it | What lands there |
|---|---|---|
| **Shared** | Every agent and every person with access to Brain in that product. | The default for every write. Everything ingested from a connected source, and everything cognition produces. |
| **Private** | Only the single agent that wrote it. | Working notes an agent keeps out of everyone else's results. |

Private scope is not a security boundary you can administer: there is no way to grant one agent access to another agent's private memories. Reads span both scopes by default — an agent searching without saying otherwise sees the shared pool plus its own private memories, and can restrict a read to one of the two. A person reads the shared pool, and has no private memories of their own.

Because the pool is product-wide, a memory written by one agent is immediately part of what every other agent in that product retrieves.

## Source authority

Not everything Brain is told deserves equal weight. A statement copied out of a maintained specification is worth more than the same statement made in passing in a chat message. Every memory therefore carries one of four authority tiers, highest first.

| Tier | Meaning |
|---|---|
| `policy` | A rule that is meant to hold. The top tier; nothing overrides it. |
| `official` | Maintained, reviewed material. The default when nothing else is stated. |
| `team` | Working material produced in the course of the work. |
| `informal` | Remarks, chatter, anything said in passing. |

An agent writing directly states its own tier, and defaults to `official` when it states nothing. A defaulted `official` is indistinguishable from a deliberate one, so the tier tells you what weight a memory carries, not that anyone consciously chose it. Ingested memories take their tier from the source they were read from rather than from the individual item; the per-source defaults and the setting that overrides them are on [ingest a source on a schedule](/brain/daemons).

A tier is fixed onto a memory when the memory is written, and nothing re-resolves it afterwards. Changing what a source is trusted at applies to what is ingested from then on; memories already stored keep the tier they were given.

Authority does two things and nothing else:

- **It nudges search.** A higher tier lifts a memory slightly in the results. The effect is deliberately small — it reorders results that were already close to each other, and never pulls up a memory that does not answer the query.
- **It protects an established fact from being overwritten.** When a newly written statement would replace a stored one carrying a *higher* tier, the replacement is refused. The new statement is not discarded: it is stored, marked as conflicting with what is already there, and flagged as needing clarification, and it does not become the current version. A statement at the same tier or higher replaces the old one normally.

> Authority never hides anything. Every memory is listed and searchable regardless of tier, and the tier is shown on the memory.

## What belongs in memory

Memory is for durable statements about the product and the work around it: decisions and the reasoning behind them, conventions, the state of things, who and what the product deals with, and anything an agent should still know in a later session.

It is a poor fit for:

- **Secrets.** Credentials, tokens and keys. Memory is searchable by every agent and every person with access to Brain in the product, and its contents are processed to derive facts from them.
- **Values that change by the minute.** Anything you would rather read from the system that owns it than from a statement recorded at some earlier point.
- **Bulk material that already lives somewhere.** Connect the repository or the drive instead and let a daemon ingest it, so the material stays in step with its source rather than becoming a stale copy.
- **Personal data you have no basis to keep.** What goes in stays retrievable until someone deletes it.

## Next steps

- [Add, search and correct memories](/brain/memories): the operations this model supports, and what each one changes.
- [How memory maintains itself](/brain/cognition): what Brain consolidates in the background, and the memories it writes on its own.
- [Search the knowledge graph](/brain/knowledge-graph): the entities and relations Brain builds out of these memories.
- [Ingest a source on a schedule](/brain/daemons): where ingested memories get their authority tier.
- [Look up a Brain tool](/reference/mcp-tools): the mechanics of calling Brain from your own agents.