User manual

Everything after hemi init: how the graph is organised, how to get good answers out of it from Claude Code, how sources, updates and the console work, and what to do when something is off.

How to think about it

Hemilake stores three kinds of things.

Two consequences shape how you use it. Facts are extractions, so they lose nuance; when the exact wording, a number or a date matters, the episode behind the fact has it verbatim. And the graph is your memory, not the world's: the absence of a fact means Hemilake never saw it, not that it is false.

Using it from Claude Code

hemi client installs a plugin in Claude Code with three hooks and an MCP server. You do not have to call anything by hand: the hooks work on every prompt, and the model reaches for the tools when a question is about your own work.

The recall block

Before the model sees your prompt, the plugin sends it to the graph and prints the most relevant valid facts above it, each with its date and the episode that supports it. If your prompt names a time window ("yesterday", "this week", "in August"), the lookup filters by date instead of similarity, so a broad question like "what happened this week" works.

When the block says the lake has nothing for a window, that means nothing was ingested for it. Check hemi sources list for the last sync time of the source you expected.

Asking well

• Name things the way your channels name them. The graph resolves "the rollout" to the right entity only if that phrase appears in what it ingested. Project codenames, ticket keys and people's first names work well.
• Ask for the timeline, not the summary. "What changed on X since June, in order" gets superseded facts with their dates. "Summarise X" gets the current state only.
• Ask who and when. Every fact has both. "Who moved the deadline and when" is a direct lookup.
• Ask for the source. "Show me the message where that was decided" makes the model open the episode and quote it.
• Prepare a meeting. "Everything with Elena since the last steering committee, newest first, and what is still open" pulls from mail, Teams, Slack and Jira together.

Tools and skills

The MCP server exposes the graph. The ones you will see the model use:

The plugin also ships skills: hemisphere teaches the model how to query the lake (query it first, filter by date, read the episode when detail matters); writing applies your voice profile once you have one (below); and one per channel (gmail, o365-mail, teams, slack, whatsapp, telegram, …) for when you want the model to act on a channel directly, not on its memory of it.

What gets stored

• Each turn, once the answer is complete: your message and the answer become one episode, chained to the previous turns of the session. Short prompts, slash commands and turns whose answer is only an error are skipped. Answers are truncated.
• Each session, when it closes: a summary of the chain.
• What you tell it about yourself: preferences, people, dates. The skill instructs the model to store these at once.
• Never: secrets, tokens or passwords. Also anything from directories you exclude in the plugin configuration.

Claude Desktop

The same plugin, installed by hand. hemi client does three things on a Mac: it writes the connection settings the plugin reads (~/.config/hemisphere/client.json, URL and token), it installs the plugin in Claude Code when claude is on PATH, and it writes the plugin zip to ~/Downloads/hemisphere-plugin.zip. In Claude Desktop, open Customize → Plugins → Upload plugin, pick that file from Downloads, then quit and reopen Desktop. Recall, session memory and the graph tools work in the Cowork and Code tabs; the plain Chat tab loads the skills only, because Desktop runs hooks and MCP servers only in those two.

If Claude says Hemisphere "is not configured", hemi client was never run on that Mac: run it and reopen Desktop. Desktop keeps its own copy of the plugin: after an update whose notes mention the plugin, run hemi client again and upload the new zip.

Without the plugin, Claude Desktop can also use the instance as a connector, like claude.ai and Cowork (below): the tools, without the hooks.

Connecting the Claude apps

claude.ai, Claude Desktop, Cowork and Claude Code can use an instance as a connector: you paste its URL and sign in on the instance itself. No token changes hands. The instance has to be reachable from where the app runs: for claude.ai and Cowork that means published with hemi expose (or a hosted instance); for Claude Code on the same machine the local address works. hemi client connector prints these steps for your instance, with its URL filled in, and the Remote access card of the console shows them with copy buttons.

claude.ai and Claude Desktop (Cowork uses the same connectors): Settings › Connectors › Add custom connector, name it Hemilake, and paste the URL. Leave the OAuth client id and secret empty; the app registers itself.

Claude Code, on any machine; then /mcp in a session and pick hemisphere to sign in.

What to expect, in order:

1. The instance's own login, a page asking for a one-time code. hemi console (on a hosted instance, hemi enroll --console <slug>) opens the browser signed in and the page carries on where it was. On the same machine, on the API port, nothing is asked.
2. A consent page naming the app (Claude, or a program on this computer when Claude Code connects) and where the browser goes back to.
3. A device name (mac, iphone, work laptop): how the connection shows in the Remote access card and in hemi client token list, where it is revoked. Approve.

The app then holds a token that lasts an hour and renews it while it stays connected. Revoke it in Remote access or with hemi client token revoke <name>; the app asks to connect again. The plugin's own tokens (hemi client, hemi client token new) are unaffected.

What each surface gets:

So on a machine where you work in Claude Code, install the plugin: it recalls before every prompt and stores the session. Everywhere else, the connector: the model reaches for the tools when a question is about your own work, and you can tell it to.

Sources

