Records

Records are structured data stored on a page. Use them for anything you track, such as customers, decisions, hires, or incidents, so that people and agents can read them as data.

Tables and logs

A page holds one of two kinds of records:

Kind	How it works	Use it for
Table	Each row has a unique key. Writing a row with an existing key replaces that row.	Things that change, such as customers, open roles, or decisions.
Log	Each entry is added with a timestamp. Entries are never replaced.	Things that happen, such as deploys, calls, or daily metrics.

A page is a table if its metadata sets a key. A page with records and no key is a log.

Create a table

Ask your agent, for example: "Make a table at crm:customers, keyed by id, with name, stage, and owner."

To create one with the CLI, write the page and then set its key:

known acme wiki write crm:customers --title "Customers" --text "Every customer, keyed by id."
known acme wiki meta crm:customers --text '{"key": "id"}'

To make sure every row has the fields you expect, add a schema.

Write records

Use wiki set to write a row to a table or add an entry to a log:

known acme wiki set crm:customers --text '{"id": "acme", "name": "Acme", "stage": "pilot", "owner": "sam"}'
known acme wiki set ops:deploys --text '{"service": "api", "version": "1.42.0"}'

On a table, wiki set replaces the whole row. Fields you leave out are removed. To update one field, read the row, change the field, and write the full row back.

To make sure nobody changed the row since you read it, pass the row's version with --if-version <n>. The version is in the row's _v field. If the row has changed, the write fails.

On a log, wiki set adds an entry with the current time. To record something that happened earlier, add --ts <time>.

To delete a record, use wiki del:

known acme wiki del crm:customers/acme

Read records

known acme wiki records crm:customers
known acme wiki get crm:customers/acme
known acme wiki records ops:deploys --reverse --limit 20
known acme wiki records ops:deploys --since 2026-10-01T00:00:00Z

Command	Returns
wiki records	All records. Table rows are sorted by key; log entries by time, oldest first.
wiki get	One record, by its key or, on a log, its _id.
--reverse	Newest first on a log, highest key first on a table.
--since, --until	Log entries in a time range.

Results are returned in pages of up to 1,000 records. To get the next page, pass the --cursor value from the previous result.

System fields

Known adds these fields to every record:

Field	Description
_ts	When the record was written.
_actor	Who wrote it.
_v	On a table, the row's version number.
_id	The record's ID.

Your own field names can't start with _.

Records in the browser

A page with records opens on its Data view, which shows the records in a grid. You can sort and filter the grid. Your sort and filter settings are saved in your browser.

If a table row has a content field with text, the row opens as its own page, with content shown as Markdown. Search and links use a row's title field as its name, or its name field if it has no title.

You can't edit records in the browser. Use an agent or the CLI. The grid updates as soon as a record changes.

Row history

Tables keep every version of every row, including deletions:

known acme wiki history crm:customers/acme
known acme wiki diff crm:customers/acme --version 3

To read a whole table as it was at a point in time, use wiki records --at <time>. Log entries have no versions, because they can't be changed.

Limits

• A record is a JSON object of up to 16,384 characters.
• A page can hold any number of records.
• Writing records doesn't create page revisions.

FAQ

What can agents do with records?

Agents can read, write, and delete table rows. Only people can delete log entries, remove a page that holds records, change a table's key, or lower a retention limit.

Can I search log entries?

No. Search includes pages and table rows only. To find log entries, use wiki records with --since and --until.