Operator memory tools

Memory is what makes a Hyponema agent feel continuous — it carries facts, preferences, open threads, and emotional context across sessions. As an operator you don’t usually touch it; the agent’s memory-managed tools write to it, and the engine retrieves from it at conversation time.

When you do need to look, you have two surfaces: the dashboard and the memory API.

When to inspect memory

• A user reports a confused agent. Check what memory the agent is loading for that user.
• You’re testing a new persona. Verify it isn’t over-injecting context or carrying stale facts.
• You’re rolling out a new agent in a sensitive domain. Confirm sensitive-topic cooldowns are firing as expected.
• You’re handling a DSAR request. The compliance API gives the user the same shape, with retention rules applied.

What memory tracks

The engine stores per-user, per-tenant:

• Observations and durable facts — preferences, constraints, relationships, support context.
• Corrected facts — supersede chains that record contradictions instead of silently overwriting.
• Open threads — unresolved follow-ups and promises.
• Narrative arcs and emotion — long-running trajectory used to ground tone.
• Session resume snapshots — “where did we leave off?” anchors.
• Sensitive-topic cooldowns — windows after which the agent refrains from re-opening a hard topic unless the user does.

The conceptual model is covered in Memory. This page is about the operator-facing tools.

Dashboard

Open Memory for a workspace-level view: top topics, recent observations, supersede activity, and sensitive-topic cooldowns. Filter by agent or user.

Open Users and pick a user for a per-user view: profile fields, attributes, memory observations, open threads, recent conversations, and any post-session extraction records produced by the agent. From here you can link straight to History filtered for that user.

Memory taxonomy

Each workspace has a taxonomy of topic categories and tags the engine uses to organize observations. Edit it from Memory → Taxonomy when you want to:

• Rename a category for clarity.
• Mark a tag as sensitive so cooldown logic applies.
• Add a vertical-specific tag (e.g. medication names, claim types).

Taxonomy changes apply going forward; existing observations are not re-tagged retroactively.

Profile fields

Profile fields are structured per-agent attributes you decide an agent should always know about a user (e.g. preferred_name, plan_tier, account_owner). They are first-class on the user row and are exposed to prompts through system variables and to tools through input.

Manage profile fields from the agent’s Variables tab (the same surface that handles dynamic variables) and per-user values from the user detail page’s Profile tab. The same shape is available through:

curl "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/profile-fields" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY"

curl -X PATCH "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/agents/$AGENT_ID/users/$USER_ID/profile-values" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "values": { "preferred_name": "Mar" } }'

User attributes

User attributes are looser-typed labels you can attach to a user without committing to a workspace-wide profile field — useful for cohort tagging or temporary flags. Add and remove from the user detail page’s Attributes tab:

curl -X POST "https://api.hyponema.ai/workspaces/$WORKSPACE_ID/users/$USER_ID/attributes" \
  -H "Authorization: Bearer $HYPONEMA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "key": "beta_cohort", "value": "wave_2" }'

Memory API

GET /workspaces/{ws}/users/{user_id}/memory/observations returns durable observations with their supersede chains. Other endpoints under the memory router cover open threads, sensitive cooldowns, narrative arcs, and the resume snapshot.

These endpoints exist primarily to power the dashboard. They are stable enough for operator use, but the canonical place to inspect memory is the dashboard.

What not to do

• Don’t edit memory by hand in production to “fix” bad behavior. Fix the persona or the agent configuration; let memory follow naturally. Manual edits create supersede chains the agent did not author and can confuse it.
• Don’t put PII in dynamic variable names, tool names, or trace tags — those are not designed to carry sensitive content. Profile fields exist for that.
• Don’t rely on memory for hard-state product data (open ticket, plan tier, account balance). Use a tool that calls your real system of record instead.