Obligations
How Hyperstruck remembers what is owed, who owes it, to whom and by when, and puts it in front of your agent at the moment it matters.
In short
An obligation is a commitment somebody made: who owes it, who it is owed to, and usually a due date. Hyperstruck records it from your notes or from your own API call, offers it to the agent when it comes due, and keeps it open until it is closed or it expires.
A meeting note says "Priya will send the revised rate card to Harlow Freight by Friday." The following Thursday an agent prepares the account review for Harlow Freight. A learning cannot hold that sentence, because it is about one company. A claim cannot hold it either, because it is a promise rather than a value. The obligation holds it, and the agent starts Thursday's review knowing a rate card is due tomorrow.
What an obligation is
| Example | |
|---|---|
| The commitment | Send the revised rate card |
| Who owes it | Priya |
| Who it is owed to | Harlow Freight |
| When | By Friday, in the note's own time zone |
| On whose word | Read from a note, not typed by a person |
| Where it came from | The passage of the note that says so |
Each party is either a named person or organization, or a role you choose, such as account_manager. A named party is matched to the same entity your claims use, so an obligation owed to Harlow Freight and a claim about Harlow Freight are about the same thing.
An obligation is one of two kinds. A commitment is owed by one side to another. A meeting is owed jointly by the people attending it.
Where obligations come from
| Source | What you do | Recorded as |
|---|---|---|
| Your notes | Send a note through Distill or the Documents API. Commitments in it are read out, and the passage each came from is kept with it where it can be located. | source_observed |
| Your own call | Record one directly with the parties and the due you state. Nothing is inferred. | user_directed |
A due written as a phrase, "by Friday" or "end of next week", is resolved against the date the note declares for itself. A note that declares no date is resolved against the time it arrived.
An agent's own promises are not recorded by default
An agent that ends a run with "I'll confirm the volumes by Friday" has made a commitment too. Recording those from the final_output you send on observe is off unless it has been switched on for your tenant. When it is on, they are recorded as agent_committed and held for review rather than offered back to the agent.
How an obligation reaches your agent
When the agent resolves. The resolve step of the learning loop returns a third block beside learnings and claims: the few open obligations that bear on this moment. One qualifies because its window has opened (it is overdue, due, or within its lead time), because it involves an entity the goal is about, or because a claim it rested on has since changed. The block carries five by default. An agent with nothing due gets no block at all.
When you ask a question. An answer from the Answer API carries the obligations in its scope, open or closed, in obligations.
When you go looking. The Obligations API lists everything an agent holds, open or closed.
An obligation with a due becomes actionable three days before it, unless you set a different lead. One without a due is held and offered sparingly, since it has no date to rank on.
How an obligation closes
Every obligation ends in one of five states.
| Status | Meaning | Recorded with |
|---|---|---|
kept | It was done. | Who said so: reported, evidenced or declared |
dropped | It will not be done. | A reason: not_an_obligation, no_longer_applies, wont_do or duplicate |
expired | Nobody closed it in time, or it was pushed out to make room for a newer one. | A reason: due_passed, undated_aged, neglect or capacity |
superseded | A changed commitment replaced it. | A link to its successor |
cancelled | The record was a mistake, such as a test write. | Nothing; no judgment is made |
Three things close an obligation:
- Your agent's turn. Report what the turn resolved on reinforce, using the ids resolve offered.
- A person or a system. Close, cancel or supersede one obligation by id.
- Time. An obligation nobody closes expires 14 days after its due, or 90 days after it was recorded when it has no due. One recorded after its due had already passed gets its 14 days from recording. None outlives a year.
What waits on a person
Some open obligations wait on a decision rather than a date. Ask for them with needs_review=true, and each comes back saying why.
| Reason | What happened |
|---|---|
untrusted_provenance | It came from a source marked untrusted. |
premise_retracted | A claim it rested on was retracted or erased. |
later_standing | A later note says it was already done, withdrawn or replaced. |
neglected | It was shown to the agent five times and nobody decided. |
The first two are kept out of what the agent is offered until someone decides. A later note never closes an obligation by itself: it raises the question and leaves the answer to a person.
What an obligation is not
- Not a task tracker. There are no assignees, boards or priorities. It records that something is owed and whether it was kept.
- Not a reminder service. Nothing is sent to anyone. An obligation surfaces when the agent resolves or when you read it.
- Not permanent. Every obligation carries an expiry from the moment it is recorded.
- Not kept past its note. Erasing a document deletes the obligations read only from it. One that also cites another note survives.
Related pages
- Obligations API for every route, field and error
- Answer API for the obligations an answer carries
- Distill documents and the Documents API for sending the notes obligations are read from
- Learning loop for where resolve and reinforce sit
- Memory for the other shelves