The Brain area publishes 41 REST endpoints. Paths are relative to https://api.lepsto.com; see Authentication for the required header.
POST/brain/admin/shared-memory/reset
DESTRUCTIVE admin op: reset a product's SHARED Brain memory (vectors + knowledge graph) and clear its connector_state so a re-ingest re-writes. Requires confirm:true AND confirmProductId echo; gated by an env arm flag, an env allowlist, and governance access.
MCP tool: brain_product_shared_memory_reset
Parameters
| Name | In | Type | Required | Description |
|---|
productId | body | string
| • | Explicit product id whose SHARED memory will be wiped. Never inferred from ambient context. |
confirmProductId | body | string
| • | Must EXACTLY equal productId (double-entry confirmation). |
confirm | body | boolean
| • | Must be true to proceed. Guards against accidental invocation. |
Response
Returns object.
| Field | Type | Always | Description |
|---|
scope | string
| • | — |
productId | string
| • | — |
graphDeleted | number
| • | — |
vectorsDeleted | number
| • | — |
connectorStateRowsCleared | number
| • | — |
GET/brain/backups
List the current product's backups (most recent first).
MCP tool: brain_backups_list
Parameters
No parameters.
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
id | string
| • | — |
error | string | null
| • | — |
status | stringone of: running, completed, failed
| • | — |
gcsPath | string
| • | — |
trigger | stringone of: scheduled, manual, pre-restore
| • | — |
createdAt | string (date-time)
| • | — |
edgeCount | number | null
| • | — |
nodeCount | number | null
| • | — |
productId | string
| • | — |
sizeBytes | number | null
| • | — |
updatedAt | string (date-time)
| • | — |
snapshotId | string
| • | — |
embeddingDims | number | null
| • | — |
engineVersion | string | null
| • | — |
POST/brain/backups
Request an on-demand point-in-time backup of the current product's Brain memory. Async (202): records a running snapshot and runs the backup in the background — returns { accepted, snapshotId }; poll brain_backups_list / brain_backup_status for completion. Rejects (409) if a backup is already running for the product.
MCP tool: brain_backup_create
Parameters
No parameters.
Response
Returns object.
| Field | Type | Always | Description |
|---|
accepted | booleanone of: true
| • | — |
snapshotId | string
| • | — |
GET/brain/backups/:snapshotId
Get a backup status by snapshot id, or the latest backup for the current product.
MCP tool: brain_backup_status
Parameters
| Name | In | Type | Required | Description |
|---|
snapshotId | path | string
| — | Specific snapshot to look up; omit for the latest. |
Response
Returns object | null.
GET/brain/clickup/channels
List the chat channels in a ClickUp workspace connection (for selecting channels to ingest)
MCP tool: brain_clickup_channels_list
Parameters
| Name | In | Type | Required | Description |
|---|
connectorId | query | string (uuid)
| • | — |
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
name | string
| • | — |
channelId | string
| • | — |
GET/brain/clickup/connections
List the ClickUp workspace connections available to the current product
MCP tool: brain_clickup_connections_list
Parameters
No parameters.
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
status | string
| • | — |
connectorId | string
| • | — |
workspaceId | string
| • | — |
workspaceName | string
| • | — |
GET/brain/clickup/lists
List all lists in a ClickUp space, both folderless and within folders. Filters by search when supplied.
MCP tool: brain_clickup_lists_list
Parameters
| Name | In | Type | Required | Description |
|---|
connectorId | query | string (uuid)
| • | — |
spaceId | query | string
| • | — |
search | query | string
| — | — |
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
name | string
| • | — |
listId | string
| • | — |
archived | boolean
| • | — |
folderId | string | null
| • | — |
folderName | string | null
| • | — |
GET/brain/clickup/spaces
List the spaces in a ClickUp connection. Filters by search when supplied.
MCP tool: brain_clickup_spaces_list
Parameters
| Name | In | Type | Required | Description |
|---|
connectorId | query | string (uuid)
| • | — |
search | query | string
| — | — |
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
name | string
| • | — |
spaceId | string
| • | — |
archived | boolean
| • | — |
POST/brain/cognition/digest
Queue a System-2 digest over the product shared pool (async); returns { accepted, run_id }. Poll brain_cognition_status for the result.
MCP tool: brain_cognition_digest
Parameters
No parameters.
Response
Returns object.
| Field | Type | Always | Description |
|---|
run_id | string
| • | Id of the queued run. The completion event carries the same `run_id`, which is how a waiting step ties the event back to this call; brain_cognition_status reports the same run. |
accepted | booleanone of: true
| • | Always true — the run was queued. The call fails outright rather than reporting a false here. |
GET/brain/cognition/status
Read the engine-global System-2 queue gauge plus this product's last digest/sweep run (status, counts, timing).
MCP tool: brain_cognition_status
Parameters
No parameters.
Response
Returns object.
| Field | Type | Always | Description |
|---|
sweep | object | null
| • | — |
digest | object | null
| • | — |
engine | object
| • | — |
POST/brain/cognition/sweep
Queue a cross-domain sweep over the product shared pool (async); returns { accepted, run_id }. Poll brain_cognition_status for the result.
MCP tool: brain_cognition_sweep
Parameters
No parameters.
Response
Returns object.
| Field | Type | Always | Description |
|---|
run_id | string
| • | Id of the queued run. The completion event carries the same `run_id`, which is how a waiting step ties the event back to this call; brain_cognition_status reports the same run. |
accepted | booleanone of: true
| • | Always true — the run was queued. The call fails outright rather than reporting a false here. |
GET/brain/daemons
List configured ingestion daemons for this product
MCP tool: brain_daemons_list
Parameters
No parameters.
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
id | string
| • | Id of this ingestion daemon — the value every other daemon tool takes as `id` |
name | string | null
| • | Operator-given label for this daemon; null when it was never named |
repo | string | null
| • | GitHub repository this daemon reads from; null on clickup and gdrive daemons |
type | string
| • | Which source this daemon ingests from: 'github', 'clickup' or 'gdrive' |
model | string | null
| • | The model an operator PINNED on this daemon, not necessarily the one that runs; null means Auto. Read effectiveModel for what extraction actually uses. |
owner | string | null
| • | GitHub owner (user or org) this daemon reads from; null on clickup and gdrive daemons |
branch | string | null
| • | Branch the GitHub daemon reads, usually main; null on clickup and gdrive daemons |
config | string
| — | This daemon's source settings, shaped by `type`: github carries markdown/issues/pulls toggles and glob filters, gdrive carries docs/pdf/text toggles and recurse. Meant for display, not for binding a later step to. |
enabled | boolean
| • | False while the daemon is paused — a paused daemon starts no runs and reingest requests against it clear paths but trigger nothing |
loadMode | string
| • | Which lane runs go to: 'hot' finishes in minutes, 'batch' queues the work with the model provider and can take hours |
lastRunAt | string | null
| • | When this daemon last ran, as an ISO-8601 timestamp; null when it has never run |
lastResult | string
| — | Summary the last run recorded, overwritten wholesale each run; null when the daemon has never run. Use brain_daemon_runs for the run history. |
connectorId | string | null
| • | Id of the connector holding the credentials this daemon runs with; null on github daemons, which use the repo connection |
clickupConfig | string
| — | Workspace, space, list, content toggles and chat channels for a clickup daemon; null for every other type |
degradedCount | number
| • | How many of this daemon's documents are known to have extracted incompletely, accumulated across all runs (the last run overwrites lastResult, this does not). 0 does NOT mean clean on its own — read it together with unmeasuredCount. |
effectiveModel | string | null
| • | The model this daemon ACTUALLY extracts with — `model` when it is pinned and still allowed, otherwise the platform default that Auto resolves to; null when nothing resolves. This is the one to report, not `model`. |
sourceAuthority | string | null
| • | Authority tier stamped on the memories this daemon writes (highest→lowest: policy, official, team, informal); null means Auto — resolved per source category |
unmeasuredCount | number
| • | How many of this daemon's documents nobody has measured: ingested before the check existed, or staged in a batch run that has not finished extracting. Unmeasured is NOT clean — while this is above 0, degradedCount is a floor, not a verdict, and the count drains itself as those documents are extracted. |
POST/brain/daemons
Create a new ingestion daemon (github, clickup or gdrive)
MCP tool: brain_daemon_create
Parameters
| Name | In | Type | Required | Description |
|---|
type | body | stringone of: github, clickup, gdrive
| — | — |
name | body | string
| — | — |
connectorId | body | string | null
| — | — |
owner | body | string
| — | — |
repo | body | string
| — | — |
branch | body | string
| — | — |
config | body | string
| — | — |
clickupConfig | body | object
| — | — |
loadMode | body | stringone of: hot, batch
| — | — |
model | body | string | null
| — | — |
sourceAuthority | body | string | nullone of: policy, official, team, informal
| — | — |
Response
Returns object.
| Field | Type | Always | Description |
|---|
id | string
| • | Id of this ingestion daemon — the value every other daemon tool takes as `id` |
name | string | null
| • | Operator-given label for this daemon; null when it was never named |
repo | string | null
| • | GitHub repository this daemon reads from; null on clickup and gdrive daemons |
type | string
| • | Which source this daemon ingests from: 'github', 'clickup' or 'gdrive' |
model | string | null
| • | The model an operator PINNED on this daemon, not necessarily the one that runs; null means Auto. Read effectiveModel for what extraction actually uses. |
owner | string | null
| • | GitHub owner (user or org) this daemon reads from; null on clickup and gdrive daemons |
branch | string | null
| • | Branch the GitHub daemon reads, usually main; null on clickup and gdrive daemons |
config | string
| — | This daemon's source settings, shaped by `type`: github carries markdown/issues/pulls toggles and glob filters, gdrive carries docs/pdf/text toggles and recurse. Meant for display, not for binding a later step to. |
enabled | boolean
| • | False while the daemon is paused — a paused daemon starts no runs and reingest requests against it clear paths but trigger nothing |
loadMode | string
| • | Which lane runs go to: 'hot' finishes in minutes, 'batch' queues the work with the model provider and can take hours |
lastRunAt | string | null
| • | When this daemon last ran, as an ISO-8601 timestamp; null when it has never run |
lastResult | string
| — | Summary the last run recorded, overwritten wholesale each run; null when the daemon has never run. Use brain_daemon_runs for the run history. |
connectorId | string | null
| • | Id of the connector holding the credentials this daemon runs with; null on github daemons, which use the repo connection |
clickupConfig | string
| — | Workspace, space, list, content toggles and chat channels for a clickup daemon; null for every other type |
degradedCount | number
| • | How many of this daemon's documents are known to have extracted incompletely, accumulated across all runs (the last run overwrites lastResult, this does not). 0 does NOT mean clean on its own — read it together with unmeasuredCount. |
effectiveModel | string | null
| • | The model this daemon ACTUALLY extracts with — `model` when it is pinned and still allowed, otherwise the platform default that Auto resolves to; null when nothing resolves. This is the one to report, not `model`. |
sourceAuthority | string | null
| • | Authority tier stamped on the memories this daemon writes (highest→lowest: policy, official, team, informal); null means Auto — resolved per source category |
unmeasuredCount | number
| • | How many of this daemon's documents nobody has measured: ingested before the check existed, or staged in a batch run that has not finished extracting. Unmeasured is NOT clean — while this is above 0, degradedCount is a floor, not a verdict, and the count drains itself as those documents are extracted. |
DELETE/brain/daemons/:id
Remove an ingestion daemon and its connector state (leaves ingested memory)
MCP tool: brain_daemon_remove
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon to act on, as returned by brain_daemons_list |
Response
Returns object.
| Field | Type | Always | Description |
|---|
ok | booleanone of: true
| • | — |
GET/brain/daemons/:id
Get a specific ingestion daemon by id
MCP tool: brain_daemon_get
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon to act on, as returned by brain_daemons_list |
Response
Returns object.
| Field | Type | Always | Description |
|---|
id | string
| • | Id of this ingestion daemon — the value every other daemon tool takes as `id` |
name | string | null
| • | Operator-given label for this daemon; null when it was never named |
repo | string | null
| • | GitHub repository this daemon reads from; null on clickup and gdrive daemons |
type | string
| • | Which source this daemon ingests from: 'github', 'clickup' or 'gdrive' |
model | string | null
| • | The model an operator PINNED on this daemon, not necessarily the one that runs; null means Auto. Read effectiveModel for what extraction actually uses. |
owner | string | null
| • | GitHub owner (user or org) this daemon reads from; null on clickup and gdrive daemons |
branch | string | null
| • | Branch the GitHub daemon reads, usually main; null on clickup and gdrive daemons |
config | string
| — | This daemon's source settings, shaped by `type`: github carries markdown/issues/pulls toggles and glob filters, gdrive carries docs/pdf/text toggles and recurse. Meant for display, not for binding a later step to. |
enabled | boolean
| • | False while the daemon is paused — a paused daemon starts no runs and reingest requests against it clear paths but trigger nothing |
loadMode | string
| • | Which lane runs go to: 'hot' finishes in minutes, 'batch' queues the work with the model provider and can take hours |
lastRunAt | string | null
| • | When this daemon last ran, as an ISO-8601 timestamp; null when it has never run |
lastResult | string
| — | Summary the last run recorded, overwritten wholesale each run; null when the daemon has never run. Use brain_daemon_runs for the run history. |
connectorId | string | null
| • | Id of the connector holding the credentials this daemon runs with; null on github daemons, which use the repo connection |
clickupConfig | string
| — | Workspace, space, list, content toggles and chat channels for a clickup daemon; null for every other type |
degradedCount | number
| • | How many of this daemon's documents are known to have extracted incompletely, accumulated across all runs (the last run overwrites lastResult, this does not). 0 does NOT mean clean on its own — read it together with unmeasuredCount. |
effectiveModel | string | null
| • | The model this daemon ACTUALLY extracts with — `model` when it is pinned and still allowed, otherwise the platform default that Auto resolves to; null when nothing resolves. This is the one to report, not `model`. |
sourceAuthority | string | null
| • | Authority tier stamped on the memories this daemon writes (highest→lowest: policy, official, team, informal); null means Auto — resolved per source category |
unmeasuredCount | number
| • | How many of this daemon's documents nobody has measured: ingested before the check existed, or staged in a batch run that has not finished extracting. Unmeasured is NOT clean — while this is above 0, degradedCount is a floor, not a verdict, and the count drains itself as those documents are extracted. |
PUT/brain/daemons/:id
Update an ingestion daemon (config, enabled, name, branch)
MCP tool: brain_daemon_update
Parameters
| Name | In | Type | Required | Description |
|---|
name | body | string | null
| — | — |
config | body | string
| — | — |
clickupConfig | body | object
| — | — |
enabled | body | boolean
| — | — |
branch | body | string
| — | — |
loadMode | body | stringone of: hot, batch
| — | — |
model | body | string | null
| — | — |
sourceAuthority | body | string | nullone of: policy, official, team, informal
| — | — |
id | path | string
| • | — |
Response
Returns object.
| Field | Type | Always | Description |
|---|
ok | booleanone of: true
| • | — |
GET/brain/daemons/:id/batch-status
Get batch ingestion status for a daemon (pending count, job, ETA, model, outcome)
MCP tool: brain_daemon_batch_status
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon to act on, as returned by brain_daemons_list |
Response
Returns object.
| Field | Type | Always | Description |
|---|
run | object | null
| • | — |
model | string | null
| • | — |
daemonId | string
| • | — |
loadMode | string
| • | — |
pendingCount | number
| • | — |
supportsBatch | boolean
| • | — |
effectiveModel | string | null
| • | — |
POST/brain/daemons/:id/reingest
Force re-ingest of specific document paths for a daemon: clears their stored content hash and triggers a realtime run, so degraded or never-measured documents are re-extracted instead of hash-skipped forever
MCP tool: brain_daemon_reingest
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon that owns these documents, as returned by brain_daemons_list |
paths | body | string[]
| • | Source paths to re-ingest, exactly as the daemon recorded them (a repo path such as docs/spec.md, a Drive file id, a ClickUp item id). 1-100 per call. |
Response
Returns object.
| Field | Type | Always | Description |
|---|
runId | string | null
| • | The run started to pick the cleared paths up — brain/daemon.run-completed for this id is what finishes the step. Null when no run was started (see triggered/triggerError). |
cleared | string[]
| • | Paths whose ingest state was cleared, so the next run will read them again from scratch |
notFound | string[]
| • | Paths this daemon has no ingest record for — usually a typo, or a document it never ingested |
triggered | boolean
| • | True when a run was started to pick the cleared paths up; false when the daemon is paused, a run is already in flight, or nothing was eligible |
triggerError | string
| — | Why no run was started; absent when one was |
skippedPending | string[]
| • | Paths left alone because they are in an unfinished batch; re-ask once that run has finished |
POST/brain/daemons/:id/run
Trigger an immediate run for a daemon and return its current status
MCP tool: brain_daemon_run
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon to act on, as returned by brain_daemons_list |
Response
Returns object.
| Field | Type | Always | Description |
|---|
done | boolean
| • | True once the run has finished, whether it succeeded or failed |
runId | string | null
| • | Id of the run being reported; null when this daemon has never run |
status | stringone of: queued, running, done, failed, none
| • | Where the run stands: 'queued' waiting to start, 'running' in progress, 'done' finished, 'failed' gave up, 'none' this daemon has never run |
sources | array
| • | Per-source progress as the connector reported it; the shape differs by connector type and is meant for display, not for binding a step to |
progress | object | null
| • | Document counts for the run; null when nothing has been counted yet |
routedTo | stringone of: realtime, batch
| • | Which lane the run went to: 'realtime' finishes in minutes, 'batch' queues the work with the model provider and can take hours |
triggered | boolean
| • | True when this call actually started a run; false when one was already in flight and nothing new was started |
triggerError | string
| — | Why the run could not be started; absent when it was started |
GET/brain/daemons/:id/runs
Recent run history for a daemon with per-run ingest counts
MCP tool: brain_daemon_runs
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon whose run history to read, as returned by brain_daemons_list |
limit | query | integer
| — | How many of the most recent runs to return (default 20, max 100) |
Response
Returns object.
| Field | Type | Always | Description |
|---|
runs | object[]
| • | The most recent runs, newest first |
daemonId | string
| • | Id of the daemon these runs belong to |
GET/brain/daemons/:id/status
Get the latest run status for a daemon
MCP tool: brain_daemon_status
Parameters
| Name | In | Type | Required | Description |
|---|
id | path | string
| • | Id of the ingestion daemon to act on, as returned by brain_daemons_list |
Response
Returns object.
| Field | Type | Always | Description |
|---|
done | boolean
| • | True once the run has finished, whether it succeeded or failed |
runId | string | null
| • | Id of the run being reported; null when this daemon has never run |
status | stringone of: queued, running, done, failed, none
| • | Where the run stands: 'queued' waiting to start, 'running' in progress, 'done' finished, 'failed' gave up, 'none' this daemon has never run |
sources | array
| • | Per-source progress as the connector reported it; the shape differs by connector type and is meant for display, not for binding a step to |
progress | object | null
| • | Document counts for the run; null when nothing has been counted yet |
GET/brain/daemons/gdrive/connections
List Google Drive connections for this product with their picked files
MCP tool: brain_gdrive_connections_list
Parameters
No parameters.
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
email | string
| • | — |
connectorId | string
| • | — |
displayName | string
| • | — |
pickedFiles | object[]
| • | — |
GET/brain/daemons/runs/:runId/items
List the per-item ingest ledger for a run (filter by outcome, esp. denied)
MCP tool: brain_daemon_run_items
Parameters
| Name | In | Type | Required | Description |
|---|
runId | path | string
| • | — |
outcome | query | stringone of: discovered, fetched, ingested, skipped_unchanged, denied, error
| — | — |
sourceKind | query | string
| — | — |
limit | query | integer
| — | — |
cursor | query | string
| — | — |
Response
Returns object.
| Field | Type | Always | Description |
|---|
items | object[]
| • | — |
runId | string
| • | — |
counts | object
| • | — |
nextCursor | string | null
| • | — |
GET/brain/knowledge/entities
Search product knowledge-graph entities (Feature, Decision, Risk, …) for the current product
MCP tool: brain_knowledge_search
Parameters
| Name | In | Type | Required | Description |
|---|
name | query | string
| — | Filter by entity name / alias substring |
entity_type | query | string
| — | Filter by ontology entity type (e.g. Feature, Integration) |
limit | query | integer
| — | Max entities |
offset | query | integer
| — | Pagination offset |
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
Response
Returns object.
| Field | Type | Always | Description |
|---|
total | number
| • | How many entities match in total, across all pages — not the length of this page |
entities | object[]
| • | Matching entities, best match first |
elapsed_ms | number
| • | How long the engine took to answer, milliseconds |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
GET/brain/knowledge/entities/:entity_ref/memories
List the memories a knowledge entity was extracted from (its DERIVED_FROM evidence)
MCP tool: brain_knowledge_entity_memories
Parameters
| Name | In | Type | Required | Description |
|---|
entity_ref | path | string
| • | Entity id, name, or alias to fetch backing memories for |
limit | query | integer
| — | Max memories (default 50) |
offset | query | integer
| — | Pagination offset |
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
Response
Returns object.
| Field | Type | Always | Description |
|---|
total | number
| • | How many memories back this entity in total, across all pages |
entity | object | null
| • | The entity the memories belong to; null when `entity_ref` matched nothing |
memories | object[]
| • | One page of the memories this entity was drawn from — the same shape brain_memory_list returns |
elapsed_ms | number
| • | How long the engine took to answer, milliseconds |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
GET/brain/knowledge/entities/:entity_ref/neighborhood
Expand the neighborhood (related entities + relations) around one knowledge entity
MCP tool: brain_knowledge_neighborhood
Parameters
| Name | In | Type | Required | Description |
|---|
entity_ref | path | string
| • | Entity id or name to expand around |
depth | query | integer
| — | Hops to expand (engine clamps to 3) |
relation_type | query | string
| — | Only traverse this relation type |
entity_type | query | string
| — | Only include neighbors of this entity type |
limit | query | integer
| — | Max neighbors |
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
Response
Returns object.
| Field | Type | Always | Description |
|---|
root | object | null
| • | The entity that was expanded around; null when `entity_ref` matched nothing |
entities | object[]
| • | The neighbours reached within `depth` hops of the root, the root excluded |
relations | object[]
| • | The relations that connect the root and the neighbours above |
elapsed_ms | number
| • | How long the engine took to answer, milliseconds |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
GET/brain/knowledge/graph
Export the product knowledge graph (entities + typed relations) as nodes and edges; truncation keeps the highest-degree nodes, so a small limit returns the hub concepts
MCP tool: brain_knowledge_graph
Parameters
| Name | In | Type | Required | Description |
|---|
limit | query | integer
| — | Max nodes (default 5000). When the cap applies, the highest-degree nodes are kept, so a small limit (e.g. 100) returns the hub concepts. |
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
Response
Returns object.
| Field | Type | Always | Description |
|---|
edges | object[]
| • | The typed relations between those entities |
nodes | object[]
| • | The entities in the exported graph |
totals | object
| • | Sizes of what was actually returned |
truncated | boolean
| • | True when `limit` cut the export short — the highest-degree nodes were kept, so what you get is the hubs |
elapsed_ms | number
| • | How long the engine took to answer, milliseconds |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
GET/brain/knowledge/relations
List typed relations (depends_on, competes_with, …) in the product knowledge graph
MCP tool: brain_knowledge_relations
Parameters
| Name | In | Type | Required | Description |
|---|
relation_type | query | string
| — | Filter by ontology relation type (e.g. depends_on) |
source_entity | query | string
| — | Filter by source entity id or name |
target_entity | query | string
| — | Filter by target entity id or name |
limit | query | integer
| — | Max relations |
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
Response
Returns object.
| Field | Type | Always | Description |
|---|
relations | object[]
| • | The relations matching the filters |
elapsed_ms | number
| • | How long the engine took to answer, milliseconds |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
GET/brain/memory
List memories (shared + your private by default)
MCP tool: brain_memory_list
Parameters
| Name | In | Type | Required | Description |
|---|
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
limit | query | integer
| — | How many memories to return, max 1000. Omit to use the engine's own page size. |
offset | query | integer
| — | How many memories to skip before this page — offset 100 with limit 100 is the second page. Omit to start at the beginning. |
order | query | stringone of: asc, desc
| — | Sort by write time: 'desc' newest first, 'asc' oldest first. Omit to take the engine's own order. |
Response
Returns object.
| Field | Type | Always | Description |
|---|
total | number
| • | How many memories match in total, across all pages — not the length of this page |
memories | object[]
| • | One page of memories, newest first unless `order` said otherwise |
POST/brain/memory
Store a memory for the current product. `extraction` reports what fact extraction made of it. `success: false` with `extraction.status: 'failed'` means the raw memory IS stored under `memory_id` and is searchable, only its facts are missing — do not add the same content again, that stores a duplicate. `extraction.status: 'empty'` is a success: nothing new came out of it — the content held nothing durable, or it is already in memory.
MCP tool: brain_memory_add
Parameters
| Name | In | Type | Required | Description |
|---|
content | body | string
| • | The memory text to store |
metadata | body | object
| — | Optional structured metadata |
scope | body | stringone of: shared, private
| — | 'shared' = product-wide pool (default); 'private' = this agent only |
source_authority | body | stringone of: policy, official, team, informal
| — | Source authority (highest→lowest): policy > official > team > informal. Omit to default to official; an unrecognized value is rejected. |
Response
Returns object.
| Field | Type | Always | Description |
|---|
success | boolean
| • | True when the memory was stored and its facts extracted (or there was nothing to extract). False when extraction failed — the raw memory is still stored under memory_id — or when the memory was not stored at all |
memory_id | string
| • | Engine id of the memory just stored; keep it to read, replace or delete the memory later |
error_code | string
| — | Present only when success is false. Tell stored from not stored by `extraction`, not by this code: with extraction.status 'failed' the raw memory IS stored and searchable under memory_id, only its facts are missing — do not re-add the same content, that stores a duplicate. With no `extraction` nothing was stored, and the add can be retried |
extraction | object
| — | What fact extraction made of this memory |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
DELETE/brain/memory/:memory_id
Delete a memory you own (or a shared one)
MCP tool: brain_memory_delete
Parameters
| Name | In | Type | Required | Description |
|---|
memory_id | path | string
| • | Engine memory id |
Response
Returns object.
| Field | Type | Always | Description |
|---|
success | booleanone of: true
| • | Always true — the call fails outright rather than reporting a false here |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
deleted_count | number
| • | How many memory rows the engine removed for this id; 0 when it was already gone |
GET/brain/memory/:memory_id
Get one memory by id (product+agent scoped)
MCP tool: brain_memory_get
Parameters
| Name | In | Type | Required | Description |
|---|
memory_id | path | string
| • | Engine memory id |
Response
Returns object.
| Field | Type | Always | Description |
|---|
tags | string[]
| • | Engine tags on this memory; empty when it carries none |
layer | stringone of: l6_schema, l7_intention, l4_identity, l0_basic_info, l2_fact, l3_summary, l5_knowledge, l1_raw
| • | Engine memory layer (l0_basic_info…l7_intention) |
custom | object
| • | Free-form metadata, verbatim as the writer passed brain_memory_add's `metadata`; keys are the caller's |
source | stringone of: vdb, graph
| • | Which store answered the read — 'vdb' the vector store, 'graph' the memory graph. Diagnostic; the content is the same either way. |
status | string
| • | Engine lifecycle status of the row — 'active' for a memory in use |
content | string
| • | The memory text itself |
user_id | string
| • | Engine user namespace the memory was written under |
agent_id | string
| • | Engine agent namespace the memory was written under |
is_latest | boolean
| • | True when this is the current version of the memory; false when a newer one has replaced it |
memory_at | number | null
| • | When the remembered EVENT happened, epoch milliseconds; null when the writer stated no time |
memory_id | string
| • | Engine id of this memory — the id that was asked for |
speculate | string | null
| • | The engine's own inference about this memory, or null when it recorded none |
confidence | number
| • | The engine's confidence in this memory, 0..1 |
elapsed_ms | number
| • | How long the engine took to answer, milliseconds |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
supersedes | string[] | null
| • | Ids of the memories this one replaced; null when it replaced none |
gmt_created | number
| • | When this memory row was written, epoch milliseconds |
superseded_by | string[] | null
| • | Ids of the memories that replaced this one; null while it is still current |
source_authority | stringone of: policy, official, team, informal
| • | Source authority (highest→lowest): policy > official > team > informal |
source_raw_memory_id | string | null
| • | Id of the l1_raw memory this one was derived from; null when it was written directly |
PATCH/brain/memory/:memory_id
Replace a memory you own (or a shared one)
MCP tool: brain_memory_update
Parameters
| Name | In | Type | Required | Description |
|---|
memory_id | path | string
| • | Engine memory id |
content | body | string
| • | Replacement content |
Response
Returns object.
| Field | Type | Always | Description |
|---|
success | booleanone of: true
| • | Always true — the call fails outright rather than reporting a false here |
memory_id | string
| • | Engine id of the memory that was replaced |
request_id | string
| • | Engine request id for this call — quote it when reporting a problem |
GET/brain/memory/search
Search memories for the current product
MCP tool: brain_memory_search
Parameters
| Name | In | Type | Required | Description |
|---|
query | query | string
| • | Natural-language search query |
limit | query | integer
| — | Max results per channel |
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private. A person sees shared only (empty private namespace). |
Response
Returns object.
| Field | Type | Always | Description |
|---|
normal | object[]
| • | Ordinary hits: the facts, summaries and raw notes that match the query |
profile | object[]
| • | Hits describing WHO the subject is — stable identity and preference memories (l0/l4). Usually the ones worth carrying into a prompt. |
proactive | object[]
| • | Hits the engine offers unprompted — intentions and open threads (l7) it judged relevant to the query rather than matched to it |
GET/brain/memory/stats
Summary counts for the current product (memories by layer, graph nodes/edges, entities, raw memories left without facts)
MCP tool: brain_memory_stats
Parameters
| Name | In | Type | Required | Description |
|---|
scope | query | stringone of: shared, private, both
| — | Read scope; 'both' (default) unions shared + your private |
Response
Returns object.
| Field | Type | Always | Description |
|---|
graph | object
| • | Size of the engine's memory graph |
memories | object
| • | Memory counts for the requested scope |
knowledge | object
| • | Size of the product knowledge graph |
extraction_gaps | object | null
| • | Raw memories left without facts, for the caller's product and scope. Counts only, and a lower bound. Null when the engine could not compute it |
POST/brain/restores
DESTRUCTIVE: full-replace restore of the current product's Brain from a snapshot (wipe + load). Takes an automatic pre-restore snapshot first (safety net). Requires confirm:true AND confirmProductId echo; refuses on product/snapshot mismatch or embedding-dims mismatch. Async — returns { accepted, restoreId }; poll brain_restore_status.
MCP tool: brain_backup_restore
Parameters
| Name | In | Type | Required | Description |
|---|
snapshotId | body | string
| • | The snapshot id to restore for the current product. |
confirmProductId | body | string
| • | Must EXACTLY equal the current product id (double-entry confirmation). |
confirm | body | boolean
| • | Must be true. DESTRUCTIVE: the product's current Brain is wiped and replaced. |
Response
Returns object.
| Field | Type | Always | Description |
|---|
accepted | booleanone of: true
| • | — |
restoreId | string
| • | — |
GET/brain/restores/:restoreId
Read a restore run's status (pending|wiped|importing|completed|failed) with counts + timing, by restoreId (returned by brain_backup_restore).
MCP tool: brain_restore_status
Parameters
| Name | In | Type | Required | Description |
|---|
restoreId | path | string
| • | The restore run id (returned by brain_backup_restore). |
Response
Returns object | null.
GET/brain/usage/report
Reported LLM/embedding token usage for this product, next to the platform billing aggregate
MCP tool: brain_usage_report
Parameters
| Name | In | Type | Required | Description |
|---|
days | query | integer
| — | How many UTC days of this product's ledger to return, ending today (default 30, max 90) |
Response
Returns object.
| Field | Type | Always | Description |
|---|
note | string
| • | A standing warning, in words, that product.rows and platform.meters have different subjects and need not match |
product | object
| • | Brain's own ledger, for THIS product only |
platform | object | null
| • | The platform billing aggregate for the whole ORG; null if it could not be read |
platform_error | string | null
| • | Why the platform aggregate is null; null when it was read successfully |
GET/brain/vcs/branches
List branches for a repository on a GitHub connection
MCP tool: brain_connector_branches_list
Parameters
| Name | In | Type | Required | Description |
|---|
connectorId | query | string (uuid)
| • | — |
repoFullName | query | string
| • | — |
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
name | string
| • | — |
commitSha | string
| • | — |
GET/brain/vcs/connections
List the GitHub connections available to the current product
MCP tool: brain_connector_connections_list
Parameters
No parameters.
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
status | string
| • | — |
connectorId | string
| • | — |
accountLogin | string
| • | — |
installationId | string
| • | — |
GET/brain/vcs/repos
List repositories accessible to a GitHub connection. Filters by search when supplied.
MCP tool: brain_connector_repos_list
Parameters
| Name | In | Type | Required | Description |
|---|
connectorId | query | string (uuid)
| • | — |
page | query | integer
| — | — |
search | query | string
| — | — |
Response
Returns object[].
| Item field | Type | Always | Description |
|---|
private | boolean
| • | — |
fullName | string
| • | — |
defaultBranch | string
| • | — |
Was this page helpful?Thanks for your feedback!