shadowgraph_remember
Add or reconcile scoped memories by identity tuple, applying ADD, UPDATE, DELETE, or NOOP with full revision history. Solves duplicate and stale memory writes while keeping changes auditable.
Instructions
Add or reconcile one scoped memory, or apply an ADD/UPDATE/DELETE/NOOP plan, by identity tuple. Use shadowgraph_record_decision for a choice, shadowgraph_record_fact for an observation, shadowgraph_recall to read memory back. Identical content is a NOOP, new content supersedes and keeps history, DELETE invalidates; every call commits a revision.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| key | No | Stable caller-chosen name within this scope and type, such as hotel-style. Reusing it reconciles that memory rather than adding a second one. | |
| tags | No | Free-form labels stored with the memory. Part of the compared content, so changing them produces a new version. | |
| text | No | The memory content itself. Stored verbatim, searched as content, and compared to decide ADD, UPDATE, or NOOP. | |
| actor | No | Who performed this write, such as an agent or person name. Stored for audit; never used to grant trust. | |
| scope | No | Scope selector. Omitted or partial fields mean explicit nulls, not "any": identity is the exact (project, userId, agentId, runId, memoryType, key) tuple, so a run-scoped memory never leaks into a user-only read. | |
| client | No | Which client software performed this write, such as the host application name. | |
| project | No | Project namespace. Defaults to "default"; an empty string is rejected. | |
| validTo | No | ISO 8601 instant after which it stops being true, or null for open-ended. Must be later than validFrom. | |
| metadata | No | Caller-owned JSON object kept with the memory. Part of the compared content, so changing it produces a new version. | |
| embedding | No | Caller-supplied vector for this text. Omit to use the configured embedding provider; with no provider the record is still stored and recall reports semantic.available=false instead of renaming lexical overlap as semantic. | |
| sessionId | No | Caller-owned identifier that groups related writes in the audit trail. | |
| validFrom | No | ISO 8601 instant from which this memory is true in the modeled world. Defaults to the write time. Writes for one identity must arrive in non-decreasing validFrom order. | |
| memoryType | No | Which kind of memory this is, and part of its identity. preference and profile are durable user facts, goal a desired state, instruction an operating constraint, procedure reusable steps, episode a recallable event, note general knowledge. | |
| operations | No | A batch plan. Supply this instead of a single memory, typically from an extraction step. Every operation is validated before the first one is applied, so a malformed late operation cannot leave a half-applied batch. | |
| 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. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||