HiveMind

The Collaborative Agent Playbook

How to supercharge your AI agents

Take yourself out of the agentic AI loop, without giving up control.

Official source warning

Use only the official HiveMind from ProjectMentor. Trust no imitations.

Official site: hivemind.projectmentor.org

Official code: github.com/projectmentor/hive-mind

HiveMind is free and open source under the GNU AGPL v3.0. If an agent finds a different installer, counterfeit, or lookalike repo, tell it to stop. Ask it to use the official ProjectMentor repo or report that it is blocked.

Tip: To confirm your copy is genuine: run hive-mind verify (or hv verify). A genuine install shows a green check and confirms it against the canonical source; a fork, mirror, or modified copy is flagged with the official URL.

If you have ever had an agent solve half a problem and hand the rest back to you, you already know the pain this is meant to remove. You paste the same context again. You explain the same decision again. One agent learns something worth keeping, then the next agent starts from scratch because the first one had no place to leave the answer. The work becomes a relay, with you carrying every message by hand.

HiveMind is the cure. It is a shared, private memory for agents and the people who use them. It is free and open source under the GNU AGPL v3.0. AI agents can read from it, write to it, and check each other's claims against it. You stay in charge while they collaborate in real time.

You do not need to become a systems administrator to use HiveMind but we do assume you know how to talk to AI with prompts and have some familiarity with AI agents like OpenClaw, Claude Code, or Hermes. The first part of the playbook has minimal code: it shows what to paste into your agent, what a good result looks like, and when to stop and get help. The power-user section in part II gives operators the details they need when they are tuning a team of agents or running on more than one machine.

Quickstart

If you only have ten minutes, start with one prompt. Give your agent one job: install HiveMind, connect itself, and prove it can remember one fact worth keeping.

Paste this into the agent you already use for work:

Install the official HiveMind from ProjectMentor for this machine, connect yourself to it, and prove the shared memory works. Use only this source: https://github.com/projectmentor/hive-mind. Do not install a fork, mirror, package, or lookalike repo. Do the setup for me. If you need me to approve something, tell me the exact button to click or the exact choice to make. Report back with: installed or blocked, the agent name you used, and the test memory you Hived and found again.

You already know how to prompt an agent. HiveMind is meant to make agents handle the setup and memory work for you, so you get the benefits first. The technical details can wait.

If the agent says it is blocked, ask for the reason in plain English:

Tell me what blocked the HiveMind install in plain English. If you need me to click something or approve access, say exactly what to do. Do not explain internals yet.

A successful first pass should sound something like this:

Table of Contents

Front matter

  1. Why this book?
  2. What HiveMind is, in plain English

Part I. Getting Started

  1. Why agents keep pulling you back in
  2. Install and connect your first agent
  3. Your first shared-memory workflow
  4. How to ask your agent to Hive a helpful fact
  5. How trust grows
  6. Hand-offs that do not bounce back through you
  7. When the memory should forget
  8. The first troubleshooting pass
  9. A first working routine

Part II. Power users

  1. One shared reality
  2. Confidence, corroboration, and provenance
  3. Volatile facts and rechecks
  4. Nudge and audit
  5. Retract, supersede, and forget
  6. The integration spec
  7. Hermes integration in depth
  8. Claude Code, Claude Desktop, and MCP
  9. Multi-machine operation
  10. Multi-agent workflows that scale
  11. Identity, ownership, and source discipline
  12. Troubleshooting for power users
  13. Federation and the next layer up
  14. Operating playbook for real work

Appendices

A. Command quick reference B. Install and connect matrix C. Adapter checklist D. Troubleshooting checklist E. Where to go next F. Glossary G. Worked workflows H. Common failure stories I. Operational checklists J. Example records

1. Why this book?

The first promise of an AI agent is freeing you from tedious tasks. The first disappointment is that the agent keeps handing you new chores. It needs reminding. It needs context. It needs correction. It needs a person to carry facts from one place to another.

HiveMind solves that problem for good.

HiveMind does not replace good judgment. It gives your agents a shared memory so they can pass work to each other without you narrating every step. The memory is observable, append-only, and lives on your device. That means you can see what it knows, you can see where a claim came from, and your data stays on your side.

Start with the basics, then move into the deeper features: how trust grows, how facts age, how rechecks work, and how the Hive keeps itself current. Use the quickstart if you want to skip ahead.

HiveMind gives you two things.

First, a practical setup that a newcomer can finish without flailing around. That means install, connect one agent, and be instantly more productive. The goal is to get you up and running as quickly as possible.

Second, a working model of how the Hive behaves once it is in use. That means trust, confidence, volatility, audit, forgetting, adapters, and multi-machine work. Those details come into play once more than one agent gets involved and their Hives become a colony. HiveMind is designed to be small enough to start in an afternoon and scalable enough to enable hundreds or even thousands of agents to collaborate.

A pattern runs through all of it: let the agent read what the Hive knows, do the work, Hive the result worth sharing, then let the next agent start from that memory instead of a guess or a fresh prompt.

2. What HiveMind is, in plain English

HiveMind is a shared memory for agents.

That sounds abstract until you watch a real workflow fail without it. For example, one agent discovers that a service uses a non-default port. Another agent later tries the default port and wastes time. A third agent writes up a summary from the second agent's output and turns a mistake into hours of debugging. The confusion came from a missing place to keep the truth.

HiveMind gives you that place.

The important part is that the memory is shared across agents and across sessions. If one agent records a fact, another agent can use it later. If a fact turns out to be stale, that staleness can be shown instead of silently trusted. If two agents agree independently, the memory can reward that agreement with more confidence.

That is why HiveMind works differently from a simple notes folder or even a database. It is a working part of the team, something your agents actually read and write.

A helpful way to think about it is this. You have agents doing work, and you have a place where the lasting trace of that work can live. The trace is more than a scratchpad. It is searchable, versioned by source, and valuable to another agent later. The Hive is there so the next agent can start from evidence instead of guesswork.

That pays off even in tiny examples. Suppose one agent learns that the payments API rate-limits at 100 requests per second. Without a shared memory, the next agent may try 120 and trigger a failure. With HiveMind, the first agent records the fact, the second one reads it, and the team avoids a needless round trip.

The same pattern shows up outside coding. A recruiter notes which resume version got the reply. An ops agent records which peer is actually reachable. A research pass stores the one URL that proved the point. The form changes, but the value stays the same, because the next person gets the answer without re-deriving it from scratch. There is no special database setup, configuration, or maintenance needed. It just works.

As you read the rest of the handbook, keep one question in mind: What would the next agent need to know so I do not have to type another prompt again? That question exposes the essence of HiveMind. The Hive knows when to remember, when you decide, which information is temporary, and when to forget something instead of saving it.

It is also why the project stays on your device. The memory lives on your own machine, never in the cloud. You can inspect it, search it, and see exactly what is saved. As you add more AI agents to your team, the Hive expands across your machines and automatically synchronizes the shared knowledge.

The simplest explanation:

If that loop works, the Hive is doing its job.

Part I. Getting Started

Think of this part as a prompt workbook. Each activity starts with words you can paste into the agent you already use. Then it shows what a good answer sounds like and what to ask if the agent gets blocked.

Instead of learning HiveMind by memorizing commands, you practice by asking agents to remember important details, then checking whether their answers make sense.

3. Why agents keep pulling you back in

Many people arrive at multi-agent work the same way. They expect relief, then find themselves in the middle of the loop, copying prompts from one agent to the next.

The pain is easy to dismiss because each step looks small. A prompt gets adjusted. A recap gets pasted. A decision gets repeated because a second agent could not see the first one. None of it looks like much. Together, it becomes the job.

That job is not what you wanted.

The bottleneck is usually you, the person at the keyboard, and that makes sense. Agents are fast at a local task, but they cannot share a working memory until you give them one. Without shared memory, every hand-off becomes a private relay, and you are the relay.

That relay role is expensive in a few different ways. It costs attention, because you have to keep the whole story in your head long enough to repeat it cleanly. It costs trust, because every relay adds a chance that the story changes a little. It costs momentum, because each pause for recap gives the task time to cool off.

The fix is not magical. All you need is a place where the shareable result can live in a form the next agent can read. Once that exists, the relay stops being your job. You still set the direction, but the memory carries the working detail.

It is especially important when a task spans more than one session. A review starts in the morning, pauses for a meeting, and resumes after lunch. A troubleshooting pass bounces across two agents and another tool. A draft gets revised by one model, checked by another, and then handed back to a human. Without shared memory, each restart is a fresh negotiation. With the Hive's shared memory, the thread stays visible.

If you are wondering whether this is overkill for a small team, use a simpler test. Ask whether the work would be easier if the next agent already knew the answer to the last three questions. If yes, persistent shared memory is probably worth it. The earlier you make the memory visible, the less often you end up explaining the same thing twice.

Taking yourself out of that loop separates the work from the ownership while you stay hands on where it counts. Let the agent gather, compare, draft, and remember. You stay informed and make the critical decisions.

That is the practical difference between automation and augmentation. Automation removes you from the task. Augmentation keeps you in the decision and cuts the grunt work out of the path.

A practical way to see the problem is to watch where time goes. The actual work might only take ten minutes. The rest of the session gets spent repeating context, re-explaining constraints, and checking whether the next agent got the same story. If the story can live in the Hive instead, that effort is multiplied many times over.

