Metadata-Version: 2.4
Name: hyperspell-brain
Version: 0.4.5
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: hyperspell<1,>=0.36
Requires-Dist: typer<1,>=0.12
Provides-Extra: mcp
Requires-Dist: hyperspell-mcp<1,>=0.1; 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.
> The MCP `ask` tool defaults 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**.

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

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