> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memoclaw.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Store Memory

> POST /v1/store — Store a single memory with semantic embeddings.

<Snippet file="snippets/x402-callout.mdx" />

**Price:** \$0.005 USDC

## Request Body

<ParamField body="content" type="string" required>
  The memory text. Max 8,192 characters.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata. Max 4 KB, 20 keys, 3 levels deep.

  <Expandable title="Nested fields">
    <ParamField body="metadata.tags" type="string[]">
      Tags for filtering. Max 10 tags, 64 characters each.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="importance" type="number">
  Float between 0 and 1. Affects ranking in recall. Default: `0.5`.
</ParamField>

<ParamField body="namespace" type="string">
  Isolate memories per project or context. Default: `"default"`. Max 255 characters.
</ParamField>

<ParamField body="memory_type" type="string">
  One of: `correction`, `preference`, `decision`, `project`, `observation`, `general`. Each type has a different decay half-life. Default: `"general"`.
</ParamField>

<ParamField body="session_id" type="string">
  Session identifier for multi-agent scoping. Max 255 characters.
</ParamField>

<ParamField body="agent_id" type="string">
  Agent identifier for multi-agent scoping. Max 255 characters.
</ParamField>

<ParamField body="expires_at" type="string">
  ISO 8601 date string. Memory auto-expires after this time and is excluded from all queries. Must be in the future.
</ParamField>

<ParamField body="pinned" type="boolean">
  Pin this memory to exempt it from decay. Default: `false`.
</ParamField>

<ParamField body="immutable" type="boolean">
  Lock the memory from future updates and deletes. Default: `false`. Once stored as immutable, the memory cannot be modified or removed (returns 409 Conflict).
</ParamField>

## Response (201 Created)

<ResponseField name="id" type="string">
  UUID of the stored memory.
</ResponseField>

<ResponseField name="stored" type="boolean">
  Always `true`.
</ResponseField>

<ResponseField name="deduplicated" type="boolean">
  Whether the memory was deduplicated (merged with an existing similar memory instead of creating a new one).
</ResponseField>

<ResponseField name="tokens_used" type="number">
  Embedding tokens consumed.
</ResponseField>

## Example

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://api.memoclaw.com/v1/store \
    -H "Content-Type: application/json" \
    -d '{
      "content": "User prefers dark mode and vim keybindings",
      "metadata": {
        "tags": ["preferences", "ui"]
      },
      "importance": 0.8
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.memoclaw.com/v1/store", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      content: "User prefers dark mode and vim keybindings",
      metadata: {
        tags: ["preferences", "ui"],
      },
      importance: 0.8,
    }),
  });

  const data = await response.json();
  ```

  ```python Python theme={null}
  from memoclaw import MemoClaw

  client = MemoClaw()
  result = client.store(
      "User prefers dark mode and vim keybindings",
      importance=0.8,
      tags=["preferences", "ui"],
  )
  ```
</CodeGroup>

```json Response theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "stored": true,
  "deduplicated": false,
  "tokens_used": 15
}
```