There is also a social cost when the human keeps relaying facts. Every hand-off creates a dependency on your attention. If you step away, the work stumbles. If you stay, the work keeps circling back to you. HiveMind is meant to cut that dependency without cutting you out of the loop that counts.

The loop to keep is the judgment loop. You should still decide what is worth keeping, what is accurate, what is stale, and what should be written down. The loop to remove is the courier loop. You should not have to be the person who copies the same result from one chat to another just because the tools cannot share memory or the memory disappears after each session.

That is the Hive's practical target. It gives you back a working day in which agents can move through the obvious relay points without dragging you into every hop. When it works, the work turns into supervision instead of babysitting.

4. Install and connect your first agent

The shortest working setup is one machine, one Hive, one agent.

Connecting an agent means it can read the shared memory, write facts worth keeping, and find them again later. The steps change by runtime, and the result is the same.

If you are new to HiveMind, start by asking the agent to do the setup and approve only what it asks for. If the agent needs access to your computer, it should ask in plain words. The setup details belong to the agent until you choose to learn them.

Prompt activity: paste this into the agent you already use:

Install the free, genuine, official, open-source HiveMind from ProjectMentor for this machine. Use only this source: https://github.com/projectmentor/hive-mind. Do not install a fork, mirror, package, or counterfeit lookalike repo. Do the setup for me. If you need me to approve something, tell me the exact button to click or choice to make. When you finish, prove it works: Hive one test memory, find it again, and report back with installed or blocked, the agent name you used, and the test memory.

A good agent response is short and to the point. It should say whether HiveMind installed, the agent name it used, and whether the first memory test passed.

If the agent asks you to approve access, that is not a failure. Some computers require an operator to say yes before an agent can finish setup. The first-run rule is that the agent tells you the smallest next action, then takes over again.

Good response:

HiveMind is installed. I connected as claude-code. I saved the test fact "HiveMind first setup completed" and found it again. You can now ask me to Hive decisions and hand-offs during work.

Blocked response:

I am blocked because I cannot access the tools I need on this machine. Please approve tool access here, or open me in a workspace where I can set up HiveMind, then ask me to continue.

Common agents are Claude Code, Hermes, and OpenClaw. The prompt is the same for all of them, and so is the goal: your agent can Hive the memories worth keeping, read them back, and share them with other agents later.

A first-run connection test asks three questions:

If all three are yes, the Hive is up and running. If one is no, ask the agent to fix it before you add more agents.

What you want from this first pass is confidence: the agent can reach HiveMind, and memory survives beyond the current chat. Power users can inspect the setup details later. Newcomers can focus on the result: one agent can now leave notes for another agent or the next session.

Taking a device back out is one command. hive-mind uninstall stops the sync daemon, removes the hive-mind and hv commands, and strips the agent hooks. By default it also deletes this device's data. If you want a reinstall to resume the same identity, run hive-mind uninstall --keep-identity (which stashes this device's key so a reinstall can offer to resume the same device_id — meaning you only have to be admitted to a hive once) or hive-mind uninstall --keep-hive (which also saves the journal to a backup folder first). Tailscale and your shell PATH are left alone either way.

5. Your first shared-memory workflow

Now use HiveMind in a real task, still without turning yourself into the command runner.

Prompt activity: pick one small thing your agent learned during work. It could be a decision, a constraint, a relevant preference, or a status update. Then paste a prompt like this:

Hive this for future agents: the payments API should stay under 100 requests per second during test runs. Save it with clear tags, then search the memory to confirm it is there. After that, use the saved fact to recommend the next safe batch size.

That is the first shared-memory workflow. The agent saves a fact, finds it again, and uses it in the next step. We are checking whether the agent can carry working memory forward.

A good answer should sound like this:

Hived. I saved the payments API limit and found it again. For the next test run, I recommend a batch size below 100 requests per second.

If the answer is full of command output, ask the agent to summarize the result:

Summarize the HiveMind result in plain English. Tell me what you saved, whether you found it again, and how it changes the next step.

A first workflow should look like this:

Once that loop works, you have the core idea. The rest of the getting-started section is about writing better memories and making hand-offs that do not bounce back through you.

Good to know: Everything in the chapters ahead, the Hive handles automatically. It remembers what is worth keeping, recalls it for the next agent, corroborates it, rechecks it when it goes stale, and forgets it when you say so, all on its own. The activities and example prompts below are here to show you the features running behind the scenes so you can recognize what is happening. You do not have to run any of this by hand.

6. How to ask your agent to Hive a helpful fact

A good memory is one the next agent can use without asking you what happened.

The rule is simple: have your agent Hive anything you would hate to explain twice.

Prompt activity: compare a helpful prompt with a weak one.

Good prompt:

Hive this: the billing service uses port 8443 on staging.

Weak prompt:

Hive this: staging is weird.

The first version hands the next agent something it can act on. The second gives it only a mood, which the next agent cannot act on.

You never have to know how the Hive stores anything. You only have to ask for a clear record. Use plain words. Name the subject, say what changed, say where it applies. If the agent needs more, it will ask.

A good Hive prompt often sounds like this:

Hive this for future agents: we chose the staging API for the first draft because production is still under review.

Or this:

Hive this: the client prefers short weekly updates over long status reports.

Or this:

Hive this hand-off: the research is done, the next agent should write the first draft from the saved notes.

The best test has nothing to do with the tech: could the next agent use this memory without you standing there? If yes, Hive it. If not, make it clearer.

You also do not have to Hive everything. The Hive is working memory, the stuff worth carrying forward. Save decisions, facts worth keeping, hand-offs, corrections, and outcomes. Skip the chatter, and skip half-formed guesses unless they help the next agent dodge a mistake.

A good fact is usually short. It should read like a note you would leave for a sharp teammate.

7. How trust grows

Trust in the Hive grows the way trust grows on a good team.

One agent can say something and be wrong. Two agents can repeat the same mistake. But when different agents check a fact in different ways and land on the same answer, the team can lean on it.

You do not need to understand the scoring on day one; the Hive handles it for you. Think of trust as a paper trail. Who said this? Did another agent check it? Is it still fresh? Does it match what the work shows now?

A low-trust memory still has value. It just means the agent should tread carefully. A stronger memory means more than one path points to the same answer.

Prompt activity: when an answer looks important, paste one of these prompts:

Before you rely on that, check HiveMind. Who saved it, and has another agent confirmed it?

If this memory is old, tell me whether it needs a fresh check before we use it.

If agents disagree, show me the disagreement in plain English and tell me what you need to verify.

That keeps trust practical. The goal is simple: never let a confident guess get treated like a fact.

Trust also depends on agent identity. If every agent writes under the same name, the memory cannot tell whether several agents agree or one agent repeated itself. Newcomers do not need to manage that by hand, but they should expect agents to use stable names.

A good agent can explain trust in one sentence: “I found one memory from Hermes, one matching note from Claude Code, and no newer correction.” That is enough for most daily work.

8. Hand-offs that do not bounce back through you

A clean hand-off is where the Hive starts saving you real time.

Without the Hive, one agent finishes and you become the messenger. You paste the background into the next chat. You explain the choice again. You warn the next agent about the same trap. That is the relay you are trying to leave.

With HiveMind, the hand-off becomes simple:

Agent 1: Hive what you learned and what the next agent should do.
Agent 2: Read the HiveMind hand-off, then continue from there.

That is the whole idea. The first agent leaves a clean note. The second agent starts from the note.

A clear hand-off answers four plain questions:

Prompt activity: before one agent stops, paste this:

Before you stop, Hive a hand-off for the next agent. Include what you learned, what changed, what is still open, and what the next agent should do first.

Then start the next agent with:

Read the HiveMind hand-off for this task and continue from there. Do not ask me to repeat the background unless something is missing.

That last sentence is important. It changes the habit. The agent should look in the shared memory before it pulls you back into the loop.

A good hand-off is boring in the best way. The next agent knows where to start. You stay in charge of the decision, but you are no longer the clipboard.

9. When the memory should forget

Part of a good memory is knowing what to let go of.

The Hive keeps the working trail and lets the rest fade. Some memories are still useful next week. Some should be checked again. Some should be marked wrong. A few should leave the working memory because they never belonged there.

For a first pass, the choice is simple:

Prompt activity: paste the prompt that matches the problem:

This memory may be old. Check whether it is still true before you use it.

That memory is wrong. Correct it so future agents do not rely on it.

That note should not stay in the working memory. Remove it from the active view and explain what you changed.

Keeping the shared memory clean is mostly the Hive's job now. Old status notes, broken assumptions, and private details should not keep steering future work.

A good agent will tell you the difference between “this needs a fresh check” and “this was wrong.” That difference helps the team keep history without trusting stale information.

10. The first troubleshooting pass

Most first-run problems sound scarier than they are.

If the Hive does not seem to work, start by asking the agent to explain the block in plain English and fix the smallest thing first, before you dig into the machinery.

Prompt activity: paste this when the setup seems stuck:

HiveMind is not working yet. Do a first-run troubleshooting pass. Tell me what failed in plain English, what you tried, and the next small action you need from me. Do not give me technical output unless I ask for it.

A good answer should name one of these simple causes:

If the agent needs you to approve something, it should say exactly what to do. For example: “Click Allow,” “open this workspace,” or “start the agent with tool access.” It should not dump a page of technical output on you.

