Cortex

Use this when the answer depends on the user's own context: facts about them or their work, decisions they made, preferences or constraints they stated, or anything they refer back to from an earlier conversation ("as we agreed", "my project", "the client we discussed"). Use it as well when the user asks for something done their usual way, in their format, tone, style or stack ("the way I normally write these", "my usual setup"): their way is what the memory holds. Also use it when the user asks what you know or remember about something. Returns the matching memories with id, title and url to cite; fetch returns the full text of one. Cortex is the user's own memory layer: what is saved through it stays available in the other AI apps they connect to the same account. Do not use it for general knowledge, for questions that do not depend on this particular user, or when everything needed is already in this conversation.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to look for, in natural language and in the user's own words, e.g. \"which database we chose for billing\""
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "url"
        ]
      }
    }
  },
  "required": [
    "results"
  ]
}

Use this when a search result looks relevant and you need its full text before answering. Takes the id returned by search, and returns the memory with its url, which you cite in your answer. Do not call it with an id from anywhere else: only search results carry valid ids.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The id of a memory, exactly as returned by search"
    }
  },
  "required": [
    "id"
  ]
}

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "text": {
      "type": "string"
    },
    "url": {
      "type": "string"
    },
    "metadata": {
      "type": "object"
    }
  },
  "required": [
    "id",
    "title",
    "text",
    "url"
  ]
}

Use this when the user asks about a topic as a whole ("what do you know about X", "where are we with X", "catch me up on X"): returns one narrative synthesis of the relevant memories, saying what holds now and what was superseded. Do not use it to look up a single fact or when you need sources to cite: search returns individual memories with their urls.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string"
    }
  },
  "required": [
    "query"
  ]
}

Use this whenever the user tells you to remember, note down, keep or save something, in any language. Use it as well when they state something they will need again later and would not want to repeat: a decision and the reason behind it, a stable fact about them or their work, a preference or a constraint, a conclusion they reached after effort, a correction of something believed before. Then say in one line what you saved, so they can tell you to drop it. The server rejects duplicates by itself: a refused write is not an error, do not rephrase it and try again. Do not save questions, brainstorming, passing remarks or anything the user has not actually stated, and never save passwords, tokens, keys, card numbers or other credentials, even if the user pastes them.

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Short title, in the user's language, e.g. \"Billing service: chosen database\""
    },
    "content": {
      "type": "string",
      "description": "Text to remember, in the user's language"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "event_time": {
      "type": "string",
      "description": "Optional. Set only when an explicit, unambiguous ISO 8601 date (e.g. 2026-09-28 or 2026-09-28T14:00:00Z) of the event or measurement applies to the whole memory. Never infer a date and never use the save date: omit it if unknown. Save facts from different dates as separate memories."
    },
    "basis": {
      "type": "string",
      "enum": [
        "observed",
        "inferred"
      ],
      "description": "Origine dell'informazione: 'observed' se letta direttamente da una fonte (documento, output di uno strumento, dato reale), 'inferred' se e' una deduzione o una stima. Registrata al salvataggio e restituita al richiamo."
    },
    "claims": {
      "type": "array",
      "description": "Opzionale. Fatti atomici gia strutturati, uno per decisione o affermazione: se li passi, il rilevamento dei conflitti li usa direttamente invece di estrarli dal testo. Esempio: {subject: 'Project Vega', predicate: 'adotta', object: 'Redis'}.",
      "items": {
        "type": "object",
        "properties": {
          "claim_text": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "predicate": {
            "type": "string"
          },
          "object": {
            "type": "string"
          },
          "confidence": {
            "type": "number"
          }
        },
        "required": [
          "subject",
          "predicate",
          "object"
        ]
      }
    }
  },
  "required": [
    "title",
    "content"
  ]
}

Use this when a previous cortex_write returned a job_id as queued and the user asks whether it was saved: returns the quality gate verdict for that job and any contradiction it opened. Do not call it for a write that already came back with a verdict.

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "string",
      "description": "The job_id returned by a cortex_write that came back as queued"
    }
  },
  "required": [
    "job_id"
  ]
}

Use this when the user asks to delete a specific memory, given the id returned by search. Ask the user to confirm before calling it: the deletion is permanent and cannot be undone. Do not use it to fix a memory that is merely out of date: saving the corrected version with cortex_write is what keeps the history.

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "The id of the memory to delete, exactly as returned by search"
    }
  },
  "required": [
    "id"
  ]
}

Use this when the user asks what contradicts what in their memory, or when a memory you just read is flagged as conflicting and the user has to decide which version holds. Returns the pairs of contradicting statements with their status. Do not use it as a list of memories: it only returns detected contradictions.

{
  "type": "object",
  "properties": {}
}