hyperbrain — agent-first CLI for the Hyperspell company brain

Hyperspell is the brain for your business — the memory layer that unifies everything your company knows. hyperbrain is the command line into it: one verb that humans and agents use to query, write, and synthesize that memory. Structured JSON by default, pipe-friendly, no interactive prompts required.

hyperbrain ask "what's our deployment strategy?"      # synthesized answer + sources
hyperbrain search "rds proxy" --source slack -n 5     # ranked documents, no synthesis
echo "remember this" | hyperbrain remember            # write knowledge in
hyperbrain memories status                            # indexing progress per source
hyperbrain schema                                     # dump the command tree as JSON

Websites

Manage indexed public sites with the same identity and API as the dashboard and MCP:

hyperbrain websites list
hyperbrain websites index https://help.example.com/docs --limit 100 --max-depth 3
hyperbrain websites status https://help.example.com/docs
hyperbrain websites pages https://help.example.com/docs
hyperbrain websites refresh https://help.example.com/docs
hyperbrain websites cancel https://help.example.com/docs
hyperbrain websites remove https://help.example.com/docs
hyperbrain websites remove https://help.example.com/docs --confirm
hyperbrain websites schedule set https://help.example.com/docs --frequency weekly --timezone America/Los_Angeles --limit 100 --max-depth 3
hyperbrain websites schedule get https://help.example.com/docs
hyperbrain websites schedule disable https://help.example.com/docs

New crawls are manual by default. refresh uses saved schedule limits unless you override them. A queued response means the crawl was accepted; use status to check completion and partial coverage. Saving a schedule does not crawl immediately. Schedules offer never, daily at 09:00, or weekly on Monday at 09:00 in an IANA timezone; an existing crawl is allowed to finish, overlapping runs are skipped, and disabling a schedule retains indexed pages. The website list supports --query, --cursor, and --limit.

Why this exists

If agents are the primary consumer, why a CLI and not just the API? Because the CLI is the universal adapter. Any agent that can spawn a shell — Claude Code, Cursor, a cron job, an autonomous worker you haven't built yet — can use hyperbrain with zero bespoke integration. No protocol to implement, no server to run, no SDK to vendor. Where MCP says "speak this protocol," hyperbrain says "here's a verb."

And note the framing: this is a brain / memory layer, not retrieval-as-a-service. Anyone can do vector search. The value — and the hard part — is keeping a living, curated, coherent company memory that's current. hyperbrain ask (synthesis) and hyperbrain remember (write-back) point at that; raw search is just the primitive underneath.

How it's used best

The highest-leverage move is to register hyperbrain as a tool your agents can call, and let them decide when to consult company memory. hyperbrain schema exists precisely so an agent can introspect every capability as JSON.

Pick the right verb and effort for the job:

⚠️ ask only synthesizes an answer at -e medium or higher (and needs agentic retrieval enabled for your app). At minimal/low it returns ranked documents with answer: null — effectively a slower search. When the answer is null, the reason is in the response's errors (e.g. "agentic retrieval not enabled … effort downgraded high→low"), and the CLI prints it to stderr. Both hyperbrain ask and the MCP ask tool default to medium for this reason.

Lean into composability — this is where it beats a UI:

hyperbrain ask "what's our deploy process?" -o json | jq -r .answer   # clean text for a prompt
hyperbrain search "rds proxy" --source slack -n 20 | jq '.documents[].title'
hyperbrain schema | jq                                                # discover every capability

Close the loop. A brain only gets smarter if knowledge flows back in. Treat remember as a habit — decisions, postmortems, the "why" behind a choice — so future queries (by humans or agents) surface it:

echo "Decision: standardizing on X because Y" | hyperbrain remember --title "arch decision"

Rule of thumb: scope tight (--source, low effort) for speed and precision; go broad and high-effort only for hard, cross-source questions. The UI shows you the brain — the CLI lets your agents think with it.

Review session sharing

Agents can review pending activity without the dashboard using a personal credential and a server with the sharing API:

hyperbrain memories sharing-requests --query "handoff"
hyperbrain memories get vault RESOURCE_ID
hyperbrain memories decide-sharing vault RESOURCE_ID share --confirm
hyperbrain memories decide-sharing vault OTHER_RESOURCE_ID keep_private --confirm

