{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/innernet-live/json-schema/innernet-live-agent-schema.json",
  "title": "Agent",
  "x-generated": "2026-11-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/innernet-live-openapi.json#/components/schemas/Agent",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "slug": {
      "type": "string",
      "description": "Unique per person. What you put in the path (or `me`, for the agent a key is bound to)."
    },
    "name": {
      "type": "string",
      "maxLength": 80
    },
    "kind": {
      "type": "string",
      "enum": [
        "personal",
        "product"
      ],
      "description": "`personal` works for the person; `product` works for other people (it keeps `user_id` memories)."
    },
    "purpose": {
      "type": [
        "string",
        "null"
      ],
      "maxLength": 280
    },
    "avatar_url": {
      "type": [
        "string",
        "null"
      ],
      "format": "uri",
      "description": "The picture the person gave this agent in their dashboard, or null (it then wears the mark of the tool it lives in, or its initial). Read only: no request sets it."
    },
    "status": {
      "type": "string",
      "enum": [
        "active",
        "paused",
        "retired"
      ],
      "description": "A paused agent keeps and recalls nothing (423). A retired one (the person retired it in their agents space) holds no key and answers the same, but can still be read and exported."
    },
    "created_via": {
      "type": "string",
      "enum": [
        "dashboard",
        "api",
        "connection"
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "updated_at": {
      "type": "string",
      "format": "date-time"
    },
    "last_active_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "parent": {
      "type": [
        "string",
        "null"
      ],
      "description": "The slug of the agent this one works under, or null for a top-level agent. A sub-agent has a memory, keys and settings of its own (it started as a copy of its parent's); two levels only. An agent's own key is never told its parent."
    },
    "access": {
      "type": "string",
      "enum": [
        "sealed",
        "asks",
        "trusted",
        "mix"
      ],
      "description": "What it may do with the person, in one word (`asks` is \"asks first\"); `mix` when its settings are a mix of their own."
    },
    "settings": {
      "$ref": "#/$defs/AgentPolicy"
    },
    "counts": {
      "type": "object",
      "description": "On a list and a single read. What the agent keeps now (current versions, not expired).",
      "properties": {
        "memories": {
          "type": "integer"
        },
        "users": {
          "type": "integer"
        },
        "about_you": {
          "type": "object",
          "properties": {
            "held": {
              "type": "integer"
            },
            "kept": {
              "type": "integer"
            },
            "declined": {
              "type": "integer"
            },
            "auto": {
              "type": "integer"
            }
          }
        }
      }
    }
  },
  "$defs": {
    "AgentPolicy": {
      "type": "object",
      "description": "An agent's settings: one object, the same in the dashboard and here. Every setting has a default, a PATCH deep-merges into what is there (lists replace), and one wrong setting refuses the whole patch with a sentence naming it.",
      "properties": {
        "memory": {
          "type": "object",
          "description": "What it keeps.",
          "properties": {
            "infer": {
              "type": "boolean",
              "default": true,
              "description": "Read what it is told into separate memories (one model call), or keep the text as given."
            },
            "instructions": {
              "type": "string",
              "maxLength": 4000,
              "default": "",
              "description": "What to keep, in your words."
            },
            "kinds": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string",
                "enum": [
                  "fact",
                  "preference",
                  "episode",
                  "procedure",
                  "instruction",
                  "note"
                ]
              },
              "description": "The kinds it keeps; anything else is skipped. Default: all six."
            },
            "exclude": {
              "type": "array",
              "maxItems": 20,
              "items": {
                "type": "string",
                "maxLength": 80
              },
              "description": "Topics it never keeps."
            },
            "redact": {
              "type": "object",
              "description": "Taken out BEFORE anything is stored or sent to a model.",
              "properties": {
                "emails": {
                  "type": "boolean",
                  "default": false
                },
                "phones": {
                  "type": "boolean",
                  "default": false
                },
                "secrets": {
                  "type": "boolean",
                  "default": true
                },
                "cards": {
                  "type": "boolean",
                  "default": true
                }
              }
            },
            "retention": {
              "type": "object",
              "description": "Days until a memory is deleted (null = never). `run_days` applies to anything with a run_id, `episode_days` to episodes.",
              "properties": {
                "default_days": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 3650,
                  "default": null
                },
                "episode_days": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 3650,
                  "default": 90
                },
                "run_days": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "minimum": 1,
                  "maximum": 3650,
                  "default": 30
                }
              }
            },
            "max_memories": {
              "type": "integer",
              "minimum": 100,
              "maximum": 100000,
              "default": 10000,
              "description": "Counts earlier versions too: earlier versions go first, then the oldest, least important memories."
            },
            "dedupe": {
              "type": "string",
              "enum": [
                "merge",
                "keep"
              ],
              "default": "merge",
              "description": "`merge` makes a near-duplicate the next version of the memory it repeats; `keep` keeps both."
            }
          }
        },
        "person": {
          "type": "object",
          "description": "What it learns about the person who owns it, and how much of them it may read.",
          "properties": {
            "funnel": {
              "type": "string",
              "enum": [
                "off",
                "ask",
                "auto"
              ],
              "default": "ask",
              "description": "`ask` holds each one for the person's yes, `auto` files it at once, `off` keeps it with the agent."
            },
            "min_confidence": {
              "type": "number",
              "minimum": 0.5,
              "maximum": 1,
              "default": 0.7,
              "description": "Below this, a memory is kept as the agent's own and never offered."
            },
            "never": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Personal dimensions it may never file under. Default: relationships, hauntings, kin, somatic."
            },
            "disclosure": {
              "type": "string",
              "enum": [
                "private",
                "self",
                "trusted",
                "work"
              ],
              "default": "private",
              "description": "The class floor for anything it files; the fold can only make it more private."
            },
            "read": {
              "type": "string",
              "enum": [
                "none",
                "standard",
                "personal",
                "private"
              ],
              "default": "standard",
              "description": "How deep into the person's own memory it may read when it recalls with include_person."
            }
          }
        },
        "recall": {
          "type": "object",
          "description": "How it remembers.",
          "properties": {
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 10
            },
            "threshold": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "default": 0
            },
            "rerank": {
              "type": "boolean",
              "default": false,
              "description": "Re-read the best candidates by meaning (in-process embeddings, nothing stored)."
            },
            "recency": {
              "type": "number",
              "minimum": 0,
              "maximum": 1,
              "default": 0.3,
              "description": "How much newer beats older."
            },
            "include_person": {
              "type": "boolean",
              "default": false
            }
          }
        },
        "limits": {
          "type": "object",
          "properties": {
            "writes_per_minute": {
              "type": "integer",
              "minimum": 1,
              "maximum": 6000,
              "default": 120
            },
            "reads_per_minute": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20000,
              "default": 600
            },
            "extract_per_day": {
              "type": "integer",
              "minimum": 0,
              "maximum": 100000,
              "default": 1000,
              "description": "0 turns reading off: a remember with `infer` on answers 400. All of one person's agents also share 20,000 a day."
            }
          }
        }
      }
    }
  }
}