Memory tools
The memory.* tools: ask enterprise memory a question, and teach it a note.
Generated from the built-in tools registry. Do not edit by hand.
Enterprise memory is what the company has learned, in layers: a task, a member, a role, a team and the whole enterprise. Every run already consults it before its work and learns from it afterwards, without calling anything.
These two tools are for a run that needs more: memory.ask asks a question of its own mid-run, and memory.train records something the run established. Train what the run observed, never what an ask just gave back.
A person’s own agent uploads a note to a team or the whole enterprise with memory.upload, over the API and the OS MCP server, under memory:write. Task, member and role notes stay on memory.train. A run never calls memory.upload, so a task that declares it is refused when it is saved (tool_not_run_callable).
| Tool | What it does | Effect |
|---|---|---|
memory.ask |
Ask enterprise memory a question, and get an answer with its evidence. | read |
memory.train |
Teach enterprise memory one note, at the task layer by default. | write |
memory.upload |
Upload one note to a team or the whole enterprise. | write |
memory.ask
Ask enterprise memory a question, and get an answer with its evidence.
What the model reads:
Ask enterprise memory a question and get an answer with the evidence behind it. Pass purpose (what you need it for) and, to restrict the search, teamId or projectId — an explicit filter is honoured as given and never widened, so omit both to search the whole enterprise. Pass selection to say which notes may answer: any (the default), trained (only what somebody taught, never what a run retained after its work) or confirmed (only the owner's own word: a note a person taught, or a decision they made at a gate). Before asking a person something they may already have decided, ask with selection confirmed and a purpose that does not quote the answer: insufficient_evidence means nothing confirmed matched, so you may ask. Returns answer, evidence, appliedFilters, appliedSelection, status and usage. Each evidence row carries its origin, kind, authorKind, sourceEventId and its layer and layerId, which say what it covers. A status of unavailable means memory could not be asked: carry on without it, and never read it as memory knowing nothing. In a run the reply always fits one result: evidence holds the notes that fit, whole; a first note too long on its own is cut and marked partial, with chars as its full length; and omitted names each note that matched and is not there. answer names the notes cited, and their text is in evidence only. Pass limit to get at most that many notes. Asking never stores anything.
| Field | Type | Required | Description |
|---|---|---|---|
purpose |
string | no | What you need the answer for. Shown in the answer. |
teamId |
string | no | Restrict to this team. Never widened back out. |
projectId |
string | no | Restrict to this project. Never widened back out. |
limit |
integer, 1 to 20 | no | The most notes to return. Defaults to 20. |
selection |
string, one of any, trained, confirmed |
no | Which notes may answer. Defaults to any. trained leaves out what runs retained after their work; confirmed keeps only the owner's own word. Never widened. |
No other fields are accepted.
- Effect: read.
- Retry: Safe: repeating the call changes nothing. Asking never stores anything.
- Called by: a run, the API, the CEO chat, the OS MCP server.
- Returns:
{ answer, evidence, appliedFilters, appliedSelection, status, usage }.statusisanswered,insufficient_evidence(nothing in scope, or nothing the selection allows),conflict(notes disagree) orunavailable(memory could not be asked: no answer and no evidence, and not the same as knowing nothing).appliedSelectionis the selection the answer was drawn under:anywhen none was named. A run reads a fixed set of layers (task, team and enterprise): a filter narrows within them and never adds one. A run also getsomitted:[{ id, layer, sourceEventId, chars }]for each note that matched and did not fit in one result, andusage.evidenceOmitted. Over HTTP nothing is left out, andanswercarries the text of every note. - API:
GET /v1/memory/ask(memory:read)
Example:
{
"purpose": "How has this task handled flaky checks before?"
}
Example, at most three notes:
{
"purpose": "What does the trial include?",
"limit": 3
}
Example, only the owner's own word:
{
"purpose": "prior owner decisions about refunds over the limit",
"selection": "confirmed"
}
memory.train
Teach enterprise memory one note, at the task layer by default.
What the model reads:
Teach enterprise memory one note. Pass body, optionally layer (task, the default; member and role are accepted; team and enterprise only when this task version grants that layer and the source event id starts with the granted prefix, on a cloned task too, unless a team the running member sits on or leads has withdrawn that layer, else clone_memory_not_granted), source ({eventId, revision}) naming the event you learned it from, so retrying it is not stored twice, and kind (fact, the default; inference, preference or correction). To correct a note, pass kind correction and supersedes ({entryId}) naming the entry it replaces: that retires the old note when it is in the layer you are writing, and a team or enterprise note only when this version grants that layer for the note's event id. Returns status (accepted, retained, consolidating or failed), the stored entry and usage. Author and enterprise come from this run, never from you.
| Field | Type | Required | Description |
|---|---|---|---|
body |
string | yes | The note to retain. |
layer |
string, one of task, member, role, team, enterprise |
no | Defaults to task. team and enterprise need a grant on this task version. |
source |
object | no | The source event this came from. Retrying the same pair is not stored twice. |
source.eventId |
string | no | |
source.revision |
string | no | |
kind |
string, one of fact, inference, preference, correction |
no | What kind of note this is. Defaults to fact, and a kind outside this list is stored as a fact. A correction replaces the note named in supersedes. |
supersedes |
object | no | The entry this note corrects. With kind correction it retires that entry: memory answers from the correction, and the old note stays only for audit. A run retires an entry in the layer it is writing. A team or enterprise note is retired only when this version grants that layer for the note's event id; one it cannot retire stays live, and the pair is reported as a conflict. Without kind correction the entry id is only recorded. |
supersedes.entryId |
string | yes | The id of the entry this note corrects. |
What chat reads, through os.use_tool:
Teach enterprise memory one note about one of the enterprise's tasks, as the person asking: they are its author, and it needs their tasks:write. Pass taskId (os.list_task_definitions lists the tasks) and body, and optionally layer (task, the default; member, role, team or enterprise; team is the first team a holder of the task's role sits on, else memory_task_on_no_team; a cloned task trains its own task layer only, else clone_cannot_train_up), source ({eventId, revision}) naming the event it came from, so a retry is not stored twice, and kind (fact, the default; inference, preference or correction). To correct a note, pass kind correction and supersedes ({entryId}) naming the entry it replaces: a person's correction retires it in any layer. To teach a team by name, or the enterprise with no task, use memory.upload. Returns status (accepted, retained, consolidating or failed), the stored entry and usage. The enterprise comes from the conversation, never from the arguments.
| Field | Type | Required | Description |
|---|---|---|---|
taskId |
string | yes | The task the note is about, by id. |
body |
string | yes | The note to retain. |
layer |
string, one of task, member, role, team, enterprise |
no | Defaults to task. team is the first team a holder of the task's role sits on. A cloned task trains task only. |
source |
object | no | The source event this came from. Retrying the same pair is not stored twice. |
source.eventId |
string | no | |
source.revision |
string | no | |
kind |
string, one of fact, inference, preference, correction |
no | What kind of note this is. Defaults to fact, and a kind outside this list is stored as a fact. A correction replaces the note named in supersedes. |
supersedes |
object | no | The entry this note corrects. With kind correction it retires that entry: memory answers from the correction, and the old note stays only for audit. Without kind correction the entry id is only recorded. |
supersedes.entryId |
string | yes | The id of the entry this note corrects. |
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on
source(eventId,revision), or on the tool call when there is no source: a repeat is not stored twice. - Called by: a run, the API, the CEO chat.
- Needs:
taskis always allowed.memberandroleonly on an original task, never a clone.teamandenterpriseonly when this version grants that layer and the source event id starts with the granted prefix. A cloned task may too, in its own enterprise's memory and never its publisher's, as a task the enterprise wrote itself may; only a layer withdrawn on the team's page of a team the running member sits on or leads stops it, withclone_memory_not_granted. Reserved event ids (team:andgate:) stay refused.
- Returns:
{ status, entry, usage }.statusisaccepted,retained,consolidatingorfailed. Author and enterprise come from the run. - API:
POST /v1/tasks/:taskId/memory/train(tasks:write)
| Error | When | What happens |
|---|---|---|
clone_cannot_train_up |
A cloned task asked for the member or role layer. |
Run fails |
clone_memory_not_granted |
A cloned task asked for team or enterprise and one of the running member's teams has withdrawn that layer on its page. |
Run fails |
grant_denied |
The call asked for team or enterprise and this version does not grant that layer for the event id. |
Run fails |
Example:
{
"body": "The release check needs the preview URL before it can start.",
"source": {
"eventId": "evt_1",
"revision": "1"
}
}
memory.upload
Upload one note to a team or the whole enterprise.
What the model reads:
Upload one note to a team or the whole enterprise. Pass layer (team or enterprise) and body. A team upload also passes teamId, a team in this enterprise; an enterprise upload passes no teamId. Optionally pass kind (fact, the default; inference, preference or correction) and source ({ eventId, revision }), the event the note was learned from, so uploading it again is not stored twice. To correct a note, pass kind correction and supersedes ({ entryId }) naming the entry it replaces. Author and enterprise come from the caller. Task, member and role notes are not uploaded here. A task that declares this tool is refused when it is saved. eventId and revision are strings. A source that is not an object, or a half that is not a string, is refused with memory_source_invalid. A call that leaves source out, or leaves either half empty or out, is stored as a new note each time.
| Field | Type | Required | Description |
|---|---|---|---|
layer |
string, one of team, enterprise |
yes | team or enterprise. A team upload names teamId. |
teamId |
string | no | The team, when layer is team. Leave it out when layer is enterprise. |
body |
string | yes | The note to retain, one claim in a sentence. |
kind |
string, one of fact, inference, preference, correction |
no | fact, the default; inference, preference or correction. A correction replaces the note named in supersedes. |
source |
object | no | Where the note was learned, as { eventId, revision }, both strings. The same pair in this enterprise is stored once. |
supersedes |
object | no | The entry this note corrects, as { entryId }. With kind correction it retires that entry. |
No other fields are accepted.
- Effect: write.
- Retry: Idempotent: a repeat of the same call acts once, or leaves the same state. Keyed on source (eventId, revision). A call that leaves source out, or leaves either half empty or out, has no key, so each such call is stored as its own note.
- Called by: the API, the CEO chat, the OS MCP server.
- Returns:
{ status, entry, usage }.statusisaccepted,retained,consolidatingorfailed. Author and enterprise come from the caller. - API:
POST /v1/memory/train(memory:write)
| Error | When | What happens |
|---|---|---|
memory_org_layer_required |
layer is not team or enterprise. Task, member and role notes are not uploaded here. |
Tool error |
memory_team_required |
layer is team and teamId is missing. |
Tool error |
memory_team_not_applicable |
layer is enterprise and teamId is set. |
Tool error |
team_not_found |
teamId names no team in this enterprise. |
Tool error |
memory_source_invalid |
source is not an object, or its eventId or revision is there but is not a string. Nothing is stored. |
Tool error |
reserved_source_event |
source.eventId is a key the OS writes itself, such as team:<teamId>:… or a gate-learning key. |
Tool error |
Example:
{
"layer": "team",
"teamId": "5f0c1d2e-0000-4000-8000-000000000012",
"body": "Releases ship on Tuesday.",
"kind": "fact",
"source": {
"eventId": "note-1",
"revision": "1"
}
}