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 — 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.

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 (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).
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 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 <agent_user_memory> 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:

{ "key": "preferred_name", "kind": "text" }

A pinned rule plus a structured record list:

[
  { "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 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 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 for authentication and the full tool catalogue.