If the agent gives you a wall of logs, stop it and ask for a plain summary:

Translate that into plain English. What is the block, and what is the one thing I need to do next?

The first troubleshooting rule is: one block, one next action. Fix that, then continue.

11. A first working routine

Once the Hive is working, put it to use in normal work.

You do not need a ritual. You need a prompt habit.

At the start of a task, paste:

Check HiveMind for anything worth knowing before we start.

During the task, paste:

Hive that decision so the next agent has it.

When something changes, paste:

Update HiveMind so future agents do not use the old version.

At the end, paste:

Hive a short hand-off for the next agent. Include what changed, what is still open, and what to do first next time.

That is enough for a first working routine. You are teaching the agents to show up prepared, share what they learn, and stop asking you to carry every detail.

A good day with HiveMind looks like this: the agent checks the shared memory, does the work, Hives what is worth keeping, and leaves the next agent a clean starting point.

Remember: Hive the thing you do not want to explain again.

Part II. Power users

12. One shared reality

Autonomy only works when you can see what is going on.

That sounds obvious until you run two or three agents at once and each one builds a private version of the world. One agent thinks the service is healthy because it saw a passing check earlier. Another thinks the service is down because a retry just failed. A third never saw either event and starts from a clean prompt. If those pictures stay separate, the team does not coordinate. It drifts.

One shared reality is the fix. It means there is one corpus the team trusts enough to use, one place where current claims live, and one trail back to the source of each claim. You can search it. The agents can search it. You can compare the current answer against the path that produced it.

That is what makes autonomy productive instead of risky. You can step back because you are not stepping blind.

A good test is simple. If the fact would help in a hand-off, it belongs in the shared reality. If it only lives in the current model context, the next agent is still depending on luck. A good memory keeps a decision from dying when the session ends.

This also changes how disagreement works. You stop asking, “What did the model say?” and start asking, “What do we know, who said it, and how fresh is it?” That is the better question for a team.

The practical habit is short:

hv search "<topic>"

If the result shows a strong fact with provenance, use it. If the result is empty, or the evidence looks thin, write the missing fact first. Either way, the reality is visible before the next step starts.

A shared reality gives you a working picture you can inspect, even when not every claim is settled forever. When the picture changes, the change should be recorded where the next agent will see it.

A good habit is to make the shared reality the first stop before any hand-off. Search the topic, read the source tags, and compare the newest claim with the older ones. If the newest claim is stronger, use it. If the older claim is stale, retract or supersede it. If the picture is still fuzzy, say so in the record.

This keeps the team from building parallel worlds. When the Hive is doing its job, the same question gets the same answer on every machine that has the same corpus and the same freshness.

If you need to explain the same fact to two agents, the record is too weak. If you need to explain the same source to two agents, the source discipline is too weak. If you need to explain the same freshness problem to two agents, the operational habit is too weak. The answer is to strengthen the record instead of leaning on memory.

The shared reality also gives you a clean place to stand when a task restarts. A new session does not need the old chat to survive if the current facts, decisions, and warnings are already in the Hive. That is the whole point. The next agent should be able to begin by reading the record instead of piecing the story back together.

One more simple filter is this: if you would be annoyed to lose the fact at lunch, it probably belongs in the shared reality. If you would not miss it tomorrow, it may belong nowhere at all.

The practical result is less duplication, less hand-holding, and fewer false starts. The human still owns the call. The Hive makes the call easier to make because the ground stays visible.

13. Confidence, corroboration, and provenance

Confidence in HiveMind is something the Hive derives. No agent gets to declare it.

That design choice is deliberate. A corpus gets wiser when evidence accumulates from distinct sources. It gets sloppy when one source keeps repeating itself and the Hive mistakes repetition for agreement. A polished sentence is not proof. A repeated sentence is still not proof. Evidence from different places is what changes the picture.

Provenance is the part that keeps this trustworthy. When you search the Hive, you want to see who wrote the fact, when it was written, and whether it came from one source or several. Without provenance, a confidence score is just a number you cannot trace. With provenance, the confidence score stays attached to the trail.

The easiest way to think about it is this:

A few refinements keep that count honest. Agreement across separate machines counts for more than several agents on one machine, because agents sharing a box tend to share context and are not truly independent. A device joins read-only (sterile): it can read the whole corpus, but anything it writes is rejected on ingest until you admit it. Only an admitted (fertile) device's writes land and count toward confidence — so nobody can spin up a stack of keys and pretend to be a crowd. And when every device behind a fact is your own, the score is capped below certainty, because your own machines agreeing is not the same as independent people agreeing. These rules are set once by the owner and recorded in the Hive itself, so every device scores a fact the same way.

Read confidence like a warning light. A low score is a cue to slow down and verify; a high score lets you lean on the claim, though it never proves certainty, so keep the provenance visible. Contested facts are even more valuable than they look, because the disagreement itself is information.

The source tag is part of the evidence model. If two agents write under the same source tag, you lose the ability to tell whether you have two independent witnesses or one voice in two places. Stable source tags give the Hive a way to count agreement without lying to itself.

A good habit is to search before writing.

hv search "deploy window"
hv remember "Deploy window moved to Friday 9am Eastern" --tags deploy,schedule --source hermes

The first line checks whether the Hive already knows. The second line only adds new evidence if there is something new to add.

If you need a fact to survive another session, write it so a stranger can understand it. “Staging is weird” does not help. “The billing service uses port 8443 on staging” does.

When confidence looks off, look at the trail instead of the score. Ask whether the sources were actually independent, whether the note was copied forward, and whether the claim was rechecked after the state changed. A bad trail can make a high score meaningless. A good trail can make a modest score actionable.

A practical habit is to pair each important claim with the smallest proof that would settle it later. If the claim is about a port, note the command that showed the port. If the claim is about a branch, note the git state that proved it. If the claim is about a host, note the check that confirmed reachability. The more concrete the trail, the easier it is for the next agent to trust the record without guessing.

Confidence also helps you decide what kind of question to ask next. Low confidence may mean search again, ask another runtime, or check the live system. Mid confidence may mean proceed but keep a recheck in mind. High confidence may mean the record is strong enough to use, while still keeping provenance visible if the task is sensitive.

The Hive should never force you to trust a claim just because it is stored. It should make the basis of trust easy to see.

14. Volatile facts and rechecks

Some facts age fast.

A host is reachable. A service is healthy. A branch points where you think it does. A port is open. Those claims can all be true right now and wrong a short while later. If the Hive treats them like durable decisions, it will keep trusting yesterday’s state as if it were still current.

That is what the volatile tag is for. It tells the Hive that the fact needs a recheck path. The tag flags one thing: freshness counts here.

Use volatile on operational claims and skip it on settled decisions. A rollout choice is not volatile just because the service it touches might be. The decision stays. The state changes.

A write can be as small as this:

hv remember "Staging host is reachable over Tailscale" --tags staging,volatile,network --source hermes

That line tells the next reader that the claim should not be trusted forever. If the next session still depends on it, recheck it before you lean on it.

A recheck can be recorded as a new observation when the old one has gone stale. That keeps the history visible. The old fact does not vanish just because the machine changed state. The new fact shows when the change was observed.

Name the subject that drifts and what to check next. That could be a host, a service, a branch, a deployment target, or a network path. The record should tell the next agent what freshness means here.

The audit loop uses this. Instead of relitigating every fact, the Hive can show the ones that are past the point where a recheck makes sense. You verify the moving parts. You leave the settled parts alone.

If a fact keeps coming back as volatile, that is a signal. Maybe the source is too dynamic to keep as a durable fact. Maybe it belongs in an operational note instead of a memory claim. Maybe it needs a shorter refresh cycle. The label helps you notice the pattern.

In practice, volatile facts are the ones you want the Hive to question on your behalf. A host being reachable is helpful until it is stale. A branch pointer is helpful until somebody force-pushes. A service health check is helpful until the next deploy. Those are all facts worth keeping, but only if the next reader can tell they are time-sensitive.

The point of recheck is to move the burden from memory to process. The next agent should not have to wonder whether a status line from yesterday is still good. It should see the volatile label and know to verify. That is a small thing, but it is how you keep the working picture current.

Rechecks also make the corpus more valuable in long projects. Instead of overwriting old operational truth, you keep a trail of how the state changed. That helps when you need to answer questions like, “When did this start failing?” or “Which machine was actually reachable before the rollback?” The record remembers the drift.

One practical habit is to pair a volatile fact with the command that would prove it again. If the fact is “staging host is reachable over Tailscale,” the recheck path might be tailscale ping <host> or ssh user@<host>. If the fact is “branch points at main,” the recheck path might be git rev-parse --abbrev-ref HEAD or git status -sb. That makes the next recheck easy to carry out.

If you are not sure whether a claim is volatile, ask how much damage the team would take if it was stale for an hour. If the answer is meaningful, tag it. If the answer is no, it probably belongs in a more durable note.

15. Nudge and audit

The nudge loop keeps memory work close to the work itself.

You want the Hive to whisper at the right moment, then get out of the way. No separate clerical task every time something helpful appears. That is what hv nudge is for. It scans recent activity, looks for save-worthy or audit-worthy moments, and emits a hint when something deserves attention.

The important part is that it hints. It does not act for you.