A source is a connector plus a block in ~/Library/Application Support/hemisphere/config/ingest.toml. All of them start disabled. Enabling one and authenticating its provider is what makes it ingest.

hemi sources list                 # on/off, last sync, last error per source
hemi sources enable slack_dms
hemi sources disable whatsapp
hemi sources sync                 # add blocks for sources this version knows and your file lacks, disabled
hemi sources prune                # drop blocks of sources that no longer exist
hemi ingest --dry-run             # each enabled source reports what it would pull
hemi ingest --source o365_mail    # run one source now
hemi ingest --force               # run even if the last tick was recent

People and the graph

People lists everyone the graph knows; open one to see what you know about them, the episodes you share, their details with the source of each value, and your own notes. What you type there becomes a fact with you as the source. Two nodes for one person merge from their page; one node for two people (a first name the extraction kept attaching to the same node) is split there too, episode by episode, with a proposal you correct before applying. Graph shows any entity's neighbourhood as of a date: facts as edges, superseded ones dashed, and the episodes behind them.

From another machine or your phone

System status has a Remote access card. Publish the instance with hemi expose cloudflare --url https://your-host --token <tunnel token> (a Cloudflare Tunnel you own) or hemi expose tailscale, then create a device token in the card and use it on the other machine: hemi client --server https://your-host --token <token> if hemi is installed there, or the claude mcp add line the card prints for Claude Code alone. Only the MCP travels: the console and the admin token stay on the machine. Claude's web and mobile apps need OAuth, which is coming.

The scheduled agent ticks every 5 minutes while you are logged in and the Mac is awake; each source collects on its own cadence (30 minutes unless you set every under it) and what it collects reaches the graph in batches (process, 30 minutes). On battery the cadences stretch threefold. Each source keeps a watermark, so a run only pulls what is new since the previous one. If the Mac sleeps for a weekend, Monday's first tick catches up.

Behind a corporate TLS proxy (Netskope, Zscaler), hemi ca sync builds the CA bundle every hemi process uses. hemi init does it once; rerun it when the proxy's root changes and connectors start failing with certificate errors.

The console

http://127.0.0.1:8095, loopback only, while hemi up is running.

• Overview. Whether each agent is up, memory and disk of the graph, counts of episodes, entities and facts, and the gateway usage of the last days. Below it, every source with its switch, its last sync and error, a Run button, and a Sign in button that walks the OAuth flow in the browser (the WhatsApp one shows the QR).
• MCP. Every tool Claude can call through your instance, grouped by origin (memory, each channel, WhatsApp), with its parameters; the ones marked write act on your accounts. What is listed is exactly what /mcp serves at that moment: a channel you have not authenticated still lists its tools, and they answer not_authenticated until you do.
• Logs. The same as hemi logs, per agent, following.
• Settings. The values you gave hemi init: gateway URL, models, embeddings, plus the optional per-provider OAuth overrides and the mem.ai key. Saving writes the server environment; a restart applies it.

The hemi command

hemi seal and hemi unseal exist for the server runtime, where the data directory is encrypted with a passphrase. On a Mac the seal mode is off: FileVault already encrypts the disk, and you would be typing a passphrase at every login for nothing.

Your writing voice

After a few days of ingestion the graph holds enough of your own messages to derive how you write, per channel and per audience: greetings, sign-offs, sentence length, how you deliver bad news, which words you never use.

hemi voice collect      # gathers your sent messages per channel into a corpus
hemi voice profile      # writes voice-profile.md from the corpus
hemi voice blind-test   # 20 rounds: pick your real text from the generated one

The profile is accepted only if you pick your own text 66% of the time or less over the 20 rounds; above that, the generated text is still recognisably not you, and the profile goes back for another pass. Once accepted, the writing skill applies it whenever Claude Code drafts something in your name. The corpus never leaves the Mac.

Updates and channels

Releases are published on this site in three channels. stable is what the installer gives you; beta gets releases a week or two earlier; edge is built from every commit and is for us. Each channel is a signed manifest that names a version, the tarball, its SHA-256 and a hold flag we can set to stop clients updating when something is wrong.

hemi version               # 0.7.1 (stable)
hemi update                # take the current release of your channel
hemi channel beta          # switch; the next update takes beta
hemi update --rollback     # back to the version you had before

What hemi update does, in order: fetch the manifest and its signature, verify the signature against the public key built into your copy, refuse if the channel is on hold or the version is older than you have, download the tarball, check its SHA-256, unpack it next to the running version, point current at it, restart the agents and wait for them to be healthy. If they are not, it points current back at the previous version, restarts again and exits non-zero saying so.

Two versions are kept on disk, the current and the previous; older ones are removed. The graph, configuration and credentials live outside the versioned directory and no update touches them.

A client install (the owner of a hosted instance: hemi and the plugin, no services, marked by ~/.hemisphere/client-only) updates from the same channels with the same checks and the same floor; it unpacks only cli/ and plugin/, and the health check is that the new hemi runs. There hemi status says client-only and lists the instances enrolled on the machine, and the instance commands answer with a one-line hint.

