# Documents and tables

Source: https://www.hyperagent.com/docs/knowledge/documents-and-tables

> For AI agents: the documentation index is at https://www.hyperagent.com/llms.txt and the complete documentation in one file at https://www.hyperagent.com/llms-full.txt. Any docs page is also served as Markdown by appending `.md` to its URL.

Reference material an agent reads and maintains: documents for writing that grows, tables for records with typed columns, shared across threads.

Some knowledge is too alive to be a memory. The strategy doc that grows a section every week. The pipeline table that looks different every day. A memory is a settled fact; this material keeps moving, and it needs somewhere to live between runs. **Documents** and **tables** are that somewhere: the reference material an agent reads from, edits in place, and carries from one thread to the next.

A memory is one fact the agent recalls. A document or table is a body of
material the agent reads and keeps current: structured, versioned, and
available across every thread that should see it.

## A document is named sections, edited one at a time [#a-document-is-named-sections-edited-one-at-a-time]

A document is not one block of text. It is a set of named **sections**, each holding Markdown, and the agent works on them one at a time. That structure is what lets an agent update a document without rewriting it.

When an agent maintains a document, it can:

* **Append to a section**, adding this week's findings to the Research section without touching anything else.
* **Replace a section**, swapping stale content for current content in place.
* **Insert a new section** where the document has grown a new concern.

Because each edit targets a section rather than the whole file, the surrounding sections stay exactly as they were, and every change is recorded. A document keeps **full version history**: each update is a snapshot you can read back or roll the document to, so a report an agent has maintained for months still carries the record of how it got here.



### Document scopes [#document-scopes]

A document is visible to as much or as little as you decide. You choose that reach with its scope:

The document belongs to the thread it was made in and travels no further.
Use it for material that only this piece of work needs.

Shared across all the threads in a project, so a brief written once is
present wherever that project's work happens.

Available to every thread, for material an agent should always be able to
reach: a brand guide, operating principles, a customer brief.

Documents you create this way live on the [Documents page](https://www.hyperagent.com/docs/concepts/library) and in the Library alongside everything else your agents produce, searchable across threads.



Every thread quietly gets its own document, created automatically to hold that
conversation's working state. It runs on the exact same sections-and-history
machinery, but it is a working note for one thread, so it stays out of the
Library rather than joining your reference material. See [Thread
Context](https://www.hyperagent.com/docs/concepts/threads/thread-context).

## A table is typed columns and rows [#a-table-is-typed-columns-and-rows]

A table is structured records: columns you define and rows the agent fills. Each column has a **type**, and the type is what keeps the data clean enough to reuse.

| Column type | Holds                                      |
| ----------- | ------------------------------------------ |
| **Text**    | Names, labels, free notes                  |
| **Number**  | Counts, amounts, scores                    |
| **Date**    | A calendar date                            |
| **URL**     | A link to a source or record               |
| **Boolean** | A true or false state, such as done or not |



A table is born in the thread where the agent first builds it. From there you decide how far it reaches:

* **Promote it to an agent**, so that agent can reach the table in any of its threads.
* **Make it global**, so it is available broadly, the way a pricing table or a shared lead list should be. Whether an agent can actually see global tables is governed by that agent's **global tables** setting, so global reach and the agent's permission to use it are two separate switches.

To pull an existing table into a conversation, **@mention** it in the thread, the same way you would point a teammate at the right file. And when you need the data elsewhere, **export it as CSV or JSON**.



This is the one place tables and documents diverge. A document records every
version and can be rolled back; a table holds only its current state. Before a
change you might want to undo, export the table to CSV or JSON so you keep a
copy of where it stood.

## Bring existing material into a thread [#bring-existing-material-into-a-thread]

A document or table does not fill the context window merely because the agent is allowed to reach it. The agent opens the material when the request calls for it, or you can point to it directly with an **@mention**. The resulting read or update appears in the thread's tool activity, so the source and change remain connected to the run.

Scope and direct mention solve different problems. Scope makes the material eligible for a thread or agent to use; an @mention tells the agent that this specific request should use it now. See [How context gets into a thread](https://www.hyperagent.com/docs/concepts/threads/loading-context#fetched-when-the-work-calls-for-it) for how retrieved material enters the run.

## Documents hold writing, tables hold records [#documents-hold-writing-tables-hold-records]

You don't have to decide between a document and a table; ask for what you need and the agent picks the shape the material wants. The distinction is worth knowing so you can read what it made, and steer it when you have a preference:

A brief, a plan, a research write-up, a set of operating principles.
Anything you'd read top to bottom, that gains sections as the work goes on.

A lead list, an account tracker, a comparison, a dataset. Anything with rows
the agent fills in, sorts, and queries.

Ask for "a tracker of these accounts" and you'll get a table; ask for "a brief on this account" and you'll get a document. Name the shape yourself ("keep this as a table") when you want to override the call.

The other two kinds of knowledge live elsewhere, and it is worth being clear about the line. A settled fact the agent should be able to recall in future work is a [memory](https://www.hyperagent.com/docs/concepts/memories), not a line in a document. A method the agent should follow every time is a [skill](https://www.hyperagent.com/docs/concepts/skills), not instructions buried in a document. Documents and tables are for the reference material in between: the things the agent reads, updates, and cites.

If you find yourself pasting the same set of records into the conversation run
after run, or the agent keeps rebuilding the same list from scratch, that list
is asking to be a table. Save it once with typed columns and the agent reads
it directly instead of reconstructing it every time.

## FAQs [#faqs]

Yes. A table starts in one thread, but you can promote it to an agent so it reaches every thread that agent works in, or make it global so it is available broadly. To bring it into a specific conversation, @mention it in that thread. For a global table, remember the agent also needs its global tables setting on to see it.

Yes. Documents keep full version history. Every update is a snapshot, so you can read an earlier version or restore the document to it. A report an agent has maintained for weeks carries its whole record of change.

Tables do not keep version history, so there is no earlier version to restore. A table holds only its current state. If you are about to make a change you might want to reverse, export the table to CSV or JSON first so you keep a copy of where it stood.

Two things gate it. A table is scoped to the thread it was made in until you promote it to an agent or make it global, so by default other threads cannot reach it. And even a global table is only visible to an agent whose global tables setting is on. If both are in place and the agent still doesn't see it, @mention the table in the thread to bring it in directly.

In the Library, alongside everything else your agents produce, searchable across all your threads. The one exception is the Thread Context Document each thread creates for its own working state. That one is a working note for a single conversation, so it stays out of the Library.