Hopper
hopperSave any URL into your knowledge base, automatically routing it to the correct ingester: research paper, GitHub repo, Substack post, article, or X thread. Preview first, then confirm.
Instructions
SAVE something into the knowledge base — a link the user wants to KEEP. Hand it any URL and it works out what the thing is and routes it to the right ingester: a research paper, a GitHub repo, a Substack post, a plain article or blog post, or a single X post. This is the ONLY manual "keep this" path; there is no separate save-a-paper or save-a-repo tool.
Reach for this whenever the user says keep / save / add / remember / "put this in OPYT" about a link — including a link YOU just surfaced from a web search. It persists a link into the trusted corpus so the knowledge-base search tool can route to it later.
TWO-PHASE, and the first phase is free or near-free:
• confirm=False (the default) → a PREVIEW. It reports which adapter the reference routes
to, WHY it routed there, the atom id, whether the KB already has it, and what a confirm
would spend. It NEVER writes. It fetches nothing for an article, paper, repo or
Substack post — you can already read those yourself, so describe them to the user in
your own words alongside the routing.
The X exception: for an x.com status link the preview reads the post (~$0.00015)
and returns a description. You cannot fetch x.com, and x:2086520133909168332 is
unverifiable by a human — so read that description back before confirming; it is the
only way the user can catch a wrong link. If unreadable comes back instead, the post
is deleted / protected / keyless: say so and do NOT confirm.
Paywalls are your job, not the preview's. This tool stores PUBLIC content only —
a paywalled Substack post is skipped by the adapter and comes back "failed". It reads
the same cookie-less public endpoint you do, so it cannot see past a wall you hit
either. If the page you read was a subscriber teaser, say so BEFORE confirming instead
of spending a round trip to be told no.
• confirm=True → runs the ingest. This spends: a metered embedding always, plus a content
gate for articles and ~$0.003 for an X post's thread. Show the preview first — a wrong
route is SILENT (a paper filed as a blog post never errors, it just sits wrong).
Skip straight to confirm=True only when the user has already said "yes, save it" about THAT specific link.
already_present: true in a preview means a confirm is a no-op — say so and don't spend.
Repeat calls are idempotent: an unchanged item is never re-fetched or re-embedded.
What it will not do — do not ask it to, and do not work around it:
• It never adds a PERSON to the tracked roster. Saving someone's article does not start
following them. add_oracle is the only way in, and it asks the user first.
• It never writes vault notes. Atoms only.
• It never guesses. A reference that is not a URL comes back unroutable with nothing
written, rather than being filed somewhere plausible.
Every saved atom is stamped entry_mode='user-saved' — the same mark an X bookmark gets,
because both mean the user personally saved it. That is load-bearing downstream: hand-saved
items steer the Frontier's standing research queries.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No | False (default) = preview only, no fetch and no writes; True = run the ingest. | |
| kind_hint | No | OPTIONAL, and only consulted when the URL host matches nothing known — a recognized host always wins, because the host is a fact and your read is not. In practice there is ONE case worth passing it for: pass "substack" when you can see the page is a Substack post on a custom domain (a `/p/{slug}` path, a subscribe widget) rather than a `*.substack.com` URL. Nothing can detect that without fetching, and it matters — routed as a plain article the post gets a different atom id and will never dedupe against the same post saved from a bookmark. The other values ("paper", "github", "x") cannot override anything: those adapters check the host themselves and refuse a URL that is not theirs. | |
| reference | Yes | the URL to save — an article, paper (arXiv / DOI / .pdf), GitHub repo, Substack post, or x.com status link. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||