Memories

1. What it is

Memories are user-scoped context HydraDB stores so your application can personalize responses over time. A memory is a unit of user-specific context HydraDB stores on behalf of an agent - a preference, a past conversation, an inferred trait, or a raw fact. Memories let an agent adapt its responses to a specific user across sessions, and surface again through Recall when relevant. Think of memories as persistent user-specific context. That’s distinct from Knowledge, which is shared, tenant-wide context ingested from documents and apps.

	Memories	Knowledge
Content	User preferences, conversations, inferred traits	Documents, files, app-generated content
Scope	Per-user (`sub_tenant_id`)	Shared across all users in a tenant
Recall endpoint	`recall_preferences`	`full_recall`
`vectorstore_status`	Index `0` (`[0]`)	Index `1` (`[1]`)

2. What it does

When you add a memory, HydraDB:

Parses the input (text, markdown, or user–assistant pairs).
Optionally runs inference (infer: true) to extract preferences and insights.
Processes and indexes it for future retrieval.
Makes it available to recall_preferences.

The infer flag controls how much structure HydraDB extracts on your behalf - see How infer works.

3. When to use it

Use memories when responses need to adapt to a specific user over time:

Capture stated or implied preferences (“prefers concise answers”).
Store past conversations the agent should reference later.
Record decisions, outcomes, or feedback tied to a user.
Build up a behavioral profile that compounds across sessions.

Use Knowledge ingestion instead when the content is shared across users - product docs, policy PDFs, internal wikis, Slack threads.

If the content is…	Store it as…
About a specific user or session	Memory
Shared across all users in your tenant	Knowledge

4. Types of memories

A memory item should typically provide either text or user_assistant_pairs, not both.

Raw text

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

Markdown

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

User–assistant pairs

Best for capturing implicit signals from dialogue.

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

5. How it works

`infer`: extract preferences for me, or store what I give you

The infer flag is the most important decision when writing a memory. It controls how much work your application has to do before sending content to HydraDB. infer: true - HydraDB extracts the preference for you. You hand HydraDB raw signal - interaction logs, dialogue, behavior, observations - and HydraDB infers the underlying preference, trait, or fact. Concretely: ship the events that imply a preference, and HydraDB derives the preference. For example, dump a stream of UI interaction logs showing that a user switched to dark mode on Day 1, kept it on for a month, and toggled it back to light once before reverting. HydraDB infers "user prefers dark mode" and indexes that. Your application never has to write the extraction logic. This is the right mode for:

Dialogue (user_assistant_pairs) where the preference is implicit
Behavior logs and event streams
Feedback (“the last summary was too long”) where the actionable trait isn’t spelled out
Anything where the raw input is messy and the useful trait has to be derived

custom_instructions only takes effect when infer: true. Use it to guide what gets extracted (e.g., "Focus on UI and notification preferences only"). infer: false (default) - HydraDB stores what you give it. You’ve already done the extraction. The text you send is the memory, verbatim. HydraDB stores and indexes it as-is. No inference, no derivation. This is the right mode for:

Facts you’ve already captured ("User's plan tier is Pro")
Pre-structured notes
Anything you want to retrieve exactly as written

The trade-off: infer: false is faster and deterministic; infer: true is more useful when your input is raw and unstructured.

Storage and scoping

Memories live in a separate vector store from Knowledge:

recall_preferences searches Memories (vectorstore_status index 0).
full_recall searches Knowledge (vectorstore_status index 1).

For personalized responses grounded in shared context, call recall_preferences and full_recall in parallel and merge the results before prompting your LLM.

Within a tenant, memories are scoped by sub_tenant_id. For per-user separation (B2C), use the user’s ID as the sub_tenant_id. For shared memory across a workspace, use a stable workspace-level ID. If you omit sub_tenant_id, the memory is written to the tenant’s default sub-tenant. See Multi-tenant support. Ingestion is asynchronous - memories aren’t immediately searchable. Poll /ingestion/verify_processing with the returned source_id until indexing_status is completed.

6. Key parameters

Top-level request body

