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 }. status is answered, insufficient_evidence (nothing in scope, or nothing the selection allows), conflict (notes disagree) or unavailable (memory could not be asked: no answer and no evidence, and not the same as knowing nothing). appliedSelection is the selection the answer was drawn under: any when 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 gets omitted: [{ id, layer, sourceEventId, chars }] for each note that matched and did not fit in one result, and usage.evidenceOmitted. Over HTTP nothing is left out, and answer carries 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:
    • task is always allowed. member and role only on an original task, never a clone. team and enterprise only 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, with clone_memory_not_granted. Reserved event ids (team: and gate:) stay refused.
  • Returns: { status, entry, usage }. status is accepted, retained, consolidating or failed. 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 }. status is accepted, retained, consolidating or failed. 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"
  }
}