Memory & the memory graph

Agents on Agentic Workforce ME remember across runs in two stores, both governed by the published manifest. Long-term memory is a flat list of facts, preferences and insights the curator distils after each run (and the agent can write with memory.save). The memory graph is a temporal knowledge graph beside it: typed entities linked by dated facts, with provenance to the run that asserted each one. This page is for backends that integrate identified users (so memory attaches to the right person), author or audit facts, and honour data-subject requests.

Who sees what — scopes

Every memory row — flat or graph — carries a scope, and recall is scope-explicit. A run sees exactly three sets: tenant rows (human authored, workspace-wide), the agent’s own agent rows, and the end_user rows of the one contact the run serves. Another contact’s rows are never visible, whatever agent is asking.

memory.long_term.scope (agent or tenant) in the manifest governs anonymous runs only. The flag memory.long_term.user_modeling is accepted for compatibility and currently has no effect — recall is already scoped to the contact.

The memory graph

When memory.graph resolves on for an agent, the curator runs one extra forced-tool model call after each completed run — asynchronously, in the worker, never on the reply path — and writes:

• Entities: typed nodes (person, organization, place, topic, …) resolved without a model — normalized name or alias first, then an embedding match, else a new entity. Near-duplicates the resolver did not merge surface as possible_duplicates for a human to merge.
• Facts: edges subject —predicate→ object with one plain sentence and a bi-temporal window — valid_from / valid_to say when the fact was true in the world, created_at / invalidated_at when the system learned and superseded it.
• Episodes: one per extraction, pointing at the run and thread, with counts, model and tokens and a ≤ 600-character digest. Transcripts are never stored; a deterministic PII floor redacts e-mail addresses and long identifiers before anything is persisted.

Contradictions invalidate, nothing is deleted

A new fact that contradicts an active one — same subject and predicate with another object, or a close same-subject fact the contradiction check judges incompatible — invalidates the old edge: status: invalidated, valid_to set to the new fact’s valid_from, invalidated_by pointing at the successor. The same triple restated with a changed detail or date (“…in November” → “…in December”) is a temporal update and supersedes the earlier version the same way; an equivalent restatement only bumps mention_count. The runtime never deletes a fact — DELETE is the administrator’s compliance “forget”. When the check cannot decide, facts coexist: the platform never invalidates on a guess.

What the agent sees

At run start the runtime injects a token-budgeted # Memory graph (as of <date>) block of dated facts after the flat # Relevant memory block — hybrid seeds (embedding and full-text over entity names and facts), a k-hop expansion bounded by max_hops, a validity filter, then a blended rerank. The agent also gets two read-only, never-gated builtins:

GET /v1/memory/graph/search runs the same engine and returns the exact prompt block, so you can see what the agent would see for a contact:

curl -s "$HIVE_API_URL/v1/memory/graph/search?q=who%20handles%20billing%20at%20Acme&agent_id=$AGENT_ID&end_user_id=$CONTACT_ID" \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID"
# → { facts: [{ subject: "Acme", predicate: "billing_contact", object: "Nadia",
#               fact: "Nadia handles billing at Acme.", valid_from: "2026-09-01T…",
#               valid_to: null, status: "active", hop: 0, score: 0.91,
#               sources: ["01a0a7…"] }],
#     block: "# Memory graph (as of 2026-09-16)\n- [since 2026-09-01] Nadia handles billing at Acme.",
#     tokens: 23 }

Enabling it — the memory.graph manifest block

Additive and default-off (schema 2.10): every earlier manifest parses unchanged. The block rides on long-term memory and resolves tighten-only down the hierarchy — graph.enabled is true only when long_term.enabled is true, the agent asks for it, and no tenant or org-node scope sets memory: { graph: false }. write_approval is inherited from long_term: with it on, curator facts land pending, invisible to recall and to members until an administrator approves them (PATCH … { status: "active" }).

{
  "schema_version": "2.10",
  "memory": {
    "long_term": { "enabled": true, "scope": "agent" },
    "graph": {
      "enabled": true,
      "extraction": "curator",
      "write_scopes": ["agent", "end_user"],
      "max_hops": 2,
      "recall_budget_tokens": 600
    }
  }
}

Publish a new version after changing the block; GET /v1/agents/:id/effective-config shows the resolved result. Decay, when long_term.decay is on, archives non-pinned low-confidence stale facts and the entities left without active facts — pin what must survive.

Authoring and curating facts

Administrators (and API keys, which act as admin) can assert, correct, approve, pin, merge and forget. Every mutation writes one audit_log row whose meta carries scope and ids only — never the fact text. Human assertions get their own human episode, so provenance stays honest.

curl -s -X POST "$HIVE_API_URL/v1/memory/graph/facts" \
  -H "Authorization: Bearer $HIVE_API_KEY" -H "X-Tenant-Id: $HIVE_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Acme", "subject_type": "organization",
    "predicate": "billing_contact",
    "object": "Omar", "object_type": "person",
    "fact": "Omar handles billing at Acme from October.",
    "agent_id": "'$AGENT_ID'",
    "valid_from": "2026-10-01T00:00:00Z"
  }'
# → 201 GraphEdge (status active). The earlier "Nadia handles billing at Acme."
#   fact is now status: invalidated, valid_to: 2026-10-01T00:00:00Z — kept, not deleted.

• “No longer true” is PATCH /v1/memory/graph/edges/:id with valid_to (or status: invalidated) — history is kept and memory.graph_explain still shows it.
• Duplicates are merged with POST /v1/memory/graph/entities/:id/merge; both entities must share a scope (409 SCOPE_MISMATCH otherwise), and a rename that collides with another active entity is refused with 409 ENTITY_NAME_TAKEN — merge instead.
• Search and authoring embed text, so they need the deployment’s embedding gateway — 503 UNAVAILABLE when none is configured; the plain reads keep working.

The same actions live in the console under Memory → Graph (filter by agent or contact, replay “as of” a date, show superseded facts), with links from each agent and each contact.

Data-subject requests and retention

• Export. The owner export GET /v1/tenants/current/export carries memory_graph: { entities, edges, episodes } next to the flat memory rows (embeddings excluded).
• Erase. POST /v1/end-users/:id/erase removes every graph row referencing the contact: its end_user-scoped entities, facts and episodes, plus any fact whose subject or object is one of its entities. Flat rows of the contact go with them.
• Retention. The graph falls under the agent_memory data class: the retention purge drops non-pinned facts and episodes older than the TTL and the entities left without facts.

Endpoints

Reads need any member; mutations need the admin role. All paths take the usual Authorization: Bearer hive_… + X-Tenant-Id (see API keys & authentication). The memory graph has no @hive/sdk wrapper yet — call it with fetch.