Memories

A memory is a preference, a decision, something already tried, or a conversation worth keeping, saved so your agent remembers it in future sessions. Your application sends it to POST /context/ingest with type=memory, and gets it back with POST /query. HydraDB does not capture memories on its own. Good moments to save one: a user states a preference, makes a decision, finishes a task, or corrects the agent. Saving “this customer already tried restarting” lets a support agent skip that suggestion later. Product docs, policies, and wiki pages are knowledge, not memories. In this guide:

Save a memory: a user preference, start to finish.
Choose where memories live: the collection field.
Let HydraDB infer the memory: the infer switch, with a behavior-log example.
Send text or a conversation: the two input shapes.
Retrieve memories: on their own, or together with knowledge.
Update or delete a memory.
Field reference and common mistakes.

1. Save a memory

This request saves one preference for the user john_123. Every memory uses the same request; only the items inside memories change. The request is multipart/form-data with these fields:

Form field	What to send
`type`	`memory`
`database`	An existing database
`collection`	The user’s own collection, such as `user_john_123`. Section 2 explains why.
`memories`	One item or a list of items, as a JSON string
`upsert`	Leave it out. It defaults to `true`, so sending an item again with the same `id` replaces the saved memory.

Save a memory: Python, TypeScript, or cURL

Set up your SDK client before running the Python or TypeScript example.

import json
import os
from hydra_db import HydraDB

client = HydraDB(token=os.environ["HYDRA_DB_API_KEY"])

result = client.context.ingest(
    type="memory",
    database="acme_corp",
    collection="user_john_123",
    memories=json.dumps([
        {
            "text": "Prefers short, direct answers with no preamble.",
            "infer": True,
            "user_name": "John",
        }
    ]),
)

import { HydraDBClient } from "@hydradb/sdk";

const client = new HydraDBClient({
  token: process.env.HYDRA_DB_API_KEY,
});

const result = await client.context.ingest({
  type: "memory",
  database: "acme_corp",
  collection: "user_john_123",
  memories: JSON.stringify([
    {
      text: "Prefers short, direct answers with no preamble.",
      infer: true,
      user_name: "John",
    },
  ]),
});

curl -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=memory" \
  -F "database=acme_corp" \
  -F "collection=user_john_123" \
  -F 'memories=[
    {
      "text": "Prefers short, direct answers with no preamble.",
      "infer": true,
      "user_name": "John"
    }
  ]'

The response lists each memory in data.results with its id and a status of queued. The payload is wrapped in the standard envelope, so read it from response.data:

{
  "success": true,
  "data": {
    "success": true,
    "message": "Memories queued for ingestion successfully",
    "results": [
      { "id": "mem_abc123", "status": "queued", "infer": true }
    ],
    "success_count": 1,
    "failed_count": 0
  },
  "error": null,
  "meta": {
    "request_id": "9d13aef4-02f4-4e73-8c62-4c2601d04f9d",
    "latency_ms": 12.3
  }
}

What each property in the item means

Property	What it is
`text`	The memory, in your words. Use `user_assistant_pairs` instead when the signal is in a conversation. Section 4 covers both.
`infer`	`true` asks HydraDB to extract the preference or fact from what you sent. `false`, the default, stores your text as written. Section 3 explains the choice.
`user_name`	The user’s name, used during inference.
`id`	Optional stable ID you choose. Send the same `id` later to replace the memory, or use it to check status and delete. Leave it out to have one generated; the response returns it either way.
`metadata`, `additional_metadata`	Values for filtering and bookkeeping, sent as objects. See Metadata.

Status

Ingestion runs in the background: HydraDB parses the input, infers the memory if you asked it to, and indexes the result. Check GET /context/status with the returned id and the same collection. The memory is searchable once indexing_status reaches graph_creation; completed means the graph work is done too. If you would rather not poll, register a webhook.

2. Choose where memories live

Memories are saved in a collection inside your database. To keep each person’s memories apart, give each person their own collection, such as user_john_123, and send it on every write, status check, and query. Your backend picks it from the signed-in session; the name itself does not authenticate anyone. If you leave collection out, the memory lands in the database’s default collection, and a query that names another collection does not read it. See Multi-tenancy.

3. Let HydraDB infer the memory

infer controls how much extraction work your application does before sending data to HydraDB.

Use `infer: true` when the input is raw signal

With infer: true, you give HydraDB messy or indirect evidence (dialogue, logs, behavior, feedback, or observations), and HydraDB extracts the useful preference, trait, or fact. Use infer: true for:

