version: "1.0.0" name: hive-memory description: Read from and write to the shared Hive Mind corpus (the hv CLI) — append-only institutional memory shared across agents (Hermes, Claude Code, …) and machines. Use to record decisions/outcomes/constraints and to check what the hive already knows before acting — especially on errors, uncertainty, or a named project/person/system. when_to_use: A decision or outcome is reached; you hit an error or gotcha; you're unsure or about to assert something checkable; the user references a project/person/system that may be in the corpus; or the user says to use hive-mind / log to the hive.

Hive Mind memory

Hive Mind is a shared, append-only memory corpus used by multiple AI agents across machines, synced peer-to-peer. You interact with it through the hv CLI. Confidence in a fact is a derived projection over the corpus — you never set it; it rises only when distinct independent sources assert the same thing. So repetition is worthless; independent corroboration and checkable outcomes are what matter.

The CLI

hv lives at ~/projects/hive-mind/hv — an absolute path that works from any directory (do not cd). Run it via the shell:

• Search: ~/projects/hive-mind/hv search "<query>" (add --format json for structured results)
• Remember: ~/projects/hive-mind/hv remember "<fact>" --tags <t1,t2> --source claude-code [--channel introspect]
• Decide: ~/projects/hive-mind/hv decide "<decision>" --rationale "<why>" --informed <ref> [<ref>…] --source claude-code

(<ref> = the sid field — h: + 10 hex, e.g. h:3f9a1c0b2d — of each fact/decision you retrieved and relied on; the raw ref node_id:seq also works. Both are stable across nodes and rebuilds. Bare local ids like 118/d17 are rowids that drift on every rebuild, and 2.0 refuses them — never pass one)

• Propose: ~/projects/hive-mind/hv propose "<hypothesis>" --tags <t1,t2> --source claude-code

(an IDEA, not a fact: starts at 0.00 and can earn confidence only from other identities' sense-channel evidence — use it for "perhaps X relates to Y", never for something observed)

• Weigh in: ~/projects/hive-mind/hv remember "<what you observed>" --supports <sid> (or --contradicts <sid>)

when an observation bears on an idea or fact, e.g. one the digest lists as open. If it comes from your reasoning rather than an observation, add --channel introspect; if it builds on or comments on an entry rather than bearing evidence, use --extends <sid> (never weighed). One relationship per write; your own support of your own idea doesn't count

• Sync: ~/projects/hive-mind/hv sync now

ALWAYS pass `--source claude-code` on remember and decide so the hive can distinguish your writes from other agents' — this is what makes corroboration and provenance work. Without it the write counts as a person's (manual), and on the owner device its links carry owner authority.

When to WRITE (be disciplined — the corpus is shared and permanent)

Write durable, checkable, reusable knowledge:

• Decisions (hv decide) with rationale — architectural / process choices. **Pass --informed

with the refs of the facts you searched and relied on**: that is how the hive later learns which knowledge proved useful once the decision's outcomes are recorded.

• Outcomes / results of actions ("did X → got Y") — checkable ground truth. When the action

carried out a recorded decision, write the outcome with --outcome-of <decision sid> --polarity 1|0|-1 so the decision earns an outcome score and the facts it relied on earn utility. Only observed outcomes count; if it is your own assessment rather than something observed, add --channel introspect.

• Corrections — something was wrong and is now right. Replace the old fact rather than leaving

both live: hv remember "<correction>" --resolves <sid of the wrong fact> (soft-retracts it). A decision that was wrong and has no replacement: hv decide --revoke <sid> --rationale "<why>" --source claude-code. A replacement instead: hv decide "<new>" --supersedes <sid>. Read the output: NOT in effect means the owner has to re-run it.

• Constraints / preferences / commitments that shape future work.
• New entities / relationships worth remembering.
• Conclusions, analysis, plans: only if worth finding later, and always with

--channel introspect. They are recorded, searchable and linkable, but count 0 toward confidence until someone's observation supports them. Two agents that read the same code and reach the same conclusion are one line of reasoning twice, not two observations.

Do NOT write your chain-of-thought (the journal is permanent, syncs to every device and is searched on every turn), restatements of things already in the corpus, or untestable speculation. A hypothesis worth testing goes through hv propose as an idea (it earns confidence from evidence; it cannot borrow it from you). Tags such as observation or confirmed help readers weigh a fact but never change how much it counts as evidence: the channel is what counts. Leave it off for what you observed; pass --channel introspect for what you concluded. Never assert your own confidence/trust number; confidence is derived, not declared.

Search before you write (hv search). If the fact is already there, don't rewrite it — its confidence rises from independent corroboration, not from you repeating it. Never write back something you just read from the hive this session (that's an echo, not evidence).

You are the salience judge — apply the rubric above. As a mechanical floor you may add --gate to remember (skips trivially short / bare-question / greeting writes); it never overrides your judgment.

When to READ

Search the hive — hv search "<terms>" — when:

• you start work on a project/person/system (search its name),
• you hit an error or gotcha (search the error text — someone may have left the fix),
• you're uncertain or about to assert something checkable,
• the user mentions a named entity that might be in the corpus.

Treat results as signals with provenance, not truth — note the confidence, the number of sources, and which node/agent said it. If the corpus holds conflicting facts on a topic, surface both with their provenance and hold the tension; do not silently pick a winner. Prefer observed outcomes over interpretations, and verify when you can.

Why the discipline

A shared memory that records everything — guesses, repetition, self-talk — becomes a confident echo chamber. Writing only checkable decisions/outcomes, checking novelty first, and surfacing conflict instead of resolving it are what keep the hive sane.