pulse
Start an agent session with a scope's checkpoint, pending counts, pins, and next reads. See what to open before acting.
Instructions
Session warm-up: the latest checkpoint, what is pending, and what to read next.
Returns {project, latest_checkpoint, pending, pinned, read_next, scope}.
latest_checkpoint is picked by created_at DESC, never by similarity --
a similarity-ranked top-1 can return a stale checkpoint over a
same-day one, which is exactly the failure mode this avoids. It is
returned in full (that's the point of pulse), with its relations
attached so linked memories are visible without a separate
get_relations call, and carries est_tokens, what this response already
spent on it.
pending is the categories list pending(domain) returns without a
type: a count per category (task, anti_pattern, handoff, note, diagram),
leaving out the empty ones. read_next is the instruction to follow with
it: open tasks first, then pending(domain, type=...) for each other
category, before acting. It is "" when nothing is pending. A pulse lists
no memories besides the checkpoint; pending(domain, type=...) lists
headers and get_memory(uid) opens one.
pinned counts the pins in scope the same way (see pending()); when it
is non-empty read_next asks for them before anything else.
domain warms up a path and everything under it, so pulse('acme/x100')
is the module-wide brief and pulse('acme/x100/p200') the routine's.
A domain that names only the deep end of a path ('p200') is resolved
to the branches it sits in -- scope.paths reports which, and an
ambiguous name resolves to ALL of them.
scope is the rest of the brief: what the scope HOLDS. scope.by_type
counts every memory per type and scope.subdomains says which level it
is sitting in (own = filed there, subtree = with its descendants).
Read them as the drill-down plan: search(query, domain=...) or
list_by_domain(domain, type=..., limit=...) on the child that holds what
you need. A pulse is the state of a scope, never its contents.
scope.stale is the one thing here about DECAY rather than contents:
how many memories in the scope carry a review_after date that has
passed. Present only when non-zero. It means somebody who knew the
subject said when to look again and nobody has -- optimize_scan lists
which ones, with their source_ref.
A scope holds what is CROSS-LISTED into it as well as what is filed
there, so warming up an end-to-end flow brings back the routines that
are steps of it wherever they live. scope.also counts how much of the
brief arrived that way, and a subdomain carries its own also --
present only when non-zero, so a store that never cross-lists never
sees the field.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No |