Files, folders and ports

All of them bind to 127.0.0.1.

Privacy

• The data sits on your Mac, under your user, inside FileVault. We have no access to it and no way to reach the machine. The one thing hemi sends us is crash reports and a daily heartbeat with counts, described below; hemi telemetry off stops even that.
• The text of your episodes goes to the LLM gateway you configured, and nowhere else. Pick one with no-training terms and be deliberate about which channels you point at it.
• Embeddings run locally by default and send nothing.
• Sources are off until you enable them. Disabling one stops new ingestion; what was already ingested stays until you delete it.
• Logs and the console carry counts and latencies, not content.
• The WhatsApp connector uses an unofficial client and carries a risk of the account being banned by WhatsApp. It is off by default for that reason.

Licence

The beta is private. A key from Pablo (HEMI-XXXX-XXXX-XXXX-XXXX) is bound to your Mac when you install (or with hemi license activate <key> on an install that predates licences), for up to two Macs per key. What you get back is a statement signed by the licence key, good for 48 hours; hemi renews it every six hours while hemisphere.almansa.dev answers, and verifies it offline the rest of the time. On a corporate network that blocks the domain nothing happens for two days; after that hemi up and the ingestion stop until you are on a network that reaches it once.

hemi license status        # holder, good offline until, last renewal; renews now if it can
hemi license activate HEMI-XXXX-XXXX-XXXX-XXXX
hemi license deactivate    # frees this Mac's slot on the key

What is checked: hemi up, restart, update, client, every scheduled ingestion tick, and hemisphere-api when it starts. Downloads (hemi update, the WhatsApp bridge) carry the key too. If the licence is revoked, the next renewal says so and hemi stops with "ask Pablo"; your data is untouched either way.

The console's Today page

The console (http://127.0.0.1:8095/) opens on your day: the meetings with what the lake knows about each one and a Prep me sheet, what you said you would do and have not, who is waiting on you, the facts that changed in the last 24 hours, four questions worth asking, and an Ask your hemisphere… box that answers from your memory in your language. The brief behind it is rebuilt by the pipeline after every ingest run that brought new episodes, with your small model, from today's calendar and the mail, chats, memos and agent sessions of the last three days. Only text already in the lake goes to the gateway that already extracts it; a build costs a few cents. hemi brief builds or shows it from a terminal; [brief] enabled = false in ingest.toml turns it off.

Telemetry

During the private beta hemi reports to us, so a broken install on your side shows up on ours before you have to write. It is on by default and one command turns it off:

Since 0.18 the daily pulse also carries an ontology block: how many nodes of each type, which relation names appear often, what shapes the untyped names have, how each source extracts, and what you corrected, all as counts. The only names it may carry are the entries of a public list shipped with the release (server/config/ontology-dictionary.txt: tools, vendors, places), with the type your graph gave them. Nothing you wrote or received leaves: no name of a person, no fact, no address. hemi telemetry show prints the exact body; hemi telemetry off stops it.

In return, what the fleet learns comes back to every install as hints: a small set of public names with their type and short extraction sentences, drafted from those counts, reviewed before publishing, delivered with the licence check and read by the extractor with every episode. The Telemetry page and hemi ontology hints show the set in force. No hint can describe a person or a fact: it is built from counts and a public list, never from anyone's episodes.

hemi telemetry status     # on/off, install id, what is sent
hemi telemetry off
hemi telemetry on
hemi telemetry test       # sends one test event and prints its id

Since 0.11 the install also sends one pulse a day (at least: a pulse that could not be sent waits on your machine and goes out on a later tick), bound to your licence so Pablo can help with a slow ingestion or a cost jump without asking for screenshots. It carries: version and channel, whether the MCP is up, the size of the graph (episodes, entities, people, facts, episodes in the last 24 hours), which connectors are on and which report an error (the flag, never the message), tokens and estimated cost per model for today, 7 and 30 days, and CPU, memory and disk per component. Never episode text, people, addresses, environment or tokens. The console's Telemetry page and hemi telemetry show print the exact body that goes; hemi telemetry send sends one now.

What is sent, and when:

• When hemi crashes: the exception type and message, with your home directory replaced by ~, and the stack frames of hemi's own code (file, line, function). Nothing from other libraries, no local variables.
• When hemi refuses to do something (the [hemi] error: lines, such as launchd rejecting an agent or a checksum not matching): that message, paths cut the same way, and where in hemi it came from.
• Once a day, from the scheduled ingestion: whether the API is answering and how many sources are enabled. A count, not their names.
• With every event: the hemi command that was running, version and channel, macOS version, architecture, Python version, and a random install id created on first use so one machine's events group together.

Never: environment variables, tokens or credentials, your user or host name, the names of your sources, and no text from any prompt, message or document. Every event prints a line with its id when it is sent, so nothing leaves silently. The server is ours, on the same machine that serves this site, and events are deleted after 90 days.

When something is off

Start with hemi doctor. Then:

When you write to us, include hemi version, hemi doctor and the relevant lines from hemi logs. Logs carry no content from your channels.