Add Memory

Add memory

import requests

url = "https://api.hydradb.com/memories/add_memory"

payload = {
    "memories": [],
    "tenant_id": "tenant_1234",
    "sub_tenant_id": "sub_tenant_4567",
    "upsert": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    memories: [],
    tenant_id: 'tenant_1234',
    sub_tenant_id: 'sub_tenant_4567',
    upsert: true
  })
};

fetch('https://api.hydradb.com/memories/add_memory', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.hydradb.com/memories/add_memory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "memories": [],
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "upsert": true
}
'

{
  "success": true,
  "message": "Memories queued for ingestion successfully",
  "results": [],
  "success_count": 1,
  "failed_count": 1
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

POST

memories

add_memory

Add memory

import requests

url = "https://api.hydradb.com/memories/add_memory"

payload = {
    "memories": [],
    "tenant_id": "tenant_1234",
    "sub_tenant_id": "sub_tenant_4567",
    "upsert": True
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    memories: [],
    tenant_id: 'tenant_1234',
    sub_tenant_id: 'sub_tenant_4567',
    upsert: true
  })
};

fetch('https://api.hydradb.com/memories/add_memory', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

curl --request POST \
  --url https://api.hydradb.com/memories/add_memory \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "memories": [],
  "tenant_id": "tenant_1234",
  "sub_tenant_id": "sub_tenant_4567",
  "upsert": true
}
'

{
  "success": true,
  "message": "Memories queued for ingestion successfully",
  "results": [],
  "success_count": 1,
  "failed_count": 1
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

{
  "detail": {
    "success": false,
    "message": "Error occurred",
    "error_code": "<string>"
  }
}

When to use it

Use this endpoint to store user-specific context that personalizes recall:

Preferences – “User prefers dark mode and detailed technical explanations”
Conversation history – chat messages between the user and your agent
User notes – markdown snippets, settings, profile data

For documents, files, and app-generated content, use POST /ingestion/upload_knowledge instead.

Endpoint

Auth: Bearer token
Idempotency: Controlled by upsert (default true – overwrites existing items with the same source_id)
Async: Yes – memories are queued for processing. Use POST /ingestion/verify_processing to check status.

For memories, metadata and additional_metadata are plain JSON objects. Do not pre-stringify them.

Example

curl -X POST 'https://api.hydradb.com/memories/add_memory' \
  -H "Authorization: Bearer <your_api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "my_first_tenant",
    "memories": [
      {
        "text": "User prefers detailed technical explanations and dark mode",
        "infer": true,
        "user_name": "Alex",
        "metadata": {"team": "engineering"},
        "additional_metadata": {"source": "onboarding"}
      }
    ]
  }'

const response = await client.upload.addMemory({
  tenant_id: "my_first_tenant",
  memories: [
    {
      text: "User prefers detailed technical explanations and dark mode",
      infer: true,
      user_name: "Alex",
      metadata: { team: "engineering" },
      additional_metadata: { source: "onboarding" }
    }
  ]
});

response = client.upload.add_memory(
    tenant_id="my_first_tenant",
    memories=[
        {
            "text": "User prefers detailed technical explanations and dark mode",
            "infer": True,
            "user_name": "Alex",
            "metadata": {"team": "engineering"},
            "additional_metadata": {"source": "onboarding"},
        }
    ],
)

Request parameters

Name	Type	Required	Description
`tenant_id`	string	Yes	The tenant to ingest into.
`memories`	array	Yes	One or more `MemoryItem` objects. See Memory item below.
`sub_tenant_id`	string	No	Sub-tenant scope. If omitted, the default sub-tenant is used.
`upsert`	boolean	No	Default `true`. If `true`, existing memories with the same `source_id` are overwritten.

Memory item

Each entry in the memories array supports three content formats. Pick one:

Format 1 – Plain text

{
  "text": "User prefers dark mode",
  "infer": true
}

Format 2 – Markdown

{
  "text": "# Notes\n\n- Prefers dark mode\n- Likes detailed explanations",
  "is_markdown": true,
  "infer": true
}

Format 3 – Conversation pairs

{
  "user_assistant_pairs": [
    { "user": "I work mostly at night", "assistant": "Got it, I'll remember that." },
    { "user": "And I prefer concise answers", "assistant": "Understood." }
  ],
  "infer": true,
  "user_name": "Alex"
}

All MemoryItem fields

