Supersede

How do I supersede a grain?

Use POST /api/memories/{id}/supersede with the old grain’s blob_hash and updated field values. Areev creates a new grain, marks the old one as superseded, and links them in a version chain.

Supersession is how knowledge evolves in an Areev context database. When a belief changes — “john likes coffee” becomes “john likes tea” — you supersede rather than delete. The old grain stays in storage with a superseded_by pointer to the new grain, creating an auditable history of how AI memory changed over time. Every supersession is logged in the audit trail and can trigger hook events.

The response returns the new grain’s blob_hash, the superseded hash matching the old grain, and a status field. Optional fields like confidence, namespace, and tags carry forward from the old grain unless you explicitly override them.

import areev

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

hits = db.recall(subject="john", relation="likes")
old_hash = hits[0]["hash"]

new_hash = db.supersede(
    old_hash,
    "belief",
    {"subject": "john", "relation": "likes", "object": "tea"}
)
print(f"New hash: {new_hash}")

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

{
  "blob_hash": "a1b2c3d4e5f6...",
  "subject": "john",
  "relation": "likes",
  "object": "tea",
  "confidence": 0.98,
  "tags": ["updated"]
}

areev supersede a1b2c3d4e5f6... belief subject=john relation=likes object="tea"

What happens to the old grain?

The old grain is preserved in storage and excluded from default recall results. It forms a version chain you can traverse to see the full history of changes.

Superseded grains retain their original content, timestamp, and hash. The supersedes metadata field links old to new, creating a directed chain from earliest to latest version. Default recall queries skip superseded grains automatically, so your AI agent memory always returns the most current version. To retrieve a superseded grain, inspect it directly by hash.

This design separates “current truth” from “historical record.” Compliance audits can walk the version chain to demonstrate when and why data changed, while agents and users see only the latest state by default.

hits = db.recall(subject="john", relation="likes")
# Returns only the latest version

old_grain = db.get("a1b2c3d4e5f6...")

GET /api/memories/customer-support/grains/a1b2c3d4e5f6...

areev inspect a1b2c3d4e5f6... --json

When should I supersede vs. forget?

Supersede when knowledge changes and you need the history. Forget when data must be permanently removed, such as for GDPR erasure requests.

Supersession preserves auditability — the old value remains accessible through the version chain, and the audit trail records the change. Forgetting permanently removes grain content from storage with no recovery path. Choose supersede for corrections, preference changes, and evolving facts. Choose forget for regulatory erasure (GDPR Art. 17), user-requested data deletion, and cases where the old data must not exist at all.

How do I view the version history?

Use the HISTORY statement in CAL or inspect individual grains to trace the supersession chain from newest to oldest version.

The history view walks the supersedes chain backward, showing each version with its hash, timestamp, and fields. This is the primary tool for compliance audits where you need to demonstrate when and how data changed within your context database.

areev cal 'HISTORY OF "a1b2c3d4e5f6..."'

POST /api/memories/customer-support/cal
Content-Type: text/cal

HISTORY OF "a1b2c3d4e5f6..."

Related

• Forgetting — permanently removing grains
• Add and Query — adding grains for the first time
• Hooks — react to supersession events with webhooks