Skip to main content

​
Overview

Delete an observation by ID. Supports both soft delete (default, marks as deleted but keeps data) and hard delete (permanent removal).
This tool is part of the admin profile and uses deferred loading. It’s primarily for manual curation, TUI operations, and data cleanup — not typical agent workflows.

​
Parameters

​
id
number
required
Observation ID to deleteGet the ID from:Example: 42
​
hard_delete
boolean
If true, permanently deletes the observationDefault: false (soft delete)
  • Soft delete: Sets deleted_at timestamp, observation remains in database but excluded from search/context
  • Hard delete: Permanently removes the row from the database

​
Response

​
result
string
Confirmation message indicating deletion mode
Soft delete: 
Memory #42 soft-deleted
Hard delete: 
Memory #42 permanently deleted

​
Usage Examples

​
Soft Delete (Default)

{
  "id": 42
}
Marks observation #42 as deleted. The data remains in the database but is excluded from:
  • mem_search results
  • mem_context results
  • mem_timeline results
  • TUI views (unless “show deleted” is enabled)
Soft deletes are reversible — you can manually update deleted_at to NULL in the database to restore.

​
Hard Delete

{
  "id": 42,
  "hard_delete": true
}
Permanently removes observation #42 from the database. This is irreversible.
Hard deletes are permanent. Use soft delete unless you’re certain the data should be gone forever.

​
When to Use

Use soft delete when:
  • Removing test data
  • Hiding observations without losing history
  • Cleaning up noise from search results
  • Temporarily excluding data (reversible)
Advantages:
  • Reversible — can restore by clearing deleted_at
  • Maintains audit trail
  • Safer for accidental deletions
Use hard delete when:
  • Removing sensitive data that must be purged
  • Database cleanup to reduce size
  • Permanently removing incorrect data
  • GDPR or data retention compliance
Advantages:
  • Actually removes data from disk
  • Reduces database size
  • Ensures data is gone
Disadvantages:
  • Irreversible
  • No audit trail

​
What Happens on Delete

​
Soft Delete

  1. Sets deleted_at timestamp to current time
  2. Observation remains in observations table
  3. Excluded from:
    • Search queries (WHERE deleted_at IS NULL)
    • Context queries
    • Timeline results
    • Default TUI views
  4. Can be shown with “show deleted” filter in TUI
  5. Database size unchanged

​
Hard Delete

  1. Row is permanently removed via DELETE FROM observations WHERE id = ?
  2. FTS5 index entry is removed
  3. No way to restore
  4. Database size reduced (after VACUUM)

​
Validation

If the observation ID doesn’t exist, you’ll get an error:
Failed to delete memory: observation not found
Use mem_search to find the correct ID.
Soft-deleting an already soft-deleted observation succeeds (updates deleted_at timestamp).
Hard-deleting a non-existent observation fails with “observation not found”.

​
Bulk Deletion

For bulk deletion (not available via MCP), use the CLI or HTTP API: 
# Soft delete all observations from a project
sqlite3 ~/.engram/engram.db "UPDATE observations SET deleted_at = datetime('now') WHERE project = 'old-project'"

# Hard delete all soft-deleted observations
sqlite3 ~/.engram/engram.db "DELETE FROM observations WHERE deleted_at IS NOT NULL"

​
Restoring Soft-Deleted Observations

Soft-deleted observations can be restored manually: 
-- Restore observation #42
UPDATE observations SET deleted_at = NULL WHERE id = 42;

-- Restore all soft-deleted observations from a project
UPDATE observations SET deleted_at = NULL WHERE project = 'my-api' AND deleted_at IS NOT NULL;
There’s no MCP tool for restoring deleted observations — use the SQLite CLI or a database browser.

​
Privacy Considerations

Soft deletes keep data on disk. For sensitive information (API keys, credentials, personal data), use hard delete or manually purge from the database.
For GDPR compliance or data purging:
  1. Hard delete the observation
  2. Run VACUUM on the database to reclaim space: 
    sqlite3 ~/.engram/engram.db "VACUUM"

​
Database Size Management

After hard deletes, reclaim disk space: 
# Check database size
ls -lh ~/.engram/engram.db

# Reclaim space after hard deletes
sqlite3 ~/.engram/engram.db "VACUUM"
VACUUM rebuilds the database file, removing unused space. Run it periodically after bulk hard deletes.

Build docs developers (and LLMs) love

Get started for freeTalk to us