Skip to main content

​
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

ParameterTypeRequiredDefaultDescription
memoryIdstringYes—ID of the memory to archive or delete
permanentbooleanNofalseIf true, permanently and irretrievably deletes. If false (default), soft-archives so recovery is possible.
reasonstringNo—Optional reason for archival/deletion (logged in audit trail)
channelstringNo—Optional channel identifier for filtering context

​
Returns

{
  "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

// Soft-archive a memory (recoverable)
crystal_forget({
  memoryId: "abc123def456"
})

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

​
Advanced usage

// 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

ErrorCauseResolution
Invalid memoryIdMissing, empty, or non-existent IDProvide a valid memory ID from recall results
permanent is not booleanMalformed inputUse true or false (omit for default false)
reason is not a stringMalformed reasonProvide a string or omit the field
channel is not a stringMalformed channelProvide a string or omit the field
Memory not foundID does not exist or was already deletedVerify ID against recent recall results
Authentication failedInvalid Convex JWT or API keyVerify 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.