Dialogue where the preference is implicit.
Behavior logs and event streams.
Feedback like “the last summary was too long.”

custom_instructions only takes effect when infer: true. Use it to guide extraction, for example: "Focus on UI and notification preferences only".

Use `infer: false` when the input is already the memory

With infer: false (the default), HydraDB stores and indexes exactly what you send. There is no extraction step. Use infer: false for:

Facts you already captured, such as "User's plan tier is Pro".
Pre-structured notes.
Text you want to retrieve exactly as written.

Rule of thumb: infer: false is faster and deterministic. infer: true is better when your input is raw, noisy, or indirect.

Infer a preference from a behavior log: Python, TypeScript, or cURL

A user has been toggling dark mode in your app. Instead of extracting the preference yourself, send the raw behavior log and let HydraDB infer the useful memory.

import json

client.context.ingest(
    type="memory",
    database="acme_corp",
    collection="user_john_123",
    memories=json.dumps([
        {
            "text": (
                "User opened the app 14 times in the last week. "
                "Switched to dark mode on first session. "
                "Toggled back to light once on 2026-04-12 at 3pm, "
                "then switched back to dark within 4 minutes. "
                "Has not changed theme since."
            ),
            "infer": True,
            "user_name": "John",
            "custom_instructions": "Focus on display and theme preferences.",
        }
    ]),
)

const result = await client.context.ingest({
  type: "memory",
  database: "acme_corp",
  collection: "user_john_123",
  memories: JSON.stringify([
    {
      text:
        "User opened the app 14 times in the last week. " +
        "Switched to dark mode on first session. " +
        "Toggled back to light once on 2026-04-12 at 3pm, " +
        "then switched back to dark within 4 minutes. " +
        "Has not changed theme since.",
      infer: true,
      user_name: "John",
      custom_instructions: "Focus on display and theme preferences.",
    },
  ]),
});

curl -X POST 'https://api.hydradb.com/context/ingest' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -F "type=memory" \
  -F "database=acme_corp" \
  -F "collection=user_john_123" \
  -F 'memories=[
    {
      "text": "User opened the app 14 times in the last week. Switched to dark mode on first session. Toggled back to light once on 2026-04-12 at 3pm, then switched back to dark within 4 minutes. Has not changed theme since.",
      "infer": true,
      "user_name": "John",
      "custom_instructions": "Focus on display and theme preferences."
    }
  ]'

Later, when POST /query runs with type: "memory" and a query like "what UI settings does the user prefer?", HydraDB can return the inferred preference (for example, "prefers dark mode") rather than the raw event log.If you sent the same input with infer: false, HydraDB would index the event log verbatim. That is useful only when you want to retrieve the log itself.

4. Send text or a conversation

Each memory item takes either text or user_assistant_pairs, not both (sending both returns 400). Choose the shape that matches the data you already have.

text: prose of any kind, such as observations, captured facts, meeting notes, or semi-structured records. Set is_markdown: true when the content uses Markdown (headings, lists, code blocks) so HydraDB keeps that structure during chunking and embedding.
user_assistant_pairs: dialogue, especially when the preference is implied rather than stated. Each pair is { "user": "...", "assistant": "..." }.

Input shapes: text, Markdown, and user-assistant pairs

Markdown notes, stored as written:

{
  "text": "# Meeting Notes\n\n## Key Points\n- Budget approved",
  "is_markdown": true,
  "infer": false
}

A plain statement, with the preference extracted:

{
  "text": "Prefers detailed technical explanations and works in PST.",
  "infer": true
}

A conversation, with the preference extracted:

{
  "user_assistant_pairs": [
    { "user": "Remember I like dark mode", "assistant": "Noted." }
  ],
  "infer": true
}

5. Retrieve memories

Memories live in their own store, separate from knowledge. POST /query reaches each store through the type parameter:

type: "memory" queries the memories store (vectorstore_status.memories).
type: "knowledge" queries the knowledge store (vectorstore_status.knowledge).
type: "all" runs both in parallel and returns a single merged, re-ranked result set.

Send the same collection you used when saving. Both stores are read from that collection, so if shared documents live in their own collection, list it next to the user’s in collections. See Query.

Query a user's memories: Python, TypeScript, or cURL

result = client.query(
    database="acme_corp",
    collection="user_john_123",
    query="How does the user like answers written?",
    type="memory",
)

for chunk in result.data.chunks:
    print(chunk.chunk_content)

const result = await client.query({
  database: "acme_corp",
  collection: "user_john_123",
  query: "How does the user like answers written?",
  type: "memory",
});

