Skip to main content
Delete or soft-delete (archive) a memory document. Soft-deleted memories are hidden from search but remain in the database for recovery.

​
Endpoint

POST /api/memory/forget
Authentication: Required (Bearer token)

​
Request body

​
memory_id
string
required
The unique identifier of the memory to forget
​
hard_delete
boolean
default:false
Whether to permanently delete the memory.
  • false (default): Soft delete - marks as deleted but keeps in database
  • true: Hard delete - permanently removes from database

​
Response

​
success
boolean
Whether the operation succeeded
​
document_id
string
The ID of the forgotten memory
​
hard_deleted
boolean
Whether the memory was permanently deleted

​
Examples

​
Soft delete (default)

curl -X POST https://your-cems-server.com/api/memory/forget \
  -H "Authorization: Bearer $CEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "550e8400-e29b-41d4-a716-446655440000"
  }'
Response: 
{
  "success": true,
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "hard_deleted": false
}
The memory is marked as deleted (is_deleted=true) but remains in the database. It will not appear in search results.

​
Hard delete

curl -X POST https://your-cems-server.com/api/memory/forget \
  -H "Authorization: Bearer $CEMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memory_id": "550e8400-e29b-41d4-a716-446655440000",
    "hard_delete": true
  }'
Response: 
{
  "success": true,
  "document_id": "550e8400-e29b-41d4-a716-446655440000",
  "hard_deleted": true
}
The memory and all its chunks are permanently deleted from the database.

​
Soft delete vs hard delete

Soft delete

  • Sets is_deleted=true flag
  • Keeps data in database
  • Hidden from search
  • Can be recovered
  • Used by scheduled maintenance

Hard delete

  • Removes from database
  • Permanent and irreversible
  • Frees up storage
  • Cannot be recovered
  • Use with caution

​
When to use each

Soft delete (default) is recommended for:
  • Cleaning up outdated or incorrect memories
  • Removing temporary context
  • Letting scheduled maintenance handle final deletion
  • Keeping audit trail
Hard delete is recommended for:
  • Removing sensitive information
  • Freeing up storage immediately
  • Cleaning up test data
  • When you’re certain the memory won’t be needed

​
Scheduled cleanup

The Re-indexing maintenance job runs monthly and:
  1. Hard deletes all soft-deleted memories older than 30 days
  2. Archives stale memories (not accessed in 90 days)
So soft-deleted memories are automatically cleaned up eventually.

​
Error responses

​
error
string
Error message if the request fails
Status codes:
  • 400 - Bad request (missing memory_id)
  • 401 - Unauthorized (invalid or missing API key)
  • 404 - Memory not found or access denied
  • 500 - Internal server error

​
CLI equivalent

# Soft delete
cems delete <memory_id>

# Hard delete
cems delete <memory_id> --hard

Build docs developers (and LLMs) love

Get started for freeTalk to us