Metadata-Version: 2.5
Name: hyperspell-brain
Version: 0.6.1
Summary: hyperbrain — an agent-first CLI for the Hyperspell company brain
Author-email: Hyperspell <hello@hyperspell.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx<1,>=0.27
Requires-Dist: tomli<3,>=2; python_version < '3.11'
Requires-Dist: typer<1,>=0.12
Provides-Extra: mcp
Requires-Dist: hyperspell-mcp<1,>=0.26.0; extra == 'mcp'
Description-Content-Type: text/markdown

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

```bash
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.
> Both `hyperbrain ask` and the MCP `ask` tool default to `medium` for this reason.

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

```bash
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:

```bash
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**.

## Entities

```bash
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

```bash
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:

```bash
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.

Generated-summary tools (`brain_status`, `list_context`, `read_context`,
`grep_context`) and `hyperbrain://context` resources are disabled, including cached
calls. Their implementations and stored files remain intact. MCP instructions no
longer direct agents to read summaries first. This does not change the ordinary CLI,
REST endpoints, or daemon filesystem sync. Local clients need the updated CLI release
(0.5.12 or newer); deploying the hosted server does not update local installations.

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

```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`.
- **Works with an app-scoped API key (device JWT rejected):** `config`,
  `structure`, canonical docs.
- **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.