Name	Type	Default	Description
`text`	string	–	Raw text or markdown content. Use with Formats 1 or 2.
`user_assistant_pairs`	array	–	Conversation pairs. Use with Format 3.
`is_markdown`	boolean	`false`	Set `true` if `text` is markdown.
`infer`	boolean	`false`	If `true`, HydraDB extracts implicit insights from the content. See Inference modes.
`source_id`	string	auto	Unique identifier. Auto-generated if omitted.
`title`	string	–	Display title for this memory.
`user_name`	string	`"User"`	User’s name. Useful for personalizing conversation pairs.
`expiry_time`	integer	–	Optional TTL in seconds. The memory is deleted after this duration.
`custom_instructions`	string	–	Custom instructions to guide inference processing.
`metadata`	object	`{}`	Tenant-level key-value metadata (plain JSON object).
`additional_metadata`	object	`{}`	Document-level key-value metadata (plain JSON object).
`relations`	object	–	Forcefully connect this memory to other sources. See Forceful relations.

Inference modes

The infer flag controls how HydraDB processes content:

infer: true – HydraDB extracts implicit preferences, insights, and entities from the text. Best for conversation history and free-form user notes where you want HydraDB to derive structured signals.
infer: false (default) – Content is chunked and indexed as-is. Best for content that should be stored verbatim, like preset profile fields or raw notes.

Always set infer explicitly. The default is false. If you’re storing conversational content and expect HydraDB to extract preferences, you must set infer: true.

Response

{
  "success": true,
  "message": "Memories queued for ingestion successfully",
  "results": [
    {
      "source_id": "1d50e5cd7c196a2bbcc1a59b037b3a44",
      "title": null,
      "status": "queued",
      "infer": true,
      "error": null
    }
  ],
  "success_count": 1,
  "failed_count": 0
}

Field	Description
`success`	`true` if at least one memory was queued.
`message`	Human-readable status.
`results`	Per-memory ingestion result.
`results[].source_id`	The ID assigned to this memory. Use this to track processing or delete later.
`results[].status`	Initial status. One of `queued`, `processing`, `completed`, `failed`.
`results[].infer`	Whether inference was requested for this memory.
`success_count`	Number of memories successfully queued.
`failed_count`	Number of memories that failed to queue.

Behavior notes

Processing is asynchronous. This endpoint returns immediately after queuing. To verify a memory is fully indexed, poll POST /ingestion/verify_processing with the returned source_id until status is completed.

Sub-tenants are created implicitly. If you pass a sub_tenant_id that doesn’t exist, HydraDB creates it automatically on first use. There is no separate sub-tenant creation endpoint.

Next: Verify processing – check ingestion status
Next: Recall preferences – retrieve memories
Related: Delete memory – remove individual memories
Alternative: Upload knowledge – for documents and app knowledge instead of user memories

Errors

Common codes: 400 INVALID_PARAMETERS, 404 TENANT_NOT_FOUND, 422 VALIDATION_ERROR. See Error Responses for the full list. Read more: Essentials → Memories · Essentials → Metadata

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

memories

MemoryItem · object[]

required

List of memory items to ingest

Minimum array length: 1

Show child attributes

Example:

[]

tenant_id

string

required

Unique identifier for the tenant/organization

Example:

"tenant_1234"

sub_tenant_id

string

default:""

Optional sub-tenant identifier used to organize data within a tenant. If omitted, the default sub-tenant created during tenant setup will be used.

Example:

"sub_tenant_4567"

upsert

boolean

default:true

If true, update existing sources with the same source_id.

Example:

true

Response

Successful Response

Response model for add_memory endpoint.

success

boolean

default:true

Example:

true

message

string

default:Memories queued for ingestion successfully

results

MemoryResultItem · object[]

List of results for each ingested memory item.

Show child attributes

Example:

[]

success_count

integer

default:0

Number of items successfully queued for ingestion.

Example:

1

failed_count

integer

default:0

Number of items that failed to queue.

Example:

1

API Documentation

Tenants

Knowledge & Memories

Recall

Managing Data

When to use it

Endpoint

Example

Request parameters

Memory item

Format 1 – Plain text

Format 2 – Markdown

Format 3 – Conversation pairs

All MemoryItem fields

Inference modes

Response

Behavior notes

Errors

Authorizations

Body

Response

​When to use it

​Endpoint

​Example

​Request parameters

​Memory item

​Format 1 – Plain text

​Format 2 – Markdown

​Format 3 – Conversation pairs

​All MemoryItem fields

​Inference modes

​Response

​Behavior notes

​Related endpoints

​Errors

Authorizations

Body

Response

When to use it

Endpoint

Example

Request parameters

Memory item

Format 1 – Plain text

Format 2 – Markdown

Format 3 – Conversation pairs

All MemoryItem fields

Inference modes

Response

Behavior notes

Related endpoints

Errors