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

# Workspace Brain

> Explore relationships across your workspace and choose which tables and records contribute to AI agent context.

Pro and Team workspaces can turn their [table records](https://docs.hookie.ai/data-workspace.md) into
connected knowledge for people, workflows and AI agents. Open **Workspace Brain**
in the sidebar. Existing and new table records are included by default, with the
same IDs and revisions. Webhooks and data sources contribute records through
the table's **Inputs** mappings in [Data workspace](https://docs.hookie.ai/data-workspace.md).

## Explore your connected data

**Graph** starts with a workspace overview. Each group represents an included
table or standalone knowledge. Counts cover the entire workspace, even when it
has more records than a single page can display. Dashed **contains** connections
show membership in the Brain. Other connections summarize saved relationships;
a loop represents relationships between records in the same group. Relationships
are created explicitly by people, workflows or agents.

Select a group or use **Find a record** to browse its records. Select a record,
then choose **Explore connections** to follow its relationships across tables and
record pages. Use **Relationship** and **Direction** to narrow the view. Select a
neighbor and explore again to continue through the graph. **Workspace overview**
returns to the map, and **Arrange** restores an automatic layout.

Record pages show up to 100 records. Connection exploration shows up to 100 nodes
and 200 edges within 64 KiB; notices identify truncated views. The overview shows
up to 500 relationship groups while its total still counts all included saved
relationships. Complete properties load when you select an individual record.

## Choose what belongs in your Brain

Choose **Manage included data** to include or exclude whole tables. An excluded
table contributes neither existing nor future records to Brain discovery and
agent context. To omit a single record, select it in **Graph** or **Grid** and
choose **Exclude from Brain**.

Excluded records and their saved connections remain stored. Table records still
work in their original tables, views, dashboards and table workflows. Including
a table again restores eligible records and preserves your individual exclusions.
To restore a record, open **Grid**, choose **Brain inclusion → Excluded**, select
the record, then choose **Include in Brain**. Its table must also be included.
The excluded-record count is a shortcut to that filter.

Writers can change these choices; readers can inspect them. Inclusion changes
have their own revision, so ordinary record edits do not overwrite them. If
someone else changes inclusion first, refresh and review before saving again.

> [!NOTE]
>
> Inclusion controls Brain discovery and context retrieval, including every hop of
> a graph workflow or agent query. Excluded records cannot bridge other records.
> It does not change existing table permissions or prevent authorized curation
> queries from reading excluded data. Context already sent to an agent stays with
> that agent.

## Edit and connect knowledge

**Grid** gives you a spreadsheet. Choose a table to edit its typed fields, or
choose **Entire workspace** to inspect names, types, JSON properties and revisions.
The **Brain inclusion** filter lets you review included, excluded or all records.
Double-click a cell to edit it. Select a record and choose **Edit node** for the
full editor. Table-backed edits also update the original table and its dashboards.

Use **New node** for standalone knowledge such as a policy, customer briefing or
agent memory. Give it a name, a type such as `knowledge`, and JSON properties.
Use **Connect nodes** to create a directional relationship such as `informs` or
`depends_on`. The **Graph** view lets you pan, zoom, move and inspect nodes and
their connections. Node positions are local to the current view.

Choose **Expand canvas** in Graph or Execution to use the screen for exploration.
Click a node to open its details alongside the expanded canvas. **Fit graph to
view** brings the visible graph into view; drag the background to pan and use
Ctrl/Cmd + scroll to zoom. Press Escape or **Exit expanded view** to return.
Use **Browse data** to open the table and dashboard navigation when you need it.
**Hide sidebar** gives the Brain the full workspace width again.

Table-backed nodes keep the table's field schema and derived name. Execution
trace nodes are read-only. Deleting a table-backed node also deletes its table
record; deleting a connection leaves both records intact.

## Preview agent context

Select a node and choose **Preview agent context**. The preview expands two hops,
with up to 40 nodes, 80 relationships and 16 KiB of serialized context. Its
truncation flags tell you what did not fit.

Agents can select root nodes, traversal direction, relation types and property
names through the API or `query_graph_context` MCP tool. Retrieval expands node
IDs before loading properties, so large payloads do not inflate the traversal.

| Setting | Default | Maximum |
| - | - | - |
| Root nodes | Required | 10 |
| Hops | 2 | 4 |
| Returned nodes | 80 | 200 |
| Returned relationships | 160 | 500 |
| Serialized response | 32 KiB | 128 KiB |
| Selected property keys | All that fit | 40 |

Results have stable ordering for unchanged data and carry current revisions.
The response includes `serialized_bytes`, `budget`, and `truncated` flags for
nodes, relationships, properties and traversal expansion. A large omitted
payload is marked `properties_omitted: true`. Choose an empty property list for
metadata only. Execution traces are excluded unless explicitly requested.

## Combine knowledge with workflows

Choose **Workflow access**, select a project, and grant **Read graph context**,
**Queue graph changes**, or both. This is a grant to the entire workspace graph,
including table records from other projects. It is separate from per-table
workflow permissions. Project-scoped API keys cannot access the graph directly.

In the [workflow builder](https://docs.hookie.ai/workflows.md), add a **Knowledge graph** step:

* **Fetch agent context** takes an array of node UUIDs or a templated array,
  plus depth, node and byte budgets. Place an AI or Agent step after it and use
  `{{graph_result}}` in that step's input. Select only the properties it needs.
* **Queue knowledge changes** takes an array of graph operations. The workflow
  supplies stable mutation IDs and generates missing IDs for new nodes, so a
  retried step does not create duplicates. Its result contains receipt IDs.

Example context step:

```json theme={"dark"}
{
  "type": "graph",
  "action": "context",
  "roots": ["{{entry.node_id}}"],
  "depth": 2,
  "max_nodes": 40,
  "max_bytes": 16384,
  "properties": ["summary", "status"],
  "output_key": "graph_result"
}
```

Example mutation step after an AI call:

```json theme={"dark"}
{
  "type": "graph",
  "action": "mutate",
  "mutations": [
    {
      "operation": "create_node",
      "node_type": "knowledge",
      "display_name": "Customer briefing",
      "properties": { "summary": "{{ai_result.summary}}" }
    }
  ]
}
```

Queued changes normally consolidate after about 15 seconds. A queue receipt
means the change is durably queued, not yet applied. Outages and backlog can
delay it. Poll the mutation receipt before depending on the changed data; the
next workflow step may run before the queue flushes.

## Review human and agent conflicts

Human edits save immediately against the revision displayed when the edit began.
Agent and workflow mutations supply their expected revision. If someone else
changed the node first, the proposed values are saved as a conflict and the
current record stays intact.

Open **Conflicts → Review proposal** to compare the latest record with the
proposal. Edit the complete properties, confirm you reviewed that revision, and
choose **Apply reviewed change**. Or select **Discard this proposal** to keep the
current record. If another edit arrives while you review, fetch the latest
revision and review again. A stale write never silently wins.

**Queue** shows pending or errored mutations and lets writers cancel changes
that have not begun applying. A workspace suspension or downgrade pauses queued
writes. Revoking a project's graph grant prevents its queued changes from applying.

## Inspect execution lineage

**Execution** displays recent workflow runs as a React Flow canvas. Select a run
to see task states, attempts, sequence and branch connections. It refreshes every
five seconds from workflow history. Click a task to inspect its metadata.

The graph projection is asynchronous. It records execution metadata without
copying prompts, payloads or HTTP headers. Large runs show a bounded portion of
their history with a truncation notice; use the workflow's history for more detail.

## Connected agents and the API

[Connected agents](https://docs.hookie.ai/connected-agents.md) use these MCP tools through their existing
workspace read/write grants:

| Tool | Purpose |
| - | - |
| `get_brain_overview` | Read complete workspace counts, table choices and grouped relationships |
| `set_brain_inclusion` | Include or exclude a table or record using its inclusion revision |
| `list_graph_nodes` / `get_graph_node` | Discover nodes and read complete current properties |
| `query_graph_context` | Fetch bounded context for inference |
| `queue_graph_mutations` | Queue versioned knowledge changes |
| `get_graph_mutation` | Poll queued, applied, errored or conflicting changes |
| `list_graph_conflicts` / `resolve_graph_conflict` | Review and resolve saved proposals |

Node discovery defaults to included data. Curation tools can explicitly request
`membership: "excluded"` or `"all"` when listing nodes, or `include_excluded: true`
when reading a node. Context queries always honor inclusion. To change a choice,
send `kind: "table"` or `"node"`, its `resource_id`, boolean `included`, and the
current inclusion `expected_version` (zero if no choice has been saved). Table
versions are in the overview; node versions are in `node.membership.version`.
They are independent of the record's content revision.

The API lives under `/admin/api/data-workspace/graph`. `GET /overview` and
`POST /inclusion` expose the same controls. Queued operations require
stable `mutation_id` and `node_id` UUIDs. Updates replace the complete properties
object and require `expected_version`. Supported operations are `create_node`,
`update_node`, `delete_node`, `upsert_edge`, and `delete_edge`. For an edge,
`node_id` is the source; provide `target_id` and `relation_type`. Revision zero
creates an edge; a positive current revision updates or removes one.

## Limits and data lifecycle

Each queue request supports 25 operations and 256 KiB. A workspace can hold 500
pending operations or 16 MiB of queued proposals. Each node's properties support
64 KiB and 20 levels of JSON nesting. Nodes can have up to 256 incoming and 256
outgoing active relationships. Pro supports 50,000 standalone/trace nodes; Team
supports 250,000, separately from table-record allowances. Database storage limits
also apply.

System traces and completed/resolved receipts become eligible for cleanup after
30 days. Curated knowledge and unresolved conflicts persist. Workspace export
includes graph records, relationships, inclusion choices, receipts and pending proposals, including
after downgrade. Workspace deletion clears both the dedicated database and its
pending mutation queue.

This V1 provides structured graph context. Semantic/vector search and historical
context snapshots are future capabilities.


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