# Forgetting memories

How to retire or permanently erase memories - default forget, purge, and scoped erasure.

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** remain in storage so you can audit what was retired and when, or review point-in-time history.

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

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

```json
{
  "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:

```http
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.

```bash
spectron forget "anything about my old job" \
  --url "$SPECTRON_URL" --api-key "$SPECTRON_API_KEY" --context-id "$SPECTRON_CONTEXT_ID"

# Preview matches without expiring anything
spectron 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:

```http
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.

```http
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:

```http
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

| Goal | Operation | Erases from storage? |
| --- | --- | --- |
| Preview what would be retired | **`POST /forget`** with **`dryRun: true`** or **`spectron forget --dry-run`** | No - read-only count |
| Agent should stop mentioning something | **`POST /forget`** (default) or **`DELETE /entities/...`** | No - expired, still auditable |
| User’s erasure request for specific topics | **`POST /forget`** with **`purge: true`** | Yes - matched content removed |
| Delete everything for a user/team scope | **`POST /scopes/forget`** | Yes - entire subtree removed |
| Retire a scope folder in the vocabulary only | **`scope:delete`** (tombstone the scope node) | Tombstone is soft - distinct from erasing facts; see [Contexts and scope](/docs/agent-memory/mental-model/contexts-and-scope.md#tombstone-vs-erase) |

## 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](/docs/agent-memory/reasoning/reconciliation-and-supersession.md) - why corrections keep history by default
- [Tri-temporal model](/docs/agent-memory/architecture/tri-temporal-model.md) - time-travel and belief history
- [Permissions and delegation](/docs/agent-memory/mental-model/contexts-and-scope.md#permissions-and-delegation) - **`memory:forget`** grants
- [REST API](/docs/agent-memory/reference/rest-api.md)