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

# Memory API — Vector Storage, Semantic Search & Files

> REST API reference for the Nonhumans Memory primitive — store and search vector memories, manage files, and query the agent's structured database.

The Memory API gives your agent a long-term, semantically searchable store. Write any piece of text as a memory — it's automatically embedded into a high-dimensional vector — then retrieve the most relevant memories later using natural-language queries. This means your agent can recall past conversations, decisions, and knowledge without needing to fit everything into a context window. Memories persist indefinitely until you delete them.

***

## POST /v1/memory

Store a new memory. The content is automatically embedded using Nonhumans' managed embedding model — you don't need to generate or store vectors yourself.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/memory \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user prefers concise bullet-point summaries over long prose.",
    "metadata": {
      "source": "user_feedback",
      "user_id": "usr_abc123"
    }
  }'
```

<ParamField body="content" type="string" required>
  The text content of the memory. This is what gets embedded and searched. Maximum 8,000 tokens.
</ParamField>

<ParamField body="metadata" type="object">
  Optional key-value pairs attached to the memory. Use metadata to tag, categorize, or filter memories without affecting the semantic content. Keys and values must be strings.
</ParamField>

**Example response:**

```json theme={null}
{
  "memory_id": "mem_01HXYZ111",
  "created_at": "2024-12-01T18:00:00Z"
}
```

<ResponseField name="memory_id" type="string">
  Unique identifier for the stored memory. Use this to delete or reference the memory directly.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  Timestamp when the memory was stored and embedded.
</ResponseField>

***

## POST /v1/memory/search

Search your agent's memory store using a natural-language query. The API returns the most semantically similar memories ranked by cosine similarity score.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/memory/search \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are this user'\''s formatting preferences?",
    "limit": 5,
    "metadata_filter": {
      "user_id": "usr_abc123"
    }
  }'
```

<ParamField body="query" type="string" required>
  Natural-language search query. Does not need to be an exact phrase — semantic similarity is used.
</ParamField>

<ParamField body="limit" type="integer">
  Maximum number of memories to return. Default `10`, max `50`.
</ParamField>

<ParamField body="metadata_filter" type="object">
  Key-value pairs used to pre-filter memories before the semantic search. Only memories whose metadata contains all specified key-value pairs are considered. This is a strict equality filter.
</ParamField>

**Example response:**

```json theme={null}
{
  "memories": [
    {
      "id": "mem_01HXYZ111",
      "content": "The user prefers concise bullet-point summaries over long prose.",
      "score": 0.94,
      "metadata": {
        "source": "user_feedback",
        "user_id": "usr_abc123"
      },
      "created_at": "2024-12-01T18:00:00Z"
    }
  ]
}
```

<ResponseField name="memories" type="array">
  Ranked array of matching memory objects.

  <Expandable title="Memory fields">
    <ResponseField name="id" type="string">
      Unique memory identifier.
    </ResponseField>

    <ResponseField name="content" type="string">
      The original text content of the memory.
    </ResponseField>

    <ResponseField name="score" type="number">
      Cosine similarity score between `0.0` and `1.0`. Higher is more relevant. Scores above `0.80` typically indicate strong semantic matches.
    </ResponseField>

    <ResponseField name="metadata" type="object">
      The metadata attached when the memory was stored.
    </ResponseField>

    <ResponseField name="created_at" type="string (ISO 8601)">
      When the memory was originally stored.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  Use `metadata_filter` to partition memories by user, session, or topic before running the semantic search. This dramatically improves precision for agents that store memories across multiple contexts.
</Tip>

***

## DELETE /v1/memory/{id}

Permanently delete a specific memory by ID. This action is irreversible.

```bash theme={null}
curl -X DELETE https://api.nonhumans.ai/v1/memory/mem_01HXYZ111 \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField path="id" type="string" required>
  The unique ID of the memory to delete.
</ParamField>

**Response:**

Returns `204 No Content` on success with no response body.

<Warning>
  Deleted memories cannot be recovered. If you need to temporarily disable a memory from search results without losing it, add a metadata tag like `"active": "false"` and use `metadata_filter` in your queries to exclude it.
</Warning>

***

## POST /v1/memory/files

Upload a file to your agent's personal drive. Files are stored durably and can be retrieved via their URL. Large documents (PDFs, spreadsheets, text files) are also automatically chunked and indexed into vector memory for semantic search.

```bash theme={null}
curl -X POST https://api.nonhumans.ai/v1/memory/files \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -F "file=@/path/to/report.pdf"
```

<ParamField body="file" type="file" required>
  The file to upload. Sent as `multipart/form-data`. Maximum file size is 500 MB. Supported formats for automatic indexing: PDF, DOCX, TXT, MD, CSV, XLSX.
</ParamField>

**Example response:**

```json theme={null}
{
  "file_id": "file_01HXYZ999",
  "name": "report.pdf",
  "size": 204800,
  "url": "https://files.nonhumans.ai/agt_01HXYZ123/report.pdf",
  "indexed": true,
  "created_at": "2024-12-01T18:15:00Z"
}
```

<ResponseField name="file_id" type="string">
  Unique identifier for the uploaded file.
</ResponseField>

<ResponseField name="name" type="string">
  Original filename as uploaded.
</ResponseField>

<ResponseField name="size" type="integer">
  File size in bytes.
</ResponseField>

<ResponseField name="url" type="string">
  Direct URL to download or share the file. URLs are authenticated — the file is only accessible with a valid agent session.
</ResponseField>

<ResponseField name="indexed" type="boolean">
  Whether the file's contents have been extracted and indexed into the vector memory store. When `true`, you can search the file's contents using `POST /v1/memory/search`.
</ResponseField>

***

## GET /v1/memory/files

List all files stored in your agent's drive. Results are returned in reverse chronological order and support cursor-based pagination.

```bash theme={null}
curl "https://api.nonhumans.ai/v1/memory/files?limit=20" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
```

<ParamField query="limit" type="integer">
  Number of files to return. Default `20`, max `100`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response's `next_cursor`. Omit to start from the most recent file.
</ParamField>

**Example response:**

```json theme={null}
{
  "files": [
    {
      "file_id": "file_01HXYZ999",
      "name": "report.pdf",
      "size": 204800,
      "url": "https://files.nonhumans.ai/agt_01HXYZ123/report.pdf",
      "indexed": true,
      "created_at": "2024-12-01T18:15:00Z"
    },
    {
      "file_id": "file_01HABC111",
      "name": "dataset.csv",
      "size": 512000,
      "url": "https://files.nonhumans.ai/agt_01HXYZ123/dataset.csv",
      "indexed": true,
      "created_at": "2024-11-28T10:00:00Z"
    }
  ],
  "next_cursor": null,
  "total": 2
}
```

<ResponseField name="files" type="array">
  Array of file objects stored in the agent's drive.
</ResponseField>

<ResponseField name="next_cursor" type="string | null">
  Cursor to pass as the `cursor` query parameter to retrieve the next page. `null` when you have reached the last page.
</ResponseField>

<ResponseField name="total" type="integer">
  Total number of files stored in the agent's drive, regardless of pagination.
</ResponseField>