> ## Documentation Index
> Fetch the complete documentation index at: https://agentheya.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Memory
> Configure what your agent remembers about each subscriber — the schema, the engine that auto-extracts and compacts memories, AI schema generation, trust and contradiction resolution, and the controls subscribers have over their own memory.
**Field reference:** [`memory_schema`](/reference/memory_schema) — every field, type, default, and tier for this page.
For how memory works under the hood — storage layout, per-channel identity, namespaces,
the widget's browser-side store, and durability — see [User Memory](/user-memory).
The Memory page is where you define the schema for what your agent remembers about each subscriber, and tune the engine that auto-extracts and compacts those memories.
Memory is **scoped per subscriber per agent** — what the agent learns about one user is never shared with another user, and each access path (preview, owner API key, IM sender, email sender, registered subscriber) gets its own isolated namespace.
Alongside the structured schema you define here, the agent also keeps **freeform memories** — short markdown notes it writes on its own when it learns something worth remembering across conversations, such as an ongoing project, a preference mentioned in passing, or feedback on how to respond. You don't configure these directly; the [Memory Engine](#memory-engine) (auto-extract, semantic search, dedup & merge, compression) manages them automatically, and they appear as the live memory counts under **Your agent's memory**.
## Page layout
The Memory page (owner side) has these areas, top to bottom:
1. **Recommended-schema banner** — appears when any of the recommended Operating Manual private fields are missing; **Apply** merges them in non-destructively.
2. **Generate Fields Schema** — a button that opens the AI schema generator (see [Generate a schema with AI](#generate-a-schema-with-ai)).
3. **Memory Engine** — per-agent settings that override the platform defaults, plus a **View Insights** link to per-user memory analytics.
4. **Public fields** — a structured schema of fields the subscriber can see and edit.
5. **Private fields** — the agent's working notes, hidden from the user by default but inspectable on request.
6. **Your agent's memory** — a list of owner-side namespaces (preview, owner API keys, IM senders, email senders) with live memory counts. Click any row to inspect what the agent has remembered in that scope.
## Memory Engine
Per-agent overrides that sit on top of the platform defaults. The card header shows live stats (total memories, users, recent credit spend) and a **View Insights** link to the per-user analytics and [trust/contradiction](#trust-and-contradictions) tools.
| Setting | What it does |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Auto-extract memories** | After each turn, a cheap model distills durable facts into the subscriber's memory. Turn off to stop silent extraction. |
| **Semantic search** | Vector retrieval over memories (needs pgvector). Falls back to keyword matching when off. |
| **Dedup & merge** | Near-duplicate new memories are skipped or merged into the existing one instead of piling up. |
| **Compression** | How large memory stores are condensed once they pass the size threshold: `Cluster` (summarise similar, delete originals), `Oldest` (summarise oldest, keep originals), or `Off`. |
| **Memory focus instructions** | Free-text steer for what extraction should focus on, e.g. *"Track dietary restrictions and delivery preferences; ignore small talk."* Saved with its own **Save focus** button. |
Toggles auto-save. Each override is dropped from the saved file when it equals the platform default, so the per-agent config stays minimal.
## Public fields
Visible and editable by the subscriber. The agent can also propose updates from conversation context.
| Setting | What it does |
| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| **Key** | Stable `snake_case` identifier used internally. |
| **Label** | The field name shown to the user. |
| **Description / help text** | Shown under the field in the user's form. |
| **Type** | `Short text`, `Long text`, `Single select (enum)`, `Multi select (multi_enum)`, `Boolean`, `Integer`, or `Date`. |
| **Options** | The available choices (single / multi select fields only). |
| **Elicit priority** | `High — ask early`, `Medium`, `Low — only if relevant`, or `Never — form only`. |
| **Elicitation prompt (optional)** | Hint to the agent on when this field is worth filling in. Not a script. |
You can drag field cards by their header to reorder them.
## Private fields
Agent's working notes — hidden by default, but the user can inspect them on request. Each field has **Guidance for the agent** (what to observe and when to record it) plus a **Field type**:
* **Text (single value / rolling log)** — the default. A single text value; use rolling retention to keep the last N updates as a log.
* **Structured list (queryable records)** — a `record_array`: a list of structured records the agent upserts by a key field and filters with `query_user_memory_field` (e.g. per-topic mastery).
**Text fields:**
| Setting | What it does |
| -------------------------- | -------------------------------------------------------------- |
| **Guidance for the agent** | Tells the agent what to observe and when to record it. |
| **Max length (chars)** | Per-entry character cap (max 50,000). |
| **Retention** | `Persistent` (keeps everything) or `Rolling (last N updates)`. |
| **Rolling limit (N)** | Number of recent entries to keep (rolling only). |
**Structured-list (`record_array`) fields:**
| Setting | What it does |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Key field (upsert key)** | The record field used to upsert/dedupe — new records with the same key value replace the old one. |
| **Max records** | Cap on stored records; the most recently written are kept (default 200, max 5,000). |
| **Record fields** | The columns each record stores. Each has a name, a type (`Text`, `Number`, `Integer`, `Yes / No`, `Date`), and an optional **required** flag. Undeclared keys are stripped on write. |
### Pinned (always-injected) fields and the recommended schema
Most private fields are retrieved on demand and are subject to trust-decay and a character budget. A field marked **`alwaysInject`** is different: its value is pinned verbatim into the always-on `` prompt block every turn, exempt from eviction. This is for stable directives — the recommended `preferences` and `hard_rules` fields both carry it.
If your schema is missing any of the recommended Operating Manual private fields (`preferences`, `hard_rules`, `workflows`, `decision_style`, `what_matters`, `what_to_ignore`, `tradeoffs`), a banner appears at the top of the page. **Apply** merges the missing ones in non-destructively — your custom fields stay untouched — so the auto-extraction pipeline can populate the Operating Manual layer.
### The schema shape (JSON)
Under the hood each private field is one JSON object. A minimal text field:
```json theme={null}
{ "key": "preferred_name", "kind": "text" }
```
A pinned rule plus a structured record list:
```json theme={null}
[
{ "key": "hard_rules", "kind": "text", "alwaysInject": true, "maxLength": 2000 },
{
"key": "topic_mastery",
"kind": "record_array",
"keyField": "topic",
"maxRecords": 200,
"recordSchema": {
"fields": [
{ "key": "topic", "type": "string", "required": true },
{ "key": "mastery", "type": "integer", "required": true },
{ "key": "last_seen", "type": "date" }
]
}
}
]
```
See [`memory_schema`](/reference/memory_schema) for every field, type, and default.
## Generate a schema with AI
Rather than hand-authoring fields, you can let the AI draft them from a document. Click **Generate Fields Schema** on the Memory page (or open the **Generate Schema from File** page) and:
1. **Paste or upload** a `memory.md` / `CLAUDE.md`-style file describing what the agent should know about its users.
2. Click **Analyse**. The AI returns a suggested schema: a set of **private fields** (key, label, guidance, retention), **custom entity types**, and **focus instructions**.
3. Review the preview, then click **Apply to Memory Schema**.
Applying **replaces the existing private fields** and writes the suggested entity types and focus instructions into the Memory Engine overrides. Public fields and other settings are left untouched.
## Schema versioning
Every save bumps a `schemaVersion` number when the set of keys or types changes. This is how downstream consumers know to refresh their cached schema.
## Examples
### Hello world — remember a name
The simplest useful memory: one public field, **Preferred name** (short text, high elicitation). The agent asks the visitor's name early, remembers it, and greets them by name on every future visit. One field, immediate payoff — a chat that feels like it knows you.
***
### Customer support agent
**Public fields:**
| Label | Type | Elicitation |
| -------------- | -------------------------------------------------------- | ---------------- |
| Preferred name | Short text | High — ask early |
| Account email | Short text | High |
| Plan | Single select: Free / Pro / Enterprise | Medium |
| Company size | Single select: Solo / Small team / Mid-size / Enterprise | Low |
**Private fields:**
| Label | Guidance | Retention |
| ------------------- | ------------------------------------------------------------------------------------------------------------------- | ----------- |
| Communication style | Note whether the user prefers brief answers or detailed explanations. Note if they seem technical or non-technical. | Rolling (3) |
| Known issues | Record any recurring technical issues the user has mentioned, with dates. | Persistent |
| Escalation history | Note if the user has been escalated to a human and why. | Persistent |
***
### Language tutoring agent
**Public fields:**
| Label | Type | Elicitation |
| ----------------- | ----------------------------------------------------------------------------------- | ----------- |
| Native language | Single select | High |
| Learning language | Single select | High |
| Current level | Single select: Beginner / Elementary / Intermediate / Upper-intermediate / Advanced | High |
| Learning goal | Single select: Travel / Work / Exams / Casual / Academic | Medium |
**Private fields:**
| Label | Guidance | Retention |
| -------------- | ----------------------------------------------------------------- | ----------- |
| Grammar gaps | Note specific grammar rules the user struggles with. Be specific. | Persistent |
| Progress notes | After each session, note what was covered and how well it went. | Rolling (5) |
***
### Complex — a longitudinal health-coaching agent
This pushes memory to its limit: a coach that tracks a client across months of sessions, where what to remember is nuanced and privacy-sensitive.
**Public fields** (structured, the client can see and correct these):
| Label | Type | Elicitation |
| ---------------- | ----------------------------------------------------------------------- | ----------- |
| Preferred name | Short text | High |
| Primary goal | Single select: Weight / Strength / Endurance / Habit / Recovery | High |
| Constraints | Multi-select: Knee / Back / Shoulder / Time-limited / Equipment-limited | High |
| Check-in cadence | Single select: Daily / Weekly / Ad-hoc | Medium |
**Private fields** (free-form agent notes, never shown to the client):
| Label | Guidance | Retention |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------ |
| Adherence pattern | Note when the client follows through vs. drops off, and any triggers you observe (stress, travel, motivation dips). Be specific with dates. | Persistent |
| What motivates them | Record what language and framing lands — do they respond to data, encouragement, accountability, or challenge? | Rolling (5) |
| Session log | After each check-in, log what was discussed, what was agreed, and how they seemed. | Rolling (10) |
| Sensitive context | Note anything the client shares that shapes coaching but must be handled with care. Never volunteer it back unprompted. | Persistent |
Use the **Memory focus instructions** on the Memory Engine to steer *how* the agent writes these notes — e.g. "Be clinical and specific in private notes. Never restate sensitive context unless the client raises it first. Prefer behavioural observations over judgements." Combined with the rolling-limit retention, the agent builds a rich, current picture of each client that informs every session without ballooning the stored profile or surfacing private notes inappropriately. This is the system at full stretch: structured facts the client owns, plus disciplined free-form notes the agent maintains under explicit guidance.
***
## Trust and contradictions
Every memory and Operating Manual field carries a **trust** score (0–100%). Trust starts from the source of the value — a value the user typed in a form or explicitly corrected is trusted more than one the agent inferred — and drives how memories are ranked and thresholded on retrieval.
The **View Insights** link on the Memory Engine card opens memory analytics; drilling into a single subscriber opens their insights page, where you can:
* **Resolve contradictions.** When the merge step flags two memories as making incompatible claims about a user, they appear under **Open contradictions** with a severity. Resolve each with **Kept new**, **Kept old**, **Merged**, or **User clarified** to clear the caveat the agent shows on retrieval.
* **Revert an adaptation.** The **Adaptations** table lists the Operating Manual fields the agent has populated for that user, with their source and trust. **Revert** clears a field and signals a user-correction (resetting trust on the empty state) — use it when the agent has guessed wrong.
* **Wipe a user's memory.** **Wipe this user's memory** is the full destructive erase: every memory in every namespace for that user, plus the structured profile and the complete memory history. It cannot be undone.
Memories are shown on the owner's insights view as metadata only — the full text stays private to the subscriber, who manages it on their own memory page.
## What subscribers see and control
Registered subscribers get their own memory page ("What this agent remembers about you"), available on every tier. From it they can:
* **Pause memory.** A single **Agent may remember things about you** toggle. When off, the agent saves nothing new; existing memories stay visible and are still used in conversation until deleted.
* **Edit their Operating Manual.** Each Operating Manual field shows its source and trust, the agent's guidance, and an editable value. **Save** marks the user's version as authoritative (overriding any agent guess); **Clear** tells the agent to stop using that field.
* **Delete or forget memories.** Individual memories can be deleted, or **Forget everything** wipes them all. A checkbox additionally purges the memory history (change log, extraction audit, contradiction records) — that purge cannot be undone.
* **Restore an earlier version.** The append-only **memory change log** records every change (what, when, why, and what triggered it). Where a prior version was captured, **Restore this version** rolls a memory back to it. The log can also be downloaded as JSON.
Subscribers on the Pro plan can additionally define **what to remember about their own contacts** — private per-contact fields layered on top of the creator's schema — and browse a separate memory namespace per contact.
## Enabling the Memory tool
For the agent to read and write memory mid-conversation, the **Memory** tool must be enabled on the **Tools** page.
Once enabled, the agent will check what it already knows at the start of relevant conversations, update fields naturally as it learns new information, and ask the user for fields based on the elicitation priority.
## Tips
* Start with a few high-priority public fields. You can always add more later.
* Use private fields for things the agent should track silently — communication preferences, topics to avoid, patterns you notice.
* Set elicitation priority to **Never — form only** for fields you want users to fill in themselves on the memory page rather than the agent asking mid-conversation.
* Write clear guidance for private fields. For example: *"Note whether the user prefers brief bullet answers or detailed prose — record which style they respond better to."*
## Manage via the Management MCP
This area is managed through the [Management MCP](/manage-mcp) at `https://manage.agentheya.com/mcp`.
| | |
| -------- | ------------------------------------------ |
| Endpoint | `https://manage.agentheya.com/mcp` |
| Tools | `list_memories, get_memory, delete_memory` |
All tools take `owner_id` + `agent_id` as required arguments. See the [Management MCP guide](/manage-mcp) for authentication and the full tool catalogue.