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

# Memory and recall

> How agents store reusable information and retrieve relevant, authorized context.

Memory lets an agent retain useful facts and preferences beyond the recent
conversation window. Each agent owns its own memory. A turn receives only a
bounded selection that is relevant and permitted for its audience.

For example, “I prefer concise updates” can become a preference about the person
who said it. A fact learned in their direct message remains private; relevance
to a public discussion does not grant permission to disclose it there.

## Using memory

| Operation | Result |
| - | - |
| `remember` | Create a new entry. It does not silently replace an older entry. |
| `recall` | Search authorized current entries and return stable IDs. |
| `amend` | Correct an existing entry by writing a new revision. |
| `forget` | Retire an entry from live retrieval while preserving its audit history. |
| `request_memory_sharing` | Ask for permission to release one exact revision to a defined audience. |

An agent can recall a fact before correcting or forgetting it. Committed memory
operations are supplied to the response generation step; a failed or unchanged
write must not be described as a successful mutation. Forgetting does not erase
previously delivered messages or the operation history.

Operators can inspect and edit memories on the agent's Memory page.
[Dreaming](/runtime/dreaming.md) can also learn and maintain memories in the
background under its configured limits and the same disclosure rules.

## Subject, source, and permission

These are separate properties:

* **Subject:** whom the fact concerns; it influences relevance.
* **Source:** who supplied it and which evidence supports it.
* **Permission:** which destination audiences may receive it.

Source attribution comes from authenticated records, not a model-provided author
claim. Names are rendered from actor records rather than embedded as permanent
identity labels in memory text. Identity links can change read-time associations
without rewriting the original evidence.

[Memory privacy](/runtime/memory-privacy.md) defines source audiences, inherited
restrictions, explicit sharing, and final delivery checks.

## Selection for a turn

Automatic context and `recall` share one retrieval service. SQL first restricts
candidates to the current agent, live revision, and permitted audience. Ranking
cannot restore an ineligible row.

The default backend uses PostgreSQL full-text search with subject, conversation,
and recency signals. Optional pgvector or Qdrant backends add semantic matches.
Lexical and semantic ranks are combined, then current canonical rows and
permissions are checked again.

Nonempty searches normally require lexical or semantic relevance. Empty searches
use subject, conversation, and recency ordering. Automatic context additionally
considers a bounded set of eligible preferences and communication-style memories
for current participants, even when their text does not match the topic. Relevant
task evidence ranks ahead of these supplemental [actor profiles](/runtime/actor-profiles.md).

The default memory allowance is 4,096 estimated tokens, configurable from 256 to
32,768. Whole entries are selected; oversized entries are skipped instead of
being cut into potentially different claims. [Prompt admission](/runtime/prompt-budget.md)
then fits memory alongside history, images, tools, and the current message.

## Optional semantic search

PostgreSQL remains authoritative. Embeddings are disposable projections of
immutable revisions. A stale vector cannot revive a forgotten or amended memory,
and a provider result cannot bypass source permissions.

Each candidate source is bounded. Semantic retrieval has a three-second deadline
and a 10,000-revision eligible-set cap. Missing, rebuilding, unavailable, or
oversized indexes fall back to authorized lexical retrieval. Learned reranking,
explicit salience scores, and confidence-based ranking are not implemented.

[Memory providers](/runtime/memory-backends.md) covers configuration, confidential
processing, index rebuilds, and provider requirements.

## Diagnosing retrieval

`memory_retrieval_events` records selected revisions, score components, estimated
cost, destination audience, and degradation categories. Query text is not stored
there: a keyed digest supports correlation without a guessable plain hash.
Prompt snapshots and tool observations still contain actual context within the
administrator trust boundary.

`eligibility_withheld_unknown` means matching memories lack sufficient audience
evidence. It calls for source review, not a weaker search filter. Permissions are
checked again before the final answer is delivered.

Implementation: [`internal/memory/retrieval.go` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/memory/retrieval.go),
[`db/queries/memory_retrieval.sql` (repository)](https://github.com/TextureHQ/formation/blob/main/db/queries/memory_retrieval.sql),
and [`internal/turn/memory_verbs.go` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/turn/memory_verbs.go).


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