tracemem/safety-and-failure-modes

Skill: TraceMem Safety and Failure Modes

Purpose

This skill teaches how to handle errors, timeouts, and failures gracefully within the TraceMem ecosystem.

When to Use

• When writing try/catch blocks around your decision logic.
• When handling network errors or policy denials.
• When ensuring your agent is robust.

When NOT to Use

• Do not use these patterns to swallow critical errors silently.

Core Rules

• Fail Closed: If something goes wrong, the default safe state is "stop and close".
• Rollback on Error: If an exception occurs, you MUST catch it and call decision_close(action="rollback").
• Idempotency: Use idempotency keys for writes to safely retry them after network blips.

Correct Usage Pattern

1. Wrapper Pattern:

   decision_id = None
   try:
      # 1. Create
      decision_id = create(...)
      # 2. Work
      do_work(...)
      # 3. Commit
      close(decision_id, "commit")
   except PolicyDenied:
      # 4a. Handle Denial
      close(decision_id, "rollback") # or abort
   except Exception:
      # 4b. Handle Crash
      if decision_id:
         close(decision_id, "rollback")
      raise
   

2. Handling Timeouts (408/504): If a request times out, you don't know if it succeeded.

   • For reads: Safe to retry.
   • For writes: Safe to retry ONLY if you provided an idempotency_key. If not, you must check state or abort.

3. Handling Rate Limits (429): Respect the Retry-After header. Wait and retry.

Common Mistakes

• Zombie Decisions: Crashing without a finally block or error handler that closes the decision.
• ** Infinite Retries**: Retrying a deny result. Policy denials are permanent for that specific context; retrying won't change the policy (unless you change input or get approval).

Safety Notes

• Audit of Failure: TraceMem records "failed" and "aborted" traces too. These are valuable for debugging. Don't be afraid to abort; it's a safety feature.