Events

Events are Portuni’s memory. They’re how agents (and people) capture what happened, when, and on which node – so that the next session doesn’t start from scratch.

What’s worth logging

Events capture knowledge that matters across sessions:

• Decisions – “Decided to use Turso instead of Postgres”
• Discoveries – “Found that admin access is always the bottleneck”
• Blockers – “Waiting for the client to provide access credentials”
• References – “Relevant doc: https://…”
• Milestones – “Phase 1 migration complete”
• Changes – “Switched from SSE to Streamable HTTP”
• Notes – general knowledge worth keeping

Not worth logging: routine actions that’ll be obvious from the code itself – renamed a file, ran tests, installed a package. Events are for things a future reader genuinely needs to know.

How events evolve

An event goes through up to four states over its life:

active --> resolved     (blocker fixed, question answered)
active --> superseded   (replaced by a newer version)
active --> archived     (no longer relevant)

Resolving. Use portuni_resolve when a blocker’s cleared or a question is answered. The resolution is merged into the event’s metadata so the history stays in one place.

Superseding. Use portuni_supersede when a decision changes or the information’s been updated. The old event becomes superseded and a new event takes its place, linked back to the original.

Editing. Use portuni_update_event for corrections of form that history does not need to keep: a typo, a shorter wording, a wrong date or type. The event keeps its ID, so references to it still hold. It also changes status directly, for example to archive an event or restore one superseded by mistake.

How events show up in context

Events appear in tool responses with detail that scales inversely with distance from where you’re looking:

Depth	What you see
0	Full events – up to 50, all fields
1	Recent events – up to 5, summary fields
2+	No events

Recent events surface through portuni_get_node and portuni_get_context whenever the agent reads a node, so the latest activity is one tool call away – no separate session-start preamble.

Note that portuni_get_context surfaces active events only – resolved, superseded, and archived events don’t appear in context walks. That’s the point of the lifecycle: resolving a blocker takes it out of every future session’s view. Use portuni_list_events with filters to dig into the full history.

Tools

Tool	What it does
portuni_log	Record an event on a node
portuni_resolve	Mark an event as resolved
portuni_supersede	Replace one with an updated version
portuni_update_event	Edit one in place (content, type, date, meta, refs, status)
portuni_list_events	Query events with filters