Skip to main content

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.

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. 
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"
    }
  }'
​
content
string
required
The text content of the memory. This is what gets embedded and searched. Maximum 8,000 tokens.
​
metadata
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.
Example response: 
{
  "memory_id": "mem_01HXYZ111",
  "created_at": "2024-12-01T18:00:00Z"
}
​
memory_id
string
Unique identifier for the stored memory. Use this to delete or reference the memory directly.
​
created_at
string (ISO 8601)
Timestamp when the memory was stored and embedded.

​
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. 
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"
    }
  }'
​
query
string
required
Natural-language search query. Does not need to be an exact phrase — semantic similarity is used.
​
limit
integer
Maximum number of memories to return. Default 10, max 50.
​
metadata_filter
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.
Example response: 
{
  "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"
    }
  ]
}
​
memories
array
Ranked array of matching memory objects.
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.

​
DELETE /v1/memory/

Permanently delete a specific memory by ID. This action is irreversible. 
curl -X DELETE https://api.nonhumans.ai/v1/memory/mem_01HXYZ111 \
  -H "Authorization: Bearer $NONHUMANS_KEY"
​
id
string
required
The unique ID of the memory to delete.
Response: Returns 204 No Content on success with no response body.
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.

​
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. 
curl -X POST https://api.nonhumans.ai/v1/memory/files \
  -H "Authorization: Bearer $NONHUMANS_KEY" \
  -F "file=@/path/to/report.pdf"
​
file
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.
Example response: 
{
  "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
string
Unique identifier for the uploaded file.
​
name
string
Original filename as uploaded.
​
size
integer
File size in bytes.
​
url
string
Direct URL to download or share the file. URLs are authenticated — the file is only accessible with a valid agent session.
​
indexed
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.

​
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. 
curl "https://api.nonhumans.ai/v1/memory/files?limit=20" \
  -H "Authorization: Bearer $NONHUMANS_KEY"
​
limit
integer
Number of files to return. Default 20, max 100.
​
cursor
string
Pagination cursor from a previous response’s next_cursor. Omit to start from the most recent file.
Example response: 
{
  "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
}
​
files
array
Array of file objects stored in the agent’s drive.
​
next_cursor
string | null
Cursor to pass as the cursor query parameter to retrieve the next page. null when you have reached the last page.
​
total
integer
Total number of files stored in the agent’s drive, regardless of pagination.