Forgetting memories

SurrealDB Agent Memory distinguishes retiring memory (the agent stops using it) from erasing memory (the content is removed for compliance). Most day-to-day use is retirement; erasure is explicit and grant-gated.

All forget operations require the memory:forget grant on the caller’s API key for the relevant scope. Keys with only read/write access cannot forget.

Semantic forget (default - retire, do not erase)

Describe what to remove in natural language. SurrealDB Agent Memory finds matching entities, facts, relations, and conversational chunks by semantic similarity, then expires them. Expired memory:

• •

  Does not appear in /query, /profile, /state, or chat context going forward.

• •

  Does not come back through a point-in-time read. A query anchored at a moment before the forget still excludes it, so forgetting holds across time travel rather than only from now on.

• •

  Does remain in storage so you can audit what was retired and when.

Forgetting is separate from expiry. A fact that simply ended, was superseded by a newer value, or aged out is still part of the record: point-in-time reads continue to serve it, which is what makes supersession history auditable. Only an explicit forget is withheld from those reads.

POST /api/v1/{context_id}/forget
Content-Type: application/json
Authorization: Bearer sk-...

{
  "query": "anything about my old job",
  "dryRun": true
}

{
  "deleted": 3
}

dryRun: true scores matching records and returns the count without writing anything - use this to preview before applying. A successful dry run emits no forget audit event. Omit dryRun or set it to false to expire records.

To apply after preview:

POST /api/v1/{context_id}/forget
Content-Type: application/json
Authorization: Bearer sk-...

{
  "query": "anything about my old job"
}

The response counts how many records were expired. Scope is enforced by the API key’s grants - you cannot forget outside the scopes your key is allowed to write (and forget) within.

agent-memory forget "anything about my old job" \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

# Preview matches without expiring anything
agent-memory forget "anything about my old job" --dry-run \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

Entity delete (default - retire one entity)

To target a specific entity by type and name:

DELETE /api/v1/{context_id}/entities/{entity_type}/{entity_name}

This expires the entity and its active facts and relations. Like semantic forget, it is a soft retirement by default - the entity no longer surfaces in retrieval, but the retired records remain stored.

Purge - permanent erasure (compliance)

When you must guarantee that content no longer exists in the memory substrate - for example a right-to-erasure request - use the same POST /forget endpoint with purge: true, or the CLI --purge flag.

POST /api/v1/{context_id}/forget
Content-Type: application/json
Authorization: Bearer sk-...

{
  "query": "anything about my old job",
  "purge": true
}

With purge: true, SurrealDB Agent Memory permanently removes the matched entities, their fact history (including prior corrections), related relations, and linked conversational chunks. After a successful purge, that content is not recoverable from memory storage.

Audit note: the trace graph may still record that a forget call occurred (who, when, which operation) without retaining the deleted content itself. Plan your compliance story around both memory erasure and trace retention policies.

Purging is opt-in. Omitting purge (or setting it to false) keeps supersession history even after the current values are expired - the default path for ordinary agent memory management.

Scoped forget - erase a whole subtree

To remove everything tagged under a scope path (a user branch, team, or project subtree), use:

POST /api/v1/{context_id}/scopes/forget
Content-Type: application/json
Authorization: Bearer sk-...

{
  "path": "user/alice/"
}

This hard-deletes all memory and knowledge records whose scope touches that subtree - entities, facts, sessions, documents, chunks, and related index state. It requires the memory:forget grant over that subtree. The response reports how many records were erased.

Use scoped forget for GDPR-style deletion when a principal’s entire branch must go, not just a single fact.

Choosing the right operation

After forget - extraction can bring facts back

Forget operates on what is stored now. If a later conversation turn mentions the same information again, extraction may create new memory for it. If you need a topic to stay gone, combine forget with product-level controls (do not re-ingest, block the source, or purge again).

Related reading

• •

  Reconciliation and supersession - why corrections keep history by default

• •

  Tri-temporal model - time-travel and belief history

• •

  Permissions and delegation - memory:forget grants

• •

  REST API