---
title: "Remember"
method: POST
path: "/v1/agents/{agent}/memories"
tags: ["agents"]
---

# Remember

`POST /v1/agents/{agent}/memories`

## Request

- Base URL: `https://innernet.live/api`
- URL: `https://innernet.live/api/v1/agents/{agent}/memories`
- Auth: HTTP bearer

Give the agent something to keep: `content` (a text) or `messages` (a conversation), not both. What it is told is redacted first (secrets and card numbers by default; emails and phone numbers if its settings say so), then, with `infer` on (the default), read into separate memories under the agent's own instructions and excluded topics. A memory is about the `agent`, about one of its `user`s (give `user_id`), or about the `owner`, the person the agent belongs to: only that last kind is ever offered to the person's own memory, held for their yes or filed at once as they set `person.funnel`, in the agent's voice and never theirs (see `about_you` in the answer). The same words again are skipped; a near-duplicate becomes the next version of the memory it repeats, unless that one is `immutable`. A paused agent answers 423. Needs the agent's own key or a person's key with `write`.

## Path parameters

- `agent` string, required

## Request body

- object
  - `content` string: The text to keep (or `messages`).
  - `messages` object[]: Or a conversation to learn from. `system` messages are dropped; a `tool` message is kept short.
    - `role` 'user' | 'assistant' | 'system' | 'tool', required
    - `content` string, required
    - `name` string
  - `infer` boolean: Overrides the agent's memory.infer for this call. With `false` the text is kept as given: one memory of at most 8000 characters.
  - `kind` 'fact' | 'preference' | 'episode' | 'procedure' | 'instruction' | 'note': Default `note` when not inferring.
  - `subject` 'agent' | 'owner' | 'user': Who it is about. When absent: the extraction decides, or `user` if `user_id` is given, else `agent`.
  - `user_id` string: One of the agent's users (your id for them).
  - `dimension` string: For a memory about the owner: the part of their life it belongs to (a personal dimension such as `preferences` or `tools`). Wins over the extraction's guess; an unknown name answers 400.
  - `run_id` string: A run, a thread or a session. Run memories expire after `retention.run_days`.
  - `tags` string[]
  - `metadata` object: At most 30 keys and 16 KB. Filter by it with `metadata.<key>`.
  - `importance` integer
  - `immutable` boolean: Never changed (PATCH answers 409) and never replaced by a newer version.
  - `event_at` string, date-time: When it happened (an ISO date, or a time with a zone).
  - `expires_at` string, date-time: In the future. Not with `ttl_days`.
  - `ttl_days` integer
  - `instructions` string: Extra guidance for the extraction, for this call only.

## Response `201`

Created: something was kept. A call that kept nothing (all duplicates, all ruled out) answers 200 with the same body.

- object
  - `memories` AgentMemory[]
    - `id` string, uuid
    - `agent` string: The agent's slug.
    - `content` string, nullable
    - `kind` 'fact' | 'preference' | 'episode' | 'procedure' | 'instruction' | 'note'
    - `subject` 'agent' | 'owner' | 'user': Who it is about: the agent's own knowledge, the person who owns the agent, or one of its users.
    - `user_id` string, nullable: Your end user, when `subject` is `user`.
    - `run_id` string, nullable
    - `tags` string[]
    - `metadata` object
    - `importance` integer
    - `confidence` number, nullable
    - `immutable` boolean
    - `source` 'api' | 'extract' | 'dashboard' | 'import'
    - `event_at` string, date-time, nullable
    - `expires_at` string, date-time, nullable
    - `supersedes` string, uuid, nullable: The memory this one is the next version of.
    - `superseded_at` string, date-time, nullable: Set once a newer version has replaced this one.
    - `about_you` object, nullable: Set when the memory is about the person who owns the agent: where it stands with them.
      - `state` 'held' | 'kept' | 'declined' | 'auto'
      - `dimension` string, nullable
    - `created_at` string, date-time
    - `updated_at` string, date-time
    - `score` number: Only on recall and context results: 0 to 1.
  - `about_you` object[]: Which of them were about the person who owns the agent, and where each stands.
    - `memory_id` string, uuid
    - `state` 'held' | 'kept' | 'declined' | 'auto'
    - `dimension` string, nullable
  - `skipped` object[]: What was not kept, and why (already kept, an excluded topic, a kind that is turned off).
    - `reason` string
    - `content` string
  - `redactions` object: How many of each were taken out before anything was stored or sent to a model.
    - `emails` integer
    - `phones` integer
    - `secrets` integer
    - `cards` integer

## Other responses

- `400`: Error: a field is wrong; `detail.field` names it, and a field this call does not take is refused by name (`invalid`)
- `401`: Error
- `403`: Error: this key cannot write (`forbidden`)
- `404`: Error: no such agent for this key (`not_found`)
- `413`: Error: the text, the conversation or the metadata is too large (`too_large`)
- `423`: Error: the agent is paused (`paused`)
- `429`: Error: over the agent's writes a minute, or its extractions a day (`rate_limited`; `Retry-After: 60`)
- `503`: Error: agents are not switched on yet (`unavailable`)

---

[API](https://skmtc.dev/innernet/apis/innernet-api.md) · [All operations](https://skmtc.dev/innernet/apis/innernet-api/llms.txt) · [OpenAPI document](https://skmtc.dev/innernet/apis/innernet-api/revisions/1ee09aec71a9?raw)