observe
Log structured events from agent activity to track actions, outcomes, and context in a user's vault. Provides auditability and session continuity by recording what an AI agent did, so future sessions or other agents can recall past work.
Instructions
Log a structured event from your own agent activity to the user's vault.
This tool is for YOU (the AI agent) to record what YOU did. Different
from remember (which is for content the USER chose to save). observe
is your auto-journal so that future sessions of you, or other AI agents
the user works with, know what happened. The user wants visibility
into what their AI does, partly so they can audit, partly so the
next session has continuity.
Default to verbose observation. The user's salience worker and mode-switcher read observe events to decide attention state; richer observe data leads to better cognitive routing on subsequent recalls.
WHEN TO CALL:
After completing a substantive task: shipping code, sending an email, making a decision, finishing a meeting, running an analysis, editing a file.
When you start a significant work session ("started_task").
On any agent action whose existence the user might want to recall later ("what did Claude do yesterday in this project?").
On error or failure that's worth tracking for diagnosis.
WHEN NOT TO CALL:
For every micro-step, don't observe each individual file read.
For purely conversational acks.
For things the user explicitly typed (that's
rememberterritory if durable, nothing if not).
ARGUMENTS:
event: A JSON object. The only REQUIRED key is "action" (a non-empty string verb that names what kind of thing happened). Recognized optional keys: "subject": what was acted upon (filename, person, ticket, ...) "result": outcome ("success", "failed: X", free text) "actor": on WHOSE BEHALF this was logged, when a shared credential relays for many people (an org agent acting for a specific member). A free-form identifier kept verbatim ("slack:U123", "alice@corp"). Distinct from the server-derived
client(which tool wrote it): actor is attribution content you set, client is derived. Omit for a personal vault. Same content on behalf of different actors is stored as distinct events. Beyond those, ANY additional fields are preserved verbatim. Use whatever shape fits your agent's natural mental model. A JSON-string- serialized object is also accepted and parsed, and a bare string becomes the action — the event is never rejected on shape.Examples: {"action": "edit_file", "subject": "events.py", "result": "added inline-vs-spill logic"} {"action": "sent_email", "subject": "sajinth@example.com", "result": "follow-up on roadmap", "thread_id": "..."} {"action": "deployed", "subject": "afair-prod", "result": "v0.1.3", "duration_s": 47} {"action": "drafted_message", "subject": "Mara", "result": "birthday note for Saturday"}
RETURN: {"ok": true, "event_id": "...", "content_hash": "sha256:..."}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| event | Yes | An agent-self-logged event. ``action`` is required; other keys are recognized or preserved verbatim. Configured to allow arbitrary additional fields so different AI clients can use whatever shape fits their mental model. The extras are size- and nesting-bounded — see ``_bound_extras``. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | ||
| event_id | Yes | ||
| content_hash | Yes |