if (!result.data || typeof result.data === "string") throw new Error("Expected structured query results");
for (const chunk of result.data.chunks) {
  console.log(chunk.chunkContent);
}

curl -X POST 'https://api.hydradb.com/query' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "API-Version: 2" \
  -H "Content-Type: application/json" \
  -d '{
    "database": "acme_corp",
    "collection": "user_john_123",
    "query": "How does the user like answers written?",
    "type": "memory"
  }'

Matching memories come back in data.chunks, ranked by relevance. Pass their text to your model as context. See How to Use API Results to turn the response into a prompt.

6. Update or delete a memory

To change a memory, send it again with the same id and the new text. upsert defaults to true, so the saved memory is replaced. Wait for the previous ingestion to reach completed or errored before sending the next update for the same id. To remove a memory, call DELETE /context with its id and the same collection.

Field reference

Request fields

Field	Default	Description
	None	Selects the memories store. Use singular `memory`.
	None	Target database. The `database` field was formerly `tenant_id`.
	default collection	User, workspace, or session scope for the memory. The `collection` field was formerly `sub_tenant_id`.
	`true`	Replace existing memories with the same `id`.
	None	JSON-stringified array of memory items.

Memory item fields

Field	Description
	Optional stable ID. Acts as the upsert key.
	Short label for display in `/context/list` and query results.
	Raw text or Markdown content. Required unless `user_assistant_pairs` is provided.
	Conversation pairs in the shape `{ "user": "...", "assistant": "..." }`. Required unless `text` is provided.
	Treat `text` as Markdown for chunking and indexing.
	When `true`, HydraDB extracts the underlying preference, trait, or fact. When `false` (the default), it stores the input as written.
	Guides extraction when `infer: true`. Ignored when `infer: false`.
	User name used during inference.
	Database-schema fields for filtering and querying. Send this as an object inside each `memories[]` item, for example `"metadata": { "department": "support" }`. Up to 16 KiB as compact JSON.
	Free-form per-memory fields for display or bookkeeping. Send this as an object. Up to 1 KiB as compact JSON.

memories is a JSON string. Inside each item, metadata and additional_metadata are plain objects; do not stringify them again.

{
  "id": "pref_dark_mode",
  "text": "User prefers dark mode and concise answers.",
  "infer": true,
  "metadata": { "department": "support", "workspace": "docs" },
  "additional_metadata": { "source": "onboarding" }
}

Common mistakes

Mistake	What goes wrong	Fix
Sending `"memory": "..."` instead of `"memories": [...]`	Validation fails	Use `"memories": [ { "text": "..." } ]`, always an array of objects
Omitting `database`	`400` (`database is required`)	Include `database` on every call
Omitting `collection` for per-user data	The memory lands in the default collection and may surface in the wrong scope	Use the user’s ID as `collection` for B2C separation
Extracting preferences yourself instead of sending the raw logs	You duplicate work HydraDB can do for you	Send the raw signal with `infer: true`
Sending pre-extracted facts with `infer: true`	HydraDB may re-derive the memory and change the original phrasing	Use `infer: false` for already-structured facts
Treating `user_name` as cosmetic	It can influence inference, so the wrong name can bias extraction	Pass the actual user’s name
Storing shared docs as memories	They will not surface when querying `type: "knowledge"`	Use knowledge ingestion with `type=knowledge` on `POST /context/ingest`

Knowledge: shared document context
Query: how memories are retrieved at query time
Multi-tenancy: scoping memories per user or workspace
Metadata: designing filterable fields

Get Started

Usage

Organize

Understand

Plugins

For Agents

1. Save a memory

What each property in the item means

Status

2. Choose where memories live

3. Let HydraDB infer the memory

Use `infer: true` when the input is raw signal

Use `infer: false` when the input is already the memory

4. Send text or a conversation

5. Retrieve memories

6. Update or delete a memory

Field reference

Common mistakes

​1. Save a memory

​What each property in the item means

​Status

​2. Choose where memories live

​3. Let HydraDB infer the memory

​Use infer: true when the input is raw signal

​Use infer: false when the input is already the memory

​4. Send text or a conversation

​5. Retrieve memories

​6. Update or delete a memory

​Field reference

​Common mistakes

​Related

1. Save a memory

What each property in the item means

Status

2. Choose where memories live

3. Let HydraDB infer the memory

Use `infer: true` when the input is raw signal

Use `infer: false` when the input is already the memory

4. Send text or a conversation

5. Retrieve memories

6. Update or delete a memory

Field reference

Common mistakes

Related