Forgetting

How do I forget a specific grain?

Use POST /api/memories/{id}/forget with the grain’s hash, a batch of hashes, a subject, or a user_id. Forgetting permanently removes grain content from storage.

Manual forgetting is the direct deletion mechanism in the Areev context database. You target grains by blob_hash for surgical removal, by hashes array for batch operations, by subject to erase all grains about an entity, or by user_id to erase all grains created by a specific actor. At least one of these parameters must be provided.

The response returns the number of grains deleted and a status field. Forgotten grains are removed from all indexes (BM25, hexastore, HNSW) and are no longer retrievable by any query. Unlike supersession, forgetting leaves no version chain — the data is gone. Use this for AI agent memory cleanup, stale data removal, and any case where the grain must not exist.

import areev

db = areev.open("./my-data")
db.forget("a1b2c3d4e5f6...")

POST /api/memories/customer-support/forget
Content-Type: application/json

{
  "blob_hash": "a1b2c3d4e5f6..."
}

POST /api/memories/customer-support/forget
Content-Type: application/json

{
  "hashes": ["a1b2c3...", "d4e5f6...", "789abc..."],
  "user_id": "john"
}

areev forget a1b2c3d4e5f6...

How does decay-based forgetting work?

The forgetting engine automatically prunes stale grains based on age, importance, and a configurable decay curve. Grains whose retention score drops below a threshold are forgotten.

Decay-based forgetting models how autonomous memory naturally fades. The engine computes a retention score for each grain using its age and importance, then forgets grains that fall below the configured threshold. Three curve types are available: exponential (default, 2^(-age / half_life) — retention hits 50% at the half-life), linear (1 - (decay_per_day * age) — constant daily decay), and Ebbinghaus (e^(-age / strength) — models encoding strength). High-importance grains decay slower because importance multiplies the effective half-life.

Default parameters are half_life=30 days, threshold=0.3, min_age_days=7, and batch=100. Grains must be older than min_age_days before they become candidates. Run decay manually with areev purge stale or schedule it as a cron job. You can scope decay to a namespace to target specific partitions of your AI memory.

areev purge stale
areev purge stale --half-life 14 --threshold 0.5 --min-age-days 3 --batch 200
areev purge stale --namespace experiments

Which grains are immune to decay?

State grains never decay, and high-importance grains decay at a reduced rate. Importance multiplies the effective half-life, so a grain with importance=1.0 decays at half the rate.

The retention formula applies an importance factor: effective_age = age / (1.0 + importance). A grain with importance=0.5 at 30 days old has an effective age of 20 days, keeping it above the threshold longer. State grains (checkpoints, session state) always return a retention of 1.0 regardless of age — they represent current values rather than historical observations and should persist until explicitly superseded or forgotten.

This tiered decay design lets a context database naturally shed low-value information while preserving high-signal content. Combine it with importance scores on write to control which grains the system retains long-term.

How does crypto-erasure work?

Crypto-erasure destroys the encryption key for a user’s or scope’s data, making all affected grains permanently unreadable. This satisfies GDPR Article 17 right-to-erasure without individually deleting each grain.

When you crypto-erase, the server destroys the key material and the encrypted grain data becomes indecipherable. The grains remain on disk as ciphertext but can never be decrypted. This is faster than individual deletion for large datasets and produces a compliance-grade erasure proof containing count, key_fingerprint, and timestamp.

Crypto-erasure is irreversible. Use it when you need to demonstrate regulatory compliance for data destruction. Scope-level erasure (scope-erase) destroys all grains in a scope path, while user-level erasure targets all grains tied to a specific user_id.

proof = db.forget_user("john")

POST /api/memories/customer-support/scope-erase
Content-Type: application/json

{
  "scope_path": "acme/prod/bot1"
}

areev forget user john
areev forget scope acme/prod/bot1

Related

• Supersede — replace grains without deleting them
• Scopes — scope-level erasure
• Add and Query — storing and retrieving grains