hyperspell-brain 0.4.2

hyperbrain — an agent-first CLI for the Hyperspell company brain

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 brain generate                             # (re)build the company-brain tree
hyperbrain memories status                            # indexing progress per source
hyperbrain schema                                     # dump the command tree as JSON

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."

It's best understood as one half of a pair:

• Passive context — the sync daemon writes the synthesized company brain into ~/.hyperspell/ and injects it into every agent's CLAUDE.md / AGENTS.md / .cursorrules. Agents start with company context without asking.
• Active query — when the synced summary isn't enough, the agent calls hyperbrain to go deeper on demand.

Neither alone is the point: the summary is cheap but shallow, hyperbrain ask is deep but costs a round-trip. Together, an agent has a free baseline and an escape hatch.

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 brain generate (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:

Want	Command	Why
A grounded answer	hyperbrain ask "…"	synthesizes + cites; defaults to all connected sources
Raw material for another tool	hyperbrain search "…"	ranked docs, no LLM — the composable primitive
Speed	-e minimal / low	verbatim retrieval, or a single LLM query-rewrite
Genuinely multi-hop questions	-e medium / high	agentic refinement loop (up to 3 / 6 rounds)

⚠️ 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. The MCP ask tool defaults 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.

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 completion zsh)"     # this session
hyperbrain completion 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

• 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. Its tools come in two tiers, mirroring how the product works:

• Local (fast, no API): list_context, read_context, grep_context read the synced ~/.hyperspell summary off disk (also exposed as hyperbrain://context/... resources). Read these first.
• Source (the full index): ask, search, remember, list_memories, list_connections go to the Hyperspell index for source-level detail.

brain_status reports what local context exists and the read-local-first workflow.

Crucially, it teaches the host how to use the brain. Coding agents learn the workflow from the daemon-written CLAUDE.md ("read the synced summary first, then query"); Claude Desktop never sees that file. So the server detects whether the sync daemon's local summary is present and bakes the same ordered methodology into its MCP instructions, pointing at the actual synced index/sections. A brain_status tool reports the live state (and the how-to) so a long session can re-check after the daemon syncs.

~/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, connections, integrations, brain generate/latest/get/progress.
• Needs an admin JWT (not yet wired): people, skills, config, canonical docs, 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.