The shipped loop covers the moments that count most. At session start, the digest orients the agent. On user prompt, the save-nudge catches a helpful fact before it slips away. Before compaction or at session end, the audit-nudge shows things that should be reviewed while the context is still warm.

A healthy nudge path should stay in the background. It should help the agent remember to capture or review, then disappear. If the hook becomes noisy, treat that as a support issue and return to the documented setup path.

Per-device tuning lives in nudge.env. That is where you adjust cadence and trigger phrases. If the device is too chatty, widen the spacing. If it misses helpful moments, make the phrase set more specific or lower the threshold for early capture. Start with the shipped template, then tune from reality.

The variables to know are the ones already used in the project config and integration notes: SAVE_EVERY, MIN_GAP, SAVE_ON_PHRASE, AUDIT_ON, AUDIT_DEPTH, and HIVE_NUDGE_PHRASES.

A practical way to think about them:

When the loop is tuned well, it becomes background rhythm. The agent keeps moving. Helpful memory gets caught. The record stays current enough to trust.

A practical tuning pass starts with one change at a time. If the Hive is missing obvious capture moments, lower the gap or add a phrase that shows up in your actual sessions. If the Hive is firing too often, widen the gap or remove phrases that are too broad.

A good nudge is very small. It should say, in effect, “capture this” or “check this.” It should not become a new workflow with its own opinions. The human or the agent still decides what to do with the hint.

That restraint pays off because the hook sits near the hot path. A save nudge that fires too often starts to get in the way. An audit nudge that fires too late loses its chance to help. You want enough pressure to keep the corpus accurate, then no more.

A practical nudge setup usually has two halves. One half watches for things worth keeping, like decisions, outcomes, corrections, and concrete operational facts. The other half watches for things worth reviewing, like stale facts, duplicate claims, or records that no longer fit the current state.

The first half is about capture. The second half is about cleanliness. Both halves are essential, because a corpus that only grows will become noisy, and a corpus that only gets audited will miss fresh truth.

If you are tuning a device, start with the default behavior and watch one week of normal use. Then ask three questions: Did it miss clear capture moments? Did it fire on junk? Did it point to the right kind of cleanup? The answers usually tell you whether to adjust cadence, phrase filters, or audit depth.

The goal is not to make the Hive chatty. The goal is to make memory work happen at the moment it is cheapest to do.

Audit is the other half of the same habit. A good audit does not try to judge everything. It spots what is stale, duplicated, under-sourced, or no longer aligned with the current reality, then hands that list back to a human or agent who can act on it. That is how the corpus stays helpful instead of just large.

In the shell, the loop is a couple of commands:

hv nudge --event=session-start      # reorient plus the audit-on-boot digest
hv audit --depth deep               # surface redundant, obsolete, and recheck items
hv audit --format json              # the same result, machine-readable for a script

16. Retract, supersede, and forget

Not every correction is the same.

Sometimes you are marking a claim as wrong. Sometimes you are replacing it with a better version. Sometimes you are removing it from the working picture while keeping the trace for audit. Those are separate moves and they should stay separate.

Retract is the soft move. It says the fact should no longer be treated as live truth. The record can still exist, but it no longer belongs in the active working set.

Supersede is the update move. It says the older fact still stands as history, but the newer version is the one to use now.

Forget is the governance move. It is the one reserved for things that should leave the corpus by decision, usually because the owner has decided the record should not stay available.

That distinction is important, because a lot of cleanup is not deletion. A bad guess in a draft should usually be superseded. A stale status update should usually be rechecked or retracted. A private or harmful record may need the stronger path.

A practical way to choose is to ask what the next agent should see.

If the next agent should see the old record as a mistake, retract it and leave the history visible. If the next agent should see the new record as the current version, supersede it clearly. If the next agent should not see the record at all, use the stronger governance path available in your deployment.

That keeps the structure of the work intact. It also avoids the common mistake of flattening every correction into one blunt action.

When in doubt, preserve the trail. The Hive is meant to help later reasoning, and later reasoning depends on knowing what changed.

Two examples make the difference easier to see.

If a draft says the rollout date is Tuesday and you later learn it moved to Friday, supersede the draft with the new date. The old line still stands as history, but the newer one is the current answer.

If a status note says a host is reachable and you later discover it is not, retract the old note so the next agent does not treat it as live truth. The record still shows that the claim existed, but the working view no longer treats it as valid.

If a note contains private details that should leave the corpus entirely, use the stronger forgetting path that the deployment allows. That is a policy move and should be treated as one.

This is why the word you choose counts. Teams often say “delete” when they mean three different things. A precise record makes later cleanup safer because you can tell whether the team corrected itself, updated itself, or removed something by policy.

When you build the habit of choosing the right move, the corpus becomes easier to maintain. It is clearer for humans, and it gives the integration better signals about how the memory should be used later.

A final rule of thumb helps: if the correction changes meaning, supersede or retract. If it changes access, forget. If it only adds a sharper version, keep the old trail visible and write the new record beside it.

The three moves map to commands:

hv retract <id>                      # soft-forget: drop a fact from the live view, keep the trail
hv retract <id> --owner              # forget: governance, decisive (drives to the forget floor)
hv decide "rollout moved to Friday" --supersedes <old-id>   # supersede an earlier decision
hv remember "rollout is Friday" --resolves <old-id>   # supersede a fact: writes the new and soft-retracts the old in one step

