Memory tools

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.

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. Returns answer, evidence, appliedFilters, status and usage. 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.

• Effect: read.
• Retry: Safe: repeating the call changes nothing. Asking never stores anything.
• Called by: a run, the API.
• Returns: { answer, evidence, appliedFilters, status, usage }. status is answered, insufficient_evidence (nothing in scope), conflict (notes disagree) or unavailable (memory could not be asked: no answer and no evidence, and not the same as knowing nothing). 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/tasks/:taskId/memory/ask (tasks:read)

Example:

{
  "purpose": "How has this task handled flaky checks before?"
}

Example, at most three notes:

{
  "purpose": "What does the trial include?",
  "limit": 3
}

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), 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.

• 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.
• 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 clone cannot use the grant. 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)

Example:

{
  "body": "The release check needs the preview URL before it can start.",
  "source": {
    "eventId": "evt_1",
    "revision": "1"
  }
}