Read the entries and apply only choices the user authorized. Existing scoped authorization is sufficient; no interactive UI is required. Without --confirm, the CLI previews without making a network request. Listing defaults to activity; --kind all includes other pending requests. has_more means more remain after the listed entries are decided; search can reach older entries.

Decisions use the same ownership and content rules as the Inbox. keep_private dismisses a request; it does not revoke access or reverse a previous decision. personal capture creates no request, and a user-less workspace credential cannot review a person's private queue. These CLI commands require an updated server; the hosted MCP tools are list_sharing_requests and decide_sharing_request. Older local stdio catalogs do not include those hosted additions.

Inspect earlier work

Personal credentials on an updated server can read private checkpoints of captured summaries. Start with the current entry, then retrieve history only when an earlier decision or link matters:

hyperbrain memories history RESOURCE_ID --query "retry"
hyperbrain memories checkpoint CHECKPOINT_ID --offset 0 --limit 12000
hyperbrain memories request-checkpoint-sharing CHECKPOINT_ID
hyperbrain memories request-checkpoint-sharing CHECKPOINT_ID --confirm

Follow next_before_revision and next_offset for more. Search is literal text within one entry. Unlike decide-sharing, the unconfirmed copy command reads the server to preview the selected capture. Confirmation creates a separate Vault copy with a sharing request; approve that copy through the normal sharing commands (sharing-requests --kind all). It does not open the private archive. Later work does not update the copy; repeating a request refuses to overwrite an edited copy.

These are captured summaries, not full conversations or verified source evidence. Company access to the current memory does not grant access to history. Deleting the original entry or erasing its owner/app deletes the private checkpoints; separate copies follow their own normal lifecycle. There is no automatic expiry. Hosted MCP exposes list_activity_history, get_activity_checkpoint, and request_activity_checkpoint_sharing; older local stdio catalogs do not.

Browse entities

hyperbrain entities list --type person -n 25
hyperbrain entities search "ACCOUNT_9001"
hyperbrain entities get <entity-id>
hyperbrain entities mentions <entity-id> -n 25
hyperbrain entities mentions <entity-id> --cursor <next_cursor> -o json

These commands use the current caller's document access. Search matches text in entity names; it does not call the app-wide semantic search endpoint. List and mention responses include next_cursor; repeat the same filters when paging. Mention results distinguish confirmed assignments from soft_candidate name matches. A matching name alone does not establish identity.

Terminal output expands nested results into sections without truncating excerpts or cursors, removes terminal control characters, and prints cursors on a separate line without inserted wrapping. --fields selects top-level response fields in both JSON and terminal output. Use -o json for the complete original API response, including candidate-expansion bounds and provenance. hyperbrain ask "<question>" -e very_high and hyperbrain search "<query>" -e very_high include retrieval provenance by default. When identity lookups suggested possible matches, terminal output shows Entity lookups: each possible match with the reference that was looked up and whether a search was restricted to it. Otherwise it shows the Entities in returned sources. Requested entity filters are counted too. JSON retains the complete provenance, including provenance.entities. Add --provenance at any effort to collect existing model turns and show full terminal evidence (entities are listed at medium effort and above), or --no-provenance to omit it. --answer-only still prints only the answer.

Search steps groups calls by model turn. When the provider returns a readable reasoning summary, the CLI shows it once above that turn's tools and outcomes. Missing summaries and turns without calls are valid. --provenance also shows recorded queries and sources. Older servers keep the flat step display. JSON preserves provenance.turns and, while the server still sends it, the deprecated provenance.steps. Provider summaries describe the model's account of a turn; tool purposes describe planned actions, while status and result count record what happened. Trace collection adds no model calls or thinking at lower efforts. On older servers that return no turn records, the CLI keeps the legacy display without generating a summary.

Auth

Reuses the sync daemon's ~/.hyperspell/config.toml — if you've run hyperspell login or hyperspell install, hyperbrain just works. Otherwise pass --api-key or set HYPERSPELL_API_KEY (a long-lived API key or a device JWT).

Precedence: flags > environment > ~/.hyperspell/config.toml > defaults.

Agent-first contract

• JSON by default to stdout when not a TTY (piped/captured); a human table on a terminal. Force either with -o json / -o table.
• Diagnostics to stderr, so stdout is a clean data channel.
• Stable exit codes: 0 ok, 2 usage, 3 auth, 4 not found, 5 API error.
• No prompts — every input is a flag, argument, or stdin.

