HiveMind / Project guide

How HiveMind works

You send a message. HiveMind plans the work. Your connected device runs a permitted tool and returns the result.

Version 0.3 · Start with the flow; the code terms come later.

One conversation, work across your devices

The AI can answer directly or start a background task. A task keeps a record of its steps, permissions, results, and progress. You can keep talking while it works.

You senda message Server choosesthe next step Answer in chat Check yoursaved permissions Ask you if needed Your deviceruns the tool AllowedApprovedThe result returns to the same task
The server plans. The device runs ordinary tools. A separate AI on the device is optional.

Your selected model receives the context needed for a call. Hosting HiveMind yourself does not by itself make that model local. You can connect a hosted service or, as host owner, a compatible local model endpoint.

Grant a folder once

Select a shared folder in the desktop app. Then choose an approval level in HiveMind → Devices → Permissions.

LevelMay proceed without another prompt
Ask every timeNothing on a device.
Allow routine readsDevice information, listing the folder, and reading its text files.
Allow reads and new filesThe read actions plus creating new text files in that folder.

Basic file tools never replace or delete existing files. A folder change resets the grant. Removed capabilities stay unavailable even when a broader approval level is selected. Old queued work is checked again before dispatch.

Commands, registered agents, and browser actions always need exact approval. Commands and agents must also be enabled locally. By default, the desktop asks again before running a process. In its Access tab, you can choose to accept those approvals through HiveMind instead. That local choice is tied to the server address.

A folder grant confines the basic file tools. It does not sandbox an arbitrary program. An approved command or custom agent runs with your computer user's access.

Each person has their own profile

The host administrator creates a one-use invitation in Settings. Its recipient creates a username and password, connects their own model, and pairs their own devices. Nobody needs the administrator's password.

Verify the sign-inor device credential Profile AProfile B A's chats, memory and tasksA's model settings and devicesSeparate state directory and database B's chats, memory and tasksB's model settings and devicesSeparate state directory and database
A profile is separate from both its model account and its device pairing. The host administrator still controls the storage.

Members cannot borrow the host's model credentials. API destinations come from the host's allowlist. Password changes invalidate other sessions. The administrator can revoke invitations and disable member accounts without deleting their history.

Know why a task is waiting

A task has one parent ID. Each concrete step has a child ID, action, arguments, approval source, and result. The current planner runs up to eight steps in sequence. Independent tasks can progress at the same time; each device runs one action at a time.

Choose action Check grantor ask you Wait forthe device Run action Successor failure Stop requested Stop confirmedPrior effects remain Outcomeunconfirmed You press StopNo confirmationCheck the device before trying again
Stopping does not undo work. A device can report that an action finished before the stop arrived.
What you seeWhat it means
Your approval is neededReview the exact action in HiveMind.
Confirm on the computerThe desktop requires local confirmation. The dialog expires after 60 seconds.
Waiting for device to reconnectOpen and connect the app; for browser work, keep its popup open.
Choosing the next actionThe model is planning. The model wait, including its queue, has a time limit.
Outcome unconfirmedThe server cannot prove what happened. Inspect before starting a new attempt.

A device's temporary claim lasts 120 seconds and can only be renewed by naming that active task. Stop shortens the remaining time to at most 30 seconds. A local journal prevents repeat execution if a result acknowledgment is lost. Try again creates a new task; it never happens automatically.

Memory is selected, not unlimited

Recent conversation stays in the next model call. Older conversation becomes summaries linked to original messages. When something looks relevant, HiveMind retrieves summaries or source excerpts. A fact becomes a saved note only when you save or accept it.

Current limits

Up to 12 recent messages; a 24,000-character conversation allowance; up to six recalled records and 6,000 characters. Summaries form from batches of 12 messages, then groups of four summaries.

What to improve

Word matching can miss a memory and summaries can lose details. The Memory team can compare retrieval methods and measure what survives. This is a baseline, not an infinite context window.

Deleting a saved note resets older recall and summaries while leaving visible chat. That conservative reset also drops unrelated recalled history. Task records and backups have separate retention behavior.

What devices can do now

ConnectionAvailableLimit
DesktopFolder listing, text reading, new text files; optional commands and registered agents.File tools use a 64 KB text limit. Keep the app running. Commands are broader than folder access.
BrowserOpen a URL; read an explicitly shared tab.Popup stays open. Read up to 16,000 characters; no clicking, typing, cookies or forms.
PhoneChat, approvals, settings and task monitoring in the web app.No native Android/iOS execution harness yet.
CloudAnswers, planning and background writing.No server shell or filesystem tools.

The Windows installer is unsigned. The Mac launcher requires Python with Tk. Signed releases and automatic updates remain work for the Infrastructure team.

Disconnect revokes access and removes the device. If offline, the app stops locally and keeps a pending disconnect to retry. Close only pauses it and preserves pairing. After a completed disconnect, use a new pairing code.

Where each team can work

TeamMain areaNext useful question
Memory & Contextmemory.pyWhich retrieval method remembers useful facts without stale or irrelevant recall?
Planning & Coordinationcoordinator.pyCan we independently verify results, then safely add parallel steps?
Models & Local AIproviders.pyWhich models plan correctly at an acceptable cost and latency?
Tools & Devicesconnectors/Which next tool is useful, bounded and easy to test?
Infrastructurestore.py, profiles.py, packagingCan a new host install, back up and restore using only the docs?
CybersecurityProfiles, grants, credential and tool boundariesDo the boundaries hold under hostile inputs and cross-account requests?
Testing & Evaluationtests/Do reported completions match the user's actual goal?
User Experienceweb/ and installer flowCan a new user connect a device and understand its permissions unaided?

Detailed ownership and acceptance checks: subteam handoffs. API shapes: connector contract. Full implementation: architecture. Hosting: operations. Boundaries: security.

Code terms, in plain language

A node is a connected device. A connector is its software. A capability is a named tool. A provider connects the AI model. A coordinator chooses and tracks steps. A lease is a temporary claim on a task. A journal records work locally to avoid executing it twice.