> ## 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.

# Conversation search

> Retrieve past messages without losing their authorship or audience restrictions.

An agent can search conversations it has observed, including messages outside the
recent history window. This retrieves attributed transcript evidence; it does not
require every useful message to have been saved as a memory.

For example, ask “What did we decide about the migration last month?” The agent
can search relevant terms, inspect the surrounding exchange, and answer from
messages the current audience is allowed to receive.

## Search surface

The runtime exposes:

```text theme={null}
search_history(query, speaker?, after?, before?, limit?)
```

`speaker` can be `anyone`, `requester`, or `you`. The time filters bound the
search; `limit` defaults to 8 and caps at 20 hits. A hit includes its conversation,
time, speaker, text, stable message ID, ranking reasons, and up to two eligible
messages on each side.

The current message and already-loaded recent history are excluded to avoid
returning context the model has just seen. A per-turn ceiling of 400 distinct
history-evidence messages limits cumulative search results. At that ceiling the
tool reports `search_budget_exhausted`.

## What can be found

Search stays inside one agent's [perspective](/perspective.md). The same audience
and source-lineage checks used for ordinary history apply before results enter
model context:

| Source | Where it can be reused |
| - | - |
| Workspace-public conversation | Permitted destinations in the same workspace, even if the requester never spoke in the source room. |
| Direct conversation | The same reader's eligible private conversation, including narrow continuity through a live identity proof. |
| Private channel or group | A destination whose complete readership is permitted by the source evidence. |
| Agent reply based on private sources | Only where all inherited source restrictions allow it. |
| Unknown source audience | Withheld. |

[Identity linking](/runtime/identity-linking.md) lets `speaker=requester` include
messages written by that person's linked accounts before verification. It does
not broaden group or workspace permissions. A revoked proof cannot authorize a
reply that has not yet passed its final delivery check.

The model supplies neither an agent ID nor a destination audience. Both come from
the current run. Neighbors pass the same eligibility checks as the matching hit.

## Retrieval and provenance

The implemented search is **lexical PostgreSQL full-text search**. Query terms
are alternatives, with ranking rewarding stronger matches. Actor, conversation,
participation, and recency signals help order results. Semantic conversation
search is not implemented; enabling a semantic memory provider does not add it.

`message_search_documents` is an indexed projection of canonical message bodies.
Queries recheck perspective and permissions and load text from canonical events.
Returned messages become part of the turn's evidence, so later memories and
replies retain their sources' restrictions. Search results compete with other
context under the [prompt budget](/runtime/prompt-budget.md).

## Inspection

Every search writes a `conversation_search_events` audit record with a keyed
query digest, filters, selected message IDs, ranking components, and exclusion
counts. The run trace shows it as `search_audit`. The audit omits query text;
ordinary tool observations and prompts remain visible to trusted administrators.
A failed audit write fails the search rather than returning unrecorded evidence.

Implementation: [`internal/graph/search.go` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/graph/search.go),
[`db/queries/conversation_search.sql` (repository)](https://github.com/TextureHQ/formation/blob/main/db/queries/conversation_search.sql),
and [`internal/turn/history_search.go` (repository)](https://github.com/TextureHQ/formation/blob/main/internal/turn/history_search.go).


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