Forget

Forget removes an entity from active use. It will no longer appear in recall results or be accessible through standard queries. XTDB retains the data in its transaction log — this is a logical delete, not a physical one.

Data Flow

POST /forget {entity_id}
       │
       ▼
┌──────────────────────────────────┐
│   DATABASE (Transaction)         │
│  1. Collect memory IDs           │
│  2. Delete relationships         │
│  3. Delete summaries             │
│  4. Delete memories              │
│  All-or-nothing: COMMIT/ROLLBACK │
└──────────────┬───────────────────┘
               │
       ┌───────┴───────┐
       ▼               ▼
 ForgetResponse   VECTOR STORE
                  (async cleanup)

What Gets Removed

Data	Recovery
memories (all versions)	XTDB history
relationships	XTDB history
memory_closure	Rebuildable
access_counts	XTDB history
summaries	XTDB history
embeddings	Re-embed from history

Deletion Order

Order matters due to foreign key constraints:

1. relationships — references memories
2. memory_closure — references memories
3. memory_access_counts — references memories
4. summaries — references entity_id
5. memories — root table, deleted last

Guarantees

Property	Guarantee
Atomicity	DB deletes are transactional (all-or-nothing)
Idempotency	Forgetting non-existent entity succeeds with 0 counts
Bitemporal	All versions removed from active queries (XTDB history retained)
Consistency	Entity will not appear in future recall results

Edge Cases

Non-existent entity: Returns success with memories_removed: 0. Intentionally idempotent.

Vector store failure: Logged but doesn’t fail the operation. Orphaned embeddings may exist temporarily. DB is the source of truth.

API

curl -X POST https://api.memlayer.dev/api/v1/forget \
  -H "Content-Type: application/json" \
  -d '{"entity_id": "alice-location"}'

Field	Type	Required	Description
entity_id	string	Yes	The entity to forget