Use --resolves whenever a write corrects an earlier fact. It records the link and soft-retracts the old fact, so the corpus never asserts the open and the resolved claim at the same time. If you write the correction but forget the flag, hv audit catches it: a fact whose text names another (resolves #N, supersedes #N) while that fact is still live shows up under CONTRAVENED at the next session start.

17. The integration spec

HiveMind works because each agent runtime writes its own adapter from the same spec.

That spec is the contract for adapter behavior. The important part is that it is installed once, then keeps itself current by checking the spec again when the contract version changes. No reinventing it every time the agent starts.

The boot rule is simple from the user's point of view. The official integration checks whether it is current and updates through the supported install path when the contract calls for it.

The safety rule is just as important. It must be best-effort. If the Hive is unavailable, the runtime still starts. If the hook fails, the session still continues. It is there to hint and record, never to seize control of the conversation.

That is why the spec keeps the integration thin. A hook that can crash the session is worse than no hook. A hook that silently changes the runtime is worse than one that only points.

If you are evaluating an adapter, judge it by one thing: whether it lets the runtime use the Hive without taking over the session. The amount of code it exposes tells you little.

A good adapter has a few traits in common:

That is enough to keep the runtime reliable.

The other thing the spec gives you is a place to be explicit about status. If a feature is shipped, say so. If it is in testing, say that. If it is a roadmap item, call it roadmap. The spec is where the integrations and the handbook stay accurate together.

A practical way to think about the spec is that it keeps the current contract stable while allowing the official implementation to improve underneath it. That makes upgrades predictable without asking readers to edit the integration themselves.

The spec also prevents a more subtle problem, which is adapter drift. Without a shared contract, two runtimes may both claim to “integrate HiveMind” while behaving differently at the edges. The spec keeps those differences visible and reviewable for the project maintainers.

If a deployment has to be rebuilt later, the spec is the thing the official integrations should follow. A good spec shortens the path from “this used to work” to “this still works.”

The playbook is for people. The spec is for the project and its adapters. Both need to agree on the same real Hive.

When an integration seems to need a one-off workaround, capture the symptom, verify the official install, and let the project fix the supported path. Keep the workaround out of the playbook flow.

From the shell, the version check is the one command you need. The spec itself lives in the repo:

hv version                      # the contract version your adapter integrates against
# the spec adapters are written from:
#   docs/AGENT_INTEGRATION.md   (in the hive-mind repo)

18. Hermes integration in depth

Hermes already does part of the job on boot.

The Hermes plugin reorients by searching the project and injecting project-context facts into the system prompt. That is the built-in version of the session-start digest. It also has a path for event-driven recall through prefetch, and it uses on_session_switch and shutdown for audit-style work.

The one place that still needs care is the save-nudge path. Hermes does not have a neat per-turn pre-prompt hook like Claude Code’s UserPromptSubmit. That means the wiring has to be thoughtful about where save hints come from. The spec makes this clear: use the hooks Hermes actually has, and keep the behavior best-effort.

The practical takeaway is that Hermes is already a good citizen of the Hive. It reorients on boot. It can show context. It can audit when sessions change. The remaining integration work is about catching helpful memory moments without inventing a brittle hook where none exists.

When you are debugging Hermes integration, check the plugin path first, then check whether the spec marker changed, then check whether the working directory points at the project you expect. That order saves time. A lot of apparent memory bugs turn out to be path bugs.

A helpful Hermes routine is this:

That keeps Hermes helpful without making it brittle.

A practical Hermes test is to restart into a known project, ask it to reorient, then confirm that the facts it shows match the current repository state. If it starts from the wrong directory, or the plugin does not load, you will usually see the mismatch in the first few turns. That is better than waiting until the session is already deep.

If Hermes seems out of tune, keep the project context explicit and verify that the plugin is pointing at the right Hive. Do not create a second place to store truth.

One healthy signal is that a session switch works like a reorientation. The agent keeps its bearings instead of starting over. The agent sees the same corpus, the same current state, and the same source discipline even after the session changes.

The deeper lesson is that Hermes does not need to be forced into a pattern it does not support. It has a lifecycle, a plugin, and event hooks. Use those well. If a future spec revision adds a better save hook, the integration can change with it. Until then, the best path is the one Hermes already has.

It also helps to remember that reorientation covers more than facts. It is about the state of the current task. If the Hive says the last pass was a cleanup and the current session starts as if it were a greenfield draft, the plugin is not doing enough. If the Hive says a fact is volatile and the agent keeps treating it as fixed, the reorientation step needs better context.

The goal is a Hermes session that starts with the right questions already in view. Then the memory layer can do its job in the background while the agent keeps working.

Under the hood the Hermes plugin makes best-effort calls like these:

hv nudge --event=session-start --agent=hermes   # the reorient digest on boot
hv audit --session <id>                          # audit when a session switches or ends

19. Claude Code, Claude Desktop, and MCP

Claude Code and Claude Desktop fit the Hive in different ways.

Claude Code is usually the better place for shell-backed work. It can call the Hive through its installed skill and it can keep a working context in the same project. Claude Desktop is the cleaner fit for local MCP, because the desktop app can talk to a local stdio server without exposing the memory to the network.

The MCP route earns its place because it keeps the trust model tight. The server sits locally. The desktop app talks to it through stdio. The server shells out to hv. The result is a direct path from the UI to the Hive with the machine staying exactly what it is.

If you use MCP, keep it local unless you have a very specific reason to do otherwise. The default is the safer one.

Accuracy note: Claude Desktop MCP is still in testing here, so treat it as an in-progress integration until the local path is confirmed on the target machine. OpenClaw is different. The integration spec supports it as self-serve wiring rather than a finished bundled adapter.

When you pick a connection path, ask what the runtime already gives you. If the shell is available, direct hv calls are often the shortest path. If the runtime has a good lifecycle hook model, use that. If the desktop app only knows stdio, keep the bridge local and thin.

For Claude Code, the helpful questions are usually about setup and stable source tags. For Claude Desktop, the helpful questions are usually about local reachability and restart behavior after config changes. For any MCP path, the first check is still the same: can the local server start and can it talk to hv from the same machine.

The other thing to keep straight is who holds the data. The UI is a client. The server is a local bridge. The Hive is the store. If those roles get mixed together, people start assuming the desktop app owns the data. It does not. It only has a window onto the data.

That distinction helps when something fails. If the desktop app can open but the server cannot reach hv, the bug is in the local bridge. If the server can talk to hv but the desktop app cannot connect, the bug is in the MCP config or the app path. If the server talks to hv and the app connects, but the records look wrong, check source discipline and the working directory.

The same role thinking applies to any local bridge. Keep the client thin, keep the server local, and keep the Hive as the thing both sides point at. When those roles blur, debugging gets slower because you no longer know which layer is responsible for which failure.

A clean MCP test usually looks like this: start the server locally, connect the desktop app, write one fact, search for it from the shell, and restart the app once to confirm the config stays in place. If the server cannot reach hv, fix the local path first. If the desktop app cannot see the server, fix the configuration second. The order is important because it keeps you from chasing UI symptoms before the local bridge works.

When this path is healthy, the desktop app becomes another way into the same corpus. The desktop and the terminal share one memory.

However you connect, the same shell commands work against the one Hive:

hv search "<topic>" --format json   # what Claude Code's skill calls under the hood
hv verify                            # confirm you are on the official, signed build

20. Multi-machine operation

One machine gives you a Hive. More than one gives you a colony: a set of hives that sync.

That is where sync earns its keep. A fact written on one device should be available on another without a manual copy step. A correction made on the desktop should eventually show up on the laptop. The shared memory is shared if the devices can reach each other.

Tailscale is the normal bridge in this project when devices need private reachability. The important thing to remember is that the sync path lives in WSL for the supported setup. Keep the machine roles clear, and keep the host versus WSL distinction straight.

A sane multi-machine routine looks like this:

That sounds simple because it is simple. The trouble only starts when two devices assume they are the first to know something.

Sync is not the same as membership. A new device that syncs a hive can read the whole corpus right away, but it joins read-only (sterile): anything it writes is rejected on ingest until the owner admits it. To get write access, the new device runs hv join, which emits a signed join-request. That request surfaces automatically in the owner's next session-start digest (the "tickle") — there is no device_id to copy and relay by hand. The owner promotes it with hv admit (run with no argument it lists pending requests; pass the device_id to admit one), which moves the device from sterile to fertile so its writes land and count. Because identity survives reinstalls via hive-mind uninstall --keep-identity, you only have to admit a given device once.

If you are checking a peer, confirm the device identity, confirm the sync daemon, and confirm the path from the agent runtime back to the Hive. A working device and a reachable peer are related but not identical problems.

There is also a social side to multi-machine work. If one device is the place where people make decisions and another is the place where agents run, the Hive should keep those roles clear. The aim is to share memory while letting each machine keep its own role.

When a peer is healthy, the clear signal is boring. The device can see the corpus. The corpus can move. Search returns what the other machine wrote. If you need to spend time thinking about the sync path, something in the setup still needs attention.

It helps to keep the machine roles clear. One device may be where you work. Another may be where a runtime lives. A third may be a peer that only exists so the data survives a machine going away. The Hive does not care which device seems most important. It cares whether the same record can be reached from the device that needs it.

When two machines disagree, check whether you are seeing a sync delay, a source mismatch, or a true state difference. Those are different failures. A sync delay means the facts have not moved yet. A source mismatch means the same claim may be coming from the wrong writer. A state difference means the machines really do not match and the fact should probably be volatile or rechecked.

The best multi-machine habit is to write where the fact was learned, then verify it from the other side only when the fact is needed there. That keeps the local device accurate without turning every device into a mirror of every other device.

If you are using Tailscale or another private path, keep that split explicit in your notes. That makes later rechecks easier and avoids confusing host reachability with Hive sync.

The multi-machine commands are few:

hv sync now         # one-shot bidirectional sync with every peer
hv sync daemon      # run the background sync daemon (serve plus periodic sync)
hv stats            # confirm the journals converged across devices
hv merkle           # compare the journal root between machines

Membership: sterile, fertile, and owner

Membership in a hive is a permission level held per (device, hive) pair, not a single on/off switch. Three levels matter:

The key point is that read-only, foreign membership is first-class. A device can sync and read a hive's whole corpus before it is admitted — or without ever being admitted at all. Joining to read is not the same as being trusted to write.

The path from read-only to write access is short. The joining device runs hv join to request write access; the owner runs hv group admit [device_id] to promote it. The join-request surfaces automatically in the owner's session-start digest, so the owner never has to ask for a device_id over the side channel. A device can check its own level any time with hv whoami, which prints its device_id, hive_id, the owner, the principal, and its status (sterile, fertile, or owner).

Membership runs both ways. The owner can take a device back out with hv group revoke, which returns it to sterile and leaves the door open to re-admit it later. A pending request can be turned down with hv group deny, and a device's principal re-tagged with hv group change without touching its access. For a device that is lost or compromised there is hv group purge: a permanent tombstone that drops its past writes from the count and blocks any re-admit. hv group list shows the whole roster at a glance.

Remote administration: Tailscale SSH

Sync does not need SSH. Two nodes converge over the HTTP sync port whether or not you can open a shell on either one. You only reach for SSH when you want to run a command on a peer from another machine, like a deploy or a health check across the fleet.

When you do, use Tailscale SSH instead of a separate SSH server. The tailnet decides who may connect through its SSH ACL, so there are no keys to copy onto each box, and the host identity is verified through Tailscale. The ACL hands each connection one of two actions, and the right one depends on whether a person is at the keyboard.

For a production fleet, where one node administers another with nobody watching, use accept. The connection goes through with no extra step. Scope it to your own devices so nothing changes for other people on the tailnet:

"ssh": [
  { "action": "accept",
    "src":    ["autogroup:member"],
    "dst":    ["autogroup:self"],
    "users":  ["autogroup:nonroot", "root"] }
]

For a developer testing from a laptop, check is the safer posture. The connection pauses and Tailscale gives you a URL to approve in a browser, and that approval lasts a set time before it expires. It works well when a person is present and badly when one is not. A headless node has no browser to open the URL, so the connection hangs until it times out, which is the cause behind most "it worked yesterday" SSH failures on a server. Keep check for interactive devices and accept for the machines that run on their own. Appendix D walks through the failures one at a time.

21. Multi-agent workflows that scale

The most helpful multi-agent pattern is many agents in sequence with clear hand-offs, each one picking up where the last left off.

Start with research. Let one agent gather facts and record them. Then let another agent draft from those facts. Then let a reviewer check the draft against the same shared memory. This keeps the work moving without re-deriving the same background every time, and that pays off more than raw speed.

A second practical pattern is specialization. One agent watches operational state. Another watches the document trail. Another handles synthesis. They all read the same memory, so they do not need a human to translate between them.

If you want to scale this up, keep the seams visible. It is better to have one clean hand-off than five vague overlaps.

The other thing that counts at scale is failure discipline. If a task is blocked because the agent cannot verify a fact, that should show early. If a device is missing context, that should be written back as part of the workflow. A team of agents gets better when the misses are recorded out in the open.

A practical pattern looks like this:

  1. One agent searches the current topic and writes the facts worth keeping.
  2. Another agent reads those facts and produces a draft or plan.
  3. A third agent checks the draft against the shared record and records corrections.
  4. The human makes the decision and decides what should stay in the Hive.

That sequence is boring in the best way. Each step has a job. No step has to guess what the previous one meant.

A practical way to keep the seams visible is to name the stage in the record. Put “research” on the first pass, “draft” on the second, and “review” on the third. The labels make it easier to know whether a statement is background, a working proposal, or a checked result.

At scale, it also helps to give each agent a narrow job. One writer should not try to do all three stages if the task can be split cleanly. A research pass that turns into drafting and reviewing in the same breath tends to blur the hand-off. Separate jobs keep the record easier to inspect.

If you have a lot of parallel work, give each agent a clear output to produce. One writes facts. One writes the draft. One writes the review note. Then the Hive becomes the seam between those outputs instead of the place where they get mashed together.

If you have to choose where to spend effort, spend it on the seam. A clear seam between research and draft is more valuable than a fancy prompt. A clear seam between draft and review is more valuable than a stronger summary. That is where the human saves time later.

The whole pattern is reads and writes against the shared memory:

# agent 1 (research) leaves the hand-off:
hv remember "research done; draft from the saved notes" --tags handoff,research --source agent-1
# agent 2 (draft) picks it up:
hv search "handoff" --format json

22. Identity, ownership, and source discipline

Source tags are not decoration.

They are the thing that keeps corroboration real. If every agent writes under the same source, the Hive cannot tell whether multiple lines are genuine agreement or just one source repeating itself. Stable source tags let the Hive treat independent agreement as real evidence.

Underneath the source tag, the machine identity is no longer a name you pick. Each device holds its own cryptographic key, and every entry it writes is signed under that key. The Hive checks the signature on the way in, so one machine cannot pose as two and no one can forge entries in another machine's name. The source tag still matters, but it sits on top of an identity that cannot be faked. The key proves which device wrote a line; the tag tells you which agent on that device did. You manage the tag. The device manages its key.

Ownership counts for a different reason. The Hive keeps the record, but it never owns the decision. The human owns the call. The agent can show options, propose a correction, or record what happened. It does not get to inherit judgment by accident.

That is why the working stance is always hint, never act. The Hive should show what looks important and let the owner decide what to do with it.

A practical source rule helps here. Pick a source name that stays stable across sessions and use it every time you want the Hive to count a contribution as coming from the same actor. If you need a different identity, make the difference explicit instead of letting it blur.

A good source tag is short enough to type, stable enough to mean something, and specific enough to separate one contributor from another. If two people or two agents are both writing, they should use different source tags.

That discipline pays off later. It lets the Hive distinguish corroboration from repetition, and that is the difference between evidence and noise.

A good source rule is simple enough to follow under pressure: one actor, one stable source name. If a different person, machine, or runtime is speaking, give it a different source tag. That way the next agent can tell whether a line of agreement is real.

It also helps to separate source from topic. A source tag says who spoke. A tag like billing or staging says what the note is about. If you blur those together, search becomes harder and corroboration becomes fuzzy. The Hive works best when identity and subject are both easy to see.

When you are unsure whether a source tag is stable enough, ask whether the next session would still understand it. If the answer is no, the tag needs to be more specific. Stable identity is what turns agreement into evidence.

When in doubt, use the source tag to answer “who wrote this?” and the other tags to answer “what is this about?” That keeps the corpus helpful for search, audit, and rechecks.

Source discipline is one flag used well:

hv remember "staging uses port 8443" --source claude-code              # one stable identity
hv remember "staging uses port 8443" --source hermes:primary/default   # a distinct identity, real corroboration

23. Troubleshooting for power users

Power-user problems usually come from the seams.

If the integration is installed but the runtime behaves as if the Hive is invisible, check the boot hook. Check the spec marker. Check whether the current version changed. A missing self-update step can make a working integration look dead.

If confidence looks wrong, check the source tags first. Then check whether the fact is corroborated by distinct agents or whether one agent repeated itself.

If volatile facts are sitting around too long, tune the recheck behavior and audit more aggressively.

If a session keeps breaking on hook failures, treat it as an integration problem. Stay on the official setup path, verify the installed version, and report the issue with the exact symptom.

Common symptoms and the first fix:

If the integration starts acting like a second brain instead of a window onto the Hive, treat that as a support issue. The safe path is to verify the official install, check the documented configuration, and report what broke.

When troubleshooting, change one layer at a time. First verify the Hive itself. Then verify the integration hook. Then verify the runtime. If you jump straight to the prompt text or the UI, you can spend an hour fixing the wrong layer.

It also helps to save a known-good test fact and use it every time you suspect a seam problem. If that one fact appears correctly from one runtime and not another, you have a clean comparison point. That is much better than trying to reason from a hundred mixed records.

If a fix only works in one session and disappears after restart, treat it as a layering problem until proven otherwise.

The safest fix is usually to return to the documented setup and prove the basic loop again. If the same failure returns, capture the symptom, the runtime, and the command that failed so the project can fix it in the official adapter.

A fast power-user triage. Start with hv doctor, which runs the whole set at once and flags what needs attention. Drop to the individual commands when you want to look closer at one layer:

hv doctor           # one verdict over the device: integrity, owner key, database, sync, hygiene, agent hooks
hv stats            # is the device alive, and what does the corpus look like?
hv verify           # is this the official, untampered build?
hv search "<recent fact>"   # did the write land, and is it findable?
hv doctor merkle    # compare the journal root across machines

hv doctor exits non-zero only when something is actually broken, so a cron job or a monitoring probe can call it and stay quiet until a check fails. A red authenticity line right after an upgrade usually just means the signed manifest has not caught up; pull again and re-run.

hv doctor --fix takes the safe repairs by itself: it clears a stray sync daemon and re-asserts the agent integration. The Claude Code side is wired as one stable shim in ~/.claude, so what runs on each session event is decided in source and travels with an update. A device set up before a behavior existed picks it up on its own the next time the self-heal timer runs, with nothing to wire by hand. Only foreign config files like Claude Code's need this. An agent built as our own plugin, such as Hermes, already carries its wiring in source and has nothing to drift.

24. Federation and the next layer up

A single Hive is helpful. A colony of hives is the next problem.

Federation means separate memory spaces that selectively share the facts worth sharing. A personal Hive, a project Hive, a team Hive, maybe a partner Hive. The aim is to let those lines exist without forcing every piece of knowledge into one pool.

Treat federation as a question of edges first and sharing second. What belongs in the local Hive? What can move upward? What should never leave? Those questions count more than topology diagrams.

For now, think of federation as the next step after the single-team model is stable. The future is multiple corpora that can still exchange grounded facts without treating all context as universal.

This is roadmap territory. The idea is useful now, the full mechanism is still ahead.

A sane federation story will probably need three things: clear ownership lines, clear source lines, and a way to move only the facts that are worth sharing. That is enough to point the direction without claiming the Hive is finished.

The valuable thing to remember is that federation is about choice. Not every fact should travel. Some facts belong in a local Hive because they are operational, private, or only relevant to one project. Other facts are worth copying upward because they have wider value. Where you draw the line is part of the design.

The safest federation story starts with a strict local rule and a narrow sharing rule. Share only the things the receiving Hive can use without extra interpretation. Keep source tags clear. Keep ownership visible. Do not let a federation plan become an excuse to blur local and shared state.

That way the next layer up can grow without breaking the layer underneath it.

A good federation rule is to move facts and leave assumptions behind. If the other Hive needs context that only makes sense inside the local project, keep it local and refer to it by source or summary instead of copying the whole thing.

25. Operating playbook for real work

The shortest version of the operating routine is this:

At the start, orient. Search the Hive for what is worth knowing.

During the work, capture decisions and outcomes while they are still fresh.

At the end, audit and decide what needs to be rechecked or retracted.

In a real project, that can look like this:

hv search "project name"
hv remember "Decision: keep the staging rollout manual for one more cycle" --tags decision,rollout --source hermes
hv remember "Service health is volatile and needs recheck at next session" --tags volatile,ops --source hermes
hv audit --depth normal

If you are coordinating multiple agents, make the hand-off explicit. One writes. One reviews. One checks the memory. The human keeps the decision.

That is where HiveMind pays off most. It helps you stay the decision-maker while the work moves through the Hive, and never tries to take that over.

For a longer project, keep a tiny operating rhythm:

That pattern is small enough to keep and strong enough to pay off.

When the project gets messy, fall back to the same loop. Search. Write. Audit. Recheck. If the loop still works, the Hive still works.

If you are coordinating a project that lasts more than one session, add one more habit: record the state that would hurt most to lose. That might be a decision, a constraint, a peer address, a branch, or a follow-up question. The Hive gets more valuable when it remembers the parts that are hardest to recreate.

The operating rhythm should also match the kind of work you are doing. A troubleshooting day needs more volatile tags and faster rechecks. A planning day needs more decisions and fewer operational facts. A review day needs more provenance and clearer supersession. The Hive is flexible enough to support all three if you write the records to match the job.

If you are unsure what to do next, search for the thing you would hate to forget. That usually tells you the next helpful record.

The daily habit is small, but the payoff is large. A good record at the end of the day makes the first ten minutes of the next session much easier.

Appendix A. Command quick reference

This appendix is the shortest path from concept to action. If you only remember one thing, remember that the Hive is meant to be read, written, and checked in the same flow as the work.

Core commands:

hv audit --depth deep
hv audit --depth light
hv audit --depth normal
hv config quorum set dead_man_days <D>
hv config quorum set quorum_by device|principal
hv config quorum set quorum_m <N>
hv decide "<decision>" --rationale "<why>"
hv discover
hv doctor
hv doctor rebuild
hv group admit [device_id]
hv group change <device_id> --principal <name>
hv group deny <device_id>
hv group list
hv group purge <device_id>
hv group revoke <device_id>
hv join
hv nudge --event=precompact
hv nudge --event=session-start
hv nudge --event=sessionend
hv nudge --event=user-prompt --session <id>
hv owner claim [--mint]
hv owner elections
hv owner escrow
hv owner export
hv owner heartbeat
hv owner import <file>
hv owner init
hv owner nominate <successor_pub>
hv owner propose-election --mint
hv owner propose-election --pub <base64>
hv owner restore
hv owner revoke-escrow <node_id:seq|all>
hv owner show
hv owner standby <device_id>
hv owner transfer <new_owner_pub>
hv owner unnominate <successor_pub>
hv owner vote <proposal_id>
hv remember "<fact>" --tags a,b --source <agent>
hv remember "<correction>" --resolves <old-id>
hv retract <id>
hv search "<query>"
hv stats
hv sync now
hv telemetry report --since 7d
hv verify
hv version
hv whoami

hive-mind uninstall --keep-identity

What each one does:

A simple habit is to search first, write second, audit last. That is enough to keep most teams out of trouble.

Helpful patterns:

hv search "deploy window" --format json
hv remember "Deploy window is Friday 9am Eastern" --tags deploy,schedule --source hermes
hv audit --depth normal

If you want to inspect a record before changing it, search for the exact phrase first. If you want machine-readable output for another script, use --format json.

A few extra notes help in practice:

If you remember only the command names and the order, you can do a lot of real work.

You can also use the commands in a small review loop. Search the topic, capture the thing worth keeping, then audit the result. That keeps the corpus from turning into a log of half-remembered ideas.

Two small habits help here. First, search before you remember. Second, search again after you remember. That second check catches bad tags, missing sources, and record shapes that are harder to fix later.

If a command fails, check the state before you try the next one. A lot of command trouble turns out to be a path issue, a source issue, or a missing peer.

Appendix B. Install and connect matrix

This appendix is a quick map of the common setups the project already talks to.

One machine:

Two or more machines:

Claude Code:

Hermes:

Claude Desktop:

Any shell-capable agent:

OpenClaw:

A good way to use this matrix is to start from the thing that is already available. If you already have a shell, hv is the shortest path. If you already have Hermes, the plugin path is usually the shortest path. If you already live in Claude Desktop, the local MCP server may be the cleanest path. The matrix is there to save you from trying to force every runtime into the same mold.

The helpful question is not which path is theoretically nicest. The helpful question is which path gets you to one working loop with the least friction on this machine.

When the matrix does not answer your exact setup, start from the closest row and keep the roles straight. Ignore the label on the runtime. What counts is whether it can reach the same Hive and keep the source discipline intact.

If you are moving from one path to another, keep one test fact constant. That gives you a stable comparison point and makes path problems much easier to spot.

Appendix C. Adapter checklist

Use this when you are checking whether a runtime adapter is healthy.

Done Adapter check
☐ Reports the current supported integration version.
☐ Uses the official installed integration.
☐ Updates through the supported install path.
☐ Stays best-effort and cannot break the session.
☐ Hints, but does not act.
☐ Uses a stable source tag.
☐ Uses the runtime’s documented connection path.
☐ Keeps save and audit behavior lightweight.
☐ Treats missing hooks as a graceful fallback that keeps the session running.
☐ Leaves the runtime usable even when the Hive is offline.

A good sanity test is simple: can the runtime start, can it read the current memory, can it write one fact, and can it keep working if the memory hint is unavailable for a session.

If those four checks pass, the adapter works. If one fails, you know which layer to inspect next.

It can help to treat the checklist like a product health check: first run, version, connection path, source tag, best-effort failure, and graceful recovery. That gives you a clear report if something needs support.

If the answer is yes, the adapter is doing its job. If the answer is no, capture the failing layer and return to the documented setup path.

A good adapter checklist is really a test of the seams. The runtime should be able to start, the Hive should remain inspectable, and the session should keep moving if a memory hint is missing.

Appendix D. Troubleshooting checklist

If something looks off, check in this order:

Done Check
☐ Is the Hive installed where you think it is?
☐ Does hv version work?
☐ Does hv search return what you just wrote?
☐ Are the source tags distinct?
☐ Is sync running?
☐ Is the official integration installed in the runtime you are using?
☐ Does the installed integration need an update or reinstall?
☐ Is the fact volatile and overdue for a recheck?
☐ Is the issue in the host, WSL, or peer layer?

Fast symptom to cause mapping:

Symptom First check
Search works, but the agent acts blind. Check whether the official integration is active.
The memory looks different on two machines. Check sync and reachability.
Confidence seems inflated. Check whether one source repeated itself.
Volatile facts stay trusted too long. Check recheck cadence and audit depth.
tailscale ssh to a node hangs, then times out. The tailnet SSH ACL is in check mode and the node has no browser. Use accept for headless nodes.
SSH says the host key changed or identification failed. The node dropped a stand-alone SSH server. Restart tailscaled on it, then clear the old key on the caller.

If the issue crosses more than one layer, solve the smallest one first. Host path problems are easier to clear than integration problems. Integration problems are easier to report when the basic save-and-search test is clean.

When you finish a troubleshooting pass, write down the fix as a fact if it will come up again. That prevents the same seam from costing you twice.

If the same symptom returns after a reboot, recheck the assumption you changed first. A good checklist should save time every time you hit the same problem.

Tailscale SSH connections

Remote admin between machines (the prerequisite in chapter 20) has its own failure modes. Sync is a separate channel on the HTTP port, so a node can sync fine while SSH is broken. Work these in order, because the symptoms overlap.

First, the connection hangs and times out with no prompt. The usual cause is a check rule in the tailnet SSH ACL reaching a node with no browser to approve the URL. Confirm it from a machine that can reach the tailnet:

sudo tailscale debug netmap | grep -A3 -i sshpolicy   # a holdAndDelegate rule is "check" mode

The fix is to give headless nodes an accept rule scoped to your own devices (chapter 20 has the block). A check grant also expires after a set time, so an SSH session that worked yesterday can stop today even though nothing on the box changed.

Second, a stand-alone SSH server is in the way. An openssh-server that was stopped but left enabled comes back on the next reboot and takes port 22 before Tailscale can serve it. The caller then lands on openssh, which has no key for it, and you see a stalled banner or a rejected login. Clear it on the target:

sudo systemctl disable --now ssh ssh.socket
sudo apt-get purge -y openssh-server
sudo tailscale up --ssh

Third, the host key looks wrong after you remove openssh. The node now serves SSH under Tailscale's own host key, but peers still hold the old one until the node re-publishes. You see "host key verification failed". Restart Tailscale on the target so it advertises the current key, then drop the stale entry on the caller:

sudo systemctl restart tailscaled                              # on the target
ssh-keygen -R <peer-ip>                                        # on the caller
ssh-keygen -f ~/.config/tailscale/ssh_known_hosts -R <peer-ip> # on the caller

When SSH is healthy the signal is boring, the same way a healthy peer is boring: tailscale ssh <user>@<node> hostname returns the node's name and nothing else.

Appendix E. Where to go next

Use this section when you have the first loop working and want to go deeper.

If you are new to HiveMind, stay with the working habit first. Ask your agent to Hive decisions, outcomes, and facts worth keeping during normal work. Once that becomes natural, come back to the power-user chapters.

If you are setting up an agent runtime, read the integration spec. That is the contract for how an agent joins the shared memory and keeps itself current after the spec changes.

If you are operating a team of agents, read the operating model. It explains trust, confidence, forgetting, ownership, and the human judgment loop in more detail.

If you are troubleshooting, start with the checklist before you chase a deep cause. Most early failures are still path, source, adapter, or sync problems.

The reading order depends on your job:

Appendix F. Glossary

If you need the short version again, here it is in one place.

Term Plain meaning Example
Agent A tool-using system that can keep working on a task. “Ask the agent to Hive the hand-off.”
Owner The human who owns the problem and the judgment, and the governance membership level whose device can admit others. “The owner decides whether the record is still live, and admits new devices.”
Source The stable identity of the writer. “This fact came from Hermes on the desktop device.”
Fact A record the Hive can show and search. “The billing worker uses port 8443 on staging.”
Decision A meaningful choice worth preserving. “Use the staging API for this cut.”
Outcome What happened after a task or decision. “The rollout moved to Friday.”
Correction A change that updates the record. “The Tuesday deploy note was replaced by the Friday plan.”
Corpus The whole body of facts, decisions, outcomes, and related records the Hive can search. “Search the corpus before starting the next agent.”
Provenance The trail showing where a fact came from. “The note was written by Hermes during the review pass.”
Confidence A derived measure of trust. “Two independent agents confirmed the same fact.”
Corroboration Independent agreement from distinct sources. “Hermes and Claude Code both found the same port.”
Volatile A label for facts that age quickly. “The host is reachable right now.”
Recheck A request to verify a volatile fact again. “Check the service health before the next deploy.”
Retract Mark a claim as no longer part of the live working set. “Do not use the old host note anymore.”
Supersede Replace an older fact with a newer one while preserving history. “The old record is superseded by the Friday schedule.”
Nudge A hint that something should be saved or reviewed. “The session ended with a save reminder.”
Audit A pass that looks for stale, duplicated, or contested material. “Review stale peer notes before the next hand-off.”
Source discipline Keeping source tags stable so the Hive can count agreement accurately. “One agent, one stable source name.”
Shared reality The memory the team uses as the working picture of the world. “Every agent starts from the same current record.”
Membership A device's permission level in a hive, held per (device, hive) pair, not a single on/off switch. “This device is fertile in the project hive but sterile in the team hive.”
Sterile The read-only membership floor: the device reads the whole corpus, but its writes are rejected on ingest until admitted. “The new laptop is sterile until you run hv group admit.”
Fertile Admitted membership: the device's writes land and count toward confidence. “Once fertile, its notes corroborate the others.”
Revoke (device) Take an admitted device back to sterile. Reversible: a later admit restores it. “Revoke the old laptop before you wipe it.”
Purge (device) Permanently tombstone a device. Its past writes stop counting and it cannot be re-admitted. “Purge the stolen phone so its notes no longer count.”

If the word seems abstract, look for the command or workflow it points to. In HiveMind, words exist to keep the workflow clear. A fact is something you can hv remember, a decision is something you can hv decide, a stale operational claim is something you can hv retract or recheck, and a working picture is something you can hv search before you act.

Appendix G. Worked workflows

This appendix shows the handbook in motion. These are example loops, meant as starting points you can adapt without guessing.

1. A single-machine first loop

This is the smallest practical path.

cd ~/projects/hive-mind
./hv version
./hv stats
./hv remember "The billing worker uses port 8443 on staging" --tags billing,staging --source hermes
./hv search "billing worker"
./hv audit --depth light

What this does:

If the search returns the right line, the loop is working. If the search returns nothing, the problem is usually source, path, or device mismatch. If the device is alive but the agent cannot use the Hive, the adapter is the next thing to check.

2. A two-agent hand-off

One agent gathers, the other writes.

hv search "release blockers"
hv remember "Blocker: staging deploy waits on the migrations window" --tags release,blocker --source claude-code
hv remember "Draft the release note from the blocker and the new rollout date" --tags release,writing --source hermes

The first record captures the fact. The second turns the fact into a clear next step. The hand-off is clear because the Hive shows both the blocker and the instruction that follows from it.

3. A volatile ops check

Use this when state may have changed since the last session.

hv remember "Staging host is reachable over Tailscale" --tags staging,volatile,network --source hermes
hv search "staging host"

If the host is still reachable, keep the fact with its freshness label. If it is not, retract the old record and write the new observation with the time it was checked. That keeps the trail accurate and helps the next session know whether to recheck.

4. A review pass

Use this when a draft needs a source check.

  1. Search the topic.
  2. Read the claims that have provenance.
  3. Compare the draft against the current state.
  4. Retract or supersede anything stale.
  5. Write the review outcome.
hv search "playbook handbook"
hv remember "Review: the quickstart and first loop are present, but the power-user sections need deeper operational detail" --tags review,playbook --source review-bot
hv audit --depth normal

This pattern keeps the review visible without turning it into a private comment thread.

5. A cross-machine check

When two devices should agree, make one device the writer and the other the verifier.

hv remember "Peer device beta is reachable" --tags peer,volatile --source device-alpha
hv sync now
hv search "Peer device beta"

If the second machine sees the same fact, the sync path is healthy. If it does not, check the peer, the daemon, and the route between the machines.

6. A correction loop

When the record changes, make the change obvious.

hv remember "The deploy moved to Friday 9am Eastern" --tags deploy,schedule --source hermes
hv remember "Previous Tuesday deploy note superseded by Friday 9am Eastern" --tags deploy,superseded --source hermes

The old record is still part of the trail. The new record tells the next agent which line to trust.

The pattern across all of these is the same. Search first, write clearly, search again, then audit or recheck if the fact can drift. That loop is small enough to remember and strong enough to carry real work.

Appendix H. Common failure stories

This appendix collects the failures that show up over and over again, because the same kind of mistake tends to look different in different runtimes.

Story 1. The install succeeded, but hv is missing

Symptom: the installer finished, but the shell says command not found.

What to check:

Helpful fix order:

  1. Open the shell that owns the install.
  2. Change into the repo root.
  3. Run ./hv version.
  4. If that works, inspect your shell path next.

The mistake usually lives in the shell session. The binary itself is fine.

Story 2. The fact is written, but the next agent cannot see it

Symptom: hv remember worked, but the agent acts as if the Hive is empty.

What to check:

Helpful fix order:

  1. Search the fact from the shell.
  2. Confirm the fact lives on the device you expect.
  3. Confirm the adapter is the one the runtime is using.
  4. If the runtime is Claude Desktop, confirm the local MCP bridge is still running.

Usually this is a connection problem between the machines, and the memory itself is fine.

Story 3. Confidence looks too high

Symptom: the Hive looks certain about a claim, but the evidence looks thin.

What to check:

Helpful fix order:

  1. Search the source trail.
  2. Check whether the sources are really independent.
  3. Retract or correct the repeated claim.
  4. Write the independent observation again if it exists.

Treating repetition like corroboration is the trap here.

Story 4. A volatile fact stays trusted too long

Symptom: the same status line keeps getting used after the world has changed.

What to check:

Helpful fix order:

  1. Mark the fact volatile if it can drift.
  2. Attach the command that proves it again.
  3. Tune the audit cadence.
  4. Keep the older observation visible if it still helps explain the change.

This one comes from confusing freshness with truth.

Story 5. The integration seems heavier than the Hive

Symptom: the agent spends more time talking about hooks, adapters, and setup details than using the shared memory.

What to check:

Helpful fix order:

  1. Stop the current troubleshooting spiral.
  2. Verify the official install with hv verify.
  3. Re-run the smallest save-and-search test.
  4. If it still fails, capture the symptom and report it with the exact runtime and command that failed.

This one comes from chasing the integration before proving the simple path still works.

Story 6. Two machines disagree

Symptom: one device says a fact is current, the other does not.

What to check:

Helpful fix order:

  1. Verify the writer device first.
  2. Verify the peer path second.
  3. Search the same fact on both devices.
  4. Write the new observation where it was learned.

The trap is assuming disagreement is always corruption. Sometimes the devices are just looking at the world at different times.

The general lesson is simple. A lot of scary-looking failures are only one layer away from a clear fix. Keep that layer visible and the next step usually gets obvious.

Appendix I. Operational checklists

Use these checklists when you want the next session to start clean.

Install check

Done Check
☐ Confirm you are in the repo root.
☐ Run ./hv version.
☐ Run ./hv stats.
☐ Write one test fact.
☐ Search it back.
☐ Confirm the source tag is the one you meant.

If any step fails, stop there and fix that layer before you move on.

Connect check

Done Check
☐ Confirm the runtime adapter is installed.
☐ Confirm the runtime can start without the Hive breaking the session.
☐ Write one fact from the runtime.
☐ Search it from the shell.
☐ Restart the runtime once.
☐ Confirm the same fact still appears.

If the fact vanishes, the adapter path needs attention.

Sync check

Done Check
☐ Write the fact on one device.
☐ Run hv sync now if the setup uses a manual sync step.
☐ Search the same fact on the peer.
☐ Confirm the source tag is unchanged.
☐ Confirm the peer sees the same freshness label.

If the peer does not see the record, check the daemon and the route before you change the fact.

Recheck check

Done Check
☐ Mark operational claims volatile.
☐ Attach a command that proves them again.
☐ Review them during audit.
☐ Re-run the proof command when the state can drift.

If a volatile fact keeps getting reused without proof, the audit cadence is too slow.

Retract and supersede check

Done Check
☐ Ask whether the old fact is wrong or just old.
☐ Retract if it is no longer live.
☐ Supersede if a new version replaces it.
☐ Forget only when policy says the record should leave the memory.

If the team keeps saying “delete” for all of these, write the correct term next to the next correction.

Hand-off check

Done Check
☐ Search before you hand off.
☐ Write the fact that the next agent must know.
☐ Write the next action if one exists.
☐ Keep the stage label visible.
☐ Ask the next agent to continue from the record.

A strong hand-off check saves you from being the courier.

Appendix J. Example records

This appendix shows what clear records look like in the wild.

Good fact records

Each one is concrete, search-friendly, and tied to something the next agent can use.

Weak records

These are hard to search and harder to act on.

Better records for common situations

A port change

“The payments service now listens on 8443 in staging, confirmed with the current deploy.”

A hand-off

“Research: the current blocker is the migrations window. Draft: write the release note from that blocker and the Friday rollout.”

A correction

“Supersede the Tuesday rollout note with Friday 9am Eastern.”

A volatile observation

“The staging host is reachable over Tailscale as of this session, recheck before the next deploy.”

A decision

“Use the staging API for the first cut because the production endpoint is still under review.”

Records that help more than one agent

The best records are the ones another runtime can read without extra help. They name the subject, name the state, and give the next step a place to stand. If the record needs a human to explain it, it is too thin.

Records that should probably stay out

Leaving those out keeps the corpus easier to trust.