shadowgraph_record_attempt
Record an attempt and its outcome to prevent blindly retrying the same failed approach, building a searchable history for future decisions.
Instructions
Record one attempt and how it turned out, so the same approach is not blindly retried. Use shadowgraph_record_decision for the choice itself, shadowgraph_record_outcome for how one played out. Appends an attempt and a journal entry; without idempotencyKey a retry records a second one.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| actor | No | Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust. | |
| client | No | Which client software performed this write, such as the host application name. | |
| reason | No | Why it turned out that way. Searchable content. | |
| result | Yes | What happened. Required, non-empty, and searchable content. Wording such as failed, error, or regression is what makes the attempt surface in shadowgraph_context as one to avoid. | |
| project | No | Project namespace. Defaults to "default"; an empty string is rejected. | |
| solution | Yes | What was tried. Required, non-empty, and searchable content. | |
| sessionId | No | Caller-owned identifier that groups related writes in the audit trail. | |
| environment | No | Where it was tried, such as a runtime, OS, or version. Searchable content, so a later attempt can be matched to the same environment. | |
| sourceClass | No | Claimed origin, never proof: agent_claimed (the default), tool_observed, human_confirmed, or production_verified. It weights confidence only. An unrecognised label downgrades to agent_claimed, kept verbatim in sourceRaw. | |
| idempotencyKey | No | Retry key scoped by project and operation: reuse it so a retry returns the first result instead of writing a duplicate. Without it every call creates a new entity. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Stable entity identifier. | |
| kind | Yes | Entity kind: decision, attempt, memory, fact, relation, review, or alternative. | |
| actor | No | Who performed the write. | |
| client | No | Which client performed the write. | |
| reason | No | Why it turned out that way. | |
| result | No | What happened. | |
| project | No | Project namespace; records imported from a schema that predates projects may carry null. | |
| solution | No | What was tried. | |
| createdAt | No | ISO 8601 creation time. | |
| relatedTo | No | Identifiers of related entities. | |
| sessionId | No | Session identifier recorded with the write. | |
| sourceRaw | No | The original origin label when it differed from sourceClass. Audit only; never evidence. | |
| updatedAt | No | ISO 8601 time of the last change. | |
| environment | No | Where it was tried. | |
| sourceClass | No | Claimed origin class recorded with the write. A claim, never proof. | |
| reusableWhen | No | Conditions under which the attempt is worth repeating. | |
| schemaVersion | No | Storage schema version this entity was written under. A value above the build’s own version is preserved rather than downgraded. |