Install

The native runtime: no Docker, no server, everything on your own Mac. About 20 minutes, most of it waiting for Homebrew.

What you are installing

A personal knowledge graph fed by your own work channels (mail, calendar, Teams, Slack, Jira, GitHub, voice memos) and read by Claude Code as long-term memory. One instance, yours, on your laptop. Facts carry when they became true and when they stopped being true, so "what did we decide about X" has an answer with a date and a source you can open.

Four launchd agents run while you are logged in: the graph database, the embeddings server, the MCP server and a local web console. Ingestion runs every 30 minutes.

Before you start

• A licence key from Pablo, HEMI-XXXX-XXXX-XXXX-XXXX. The beta is private: the key is what lets you download, install and run it, on up to two Macs.
• An Apple Silicon Mac. Tested on macOS 15.
• Homebrew.
• Claude Code installed and working: claude --version.
• About 10 GB free: the graph, two Python environments and, if you pick local embeddings, a 600 MB model.
• An OpenAI-compatible LLM gateway URL and API key. Extraction calls go there. We give you one if you do not have it.

No GitHub account and no SSH key. Everything is downloaded over HTTPS from this site.

What leaves your machine

Your graph, your data files and your credentials stay on the laptop, under ~/Library/Application Support/hemisphere. Nothing is uploaded to us and we have no access to it.

The text being analysed does go to the LLM gateway you configure in hemi init, because that is what extracts entities and facts. If you choose local embeddings, the embedding step runs on your Mac with Metal and sends nothing.

hemi itself sends us crash reports and a daily pulse with counts (version, whether the agents are up, which connectors are on, graph sizes, tokens and cost per model, CPU and memory), bound to your licence so we can help you; never content, tokens or names. It is on during the beta; hemi telemetry off turns it off. The manual lists exactly what goes.

Install

Put your key in place of the Xs, or leave HEMI_LICENSE= out and the installer asks for it. It activates the key on this Mac first (a signed statement hemi keeps and renews), then downloads the current release, checks its SHA-256, unpacks it into ~/.hemisphere, links hemi into Homebrew's bin (/opt/homebrew/bin, already on your PATH), installs the system dependencies with Homebrew (python 3.12, uv, libomp, ffmpeg, gh, jq, sqlite) and runs hemi bootstrap, which creates the graph database and the two Python environments under ~/Library/Application Support/hemisphere/runtime. Expect a few minutes on a cold Homebrew.

No sudo anywhere on this path, and never with hemi afterwards either: macOS keeps your home directory under sudo, so one root run leaves files in ~/Library/LaunchAgents that the next normal run cannot write. Open a new terminal window afterwards if hemi is not found in the one you used.

You are on the stable channel. To take beta builds instead:

hemi channel beta

Install on Linux

The same channels serve Linux, and no Docker is needed: the installer runs as your user, without sudo, and starts the same pieces as on a Mac as systemd user units (the graph database from an embedded build, llama.cpp for local embeddings, the MCP, the console). You need python 3.11 and curl; uv is installed for you. Code goes under ~/.hemisphere, data under ~/.local/share/hemisphere.

On a machine with an NVIDIA driver the embeddings use the GPU. Ports taken? Set FALKORDB_PORT, EMBEDDINGS_PORT, MCP_SERVER_PORT or HEMI_API_PORT in ~/.config/hemisphere/hemi.env before hemi up.

For a server or a VM that somebody else operates there is a second runtime: Docker Compose as root, with the data directory sealed by gocryptfs and unsealed after each boot. HEMI_RUNTIME=docker HEMI_LICENSE=… sudo -E bash on the same one-liner installs it under /opt/hemisphere with /etc/hemisphere/hemi.env; the manual covers its overlay for taken ports.

Hosted instance owners

If your instance runs on a host we operate (your invitation names it), nothing has to run on your machine but hemi and the plugin. The invitation carries this line; it works on a Mac or on Linux, as your user, and needs only python 3.11 or newer and curl (it says which package to install when python is missing):

It activates the key on this machine, downloads the current release and checks its SHA-256 like the full installer, but unpacks only cli/ and plugin/ into ~/.hemisphere, links hemi and marks the install as client-only. No Homebrew bundle, no graph database, no services. It ends by running hemi enroll with your licence: that creates this device's owner key, verifies the instance's attestation, claims the instance, connects Claude here and opens the console. Under two minutes, and the first run and channels sections below do not apply to you: sources are turned on in the instance's console.

Afterwards hemi status says client-only and shows your instance, hemi update updates the client from the same channel, and hemi client connector prints the steps for claude.ai, Claude Desktop and Cowork. The instance commands (hemi up, hemi ingest, hemi auth...) answer with a one-line hint on a client install. Back up the owner key it printed: nobody can reset it.

First run

hemi init

It asks, in order. Enter accepts the value in brackets.

Then start it and check:

hemi up
hemi status

hemi status should show falkordb, embeddings, mcp and api running. The console is at http://127.0.0.1:8095.

Connect Claude Code

hemi client

It writes the connection settings (URL and token) that the plugin reads, writes the plugin zip for Claude Desktop and prints where it is, and prints the command that installs the plugin in Claude Code.

Claude Desktop: Customize → Plugins → Upload plugin, pick the zip, quit and reopen Desktop. The Cowork and Code tabs get the memory. Claude Code: run the printed command, start claude, and confirm /mcp lists hemisphere as connected. Details in the manual.

Turn on your channels

hemi sources list          # what exists and what is enabled
hemi sources enable o365_mail
hemi sources enable o365_calendar
hemi sources enable teams

Enable the sources you want, then authenticate each provider once:

hemi auth o365       # Microsoft 365: one sign-in covers mail, calendar and Teams
hemi auth google     # Gmail and Google Calendar
hemi auth slack
hemi auth jira
hemi auth github
hemi auth whatsapp   # opt-in, scans a QR from your phone
hemi ingest --dry-run   # each enabled source reports what it would ingest

The same switches are in the console, under Sources. Start with one channel you do not mind sending to the gateway. Add the rest once you have seen a day of results.

Check that it works

Wait for one ingestion tick (30 minutes), or force it with hemi ingest. Then ask Claude Code something about last week. A recall block with facts and dates should appear above the answer.

Day to day

hemi update downloads the release, verifies its signature against the key built into your copy, then restarts the stack. If the new version does not come up healthy it puts the old one back by itself and tells you it did. Your graph and credentials are never touched by an update: they live outside the versioned install directory.

Uninstall

hemi down
rm -rf ~/.hemisphere "$(brew --prefix)/bin/hemi"
rm -rf ~/Library/Application\ Support/hemisphere    # deletes the graph and credentials

What we ask of you

Tell us what breaks, what is slow, and what you expected to find in the graph and did not. Logs and the output of hemi doctor help. This is pilot-quality software: assume rough edges, and do not put anything in it you cannot afford to lose.

The code and the product are confidential while the beta runs. Please do not redistribute the install or the credentials.