How Insights work
How an insight asks several agents, turns their records into ranked findings, and keeps the feed honest as you act and as the facts change.
In short
You name an objective and the agents that hold the relevant records. A run asks each of those agents, in parallel, through the same claims search, learnings and obligations you already use. Findings that cannot cite a fact about their subject are dropped. What remains is ranked, with a reason to act now.
This page is the mechanics. For the recruiting and support stories, see Examples. To create one, see Get started.
From a standing question to a finding
An insight is not a chat. It is a saved objective, a small set of agents (up to eight), and a choice of how runs start: When I click Run in the dashboard, or From the API so your own systems can trigger it.
On each run Hyperstruck does four things, in plain language:
- Turns the objective into questions. Each agent is a specialist, so it is asked factual questions it can answer from its own records: who, what, when, how many, what is due. Not opinions.
- Asks those agents together. They are consulted in parallel. Each one is asked the way you would ask it: a claims search for the facts, a search of its learnings for the playbook that fits, and a look at what is still owed.
- Keeps only what it can cite. A finding must rest on a claim or an obligation from this run that names its subject. A playbook on its own is not enough. Invented names do not survive.
- Writes the feed. Each kept finding has a priority, a "why now", a recommended action, optional draft, and the evidence underneath.
For example, Candidate rediscovery is a recruiting insight. For each live role it looks for people in the network who fit what the client has said since the brief, including people who earlier said they would consider this kind of role. One run asked the client-desk and conversations agents and wrote a single finding: Amelia Chen, for Juniper Labs' Founding CTO role. Replay walks that same run again without spending anything.
That is how agents "talk" for an insight. They do not hand each other private notes. Each answers from its own records. Hyperstruck reads those answers together against the objective you saved.
The output: ranked priorities and why act now
What a run writes is the feed. It is titled What is worth doing now. Open findings from every insight you can read sit on one list, highest priority first, then newest.
Each finding is that output, read top to bottom:
Why now
The dates and duties that make waiting expensive. A third outage this month and a credit callback already due. A new country manager who has not briefed an agency, with profiles owed this week. A notice deadline inside the next two weeks.
Recommended
The check or the call to make next.
Evidence
The claims, learnings and obligations underneath. Every line is one of those. If Hyperstruck cannot cite a fact about that person or company, the card is not on the feed.
| Signal | What the finding uses it for |
|---|---|
| A new claim since the last run | Something changed; this run should notice |
| An open obligation with a due date | Someone already promised; the trigger has often already happened |
| A learning that fits | The playbook for this situation (call first, route through the relationship owner, tell customers about maintenance ahead of time) |
| Earlier claims as background | Context, not a reason to nag again |
A later run of the same insight does not repeat a finding whose subject is still open. Mark it actioned or dismissed, and only a new fact about that subject can bring it back. That is how the feed stays short.
One finding, opened. The three parts above are already on the card, so the picture does not need restating. Where a line of evidence is still waiting on a decision, the draft stays held.
Acting on findings
On an open finding you have two moves:
| Action | When to use it | What happens next |
|---|---|---|
| Mark actioned | You made the call, sent the note, or did the work | The finding moves to Actioned. The next run will not raise the same facts again |
| Dismiss | It is not worth acting on | The finding moves to Dismissed. The same evidence stays off the feed |
Dismiss means "nothing here is worth doing", not "never mention this subject again". A later, different fact about the same customer can still surface. There is no permanent mute.
Drafts are for you to send from your own tools. Hyperstruck does not send the message. A draft that includes a link, or asks for payment details or a password, is withheld; the finding itself still stands, so you are not blocked from acting.
Tabs on the feed: Open, Actioned, Dismissed, and Replaced (a newer finding took over because the evidence under the old one had changed).
On your timing
An insight runs with the tools you already use, on the timing you already have. A scheduled agent, a cron job, or a click on Run now. Hyperstruck does not add a clock of its own.
| How a run starts | Where |
|---|---|
| Run now | Dashboard, on the insight under Insights, then Rules, or on its detail page |
run_insight | The MCP tool, from a scheduled agent or any other connected host |
POST /insights/{id}/runs | Your own integration: a cron job, a morning job, a webhook after ingest |
On the insight form, Run is either When I click Run or From the API. A disabled insight can still be run from the dashboard; an API key will not start it.
Each run prefers claims recorded since that agent's last successful look, and treats older claims as background. The standing question stays the same; the feed moves because the world did.
Only one run of an insight can be in progress at a time. Run now is disabled until it finishes.
Security: who can see an insight
An insight is not a side door around access control. You can only pick agents you can read. The picker lists no others, and every run checks again.
An insight is visible to you only if you can read every agent it names. Lose access to one of them and that insight, its runs and its findings disappear from your feed, rather than showing a partial answer. History is gated the same way: a finding is shown only if you can still read the agents its evidence came from.
Creating and editing need write access. Starting a run needs execute access (agents:execute), because a run is real work against your spend limit. Reading the feed needs read access to those agents plus claims:read, because findings quote claim text.
The creator of an insight, or someone who can manage all of its agents, can change or delete it. Deleting an insight removes its runs and findings, not the agents. Deleting an agent removes the insights history that consulted it, because those findings mixed its answers with the others.
See Access control for scopes and roles.
How it gets sharper
Three things compound, and they are the same records the rest of Hyperstruck already keeps:
- Better claims. A corrected plan, a new ticket, a restated conversation (Amelia Chen will consider a founding role now; seven months ago she would not) changes what the next run can cite.
- Better learnings. "Route every approach through the consultant who owns the relationship" steers every recruiting insight without anyone pasting it into the objective. Learnings earn that place through the learning loop, not by being typed into the insight.
- Your feedback on the feed. Actioned and dismissed findings stop the same evidence from coming back. New evidence is still allowed through. Refine on the insight form sharpens a vague objective and warns when the agents you picked probably cannot answer it, before you spend a run.
Leave the agents fallow and the insight has nothing to say. Keep sending documents and reporting finished work, and the feed reads like a briefing, not a search result.