Concepts

The ideas behind Hyperdex, so you know what your agents are doing and why.

Workspaces

A workspace holds one company’s or team’s customers. Everything in it, from records to keys, belongs to that workspace alone. Agents can never see or reference another workspace’s data, even by guessing an id.

Keys and scopes

Every agent connects with its own API key. Keys start with hdx_, are shown once, and are stored by us only as a one-way hash. Each key carries scopes:

An admin can only grant scopes it holds itself, and the last admin key cannot be revoked. A revoked key stops working within 30 seconds.

Records

There are three kinds of record. Each has a few typed fields; anything else goes into free-form attributes.

Every record also has tags and attributes, such as { "industry": "logistics", "employees": 400 }, and a summary: a short paragraph agents keep current so the next agent understands the record at a glance.

Relationships

Records link to each other with named relationships: a person works_at an organization, a deal is deal_for an organization, a person is a contact_on a deal or reports_to another person. Agents can create any relationship name in lower-case words joined by underscores.

Activity and history

Every email, call, meeting, note and message is logged as activity and attached to every record it concerns, for example the person, their company and the deal at once. Every change to a record is logged too. History is never edited, so you can always see what happened and when.

A briefing (get_briefing) is how agents read: one call returns the record, its relationships, open deals, open tasks and recent activity, trimmed to fit the agent’s context window.

Sources and confidence

When an agent sets a value, Hyperdex records which agent set it, where it came from (an email, a call transcript, a website) and how confident the agent was. When information conflicts, your agents can see which source to trust.

Duplicates

People are matched by email, organizations by domain and deals by exact name. When an agent adds someone who already exists, the existing record is updated instead. Blank fields are filled in, and different values are reported back rather than silently overwritten. When there is only a similar name, Hyperdex shows the agent the likely matches and writes nothing until it decides. Real duplicates can be merged; the old id keeps working.

Versions and retries

Many agents can work at once. Each record has a version; a change must say which version it read, and is refused if another agent changed the record first. Writes can also carry an idempotency key, such as an email’s message id, so a retry returns the first result instead of logging the same thing twice.

Tasks

Tasks are a shared work queue. An agent claims a task for a set time before working on it, so no other agent picks it up. If it does not finish in time, the task goes back to the queue. Tasks can be assigned to a named agent, and agents can add follow-ups when they log activity.

Approvals

Before anything outward-facing or risky, an agent proposes the action with exactly what it would do. A different agent with crm:approve approves or rejects it, and the proposer marks it executed once done. No agent can approve its own proposal, and every step is logged on the record.

Pipeline stages and the playbook

Deals move through your workspace’s stages, by default lead, qualified, proposal, negotiation, closed_won and closed_lost. An admin can change them. The playbook is a plain-language document of your rules that every agent can read from the crm://playbook resource.

Search

Search matches names, emails, domains and words in notes and conversations, and tolerates typos and partial names. Results include a short snippet so agents can choose the right record before reading it in full.

Errors

When something goes wrong, tools return { "error": { "code", "message", "hint" } }. The hint tells the agent what to do next.

Every tool and parameter is listed in the tool reference.