Install

uv tool install .          # from a clone; or: uvx --from . hyperbrain ...
# once published: uv tool install hyperspell-brain  /  pipx install hyperspell-brain

The published distribution is hyperspell-brain (the bare hyperbrain name is taken on PyPI by an unrelated project); the installed command is still hyperbrain.

Once installed, upgrade in place with hyperbrain update (a thin wrapper over uv tool upgrade; --check reports whether a newer version exists without installing, --reinstall forces fresh code from a path install). update requires a uv tool install — if you installed via pipx, upgrade with pipx upgrade hyperspell-brain instead (the command says so rather than silently no-op'ing).

Shell completion is a generator, not an installer — print the script and put it where you want:

eval "$(hyperbrain completions zsh)"    # this session
hyperbrain completions zsh >> ~/.zshrc  # persist (bash/zsh/fish supported)

hyperbrain doctor prints resolved endpoint, auth state, version, and config path with no network call — the first thing to run when something's off.

For agents

With the MCP extra installed, list_workstreams lists accessible saved briefings and get_workstream reads one by its returned ID. Follow next_cursor to read longer pages. These tools serve saved pages without generating or refreshing them.

Version 0.5.14 changes Very High ask and search responses: provenance is requested by default in every output mode, including piped JSON. JSON includes the full retrieval trace, failed sources, entity candidates, excerpts, and limitations when supplied by the API. This increases response size; callers that only need the answer or ranked documents can pass --no-provenance. --answer-only, --quiet, and --fields control printed output but do not disable the request; combine them with --no-provenance to omit that work too. The resolver uses evidence already collected during retrieval. Apps without the resolver may perform the existing bounded legacy entity lookup.

• hyperbrain help --agent — the whole CLI surface as one compact, low-token markdown doc (commands + auth tiers + contract + recipes), generated from the live command tree. Read it once to self-orient. Scope it with hyperbrain help --agent <command>.
• --fields a,b,c (global) projects every result to those top-level keys; -q/--quiet (global) suppresses stdout so you can branch on the exit code alone. Both cut token usage.
• hyperbrain schema dumps the full command tree as JSON for programmatic introspection.

MCP server (Claude Desktop)

Hosts that can't run a CLI or read CLAUDE.md — Claude Desktop chief among them — reach the brain over MCP instead. The server is an opt-in extra (it pulls starlette/uvicorn) and runs over stdio. Use ask for cited answers, search for ranked source documents, and get_memory to read a source. list_memories and list_connections inspect indexed and connected sources; remember saves notes.

brain_status is disabled. The old context tree's tools (list_context, read_context, grep_context, the hyperbrain://context resources, and brain generation and config) are gone: the tree is being removed (ENG-4858).

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hyperbrain": {
      "command": "uvx",
      "args": ["--from", "hyperspell-brain[mcp]", "hyperbrain-mcp"],
      "env": { "HYPERSPELL_API_KEY": "hs2-..." }
    }
  }
}

The API key is read from the config env (Desktop users never run hyperspell login). For local dev, point --from at the repo path instead of the published dist.

Capability tiers

• Works with a user API key: ask, search, remember, memories, entities, connections, integrations.
• Needs an admin JWT (not yet wired): people, skills, conflicts, api-keys.
• Web-only, no public API (out of scope): app creation, billing, app settings.

Design notes & honest limitations

A few things to know — and a few things worth fixing:

• ask needs at least one matching document. With zero results, the answer path currently returns a server-side 500 instead of a clean empty answer. In an agent loop this reads as a hard error when it really means "no memories matched."
• Deep effort is gated. medium / high run an agentic loop behind a per-app feature flag. If the flag is off, they silently downgrade to a single query-rewrite — so -e high isn't always doing what it says. Silent downgrade is a trust wart for an agent reasoning about cost vs. quality; it should be loud.
• Curation is the real product. Once agents remember autonomously, brain quality becomes a governance problem — indiscriminate ingestion makes a junk drawer, not a brain. The interesting question isn't "can agents write to it" but "what's true when sources disagree." That's the canonical-docs / conflicts machinery, and it's where the moat actually is.
• hyperbrain and the daemon will likely converge. They share ~/.hyperspell and half a worldview (both even have search). Today they're two tools — passive sync (hyperspell) and active query (hyperbrain) — but one binary doing both is the probable end state.