Field	Type	Required	Description
`memories`	array	Yes	One or more memory items.
`tenant_id`	string	Yes	Your tenant identifier.
`sub_tenant_id`	string	No	Sub-tenant scope. If omitted, HydraDB uses the tenant’s default sub-tenant.
`upsert`	boolean	No	Default `true`. Replaces existing entries with the same `source_id`.

Memory item fields

Field	Type	Description
`source_id`	string	Optional unique ID; auto-generated if omitted. Acts as the upsert key.
`text`	string	Raw text or markdown. Use this or `user_assistant_pairs`.
`user_assistant_pairs`	array of `{ user, assistant }`	Conversation pairs. Use this or `text`.
`is_markdown`	boolean	Treat `text` as markdown. Default `false`.
`infer`	boolean	Run inference. Default `false`. See How it works.
`custom_instructions`	string	Guides inference extraction. Only applies when `infer: true`.
`user_name`	string	The user’s name. Used during inference and personalization workflows. Default `"User"`.
`title`	string	Display title for this memory.
`expiry_time`	integer	TTL in seconds. After expiry, the memory is no longer returned by recall.
`metadata`	object	Tenant-level fields aligned with the tenant metadata schema. Keys defined in `tenant_metadata_schema` with `enable_match: true` are matchable via top-level keys in `metadata_filters` (pre-filtered, fast).
`additional_metadata`	object	Document-level free-form key-value pairs attached to the memory. Matchable at recall by nesting under `additional_metadata` (canonical) or `document_metadata` (legacy alias) inside `metadata_filters`. Applied post-retrieval. See Full recall → Metadata filters.
`relations`	object	Optional relation metadata for linking this memory to other stored context.

N. Forceful relations

Forceful relations let you explicitly link Memory items to each other at ingestion time. When a query matches a memory that has forceful relations declared, HydraDB pulls the linked memories into additional_context alongside the primary results. This is separate from the entity and relationship graph HydraDB builds automatically during ingestion. Graph extraction is derived from content; forceful relations are declared by you. Set the relations field on any item in the memories array:

{
  "relations": {
    "cortex_source_ids": ["memory-id-1", "memory-id-2"]
  }
}

curl -X POST 'https://api.hydradb.com/memories/add_memory' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme_corp",
    "sub_tenant_id": "user_alex",
    "memories": [
      {
        "text": "User prefers concise answers",
        "source_id": "pref-concise",
        "infer": true,
        "relations": { "cortex_source_ids": ["pref-tone", "pref-format"] }
      }
    ]
  }'

await client.upload.addMemory({
  tenant_id: "acme_corp",
  sub_tenant_id: "user_alex",
  memories: [
    {
      text: "User prefers concise answers",
      source_id: "pref-concise",
      infer: true,
      relations: { cortex_source_ids: ["pref-tone", "pref-format"] },
    },
  ],
});

client.upload.add_memory(
    tenant_id="acme_corp",
    sub_tenant_id="user_alex",
    memories=[
        {
            "text": "User prefers concise answers",
            "source_id": "pref-concise",
            "infer": True,
            "relations": {"cortex_source_ids": ["pref-tone", "pref-format"]},
        }
    ],
)

At recall, linked memories are returned in the additional_context field. Set search_forceful_relations: true (the default) on the request to include them.

Memory items only. Forceful relations work within the same store. Pointing a Memory item at a Knowledge source ID (or vice versa) will silently return nothing at recall time.

thinking mode only. Forceful-relation context is fetched only when mode: "thinking" is set on the recall request. In fast mode, search_forceful_relations is ignored even if set to true.

8. Minimal working example

Store a user preference scoped to a specific user.

curl -X POST 'https://api.hydradb.com/memories/add_memory' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme_corp",
    "sub_tenant_id": "user_john_123",
    "upsert": true,
    "memories": [
      {
        "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.upload.addMemory({
  tenant_id: "acme_corp",
  sub_tenant_id: "user_john_123",
  upsert: true,
  memories: [
    {
      text: "Prefers short, direct answers with no preamble.",
      infer: true,
      user_name: "John",
    },
  ],
});

import os
from hydra_db import HydraDB

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

