---
title: "Store a memory"
method: POST
path: "/api/v1/agent/memories"
tags: ["agentApiMemories"]
---

# Store a memory

`POST /api/v1/agent/memories`

Stores a new memory entry, with the authenticated agent as its source.

`scope` names the audience, and each scope requires the field that identifies it:

- `agent` — private to this agent. The default when no `scope` and no `subject_id` is
  given, so an unqualified write is private rather than shared.
- `subject` — readable by any agent in the organization dealing with `subject_id`,
  which is required. The default when a `subject_id` is given without a `scope`.
- `organization` — readable by every agent in the organization. Rejected with 422 when
  the agent belongs to none, since there would be no audience to share it with.

## Headers

- `X-API-Key` string, required

## Request body

- object
  - `memory` AgentMemoryCreateRequest, required — Request to create a new memory
    - `content` string, required — The memory content
    - `metadata` AgentMemoryCreateRequestMetadata — Additional metadata (tags, references, etc.)
      - `references` string[] — Related memory IDs
      - `tags` string[] — Tags for categorization
    - `scope` 'agent' | 'subject' | 'organization' — Who may read this memory: - `agent`: only the agent that stored it - `subject`: any agent in the organization dealing with `subject_id` - `organization`: every agent in the organization (requires the agent to be in one) Omitted, it is `subject` when `subject_id` is given and `agent` otherwise.
    - `segment` 'user' | 'agent' | 'tool' | 'guideline', required — Logical segment
    - `subject_id` string, uuid — UUID of the subject this memory is about. Required for subject scope.
    - `system` 'sensory' | 'working' | 'long_term', required — Memory system tier
    - `thought` string, required — Agent's reasoning for storing this memory
    - `type` 'iconic' | 'echoic' | 'haptic' | 'episodic' | 'semantic' | 'procedural', required — Memory type (must be valid for selected system)

## Response `201`

Created Memory

- MemoriesCreateAgentMemoryResponse201 — unresolved $ref

## Other responses

- `401` — Unauthorized
- `422` — Validation Error

## Changes

- **2026-08-26** `3cff423845a2` — 2 info
  - the `scope` request property default value `subject` was removed
  - added the new `agent` enum value to the request property `memory/scope`

[Change history](https://skmtc.dev/band/apis/request-api/changes/api/v1/agent/memories/post.md)

---

[API](https://skmtc.dev/band/apis/request-api.md) · [All operations](https://skmtc.dev/band/apis/request-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/band/request-api/revisions/3cff423845a2/schema)