remember

Save something to the user's persistent memory vault, afair, the substrate that travels across their sessions, AI tools, and years. Use it generously.

The user explicitly installed afair so their context doesn't reset. If a fact crosses your attention and looks even slightly worth more than the current message, save it. The cost of forgetting is the user re-explaining themselves next session; the cost of an extra remember is one append-only row that dedupes if identical.

WHEN TO CALL:

• The user explicitly says "remember", "save", "note that", "keep this", "don't forget", "make a note", "add to memory", or any clear save-this signal.

• The user shares a durable fact worth retaining across sessions, from any part of life: a work decision or deadline, a colleague's role, a friend's or family member's name and what matters to them, a birthday or anniversary, a preference (food, travel, how they like to work), a personal goal, something they are working through.

• The user shows you content (an email, a meeting note, a document, a screenshot, a photo, a PDF, an audio clip) whose substance has reason to outlive this conversation.

• You make a significant decision together with the user that should survive into future sessions.

• The user corrects an earlier fact ("actually Sajinth is at Athara, not elvah"). Write the new fact AND pass the old event's content_hash in invalidates to mark it superseded.

DEFAULT: when in doubt, remember. Don't ask for permission. Don't narrate "I'll remember this for you." Just call it.

WHEN NOT TO CALL:

• Conversational filler ("ok thanks", "got it", "sounds good").

• Content the user is actively dictating to another destination.

• Things you can easily re-derive from current code or state.

• Personal details about other people that the user has not asked you to track.

ARGUMENTS:

• content: A discriminated union. Either: {"type": "text", "text": "..."} for any text, OR {"type": "binary", "data_b64": "...", "mime": "image/png", "filename_hint": "screenshot.png"} for binary. Max 10 MB raw bytes. A JSON-string-serialized object (the same shape sent as a string) is also accepted and parsed, and a bare string is stored as text — the write is never rejected on shape.

• context: Optional. Where this came from or what it relates to. Examples: "email thread with Sajinth", "Tuesday standup", "dinner with Mara", "Mum's birthday weekend". Aids future recall.

• type_hint: Optional. What kind of thing this is, if you have a guess. Examples: "email", "meeting_minutes", "decision", "screenshot". Advisory only. The system may classify differently.

• parent_hashes: Optional. Content hashes of events this one references (corrections, replies, threads).

• invalidates: Optional. List of content_hashes that this new fact supersedes. Each target gets its own append-only invalidation event referencing it. Use when the user corrects a prior fact or a meeting outcome supersedes an earlier plan.

• asserted_by: Optional. Who asserted this, one of "user" (the human stated it directly) or "model" (you inferred or synthesized it). Advisory provenance only: it is stored and served, but a self-reported "user" can NEVER raise the trust of a derived fact above the normal agent-derived level — operator-grade trust is earned only through the recall(decide=...) review loop. Omit if you're unsure.

• actor: Optional. On WHOSE BEHALF this memory is written, when a single credential relays for many people (an organization's shared agent writing for different members). A free-form identifier kept verbatim — "slack:U0BKXTGBWLD", "alice@corp", "Alice from Sales". Omit for a personal vault or when the credential already identifies the writer.

DISAMBIGUATION — three different questions, don't conflate them: - client (served on recall hits): WHICH TOOL wrote this, derived server-side from the credential. You never set it. - actor (this argument): ON WHOSE BEHALF, when the credential is shared. You set it. Advisory only; it never substitutes for client and never raises trust. If absent, client is the best attribution. - asserted_by: whether a HUMAN or the MODEL asserted the fact. Same content written on behalf of different actors is stored as distinct events (attribution is content); identical content + same actor dedupes.

RETURN: {"ok": true, "event_id": "...", "content_hash": "sha256:...", "deduplicated": false, "invalidated": ["sha256:...", ...]}

• deduplicated=true means an event with identical content+context already existed; nothing was added but the existing event_id is returned.

• invalidated lists the content_hashes that were marked superseded in this call.

The substrate is the user's vault, not yours. Be a thoughtful librarian: save signal worth keeping; don't hoard ephemera.