> ## Documentation Index
> Fetch the complete documentation index at: https://docs.memorycrystal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# crystal_forget

> Archive or permanently delete a memory.

## What it does

Removes a memory from active retrieval either by soft-archiving (default, recoverable) or permanent deletion (irreversible). Soft archive is the safe default; use permanent deletion only when you are certain the memory should be irretrievably destroyed.

## Parameters

| Parameter | Type    | Required | Default | Description                                                                                                |
| --------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------- |
| memoryId  | string  | Yes      | —       | ID of the memory to archive or delete                                                                      |
| permanent | boolean | No       | false   | If true, permanently and irretrievably deletes. If false (default), soft-archives so recovery is possible. |
| reason    | string  | No       | —       | Optional reason for archival/deletion (logged in audit trail)                                              |
| channel   | string  | No       | —       | Optional channel identifier for filtering context                                                          |

## Returns

```json theme={"system"}
{
  "success": true,
  "action": "archived|deleted",
  "archived": true|false
}
```

**Field descriptions:**

* `success` — Whether the operation succeeded
* `action` — The action taken: `"archived"` (soft-delete) or `"deleted"` (permanent)
* `archived` — Whether the memory was archived (true) or permanently deleted (false)

## Examples

### Basic usage

```javascript theme={"system"}
// Soft-archive a memory (recoverable)
crystal_forget({
  memoryId: "abc123def456"
})

// Result:
// {
//   "success": true,
//   "action": "archived",
//   "archived": true
// }
```

### Advanced usage

```javascript theme={"system"}
// Permanently delete with a reason
crystal_forget({
  memoryId: "xyz789",
  permanent: true,
  reason: "Duplicate of memory xyz790, consolidating"
})

// Soft-archive with audit trail
crystal_forget({
  memoryId: "mem_old",
  permanent: false,
  reason: "Outdated deployment procedure, replaced by new Railway CI",
  channel: "devops"
})
```

## When to use this vs alternatives

* **`crystal_forget`** — When you want to remove a memory from active recall (default soft-archive) or destroy it permanently
* **`crystal_edit`** — When you want to modify a memory instead of removing it
* **`crystal_remember`** — When you want to save a new memory

## Error handling

| Error                    | Cause                                    | Resolution                                       |
| ------------------------ | ---------------------------------------- | ------------------------------------------------ |
| Invalid memoryId         | Missing, empty, or non-existent ID       | Provide a valid memory ID from recall results    |
| permanent is not boolean | Malformed input                          | Use `true` or `false` (omit for default false)   |
| reason is not a string   | Malformed reason                         | Provide a string or omit the field               |
| channel is not a string  | Malformed channel                        | Provide a string or omit the field               |
| Memory not found         | ID does not exist or was already deleted | Verify ID against recent recall results          |
| Authentication failed    | Invalid Convex JWT or API key            | Verify auth configuration in Convex client setup |

## Notes

* **Soft archive (default)**: Memory is marked `archived=true` but retained in the database. Soft-archived memories do not appear in recall results but can be recovered by an admin or via a separate unarchive operation.
* **Permanent deletion**: Memory and all associated metadata are irreversibly removed. This action cannot be undone.
* The `reason` field is optional but recommended for audit trails, especially for permanent deletions.
* The `channel` field provides context but does not filter which memories can be deleted — it's only for logging.
* Archival operations update the memory's `archivedAt` timestamp.
* All deletion/archival operations are transactional.