Tool reference
Every MCP tool, what it does, and what the agent passes.
Four tools surfaced over MCP. The agent decides when to call them; you don't write code against this surface directly. This page documents what the agent will pass and what it'll see in return.
add_episode
Write a prose memory.
Arguments the agent passes:
| Field | Type | Required | Notes |
|---|---|---|---|
content | string | yes | The prose to ingest. |
group_id | string | no ("default") | Sub-namespace within the project. |
extract_intent | bool | no (false) | Whether to run the intent annotation pipeline. Costs an intents credit when an edge gets annotated. |
Returns: the same JSON shape as POST /v1/episodes.
Maps to: POST /v1/episodes — scope write.
record_fact
Write a single subject-predicate-object triple. Lower overhead than add_episode when the agent already has structured S-P-O data.
Arguments:
| Field | Type | Required | Notes |
|---|---|---|---|
subject | string | yes | Source entity name |
predicate | string | yes | Relation (underscores → spaces) |
object | string | yes | Target entity name |
group_id | string | no ("default") | Sub-namespace |
extract_intent | bool | no (false) | Same semantics as add_episode |
Returns: same shape as POST /v1/facts.
Maps to: POST /v1/facts — scope write.
search
Retrieve facts from the active team / project.
Arguments:
| Field | Type | Required | Notes |
|---|---|---|---|
query | string | yes | Natural-language question or keyword list |
group_id | string | no ("default") | Sub-namespace |
limit | int | no (10) | 1–100 |
Returns: the same JSON shape as POST /v1/search — edges[] with fact, source/target nodes, and intent_meta when present.
Maps to: POST /v1/search — implicit read (every key has this).
retract
Soft-delete an edge so it stops appearing in future search results. Audit row is preserved.
Arguments:
| Field | Type | Required | Notes |
|---|---|---|---|
edge_uuid | string (uuid) | yes | From a prior search result |
reason | string | no | Free-form audit note |
Returns: same shape as POST /v1/retract.
Maps to: POST /v1/retract — scope admin. If your key lacks admin, the tool errors with missing_scope and the agent reports the failure.
How the agent decides
The agent reads each tool's description (provided by the MCP server) and the user's conversation context. Common patterns:
- User says "remember that…" →
add_episode. - User asks "what did I decide about…" →
search. - User says "that's wrong, ignore it" →
retract(if scope allows).
You don't have to teach Claude or Cursor how to use these — the descriptions are written so the agent can route on its own.
Errors the agent will see
Every tool can return:
unauthenticated— key is bad / expiredmissing_scope— key lacks the required scopequota_exceeded— monthly cap hit (writes,intents, orretrievals)payment_required— subscription past-due
The error envelope shape matches the REST API. See REST overview.