hm_tabular

When you upload a spreadsheet, HyperMemory processes it into workbooks, sheets and regions (the tables and blocks inside a sheet), keeping values, number formats and formulas. hm_tabular lets an agent read that structure precisely instead of guessing from a summary.

Spreadsheet querying is being extended. Today, for a processed Excel workbook every mode returns the workbook’s processed structure (its manifest); for a CSV file range and search read the cells directly, and trace returns no lineage because CSV files have no formulas.

Modes

`mode`	What it returns	Requires
`outline`	The workbook → sheet → region hierarchy.	`file_id`
`range`	The exact cells of a bounded A1 range.	`file_id`, `sheet`, `range`
`search`	Regions, headers, labels, displayed values, number formats and formulas that match a query.	`file_id`, `query`
`trace`	The calculation lineage of one cell: what it depends on (`precedents`) or what depends on it (`dependents`). Lineage is followed, not evaluated.	`file_id`, `sheet`, `cell`

Parameters

Parameter	Type	Default	Used by	Description
`mode`	string	required	all	`outline`, `range`, `search` or `trace`.
`file_id`	string	required	all	The file’s id from `hm_upload_file` or `hm_list_files`.
`include_regions`	boolean	`true`	outline	Include the regions inside each sheet.
`max_sheets`	integer	`250`	outline	Maximum sheets (1–500).
`sheet`	string	—	range, trace	Sheet name.
`range`	string	—	range	An A1 range, e.g. `B2:F40`.
`max_cells`	integer	`2000`	range	Maximum cells (1–2000).
`query`	string	—	search	What to look for.
`limit`	integer	`25`	search	Maximum matches (1–50).
`cell`	string	—	trace	The starting cell, e.g. `F12`.
`direction`	`precedents` \| `dependents`	`precedents`	trace	Which way to follow the lineage.
`max_depth`	integer	`6`	trace	How many steps to follow (1–8).
`max_nodes`	integer	`200`	trace	Maximum cells in the lineage (1–500).

Examples

{ "mode": "outline", "file_id": "file_01JBX7Q2" }

{ "mode": "range", "file_id": "file_01JBX7Q2", "sheet": "Forecast", "range": "A1:H24" }

{ "mode": "trace", "file_id": "file_01JBX7Q2", "sheet": "Forecast", "cell": "H24", "direction": "precedents" }

Equivalents

Each mode has its own REST route — POST /api/v1/memory/tabular/outline, /tabular/range, /tabular/search and /tabular/trace — and the JSON body still includes mode.

hm tabular outline file_01JBX7Q2
hm tabular range file_01JBX7Q2 --sheet Forecast --range A1:H24
hm tabular search file_01JBX7Q2 "net revenue"
hm tabular trace file_01JBX7Q2 --sheet Forecast --cell H24 --direction precedents