Engagement Resolution

When Engrammic detects decision points requiring your attention, it surfaces them through the engagement system. This guide covers how to recognize and resolve these markers.

What is Engagement?

Engagement is Engrammic's way of surfacing pending decisions that require your input:

• ProposedBelief: SAGE synthesized a belief from your knowledge. The system handles acceptance or rejection internally based on validation rules.
• Contradiction: Two claims in your knowledge base conflict. You need to resolve which is correct.
• StaleCommitment: A commitment you made is outdated by new evidence. You need to update or dismiss it.

Soft vs Hard Mode

Soft Mode

When engagement.mode == "soft":

• Recall results are still returned normally
• Markers are surfaced for your awareness
• You can resolve them when convenient

{
  "results": [...],  // Normal results
  "engagement": {
    "mode": "soft",
    "markers": [...]
  }
}

Hard Mode

When engagement.mode == "hard":

• Recall results are withheld (empty array)
• You must resolve at least one marker before continuing
• Triggered after 3+ unresolved touches

{
  "results": [],  // Empty - resolution required
  "engagement": {
    "mode": "hard",
    "markers": [...],
    "message": "Resolution required before recall results are available."
  }
}

Resolving Markers

ProposedBelief

SAGE synthesized a belief from corroborating claims. ProposedBelief acceptance and rejection are handled internally by the system. You do not call any verb to accept or reject these. If the system surfaces a ProposedBelief marker in hard mode, resolve a Contradiction or StaleCommitment marker first to unblock recall.

Contradiction

Two claims conflict. Resolve by stating the correct position:

// 1. State the correct belief with supersedes
believe(
  conclusion="<correct claim>",
  about=["<relevant_node_ids>"],
  supersedes="<incorrect_node_id>"
)

// 2. Dismiss the marker
dismiss(marker_id="<marker_id>", reason="Resolved via supersession")

StaleCommitment

A commitment is outdated. Update your position:

// 1. Form updated belief with supersedes
believe(
  conclusion="<updated commitment>",
  about=["<relevant_node_ids>"],
  supersedes="<stale_node_id>"
)

// 2. Dismiss the stale marker
dismiss(marker_id="<marker_id>", reason="Commitment updated")

MCP Tools

dismiss

Acknowledge a Contradiction or StaleCommitment marker after resolution:

dismiss(marker_id: str, reason: str)

Use dismiss only for Contradiction and StaleCommitment markers. ProposedBelief markers are resolved by the system, not by agent verbs.

tick

Lightweight engagement check without full recall:

tick(about_hint?: list[str])

Returns engagement state only. Use this to proactively check for markers if you've gone many turns without calling recall.

Troubleshooting

Stuck in Hard Mode

If recall keeps returning empty results:

1. Check engagement.markers for pending decisions
2. Resolve at least one Contradiction or StaleCommitment marker using the steps above
3. Retry recall. Results should now be available.

Common Errors

"Marker not found"

The marker_id is invalid or already resolved. Call tick to get current markers.

Best Practices

1. Check engagement field after every recall
2. Resolve soft markers promptly to avoid hard mode escalation
3. Use tick proactively if going many turns without recall
4. Provide clear reasons when dismissing markers