---
title: "Create a Memory Block"
method: POST
path: "/memory_blocks"
tags: ["Memory Blocks"]
---

# Create a Memory Block

`POST /memory_blocks`

## Request

- Base URL: `https://h2ogpte.genai.h2o.ai/api/v1`
- URL: `https://h2ogpte.genai.h2o.ai/api/v1/memory_blocks`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/h2o/apis/h2ogpte-rest-api/docs/memory_blocks/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new memory block for persistent agent memory. Memory blocks are cross-collection and per-user.

## Request body

- MemoryBlockCreateRequest
  - `name` string, required: Name of the memory block.
  - `content` string: Initial content of the memory block.
  - `system_prompt_amendment` string: System prompt amendment for agent mode that drives changes to the memory block.
  - `injection_mode` 'system_prompt' | 'user_instruction' | 'agent_file' | 'agent_tool': Where memory content is injected. 'system_prompt' (default) adds it to the LLM system prompt; 'user_instruction' prepends it to the user message; 'agent_file' makes it only available as AGENTS.md in agent mode; 'agent_tool' exposes content lazily via the read_memory_block / update_memory_block tools (no pre-injection).
  - `access_mode` 'read' | 'write' | 'read_write': Controls whether the LLM/agent can read the memory, write to it, or both.
  - `max_content_length` integer: Maximum number of characters allowed in memory content. Set to 0 for unlimited. In LLM mode, new memories are appended and oldest content is trimmed when this limit is exceeded.

## Response `201`

Successful operation

- MemoryBlock
  - `id` string, required: Unique identifier of the memory block.
  - `name` string, required: Name of the memory block.
  - `content` string, required: Text content of the memory block.
  - `system_prompt_amendment` string, required: System prompt amendment for agent mode.
  - `injection_mode` 'system_prompt' | 'user_instruction' | 'agent_file' | 'agent_tool', required: Where memory content is injected. 'system_prompt' adds it to the LLM system prompt; 'user_instruction' prepends it to the user message; 'agent_file' makes it only available as AGENTS.md in agent mode; 'agent_tool' exposes content lazily via the read_memory_block / update_memory_block tools (no pre-injection).
  - `access_mode` 'read' | 'write' | 'read_write', required: Controls whether the LLM/agent can read the memory, write to it, or both.
  - `user_id` string, required: ID of the user who owns the memory block.
  - `username` string: Username of the owner.
  - `created_at` string, date-time, required: When the memory block was created.
  - `updated_at` string, date-time, required: When the memory block was last updated.
  - `is_public` boolean: Whether the memory block is publicly accessible.
  - `is_owner` boolean: Whether the current user is the owner.
  - `max_content_length` integer: Maximum number of characters allowed in memory content. 0 means unlimited.
  - `is_auto` boolean: Whether this memory block was auto-created by the system for an AI assistant or chat session.
  - `user_count` integer: The number of users the memory block has been directly shared with (excludes the owner).
  - `group_count` integer: The number of groups the memory block has been shared with.

## Other responses

- `400`: Bad request
- `401`: Unauthorized - Invalid or missing API key
- `404`: Not found
- `409`: Conflict
- `default`: Unexpected error

---

[API](https://skmtc.dev/h2o/apis/h2ogpte-rest-api.md) - [All operations](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/h2o/apis/h2ogpte-rest-api/revisions/a82a117320f4?raw)