result = client.upload.add_memory(
    tenant_id="acme_corp",
    sub_tenant_id="user_john_123",
    upsert=True,
    memories=[
        {
            "text": "Prefers short, direct answers with no preamble.",
            "infer": True,
            "user_name": "John",
        }
    ],
)

You’ll get back a source_id for each memory and an initial status of queued:

{
  "results": [
    { "source_id": "mem_abc123", "status": "queued", "infer": true }
  ],
  "success_count": 1,
  "failed_count": 0
}

Poll /ingestion/verify_processing with the returned source_id until indexing_status is completed. After that the memory will surface in recall_preferences.

9. Inference in practice

A realistic example. The user has been toggling dark mode in your app. Instead of extracting the preference yourself, ship the raw log:

curl -X POST 'https://api.hydradb.com/memories/add_memory' \
  -H "Authorization: Bearer $HYDRA_DB_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_id": "acme_corp",
    "sub_tenant_id": "user_john_123",
    "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."
      }
    ]
  }'

const result = await client.upload.addMemory({
  tenant_id: "acme_corp",
  sub_tenant_id: "user_john_123",
  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.",
    },
  ],
});

client.upload.add_memory(
    tenant_id="acme_corp",
    sub_tenant_id="user_john_123",
    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.",
        }
    ],
)

When recall_preferences runs with a query like "what UI settings does the user prefer?", HydraDB returns the inferred preference ("prefers dark mode"), not the raw log. Your application never had to write the extraction logic. The same input with infer: false would index the raw text verbatim - useful only if you actually want to retrieve the event log itself.

10. Common mistakes

Mistake	What goes wrong	Fix
Sending `"memory": "..."` (singular, string)	Validation fails	Use `"memories": [ { "text": "..." } ]` - always an array of objects
Omitting `tenant_id`	Request validation error	Required on every call
Omitting `sub_tenant_id` for per-user data	The memory lands in the default sub-tenant and may surface across users	Use the user’s ID as `sub_tenant_id` for B2C separation
Setting `custom_instructions` with `infer: false`	Instructions are ignored	Set `infer: true` if you need them to take effect
Doing extraction yourself before sending raw logs	Wastes effort that `infer: true` already handles	Send the raw signal with `infer: true` and let HydraDB derive the preference
Sending pre-extracted facts with `infer: true`	HydraDB may re-derive and lose the original phrasing	Use `infer: false` for already-structured facts
Treating `user_name` as cosmetic	It feeds inference, so the wrong name biases what HydraDB extracts	Pass the actual user’s name
Storing shared docs as memories	They won’t surface in `full_recall`	Use Knowledge ingestion instead
Expecting immediate searchability	Ingestion is async	Poll `/ingestion/verify_processing` until `completed`
Forgetting `infer` for conversational input	Raw dialogue gets stored without preference extraction	Set `infer: true` explicitly for conversations

Knowledge - shared, tenant-wide document context
Recall - how memories are retrieved at query time
Multi-tenant support - scoping memories per user or workspace
Metadata - designing filterable fields

Get Started

Essentials

Plugins

For Agents

1. What it is

2. What it does

3. When to use it

4. Types of memories

Raw text

Markdown

User–assistant pairs

5. How it works

`infer`: extract preferences for me, or store what I give you

Storage and scoping

6. Key parameters

Top-level request body

Memory item fields

N. Forceful relations

8. Minimal working example

9. Inference in practice

10. Common mistakes

​1. What it is

​2. What it does

​3. When to use it

​4. Types of memories

​Raw text

​Markdown

​User–assistant pairs

​5. How it works

​infer: extract preferences for me, or store what I give you

​Storage and scoping

​6. Key parameters

​Top-level request body

​Memory item fields

​N. Forceful relations

​8. Minimal working example

​9. Inference in practice

​10. Common mistakes

​Related

1. What it is

2. What it does

3. When to use it

4. Types of memories

Raw text

Markdown

User–assistant pairs

5. How it works

`infer`: extract preferences for me, or store what I give you

Storage and scoping

6. Key parameters

Top-level request body

Memory item fields

N. Forceful relations

8. Minimal working example

9. Inference in practice

10. Common mistakes

Related